ROSbot ROS

ROS 2 packages for Husarion ROSbot Series.

📚 ROS API

Documentation is available in ROS_API.md.

🚀 Quick Start

⚙️ Prerequisites

1. Install all necessary tools:

   sudo apt-get update
   sudo apt-get install -y python3-pip ros-dev-tools

2. Create a workspace folder and clone the rosbot_ros repository:

   mkdir rosbot_ws
   cd rosbot_ws
   git clone -b jazzy https://github.com/husarion/rosbot_ros.git src/rosbot_ros

Build

source /opt/ros/$ROS_DISTRO/setup.bash

vcs import src < src/rosbot_ros/rosbot/rosbot_hardware.repos
vcs import src < src/rosbot_ros/rosbot/rosbot_simulation.repos

# Optional: speed up build by removing unnecessary packages
# For hardware build only, remove simulation package:
# rm -rf src/rosbot_ros/rosbot_gazebo
# For simulation build only, remove hardware package:
# rm -rf src/rosbot_ros/rosbot_bringup

export PIP_BREAK_SYSTEM_PACKAGES=1
sudo rosdep init
rosdep update --rosdistro $ROS_DISTRO
rosdep install -i --from-path src --rosdistro $ROS_DISTRO -y

colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release

Run the Robot

For ROSbot XL, you can specify a particular configuration using the launch configuration argument. If you are using the manipulation configuration, please refer to MANIPULATOR.md for detailed instructions — including the gamepad controls for the OpenMANIPULATOR-X.

Real robot:

source install/setup.bash
ros2 launch rosbot_bringup <rosbot/rosbot_xl>.yaml

Note

The ROSbot ROS Driver is strongly dependent on the firmware version. If you change driver version or ROS distro, ensure the firmware is compatible. Firmware can be updated with the flash_firmware script.

source install/setup.bash
ros2 run rosbot_utils flash_firmware --robot-model <rosbot/rosbot_xl>

The MCU talks MAVLink to rosbot_mavlink_bridge. micro-ROS was supported up to firmware v2.1.0-jazzy; firmware v2.2.0-jazzy and this driver no longer ship it.

Simulation:

source install/setup.bash
ros2 launch rosbot_gazebo simulation.yaml robot_model:=<rosbot/rosbot_xl>

Tip

You can spawn multiple robots in the simulation. To do that, run the launch file multiple times with different namespaces and initial positions (x, y, z). For example:

source install/setup.bash
ros2 launch rosbot_gazebo spawn_robot.yaml robot_model:=<rosbot/rosbot_xl> namespace:=robot1 x:=0 y:=0

All topics/services/actions are namespaced under /<namespace>/ on HW and sim — see Namespace policy.

Launch Arguments

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

🤖	🖥️	Argument	Description Type: Default
✅	✅	arm_activate	Whether to activate the manipulator arm on startup. bool: False (True for simulation)
✅	❌	asset_server	Launch husarion_asset_server, serving this robot's package:// meshes/URDF resources to the bridge's get_asset service. bool: True
✅	❌	battery_alert	ROSbot XL only. Play the low-battery alert on the on-board speaker. The speaker PCB is wired behind a USB sound card on every SBC, so without one there is no audio output at all and the node logs a single warning; audio_device in rosbot_utils/config/rosbot_xl/config.yaml overrides the auto-detected ALSA device. bool: True
✅	✅	config_dir	Path to the common configuration directory. You can create such common configuration directory with ros2 run rosbot_utils create_config_dir {directory}. string: ""
✅	✅	configuration	Specify configuration packages. ROSbot XL has the full set; ROSbot 2/3 only basic/pro/custom (basic = OAK-D Lite + RPLIDAR C1 for ROSbot 3, pro = OAK-D Pro + RPLIDAR S2 for ROSbot 3 PRO). Packages: basic, pro, telepresence, autonomy, manipulation, manipulation_pro, custom. string: basic
✅	✅	controller_manager_timeout	Seconds the spawner waits for controller_manager to load + activate the controllers (raised from 20 for slower SBCs such as the Raspberry Pi 5 on ROSbot 3). int: 60
✅	✅	joy_vel	The topic name to which velocity commands will be published. Defaults to the highest-priority arbitration input, so the gamepad overrides autonomy. string: manual/cmd_vel
✅	❌	led_animation	ROSbot XL only. Animation published at startup. none publishes nothing, so the firmware idle animation shows. Switch live with ros2 param set /<ns>/animation_publisher current_animation <name> — the <name>.png and <name>.yaml are re-read from disk on every switch, so an animation added after startup needs no restart. string: ready (choices: ready, navigation, rainbow, turn_off, none)
✅	❌	led_strip	ROSbot XL only. Enable or disable the LED strip. Publishing can also be gated at runtime with the led_strip/enable service. bool: True
✅	✅	mecanum	Whether to use mecanum drive controller, otherwise use diff drive. bool: True for rosbot_xl, False otherwise
✅	✅	namespace	Add namespace to all launched nodes. string: env(ROBOT_NAMESPACE)
✅	✅	robot_model	Specify robot model. string: env(ROBOT_MODEL) (choices: rosbot, rosbot_xl)
✅	❌	hardware_bridge	Whether to launch the SBC↔MCU MAVLink bridge (rosbot_mavlink_bridge). Set to False to skip it entirely (e.g. when running the bridge in a separate container). bool: True
✅	❌	manipulator_serial_port	Port to connect to the manipulator. string: /dev/manipulator
✅	❌	serial_baudrate	ROSbot only. Baud rate for serial communication. string: 921600
✅	❌	serial_port	ROSbot only. Serial port the MAVLink bridge opens to the MCU. string: /dev/ttySERIAL
✅	✅	servo_enabled	ROSbot XL manipulation only. Whether to start servo_node + joy2servo (joystick teleop backend for the arm). servo_node is not a lifecycle node — its collision-checking loop runs continuously once started (~91% of one CPU core, measured on a Jetson Orin Nano) and cannot be paused. Defaults to arm_activate, but can be set independently to keep the arm active while skipping the joystick backend. bool: arm_activate
✅	✅	tf_namespace_bridge	Bridge robot's namespaced TF to the global /tf and /tf_static. Only active when namespace is set. bool: True
❌	✅	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
❌	✅	rviz	Run RViz simultaneously. bool: True
❌	✅	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.0
❌	✅	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 launch files, add the -s flag to the ros2 launch command (e.g. ros2 launch <pkg> <launch> ​​-s)

🕹️ Demo

Explore demos showcasing the capabilities of ROSbots:

📎 Link	📖 Description
rosbot-telepresence	Stream live video from Orbbec Astra to a PC and control the robot using teleop-twist-keyboard
rosbot-autonomy	Enables simultaneous mapping and navigation, allowing the robot to move in unknown environments.