rosbot-firmware

STM32F4 firmware for ROSbot 3 and ROSbot XL. The MCU talks MAVLink v2 (rosbot dialect) to the SBC, where rosbot_mavlink_bridge turns it into the ROS 2 API described in ROS_API.md. One .bin per robot serves every ROS 2 distro the bridge is built for.

micro-ROS support was removed after v2.1.0-jazzy. Up to that release the firmware could also run a micro-ROS (XRCE-DDS) stack against micro_ros_agent, chosen at boot by the BACKEND: handshake line. It is still in git history; the firmware now answers BACKEND:microros with NAK.

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      # one env; envs: rosbot[_xl], rosbot[_xl]_release
just build-all            # all four envs
just flash rosbot_xl      # builds and flashes via rosbot_utils
just mavgen               # regen MAVLink dialect headers
just --list               # every recipe

just flash wraps ros2 run rosbot_utils flash_firmware; see CONTRIBUTING.md and scripts/flash.sh.

Run the SBC side

# 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

The bridge advertises the /<ns>/rosbot_mcu node that rosbot_ros (snap) consumes.

Internals

• ARCHITECTURE.md — firmware architecture, RTOS task layout, transport patterns, MAVLink stack.
• ROS_API.md — ROS topic / service contract.

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-all                   # Build all four envs
just flash rosbot_xl             # Build + flash on the connected robot
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.