Skip to main content

Robot Management and Configuration

Remote Control​

warning

Do not try controlling the robot from different sources at the same time! It may cause unpredictable behavior!

By default, the robot can be controlled using /cmd_vel topic. Panther will process all messages sent to the topic and provide output velocity to the wheels unless E-stop is triggered. Output velocities are scaled according to velocity smoother limits (see Changing Velocity Smoothing Parameters for more information). Below are some tools that allow you to control the Panther robot, but any node publishing to /cmd_vel topic will be valid.

REPEATING /cmd_vel MESSAGES

For safety reasons, the robot will initiate a stop if the time since the last velocity command exceeds 1 second. When utilizing a custom control system, ensure that velocity commands are sent at an appropriate frequency. The recommended minimum frequency is 10 Hz.

/cmd_vel SAFETY CONDITIONS

To control the Panther robot with /cmd_vel topic E-stop state has to be reset. It can be done using the ROS service, WebUI, or the Gamepad controller.

If some messages are being published to /cmd_vel while E-stop is triggered, it is impossible to reset it.

Gamepad​

The ROS Joy2Twist node allows controlling the Panther robot with a Gamepad. By default, it can be used with the F710 gamepad, but the node can be configured to work with any Gamepad controller.

  • Press B to trigger E-stop on Panther.
  • Hold LT button and press A to release the E-stop.
  • To control Panther hold the LB button and use the left stick to drive forward/backward (additionally left/right when using mecanum wheels) and the right stick to turn the robot.

For more information on how to run and use it, see the Joy2Twist GitHub page.

Keyboard​

A teleop_twist_keyboard ROS package is one of the basic ROS tools that allows you to control a robot. It converts keyboard input to velocity commands published in the /cmd_vel topic. It can be easily installed and applied to any device with ROS. When using teleop_twist_keyboard with Panther, it is advised to set the repeat_rate parameter in order to meet the required publishing rate. For more information on how to run and use it, see teleop_twist_keyboard.

REPEATING /cmd_vel MESSAGES

To run teleop_twist_keyboard with ROS parameter repeat_rate, use command:

husarion@mydevice:~$
ros2 run teleop_twist_keyboard teleop_twist_keyboard _repeat_rate:=10.0

WebUI​

WebUI is a simple user interface that can be accessed via the Internet using a browser. The interface allows you to observe the robot's status, and allows you to perform commands such as activating or resetting E-stop or controlling the robot using a joystick.

Installation​

We are not recommend installing any additional applications on the User Computer. Before installing any package on the User Computer, make sure that time synchronization has been performed.

sudo snap install husarion-webui --channel=humble
sudo snap set husarion-webui ros.namespace=panther
sudo snap set husarion-webui ros.transport=rmw_cyclonedds_cpp
sudo snap set husarion-webui webui.layout=panther
sudo husarion-webui.start
Configuration

These settings are typical for the default Panther configuration. In some situations you may want to change the port using the webui.port variable or use a custom DDS configuration by passing a configuration file to the snap (/var/snap/husarion-webui/common/{config}.xml) and specifying ros.transport variable (sudo snap set husarion-webui ros.transport={config}). For more information check: snap info husarion-webui.

After installation, you should be able to access the WebUI from any device connected to the same LAN via the address {webui-device-ip}:{port}/ui (default: 10.15.20.3:8080/ui). If both devices are on the same network created by Husarnet VPN, you can access the robot via {hostname}:8080/ui. After entering the indicated address, you should see (it is recommended to use Chrome Browser):

ROS Packages Configuration​

Changing Velocity Smoothing Parameters​

The Panther by default uses diff_drive_controller from ros2 control or mecanum_drive_controller. This controller can be customized, among others: by modifying the robot's dynamic parameters (e.g. smooth the speed or limit the robot's speed and acceleration). Its parameters can be found in the panther_controller. By default, these values correspond to the upper limits of the robot's velocities and accelerations.

Changing Wheel Type​

Changing wheel types is possible and can be done for both the real robot and the simulation. By default, three types of wheels are supported using the launch argument wheel_type. If you want to use custom wheels, all you need to do is point to the new wheel and controller configuration files using the wheel_config_path and controller_config_path parameters. These files should be based on the default files, i.e. WH01_controller.yaml and WH01.yaml.

Use of GPS in Simulation​

The NavSat system is utilized to publish the Panther robot's position within the Gazebo world. It manages navigation satellite sensors, such as GPS, which report position and velocity in spherical coordinates (latitude/longitude) through Ignition Transport.

The NavSat sensors requires the spherical coordinates of the world origin to be configured. This configuration can be accomplished, for instance, by employing the <spherical_coordinates> tag within the world's SDF or by utilizing the Ignition /world/world_name/set_spherical_coordinates service.

To obtain GPS data in Ignition, follow these steps:

  • Include the ANT02 by adding the following lines to your components.yaml file inside the components list:
  - type: ANT02
    parent_link: cover_link
    xyz: 0.185 -0.12 0.0
    rpy: 0.0 0.0 3.14
    device_namespace: gps
  • Add the following tag to your world's SDF file and specify this file using the world parameter (the default husarion_world.sdf file already includes this tag):
<spherical_coordinates>
  <surface_model>EARTH_WGS84</surface_model>
  <world_frame_orientation>ENU</world_frame_orientation>
  <latitude_deg>53.1978</latitude_deg>
  <longitude_deg>18.3732</longitude_deg>
  <elevation>0</elevation>
  <heading_deg>0</heading_deg>
</spherical_coordinates>

Linear Battery Plugin​

It is possible to simulate the battery operation of the Panther robot. By default, this feature is disabled, but you can enable it by setting the simulate_discharging parameter to true in the battery_plugin_config.yaml file or in the file pointed to by the battery_config_path parameter. Below, you will find the plugin parameters that enable battery simulation.

  • simulate_discharging [bool, default: false]: Enables battery simulation. If set to true, the battery will discharge at a constant rate (regardless of joint torque), and if it depletes completely, the robot will stop moving. When set to false, the battery will not discharge, but the battery status information will still be published on the battery/battery_status topic.
  • initial_charge_percentage [float, default: 70.0]: Sets the initial charge percentage of the battery.
  • charging_time [float, default: 6.0]: Specifies the charging time for the battery in hours.
  • power_load [float, default: 120.0]: Represents the average power load during normal operation [W] and is initially set to 120.0 W. With the default power load of 120.0 W, the robot can operate for up to 8 hours. When the simulate_discharging parameter is set to false, this value defaults to 0.0 W. Users are encouraged to customize this value to match their specific requirements. For more information on Panther power consumption, please refer to Panther Battery & Charging Documentation.
note

The battery model is quite simple and involves significant simplifications. As a result, the battery discharge rate observed on the physical robot may differ from the model's predictions.

Charging Process​

Unfortunately, there is no straightforward way to exchange LinearBatteryPlugin services between ROS and Gazebo Transport, so you need to use the ign commands. As a result, the method of charging differs between the real and simulated robot.

You can start the charging process by calling the Ignition service:

ign service --service /model/panther/battery/battery/recharge/start --reqtype ignition.msgs.Boolean --reptype ignition.msgs.Empty --req '' --timeout 0

and stop it using:

ign service --service /model/panther/battery/battery/recharge/stop --reqtype ignition.msgs.Boolean --reptype ignition.msgs.Empty --req '' --timeout 0

LED Animations​

Basic led configuration is loaded from led_config.yaml file. It includes definition of robot panels, virtual segments and default animations. Default animations can be found in the table below:

IDNAMEPRIORITYANIMATION
0E_STOP3E_STOP
1READY3READY
2ERROR1ERROR
3MANUAL_ACTION3MANUAL_ACTION
4AUTONOMOUS_ACTION3AUTONOMOUS_ACTION
5GOAL_ACHIEVED2GOAL_ACHIEVED
6LOW_BATTERY2LOW_BATTERY
7CRITICAL_BATTERY2CRITICAL_BATTERY
9CHARGING_BATTERY3CHARGING_BATTERY

Panels​

The panels section of the YAML file lists all the physical LED panels on the robot. Each panel has two attributes:

  • channel [int, default: None] the identifier for the LED panel. It is used to differentiate between multiple panels.
  • number_of_leds: defines the total number of LEDs present on the panel.

Segments​

The segments section is used to create virtual segments on the robot by dividing the LED panels into different parts. This allows for more precise control over which LEDs are lit up for different effects or indicators. Each segment has three attributes:

  • name: the identifier for the segment, such as "front" or "rear". It is used to differentiate between multiple segments.
  • channel: This specifies which LED panel the segment belongs to. It has to match one of the channels defined in the panels section.
  • led_range: This defines the range of LEDs within the panel that the segment covers. The range is specified as a start-end pair (e.g. 0-45). The range can be specified in reverse order (e.g. 45-0), which may be useful for wiring or orientation reasons.

Segments map​

The segments_map section allows creating named groups of segments on which animations can be displayed. Each entry under segments_map consists of a key representing the group name and a list of segments included in the group. Segment names have to match one of the segments defined in the segments section. By default, you can use provided mapping:

  • all [list, default: None]: Grouping both front and rear segments together.
  • front [list, default: None]: Containing only the front segment.
  • rear [list, default: None]: Containing only the rear segment.

Animations​

The led_animations section contains a list with definitions for various animations that can be displayed on the LED segments. Supported keys are:

  • animations [list, default: None]: definition of animation for each Bumper Lights. Supported keys are:
    • type [string, default None]: Specifies the type of animation. Default animation types are: panther_lights::ImageAnimation, panther_lights::ChargingAnimation.
    • segments [string, default None]: Indicates which segment mapping this particular animation applies to (e.g., all, front, rear).
    • animation [yaml, default: None]: An animation to be displayed on segments. The keys for the configuration of different animation types are explained in detail under the Animation Types section.
  • id [int, default: None]: unique ID of an animation.
  • name [string, default: ANIMATION_ID]: name of an animation. If not provided, it will default to ANIMATION_ID, where ID is equal to id parameter of the given animation.
  • priority [int, default: 3]: priority at which animation will be placed in the queue. The list below shows the behavior when an animation with a given ID arrives:
    • 1 interrupts and removes animation with priorities 2 and 3.
    • 2 interrupts animations with priority 3.
    • 3 adds animation to the end of the queue.
  • timeout [float, default: 120.0]: time in [s], after which animation will be removed from the queue.

Animation Types​

Animation​

Basic animation definition. Keys are inherited from the basic Animation class by all animations. Supported keys are:

  • brightness [float, default: 1.0]: animation brightness relative to APA102C driver global_brightness. The range between [0.0, 1.0].
  • duration [float, default: None]: duration of the animation.
  • repeat [int, default: 1]: number of times the animation will be repeated.
note

Overall display duration of an animation is a product of a single image duration and repeat count. The result of duration x repeat can't exceed 10 [s]. If animation fails to fulfill the requirement, it will result in an error.

ImageAnimation​

Animation of type panther_lights::ImageAnimation, returns frames to display based on a supplied image. Extends Animation with keys:

  • color [int, default: None]: The image is turned into grayscale, and then the color is applied with brightness from the gray image. Values have to be in HEX format. This parameter is not required.
  • image [string, default: None]: path to an image file. Only global paths are valid. Allows using $(find ros_package) syntax.
ChargingAnimation​

Animation of type panther_lights::ChargingAnimation, returns frame to display based on param value representing Battery percentage. Displays a solid color with a duty cycle proportional to the Battery percentage. The color is changing from red (Battery discharged) to green (Battery fully charged).

Defining Animations​

Users can define their own LED animations using basic animation types. Similar to basic ones, user animations are parsed using YAML file and loaded on node start. For ImageAnimation you can use basic images from the animations folder and change their color with the color key (see ImageAnimation). Follow the example below to add custom animations.

Create a YAML file with an animation description list. Example file:

## my_awesome_user_animations.yaml
user_animations:
  # animation with default image and custom color
  - id: 21
    name: ANIMATION_1
    priority: 2
    animations:
      - type: panther_lights::ImageAnimation
        segments: all
        animation:
          image: $(find panther_lights)/animations/strip01_red.png
          duration: 2
          repeat: 2
          color: 0xffff00

  # animation with custom image
  - id: 22
    name: ANIMATION_2
    priority: 3
    animations:
      - type: panther_lights::ImageAnimation
        segments: all
        animation:
          image: /animations/custom_image.png
          duration: 3
          repeat: 1

  # animation with a custom image from custom ROS package
  - id: 23
    name: ANIMATION_3
    priority: 3
    animations:
      - type: panther_lights::ImageAnimation
        segments: all
        animation:
          image: $(find my_custom_animation_package)/animations/custom_image.png
          duration: 3
          repeat: 1

  # different animations for Front and Rear Bumper Light
  - id: 24
    name: ANIMATION_4
    priority: 3
    animations:
      - type: panther_lights::ImageAnimation
        segments: front
        animation:
          image: $(find panther_lights)/animations/triangle01_blue.png
          duration: 2
          repeat: 2
      - type: panther_lights::ImageAnimation
        segments: rear
        animation:
          image: $(find panther_lights)/animations/triangle01_red.png
          duration: 3
          repeat: 1
note

ID numbers from 0 to 19 are reserved for system animations.

note

Priority 1 is reserved for crucial system animations. Users can only define animations with priority 2 and 3.

Remember to modify launch command to use user animations:

ros2 launch panther_bringup bringup.launch user_animations_file:=/my_awesome_user_animations.yaml

Test new animations:

ros2 service call /lights/set_animation panther_msgs/srv/SetLEDAnimation "{animation: {id: 0, param: ''}, repeating: true}"

Defining a Custom Animation Type​

It is possible to define your own animation type with expected, new behavior. For more information, see: Animation API.

Shutdown Behavior​

For more information regarding shutdown behavior, refer to ShutdownSingleHost BT node in the Actions section. An example of a shutdown hosts YAML file can be found below.

## My shutdown_hosts_config.yaml
hosts:
  # Intel NUC, user computer
  - ip: 10.15.20.3
    username: husarion
  # Universal robots UR5
  - ip: 10.15.20.4
    username: root
  # My Raspberry pi that requires very long shutdown sequence
  - ip: 10.15.20.12
    timeout: 40
    username: pi
    command: /home/pi/my_long_shutdown_sequence.sh

To set up a connection with a new User Computer and allow execution of commands, login to the Built-in Computer with ssh husarion@10.15.20.2. Add Built-in Computer's public key to known_hosts of a computer you want to shut down automatically:

ssh-copy-id username@10.15.20.XX
info

To allow your computer to be shutdown without the sudo password, ssh into it and execute (if needed replace husarion with username of your choice):

sudo su
echo husarion 'ALL=(ALL) NOPASSWD: /sbin/poweroff, /sbin/reboot, /sbin/shutdown' | EDITOR='tee -a' visudo

Faults Handle​

After receiving a message on the battery/battery_status topic, the panther_manager node makes decisions regarding safety measures. For more information regarding the power supply status, please refer to the BatteryState message definition and adc_battery.cpp implementation.

Power Supply HealthProcedure
GOOD-
UNKNOWN-
OVERHEAT1. Turn on the fan.
2. If the Battery temperature is higher than 55.0 [°C], trigger an emergency stop and turn off AUX.
3. If the Battery temperature is higher than 62.0 [°C], shutdown the robot.
DEADShutdown the robot.
OVERVOLTAGE1. Initiate an emergency stop.
2. Display an error animation if the charger is connected.
COLD-
note
  1. The fan exhibits a form of hysteresis, allowing it to be turned off after a delay of at least 60 seconds.
  2. Once the Panther ROS stack initializes, the fan activates and operates for a duration of approximately 60 seconds.

BehaviorTree​

This package contains two main BehaviorTree projects. One is designed for lights handling and the other for safety and system shutdown. For a BehaviorTree project to work correctly, it must contain a tree with correct names. The names are: Lights for lights BT project; Shutdown and Safety for safety BT project. Files with trees XML descriptions can be shared between projects. Each tree is provided with a set of default blackboard entries (described below), which can be used to specify the behavior of a given tree.

Nodes​

Actions​
  • CallSetBoolService - allows calling the standard std_srvs/SetBool ROS service. Provided ports are:
    • data [input, bool, default: None]: service data - true or false value.
    • service_name [input, string, default: None]: ROS service name.
  • CallSetLedAnimationService - allows calling custom type panther_msgs/SetLEDAnimation ROS service. The provided ports are:
    • id [input, unsigned, default: None]: animation ID.
    • param [input, string, default: None]: optional parameter passed to animation.
    • repeating [input, bool, default: false]: indicates if the animation should repeat.
    • service_name [input, string, default: None]: ROS service name.
  • CallTriggerService - allows calling the standard std_srvs/Trigger ROS service. The provided ports are:
    • service_name [input, string, default: None]: ROS service name.
  • ShutdownHostsFromFile - allows to shutdown devices based on a YAML file. Returns SUCCESS only when a YAML file is valid and the shutdown of all defined hosts was successful. Nodes are processed in a semi-parallel fashion. Every tick of the tree updates the state of a host. This allows some hosts to wait for a SSH response, while others are already pinged and awaiting a full shutdown. If a host is shutdown, it is no longer processed. In the case of a long timeout is used for a given host, other hosts will be processed simultaneously. The provided ports are:
    • shutdown_host_file [input, string, default: None]: global path to YAML file with hosts to shutdown.
  • ShutdownSingleHost - allows to shut down a single device. Will return SUCCESS only when the device has been successfully shutdown. The provided ports are:
    • command [input, string, default: sudo shutdown now]: command to execute on shutdown.
    • ip [input, string, default: None]: IP of the host to shutdown.
    • ping_for_success [input, bool, default: true]: ping host until it is not available or timeout is reached.
    • port [input, string, default: 22]: SSH communication port.
    • timeout [input, string, default: 5.0]: time in [s] to wait for the host to shutdown. Keep in mind that hardware will cut power off after a given time after pressing the power button. Refer to the hardware manual for more information.
    • username [input, string, default: None]: user to log into while executing the shutdown command.
  • SignalShutdown - signals shutdown of the robot. The provided ports are:
    • message [input, string, default: None]: message with reason for robot to shutdown.
Decorators​
  • TickAfterTimeout - will skip a child until the specified time has passed. It can be used to specify the frequency at which a node or subtree is triggered. The provided ports are:
    • timeout [input, unsigned, default: None]: time in [s] to wait before ticking child again.

Trees​

Lights​

A tree responsible for scheduling animations displayed on the Bumper Lights based on the Husarion Panther robot's system state.

Lights Behavior Tree

Default blackboard entries:

  • battery_percent [float, default: None]: moving average of the Battery percentage.
  • battery_percent_round [string, default: None] Battery percentage rounded to a value specified with ~lights/update_charging_anim_step parameter and cast to string.
  • battery_status [unsigned, default: None]: the current Battery status.
  • charging_anim_percent [string, default: None]: the charging animation Battery percentage value, cast to a string.
  • current_anim_id [int, default: -1]: ID of currently displayed animation.
  • e_stop_state [bool, default: None]: state of E-stop.

Default constant blackboard entries:

  • BATTERY_STATE_ANIM_PERIOD [float, default: 120.0]: refers to battery_state_anim_period ROS parameter.
  • CRITICAL_BATTERY_ANIM_PERIOD [float, default: 15.0]: refers to critical_battery_anim_period ROS parameter.
  • CRITICAL_BATTERY_THRESHOLD_PERCENT [float, default: 0.1]: refers to critical_battery_threshold_percent ROS parameter.
  • LOW_BATTERY_ANIM_PERIOD [float, default: 30.0]: refers to low_battery_anim_period ROS parameter.
  • LOW_BATTERY_THRESHOLD_PERCENT [float, default: 0.4]: refers to low_battery_threshold_percent ROS parameter.
  • E_STOP_ANIM_ID [unsigned, value: 0]: animation ID constant obtained from panther_msgs::LEDAnimation::E_STOP.
  • READY_ANIM_ID [unsigned, value: 1]: animation ID constant obtained from panther_msgs::LEDAnimation::READY.
  • ERROR_ANIM_ID [unsigned, value: 2]: animation ID constant obtained from panther_msgs::LEDAnimation::ERROR.
  • MANUAL_ACTION_ANIM_ID [unsigned, value: 3]: animation ID constant obtained from panther_msgs::LEDAnimation::MANUAL_ACTION.
  • AUTONOMOUS_ACTION_ANIM_ID [unsigned, value: 4]: animation ID constant obtained from panther_msgs::LEDAnimation::AUTONOMOUS_ACTION.
  • GOAL_ACHIEVED_ANIM_ID [unsigned, value: 5]: animation ID constant obtained from panther_msgs::LEDAnimation::GOAL_ACHIEVED.
  • LOW_BATTERY_ANIM_ID [unsigned, value: 6]: animation ID constant obtained from panther_msgs::LEDAnimation::LOW_BATTERY.
  • CRITICAL_BATTERY_ANIM_ID [unsigned, value: 7]: animation ID constant obtained from panther_msgs::LEDAnimation::CRITICAL_BATTERY.
  • BATTERY_STATE_ANIM_ID [unsigned, value: 8]: animation ID constant obtained from panther_msgs::LEDAnimation::BATTERY_STATE.
  • CHARGING_BATTERY_ANIM_ID [unsigned, value: 9]: animation ID constant obtained from panther_msgs::LEDAnimation::CHARGING_BATTERY.
  • POWER_SUPPLY_STATUS_UNKNOWN [unsigned, value: 0]: power supply status constant obtained from sensor_msgs::BatteryState::POWER_SUPPLY_STATUS_UNKNOWN.
  • POWER_SUPPLY_STATUS_CHARGING [unsigned, value: 1]: power supply status constant obtained from sensor_msgs::BatteryState::POWER_SUPPLY_STATUS_CHARGING.
  • POWER_SUPPLY_STATUS_DISCHARGING [unsigned, value: 2]: power supply status constant obtained from sensor_msgs::BatteryState::POWER_SUPPLY_STATUS_DISCHARGING.
  • POWER_SUPPLY_STATUS_NOT_CHARGING [unsigned, value: 3]: power supply status constant obtained from sensor_msgs::BatteryState::POWER_SUPPLY_STATUS_NOT_CHARGING.
  • POWER_SUPPLY_STATUS_FULL [unsigned, value: 4]: power supply status constant obtained from sensor_msgs::BatteryState::POWER_SUPPLY_STATUS_FULL.

Safety​

A tree responsible for monitoring the Panther robot's state and handling safety measures, such as cooling the robot in case of high Built-in Computer's CPU or Battery temperatures.

Safety Behavior Tree

Default blackboard entries:

  • aux_state [bool, default: None]: state of AUX Power.
  • bat_temp [double, default: None]: moving average of the Battery temperature.
  • cpu_temp [double, default: None]: moving average of the Built-in Computer's CPU temperature
  • driver_temp [double, default: None]: moving average of driver temperature. Out of the two drivers, the one with the higher temperature is taken into account.
  • e_stop_state [bool, default: None]: state of the E-stop.
  • fan_state [bool, default: None]: state of the fan.

Default constant blackboard entries:

  • CPU_FAN_OFF_TEMP [float, default: 60.0]: refers to thecpu_fan_off_temp ROS parameter.
  • CPU_FAN_ON_TEMP [float, default: 70.0]: refers to the cpu_fan_on_temp ROS parameter.
  • CRITICAL_BAT_TEMP [float, default: 59.0]: refers to the critical_bat_temp ROS parameter.
  • DRIVER_FAN_OFF_TEMP [float, default: 35.0]: refers to the driver_fan_off_temp ROS parameter.
  • DRIVER_FAN_ON_TEMP [float, default: 45.0]: refers to the driver_fan_on_temp ROS parameter.
  • HIGH_BAT_TEMP [float, default: 55.0]: refers to the high_bat_temp ROS parameter.
  • POWER_SUPPLY_HEALTH_UNKNOWN [unsigned, value: 0]: power supply status constant obtained from the sensor_msgs::BatteryState::POWER_SUPPLY_HEALTH_UNKNOWN.
  • POWER_SUPPLY_HEALTH_GOOD [unsigned, value: 1]: power supply status constant obtained from the sensor_msgs::BatteryState::POWER_SUPPLY_HEALTH_GOOD.
  • POWER_SUPPLY_HEALTH_OVERHEAT [unsigned, value: 2]: power supply status constant obtained from the sensor_msgs::BatteryState::POWER_SUPPLY_HEALTH_OVERHEAT.
  • POWER_SUPPLY_HEALTH_DEAD [unsigned, value: 3]: power supply status constant obtained from the sensor_msgs::BatteryState::POWER_SUPPLY_HEALTH_DEAD.
  • POWER_SUPPLY_HEALTH_OVERVOLTAGE [unsigned, value: 4]: power supply status constant obtained from the sensor_msgs::BatteryState::POWER_SUPPLY_HEALTH_OVERVOLTAGE.
  • POWER_SUPPLY_HEALTH_UNSPEC_FAILURE [unsigned, value: 5]: power supply status constant obtained from the sensor_msgs::BatteryState::POWER_SUPPLY_HEALTH_UNSPEC_FAILURE.
  • POWER_SUPPLY_HEALTH_COLD [unsigned, value: 6]: power supply status constant obtained from the sensor_msgs::BatteryState::POWER_SUPPLY_HEALTH_COLD.
  • POWER_SUPPLY_HEALTH_WATCHDOG_TIMER_EXPIRE [unsigned, value: 7]: power supply status constant obtained from the sensor_msgs::BatteryState::POWER_SUPPLY_HEALTH_WATCHDOG_TIMER_EXPIRE.
  • POWER_SUPPLY_HEALTH_SAFETY_TIMER_EXPIRE [unsigned, value: 8]: power supply status constant obtained from the sensor_msgs::BatteryState::POWER_SUPPLY_HEALTH_SAFETY_TIMER_EXPIRE.

Shutdown​

A tree responsible for the graceful shutdown of robot components, user computers, and the Built-in Computer. By default, it will proceed to shutdown all computers defined in a YAML file with a path defined by the shutdown_host_path ROS parameter.

Shutdown Behavior Tree

Default constant blackboard entries:

  • SHUTDOWN_HOSTS_PATH [string, default: None]: refers to shutdown_hosts_path ROS parameter.

Expected blackboard entries:

  • signal_shutdown [pair(bool, string), default: (false, '')]: flag to shutdown robot with information to display while shutting down.

Modifying Behavior Trees​

Each behavior tree can be easily customized to enhance its functions and capabilities. To achieve this, we recommend using Groot2, a powerful tool for developing and modifying behavior trees. To install Groot2 and learn how to use it, please refer to the official guidelines.

When creating a new BehaviorTree project, it is advised to use an existing project as a guideline and leverage it for reference. You can study the structure and implementation of the behavior trees in the existing project to inform your own development process. The project should consist of Lights behavior tree or both Safety and Shutdown behavior tree. Additionally, you have the option to incorporate some of the files used in the existing project into your own project. By utilizing these files, you can benefit from the work already done and save time and effort in developing certain aspects of the behavior trees.

note

It is essential to exercise caution when modifying the trees responsible for safety or shutdown and ensure that default behaviors are not removed. Remember to use the files from the existing project in a way that avoids conflicts, such as by saving them under new names to ensure they don't overwrite any existing files.

When modifying behavior trees, you have the flexibility to use standard BehaviorTree.CPP nodes or leverage nodes created specifically for Panther, as detailed in the Nodes section. Additionally, if you have more specific requirements, you can even create your own custom Behavior Tree nodes. However, this will involve modifying the package and rebuilding the project accordingly.

To use your customized project, you can modify the bt_project_file ROS parameter.

Real-time Visualization​

Groot2 also provides a real-time visualization tool that allows you to see and debug actively running trees. To use this tool with trees launched with the panther_manager package, you need to specify the port associated with the tree you want to visualize. The ports for each tree are listed below:

  • Lights tree: 10.15.20.2:5555
  • Safety tree: 10.15.20.2:6666
  • Shutdown tree: 10.15.20.2:7777

Manage ROS Nodes with Docker​

The Panther robot uses a Docker container to launch ROS nodes on the Built-in Computer. By default, four Docker containers are launched:

  • panther_ros - starts default Panther nodes,
  • gamepad_controller - starts the Gamepad node.

Docker containers can be controlled (e.g., stopped, restarted) and configured (e.g., modified restart policy) by logging into the Built-in Computer (default ssh husarion@10.15.20.2 password: husarion) and using standard Docker CLI. For more information on how to control Docker containers, refer to How to use Docker.

Modification of configuration files​

To modify the default configuration files you need to attach your modified file into docker container. To do this you need to add file using volume. Follow these steps to see how to do this.

  1. Copy and modify the desired configuration file (e.g., controller_config.yaml).

  2. To incorporate the YAML file into Docker, make changes to the main Docker compose file located at ~/compose.yaml. Add a volume entry to the panther_ros container section:

    volumes:
      # other volumes
      - /path/to/your_config.yaml:/your_config.yaml
    CHANGE FILE NAME

    Ensure to replace /path/to/your_config.yaml with the correct path to the YAML file you created.

  3. Find the appropriate fragment specifying the path to the selected config file (e.g. controller_config_path) and modify the launch command:

    command: >
      ros2 launch panther_bringup bringup.launch.py
      config_path:=/your_config.yaml

  4. Restart Docker containers to apply the changes:

    husarion@10.15.20.2:~$
    docker compose up -d --force-recreate

GNSS API​

PREREQUIREMENTS

To use the GNSS (including GPS), Panther has to be equipped with the ANT02 option.

GNSS data in NMEA format is forwarded to the Built-in Computer IP address at port 5000. Typically you can access it at upd://10.15.20.2:5000.

You can make sure the address is correct by typing http://10.15.20.1 into your browser (username: admin, password: Husarion1). Navigate to Services -> GPS -> NMEA -> NMEA forwarding -> Hostname and Port. Remember that you must be connected to the robot's WiFi network. If changes are needed, finish the configuration by pressing save & apply at the bottom of the screen. To learn more about GPS configuration, please refer to RUTX11 GPS.

Data frequency is 1 Hz and can be interacted ether with GPSD daemon

husarion@mydevice:~$
gpsd -N udp://10.15.20.2:5000

or directly with the ROS package, translating the signal to a ROS topic.

USE DOCKER COMPOSE

It is recommended to use a Docker image through a compose.yaml file.

If launching on a Built-in Computer you can utilize the main Panther compose file located at ~/compose.yaml. Edit the file using the text editor of your choice and add the following container:

  nmea-gps:
    image: husarion/nmea-gps:humble-2.0.1-20240617
    network_mode: host
    restart: always
    command: >
      ros2 launch /husarion_utils/nmea_navsat.launch.py
        robot_namespace:=panther

To restart Docker containers, execute the following command from within the directory containing the compose file:

husarion@10.15.20.2:~$
docker compose up -d --force-recreate

You should be able to see data from the GNSS by listening to a ROS topic.

husarion@mydevice:~$
ros2 topic echo /panther/gps/fix

Operating System Image Reinstallation​

In some cases, you will need to restore Panther's system to its default settings:

  • in case of accidental damage to the system,
  • to update the OS,
  • to clear all user changes and restore factory settings.

Find the full instructions in Operating System Reinstallation.