Skip to main content

ROS 2 Alpha API

Initial Release Warning

Please be advised that the software you are about to use is the first publicly available version of ROS 2 Driver for Panther. It is functional and architecture will not change in a significant way. It was tested by Husarion team, however some stability issues and bugs might still occur. Also, the ROS 2 API may face some minor changes in the following releases.

We would be grateful for your feedback related to Panther ROS 2 driver. You can reach us the following ways:

Overview​

Robot Operating System (ROS) is a set of software libraries and tools that help build robot applications. It provides a common framework for developing robot software, making it easier to share code and ideas between developers. ROS is also open-source, which means that it is free to use and modify.

By default, the Panther ROS system is deployed using Docker. Docker is a containerization platform that makes it easy to deploy and manage software. It also simplifies the process of updating the Panther ROS system.

The provided Panther ROS system is designed to compose all the basic functionalities of the robot. It allows to control of the robot with velocity commands and provides the user with odometry information, which can be used for robot localization. The Panther ROS system is also designed to monitor the robot's state and perform safety features that will prevent any hazardous behavior. The basic states of the robot are represented by the Bumper Lights signals. This allows the user to recognize if the robot is ready to operate or in E-stop mode, informs about the Battery state, or displays an animation indicating the occurrence of an error in the system. More detailed information about the state of the robot can be acquired using ROS topics. Errors in the system are also logged into the system and can be easily accessed using the Docker interface. The Panther ROS system includes a robot description, which can be used to visualize the robot with all its components.

The Panther ROS system is designed to be easy to use and maintain. It is also designed to be extensible so that it can be easily customized for different applications.

Running ROS Node Natively​

Our default configuration is shipped within a Docker container, but this doesn't mean you can't run Panther ROS drivers without it. You can find all the instructions on how to build them on panther_ros GitHub page.

AUTOSTART NATIVE ROS DRIVER

Natively build ROS packages will miss autostart functionality. It is up to the user to add it. You can do so for example by creating systemd.service.

ROS 2 System Design​

This section describes the ROS packages in the Panther ROS system. These packages are located in the panther_ros GitHub repository.

DIFFERENCES IN ROS SYSTEM

ROS 2 nodes differs slightly between Panther v1.06 and Panther v1.2+. This is caused by internal hardware differences. Despite that, the ROS API was kept as closely matched between those revisions as possible and should be transparent in most of the use cases.

This diagram represents the Panther ROS system. Some topics and services have been excluded from the graph for the sake of clarity.

Panther ROS 2 API Diagram

ROS 2 API​

panther_battery​

Package containing nodes monitoring and publishing the internal battery state of the Husarion Panther robot.

Pulled from: panther_battery/README.md

battery_node​

Publishes battery state read from ADC unit for Panther version 1.2 and above, or based on Roboteq motor controllers' data for earlier versions of the robot.

Subscribers

  • ~/driver/motor_controllers_state [panther_msgs/DriverState]: current motor controllers' state and error flags. Subscribed if using Roboteq motor controllers data.

Publishers

  • /diagnostics [diagnostic_msgs/DiagnosticArray]: battery diagnostic messages.
  • ~/battery [sensor_msgs/BatteryState]: mean values of both batteries if Panther has two batteries. Otherwise, the state of the single battery will be published.
  • ~/battery_1_raw [sensor_msgs/BatteryState]: first battery raw state.
  • ~/battery_2_raw [sensor_msgs/BatteryState]: second battery raw state. Published if second battery detected.

Parameters

  • ~/adc/device0 [string, default: /sys/bus/iio/devices/iio:device0]: ADC nr 0 device IIO path. Used with Panther version 1.2 and above.
  • ~/adc/device1 [string, default: /sys/bus/iio/devices/iio:device1]: ADC nr 1 device IIO path. Used with Panther version 1.2 and above.
  • ~/adc/ma_window_len/charge [int, default: 10]: window length of a moving average, used to smooth out battery charge readings. Used with Panther version 1.2 and above.
  • ~/adc/ma_window_len/temp [int, default: 10]: window length of a moving average, used to smooth out battery temperature readings. Used with Panther version 1.2 and above.
  • ~/battery_timeout [float, default: 1.0]: specifies the timeout in seconds. If the node fails to read battery data exceeding this duration, the node will publish an unknown battery state.
  • ~/ma_window_len/voltage [int, default: 10]: window length of a moving average, used to smooth out battery voltage readings.
  • ~/ma_window_len/current [int, default: 10]: window length of a moving average, used to smooth out battery current readings.
  • ~/panther_version [float, default: 1.2]: Panther robot version. Used to initialize correct Battery node interface.
  • ~/roboteq/driver_state_timeout [float, default: 0.2]: specifies timeout in seconds after which driver state messages will be considered old. Used with Panther version 1.06 and earlier.

panther_bringup​

The package contains the default configuration and launch files necessary to start all the basic functionalities of the Husarion Panther robot.

Pulled from: panther_bringup/README.md

External ROS Nodes​

Pulled from: panther_bringup/README.md

ekf_node​

External node type: robot_localization/ekf_node.

Extended Kalman Filter node for more accurate odometry. For more information, refer to robot_localization. The default configuration is stored in panther_bringup/config/ekf.yaml.

Subscribers

  • ~/odom/wheels [nav_msgs/Odometry]: robot odometry calculated from wheels.
  • ~/imu/data [sensor_msgs/Imu]: filtered IMU data.
  • /tf [tf2_msgs/TFMessage]: transforms of robot system.

Publishers

  • ~/odometry/filtered [nav_msgs/Odometry]: provides filtered odometry information. This topic contains a fused and enhanced estimate of the robot's pose and velocity, incorporating data from various sensors and correcting for any errors in the estimated state.
  • /tf [tf2_msgs/TFMessage]: publishes odom to base_link transform.

Service Servers

  • ~/ekf_node/set_pose [robot_localization/SetPose]: by issuing a geometry_msgs/PoseWithCovarianceStamped message to the set_pose topic, users can manually set the state of the filter. This is useful for resetting the filter during testing and allows for interaction with RViz. Alternatively, the state estimation nodes advertise a SetPose service, whose type is robot_localization/SetPose.

imu_filter_node​

External node type: imu_filter_madgwick/imu_filter_node.

Node responsible for filtering and fusing raw data from the IMU.

Subscribers

  • ~/imu/data_raw [sensor_msgs/Imu]: the raw accelerometer and gyroscope data.

Publishers

  • ~/imu/data [sensor_msgs/Imu]: the fused IMU messages, containing the orientation.

phidgets_spatial_node​

External node type: phidgets_spatial/spatial_ros_i.cpp.

The ROS driver for Phidgets Spatial.

Publishers

  • ~/imu/data_raw [sensor_msgs/Imu]: the raw accelerometer and gyroscope data.
  • ~/imu/is_calibrated [std_msgs/Bool]: whether the gyroscope has been calibrated. This will be done automatically at startup time but can also be re-done at any time by calling the imu/calibrate service.
  • ~/imu/mag [sensor_msgs/MagneticField]: the raw magnetometer data.

Service Servers

  • ~/imu/calibrate [std_srvs/Empty]: run calibration on the gyroscope.

panther_controller​

The package contains the default configuration and launch files necessary to start all the basic functionalities of the Husarion Panther robot.

Pulled from: panther_controller/README.md

External ROS Nodes​

Pulled from: panther_controller/README.md

imu_broadcaster​

External node type:imu_sensor_broadcaster/imu_sensor_broadcaster.

The broadcaster to publish readings of IMU sensors.

Publishers

  • ~/imu_broadcaster/imu [sensor_msgs/msg/Imu]: data from IMU sensor.

joint_state_broadcaster​

External node type:joint_state_broadcaster/joint_state_broadcaster.

The broadcaster reads all state interfaces and reports them on specific topics.

Publishers

  • ~/dynamic_joint_states [control_msgs/msg/DynamicJointState] - provides information about the state of various movable joints in a robotic system.
  • ~/joint_states [sensor_msgs/msg/JointState] - provides information about the state of various joints in a robotic system.

panther_base_controller​

External node type:diff_drive_controller/diff_drive_controller.

Controller which manages mobile robots with a differential drive. It converts velocity commands for the robot body into wheel commands for the base. It also calculates odometry from hardware feedback and shares it.

Subscribers

  • ~/cmd_vel [geometry_msgs/msg/Twist]: command linear and angular velocity values.

Publishers

  • ~/panther_base_controller/odom [nav_msgs/msg/Odometry]: odometry data from wheel encoders.

panther_hardware_interfaces​

PantherImuSensor Package that implements SystemInterface from ros2_control for Panther.

This package doesn't contain any standalone nodes - PantherImuSensor is a plugin loaded by the resource manager. To use this hardware interface you have to add it to your URDF (you can check how to do it in panther_description) and add an imu_sensor_broadcaster controller (example configuration provided in panther_controller package).

Pulled from: panther_hardware_interfaces/README.md

PantherSystem​

This package doesn't contain any standalone nodes - PantherSystem is a plugin loaded by the resource manager. To use this hardware interface you have to add it to your URDF (you can check how to do it in panther_description) and add a controller (example configuration provided in panther_controller package). That said apart from the usual interface provided by the ros2_control, this plugin also provides additional published topics and services specific for Panther.

Publishers

  • /diagnostics [diagnostic_msgs/DiagnosticArray]: Panther system diagnostic messages.
  • /panther_system_node/driver/motor_controllers_state [panther_msgs/DriverState]: current motor controllers state and error flags.

Parameters

Parameters that are required, are defined when including interface in URDF (you can check out panther_macro.urdf.xacro).

Physical properties

  • encoder_resolution [int, default: 1600]: property of the encoder used, shouldn't be changed.
  • gear_ratio [float, default: 30.08]: property of the gearbox used, shouldn't be changed.
  • motor_torque_constant [float, default: 0.11]: same as set in the Roboteq driver (TNM parameter), also shouldn't be changed, as it is measured property of the motor.
  • max_rpm_motor_speed [float, default: 3600.0]: max RPM speed set in the Roboteq driver (MXRPM parameter).
  • gearbox_efficiency [float, default: 0.75]: measured efficiency, used for converting read current to torque, can vary depending on different factors such as temperature and wear.

CAN settings

  • can_interface_name [string, default: panther_can]: name of the CAN interface.
  • master_can_id [int, default: 3]: CAN ID of the master device (set as in canopen_configuration.yaml).
  • front_driver_can_id [int, default: 1]: CAN ID defined in the properties of Roboteq (set as in canopen_configuration.yaml).
  • rear_driver_can_id [int, default: 2]: CAN ID defined in the properties of Roboteq (set as in canopen_configuration.yaml).
  • sdo_operation_timeout_ms [int, default: 100]: timeout of the SDO operations, currently no SDO operation is required in RT operation, so this timeout can be set to a higher value.
  • pdo_motor_states_timeout_ms [int, default: 15]: depends on the frequency at which Roboteq is configured to send motor states (PDO 1 and 2) data. By default, there should be 10 [ms] between received data, if it takes more than pdo_motor_states_timeout_ms, a motor states read error is triggered. The default value is set to be expected period +50% margin.
  • pdo_driver_state_timeout_ms [int, default: 75]: depends on the frequency at which Roboteq is configured to send driver state (PDO 3 and 4) data. By default, there should be 50 [ms] between received data, if it takes more than pdo_driver_state_timeout_ms, a driver state read error is triggered. The default value is set to be expected period +50% margin.
  • driver_states_update_frequency [float, default: 20.0]: as by default, the driver state is published with lower frequency, it also shouldn't be updated with every controller loop iteration. The exact frequency at which driver state is published won't match this value - it will also depend on the frequency of the controller (the exact value of the period can be calculated with the following formula controller_frequency / ceil(controller_frequency / driver_states_update_frequency)).
  • max_roboteq_initialization_attempts [int, default: 5]: in some cases, an SDO error can happen during initialization, it is possible to configure more attempts, before escalating to a general error.
  • max_roboteq_activation_attempts [int, default: 5]: similar to initialization, it is possible to allow some SDO errors before escalating to error.
  • max_write_pdo_cmds_errors_count [int, default: 2]: how many consecutive errors can happen before escalating to general error.
  • max_read_pdo_motor_states_errors_count [int, default: 2]: how many consecutive errors can happen before escalating to general error.
  • max_read_pdo_driver_state_errors_count [int, default: 2]: how many consecutive errors can happen before escalating to general error.

[!CAUTION] max_write_pdo_cmds_errors_count, max_read_pdo_motor_states_errors_count, max_read_pdo_driver_state_errors_count, sdo_operation_timeout, pdo_motor_states_timeout_ms and pdo_driver_state_timeout_ms are safety-critical parameters, they should be changed only in very specific cases, be sure that you know how they work and be really cautious when changing them.

panther_lights​

Package used to control the Husarion Panther Bumper Lights.

Pulled from: panther_lights/README.md

driver_node​

This node is responsible for displaying frames on the Husarion Panther robot's Bumper Lights.

Subscribers

  • ~/lights/driver/channel_1_frame [sensor_msgs/Image, encoding: RGBA8, height: 1, width: num_led]: an animation frame to be displayed on robot Front Bumper Lights.
  • ~/lights/driver/channel_2_frame [sensor_msgs/Image, encoding: RGBA8, height: 1, width: num_led]: an animation frame to be displayed on robot Rear Bumper Lights.

Publishers

  • /diagnostics [diagnostic_msgs/DiagnosticArray]: lights diagnostic messages.

Service Servers

  • ~/lights/driver/set/brightness [panther_msgs/SetLEDBrightness]: allows setting global LED brightness, value ranges from 0.0 to 1.0.

Parameters

  • ~frame_timeout [float, default: 0.1]: time in [s] after which an incoming frame will be considered too old.
  • ~global_brightness [float, default: 1.0]: LED global brightness. The range between [0.0, 1.0].
  • ~num_led [int, default: 46]: number of LEDs in a single bumper.

controller_node​

This node is responsible for processing animations and publishing frames to be displayed on the Husarion Panther robot Bumper Lights.

Publishers

  • ~/lights/driver/channel_1_frame [sensor_msgs/Image, encoding: RGBA8, height: 1, width: num_led]: an animation frame to be displayed on robot Front Bumper Lights.
  • ~/lights/driver/channel_2_frame [sensor_msgs/Image, encoding: RGBA8, height: 1, width: num_led]: an animation frame to be displayed on robot Rear Bumper Lights.

Service Servers

  • ~/lights/controller/set/animation [panther_msgs/SetLEDAnimation]: allows setting animation on Bumper Lights based on animation ID.

Parameters

  • ~controller_frequency [float, default: 50.0]: frequency [Hz] at which the lights controller node will process animations.
  • ~led_config_file [string, default: $(find panther_lights)/panther_lights/config/led_config.yaml]: path to a YAML file with a description of led configuration. This file includes definition of robot panels, virtual segments and default animations.
  • ~user_led_animations_file [string, default: None]: path to a YAML file with a description of the user defined animations.

panther_manager​

A package containing nodes responsible for high-level control of Husarion Panther robot.

Pulled from: panther_manager/README.md

manager_bt_node​

Node responsible for managing the Husarion Panther robot. Composes control of three behavior trees responsible for handling Bumper Lights animation scheduling, safety features, and software shutdown of components.

Subscribers

  • ~/battery [sensor_msgs/BatteryState]: state of the internal Battery.
  • ~/driver/motor_controllers_state [panther_msgs/DriverState]: state of motor controllers.
  • ~/hardware/e_stop [std_msgs/Bool]: state of emergency stop.
  • ~/hardware/io_state [panther_msgs/IOState]: state of IO pins.
  • ~/system_status [panther_msgs/SystemStatus]: state of the system, including Built-in Computer's CPU temperature and load.

Service Clients

  • ~/hardware/aux_power_enable [std_srvs/SetBool]: enables Aux Power output.
  • ~/hardware/e_stop_trigger [std_srvs/Trigger]: triggers E-stop.
  • ~/hardware/fan_enable [std_srvs/SetBool]: enables fan.
  • ~/lights/controller/set/animation [panther_msgs/SetLEDAnimation]: allows setting animation on Bumper Lights based on animation ID.

Parameters

  • battery_percent_window_len [int, default: 6]: moving average window length used to smooth out Battery percentage readings.
  • battery_temp_window_len [int, default: 6]: moving average window length used to smooth out temperature readings of the Battery.
  • bt_project_path [string, default: $(find panther_manager)/config/PantherBT.btproj]: path to a BehaviorTree project.
  • cpu_temp_window_len [int, default: 6]: moving average window length used to smooth out temperature readings of the Built-in Computer's CPU.
  • driver_temp_window_len [int, default: 6]: moving average window length used to smooth out the temperature readings of each driver.
  • launch_lights_tree [bool, default: true]: launch behavior tree responsible for scheduling animations on Panther Bumper Lights.
  • launch_safety_tree [bool, default: true]: launch behavior tree responsible for managing Panther safety measures.
  • launch_shutdown_tree [bool, default: true]: launch behavior tree responsible for the gentle shutdown of robot components.
  • lights.battery_state_anim_period [float, default: 120.0]: time in [s] to wait before repeating animation representing the current Battery percentage.
  • lights.critical_battery_anim_period [float, default: 15.0]: time in [s] to wait before repeating animation, indicating a critical Battery state.
  • lights.critical_battery_threshold_percent [float, default: 0.1]: if the Battery percentage drops below this value, an animation indicating a critical Battery state will start being displayed.
  • lights.low_battery_anim_period [float, default: 30.0]: time in [s] to wait before repeating the animation, indicating a low Battery state.
  • lights.low_battery_threshold_percent [float, default: 0.4]: if the Battery percentage drops below this value, the animation indicating a low Battery state will start being displayed.
  • lights.update_charging_anim_step [float, default: 0.1]: percentage representing how discretized the Battery state animation should be.
  • lights.timer_frequency [float, default: 10.0]: frequency [Hz] at which lights tree will be ticked.
  • plugin_libs [list, default: Empty list]: list with names of plugins that are used in the BT project.
  • ros_plugin_libs [list, default: Empty list]: list with names of ROS plugins that are used in a BT project.
  • safety.cpu_fan_off_temp [float, default: 60.0]: temperature in [°C] of the Built-in Computer's CPU, below which the fan is turned off.
  • safety.cpu_fan_on_temp [float, default: 70.0]: temperature in [°C] of the Built-in Computer's CPU, above which the fan is turned on.
  • safety.driver_fan_off_temp [float, default: 35.0]: temperature in [°C] of any drivers below which the fan is turned off.
  • safety.driver_fan_on_temp [float, default: 45.0]: temperature in [°C] of any drivers above which the fan is turned on.
  • safety.timer_frequency [float, default: 10.0]: frequency [Hz] at which safety tree will be ticked.
  • shutdown_hosts_path [string, default: None]: path to a YAML file containing a list of hosts to request shutdown. To correctly format the YAML file, include a hosts field consisting of a list with the following fields:
    • command [string, default: sudo shutdown now]: command executed on shutdown of given device.
    • ip [string, default: None]: IP of a host to shutdown over SSH.
    • ping_for_success [bool, default: true]: ping host until it is not available or timeout is reached.
    • port [string, default: 22]: SSH communication port.
    • timeout [string, default: 5.0]: time in [s] to wait for the host to shutdown. The Built-in Computer will turn off after all computers are shutdown or reached timeout. 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 [string, default: None]: username used to log in to over SSH.