rosbot-firmware

STM32F4 firmware for ROSbot 3 and ROSbot XL. Ships in two flavours — classic micro-ROS and the newer MAVLink + bridge — that expose the same ROS 2 API to downstream consumers.

Two firmware flavours

Pick the MAVLink flavour to drop the micro_ros_agent dependency on the SBC and run the firmware against any ROS 2 distro (jazzy, humble, future). Pick the micro-ROS flavour to stay on the known-good path. Switching is just a re-flash + restart of the SBC-side process.

Build and flash

Day-to-day workflow on the ROSbot SBC uses just:

just install-deps           # one-time: pymavlink + platformio in a venv
just build rosbot_xl        # micro-ROS variant
just build rosbot_xl_mavlink  # MAVLink variant
just flash rosbot_xl_mavlink  # builds and flashes via FTDI
just mavgen                  # regen MAVLink dialect headers
just --list                  # see every recipe

just flash wraps ros2 run rosbot_utils flash_firmware; see CONTRIBUTING.md and scripts/flash.sh for the details and PlatformIO env names.

Run the SBC side

micro-ROS: start the agent against the firmware’s transport.

# rosbot_xl (Ethernet)
ros2 run micro_ros_agent micro_ros_agent udp4 --port 8888

# rosbot (Serial)
ros2 run micro_ros_agent micro_ros_agent serial --dev <serial_port> --baud 921600

MAVLink: launch the bridge from this repo (or the released tarball).

# rosbot_xl (Ethernet, mavros default ports)
ros2 launch rosbot_mavlink_bridge rosbot_xl.launch.py namespace:=rosbot

# rosbot (Serial)
ros2 launch rosbot_mavlink_bridge rosbot.launch.py namespace:=rosbot \
  --ros-args -p serial_port:=/dev/ttyS4

Either path advertises the same /<ns>/rosbot_mcu node with the same topic list, types and QoS — rosbot_ros (snap) consumes it unchanged.

Internals

• ARCHITECTURE.md — firmware architecture, RTOS task layout, transport patterns, MAVLink stack overview.
• ROS_API.md — user-facing ROS topic / service contract (true for both flavours).
• MAVLINK_MIGRATION.md — implementation spec for the MAVLink stack, dialect IDs, phasing.

Developer info and tools

The software uses RTOS tasks to manage individual board peripherals.

Command-line workflow with just

just is a project-scoped command runner. The repo ships a justfile with the most common build / flash recipes. Run just (no args) for a recipe list.

Most-used recipes:

just build rosbot                # Build one PlatformIO env
just build-microros              # Build all four micro-ROS envs
just build-mavlink               # Build all four MAVLink envs (jazzy-mavlink branch)
just flash rosbot_xl             # Build + flash on the connected robot
just flash rosbot_xl_mavlink     # Same, for the MAVLink build
just clean                       # Wipe PlatformIO build outputs
just lint                        # Run pre-commit hooks against the tree

Flashing delegates to ros2 run rosbot_utils flash_firmware (the same entry point used by rosbot-snap’s flash_launcher.sh), via the wrapper in scripts/flash.sh. The wrapper:

• maps the PlatformIO env name to the --robot-model argument (rosbot_xl* → rosbot_xl, otherwise rosbot),
• auto-selects USB/FTDI flashing for ROSbot XL (or when SERIAL_TYPE_USB=True),
• auto-detects the FTDI tty by USB VID:PID 0403:6015 (override with SERIAL_PORT=/dev/ttyUSBx),
• points flash_firmware at the freshly built .pio/build/<env>/firmware.bin instead of the binary bundled in rosbot_utils.

Prerequisites on the ROSbot SBC:

• platformio on PATH (pip3 install -U platformio).
• A sourced ROS 2 environment with rosbot_utils available (i.e. the rosbot_ros overlay built and sourced, or run from inside the snap).
• For USB flashing: udev rules from ros2 run rosbot_utils install_udev_rules (snap installs these on post-refresh).

VS Code Tasks

To simplify the development process, we have prepared a set of VS Code tasks that can be used to build and flash the firmware.

To use these tasks, open the Command Palette (Ctrl+Shift+P) and search for “Run Task”. You will see a list of available tasks, including:

• ROSbot: Build firmware
• ROSbot (Debug): Build and deploy firmware
• ROSbot (Release): Build and deploy firmware
• ROSbot XL: Build firmware
• ROSbot XL (Debug): Build and deploy firmware
• ROSbot XL (Release): Build and deploy firmware
• Build Releases

Dev mode

To enable the development mode, which allows you to connect via USB FTDI port, press the user button while powering the MCU. The green LEDs will light up.