husarion_ugv_ros

ROS 2 packages for Husarion UGV (Unmanned Ground Vehicle). The repository is a collection of necessary packages enabling the launch of the Lynx and Panther robots.

Quick start

Create workspace

mkdir ~/husarion_ws
cd ~/husarion_ws
git clone -b ros2 https://github.com/husarion/husarion_ugv_ros.git src/husarion_ugv_ros

Configure environment

The repository is used to run the code both on the real robot and in the simulation. Specify HUSARION_ROS_BUILD_TYPE the variable according to your needs.

Real robot:

export HUSARION_ROS_BUILD_TYPE=hardware

Simulation:

export HUSARION_ROS_BUILD_TYPE=simulation

Build

vcs import src < src/husarion_ugv_ros/husarion_ugv/${HUSARION_ROS_BUILD_TYPE}_deps.repos

sudo rosdep init
rosdep update --rosdistro $ROS_DISTRO
rosdep install --from-paths src -y -i

source /opt/ros/$ROS_DISTRO/setup.bash
colcon build --symlink-install --packages-up-to husarion_ugv --cmake-args -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF

source install/setup.bash

Note

To build code on a real robot you need to run above commands on the robot Built-in Computer.

Running

Real robot:

ros2 launch husarion_ugv_bringup bringup.launch.py

Simulation:

ros2 launch husarion_ugv_gazebo simulation.launch.py

Important

You can change spawning robot in simulation, by adding robot_model:={robot_model} argument.

Launch Arguments

Launch arguments are largely common to both simulation and physical robot. However, there is a group of arguments that apply only to hardware or only to the simulator. Below is a legend to the tables with all launch arguments.

Symbol	Meaning
🤖	Available for physical robot
🖥️	Available in simulation

🤖	🖥️	Argument	Description Type: `Default`
❌	✅	`add_world_transform`	Adds a world frame that connects the tf trees of individual robots (useful when running multiple robots). bool: `False`
✅	✅	`animations_config_path`	Path to a YAML file with a description of led configuration. This file includes definition of robot panels, virtual segments and default animations. string: `{robot_model}_animations.yaml`
❌	✅	`battery_config_path`	Path to the Gazebo `LinearBatteryPlugin` configuration file. This configuration is intended for use in simulations only. string: `None`
✅	✅	`components_config_path`	Additional components configuration file. Components described in this file are dynamically included in robot's URDF. Available options are described in the manual. string: `components.yaml`
✅	✅	`controller_config_path`	Path to controller configuration file. A path to custom configuration can be specified here. string: `{wheel_type}_controller.yaml`
✅	✅	`disable_manager`	Enable or disable manager_bt_node. bool: `False`
✅	✅	`fuse_gps`	Include GPS for data fusion. bool: `False`
❌	✅	`gz_bridge_config_path`	Path to the parameter_bridge configuration file. string: `gz_bridge.yaml`
❌	✅	`gz_gui`	Run simulation with specific GUI layout. string: `teleop.config`
❌	✅	`gz_headless_mode`	Run the simulation in headless mode. Useful when a GUI is not needed or to reduce the number of calculations. bool: `False`
❌	✅	`gz_log_level`	Adjust the level of console output. int: `1` (choices: `0`, `1`, `2`, `3`, `4`)
❌	✅	`gz_world`	Absolute path to SDF world file. string: `husarion_world.sdf`
✅	✅	`launch_nmea_gps`	Whether to launch the NMEA NavSat driver node. Advisable when the robot is equipped with the ANT02. bool: `False`
✅	✅	`lights_bt_project_path`	Path to BehaviorTree project file, responsible for lights management. string: `LightsBT.btproj`
✅	✅	`localization_config_path`	Specify the path to the localization configuration file. string: `relative_localization.yaml`
✅	✅	`localization_mode`	Specifies the localization mode: - 'relative' `odometry/filtered` data is relative to the initial position and orientation. - 'enu' `odometry/filtered` data is relative to initial position and ENU (East North Up) orientation. string: `relative` (choices: `relative`, `enu`)
✅	✅	`log_level`	Sets verbosity of launched nodes. string: `INFO`
✅	✅	`namespace`	Add namespace to all launched nodes. string: `env(ROBOT_NAMESPACE)`
✅	✅	`publish_robot_state`	Whether to publish the default URDF of specified robot. bool: `True`
❌	✅	`robot_model`	Specify robot model type. string: `env(ROBOT_MODEL_NAME)` (choices: `lynx`, `panther`)
✅	✅	`safety_bt_project_path`	Path to BehaviorTree project file, responsible for safety and shutdown management. string: `SafetyBT.btproj`
✅	✅	`shutdown_hosts_config_path`	Path to file with list of hosts to request shutdown. string: `shutdown_hosts.yaml`
✅	✅	`use_ekf`	Enable or disable EKF. bool: `True`
❌	✅	`use_joint_state_publisher`	Flag enabling joint_state_publisher to publish information about the wheel position. Should be false when there is a controller that sends this information. bool: `False`
❌	✅	`use_joint_state_publisher_gui`	Flag enabling joint_state_publisher_gui to publish information about the wheel position. Should be false when there is a controller that sends this information. bool: `False`
❌	✅	`use_rviz`	Run RViz simultaneously. bool: `True`
✅	✅	`use_sim`	Whether simulation is used. bool: `False`
✅	✅	`user_led_animations_path`	Path to a YAML file with a description of the user-defined animations. string: `''`
✅	✅	`wheel_config_path`	Path to wheel configuration file. string: `{wheel_type}.yaml`
✅	✅	`wheel_type`	Specify the wheel type. If the selected wheel type is not 'custom', the wheel_config_path and controller_config_path arguments will be automatically adjusted and can be omitted. string: `WH01` (for Panther), `WH05` (for Lynx) (choices: `WH01`, `WH02`, `WH04`, `WH05`, `custom`)
❌	✅	`x`	Initial robot position in the global 'x' axis. float: `0.0`
❌	✅	`y`	Initial robot position in the global 'y' axis. float: `-2.0`
❌	✅	`z`	Initial robot position in the global 'z' axis. float: `0.2`
❌	✅	`roll`	Initial robot 'roll' orientation. float: `0.0`
❌	✅	`pitch`	Initial robot 'pitch' orientation. float: `0.0`
❌	✅	`yaw`	Initial robot 'yaw' orientation. float: `0.0`

Tip

To read the arguments for individual packages, add the -s flag to the ros2 launch command (e.g. ros2 launch husarion_ugv_bringup bringup.launch.py -s)

Developer Info

Setup pre-commit

This project uses pre-commit to maintain high quality of the source code. Install precommit after downloading the repository to apply the changes.

pre-commit install

Unit testing

Running on laptop

colcon build --symlink-install --packages-up-to husarion_ugv --cmake-args -DCMAKE_BUILD_TYPE=Release -DTEST_INTEGRATION=OFF
colcon test --packages-up-to husarion_ugv

Running on the Built-In Computer

colcon build --symlink-install --packages-up-to husarion_ugv --cmake-args -DCMAKE_BUILD_TYPE=Release -DTEST_INTEGRATION=ON
colcon test --packages-up-to husarion_ugv

benmccann/husarion_ugv_ros

README