Ros2serial: rosserial-style communication for microcontrollers on ROS 2 (first public alpha)

Hi everyone,

ros2serial puts an Arduino on ROS 2 over USB serial: topics, services and actions, from a few lines in a sketch, on boards as small as an Uno.

It’s meant for the job rosserial did in ROS 1, for projects where micro-ROS is more than you need. Inspired by rosserial and OSRF’s early ros2_serial_example.

What it does

Your driver code stays on the board, and a regular ROS 2 node on the host, r2s_bridge, presents the board to the rest of the graph like any other node.


Figure 1. The board runs your sketch and a small C core. The host runs one ROS 2 node per serial port.

A sketch reads like this:

#include <ros2serial.h>
#include <std_msgs/msg/bool.hpp>

r2s::Node node("panel");
r2s::Publisher<std_msgs::msg::Bool> button_pub(node, "button");

void on_led(const std_msgs::msg::Bool &msg) {
  digitalWrite(LED_BUILTIN, msg.data ? HIGH : LOW);
}
r2s::Subscription<std_msgs::msg::Bool> led_sub(node, "led", on_led);

void setup() {
  pinMode(2, INPUT_PULLUP);
  pinMode(LED_BUILTIN, OUTPUT);
  node.begin(Serial, 115200);
}

void loop() {
  node.spin_some();
  static unsigned long last = 0;
  if (node.connected() && millis() - last >= 100) {
    std_msgs::msg::Bool msg;
    msg.data = (digitalRead(2) == LOW);
    button_pub.publish(msg);
    last = millis();
  }
}

On an Uno, the full version of this example (examples/arduino_button_led, which also debounces) takes 11.8 KB of flash and 1.2 KB of RAM.

What is there today:

  • Publishers and subscriptions for standard message types and your own .msg definitions.
  • Services in both directions, actions served by the board (the bridge presents them as regular ROS 2 action servers), and parameters declared by the firmware that show up on the bridge node, so ros2 param set works.
  • Optional logging to /rosout and a host-synced clock on the board.
  • Each of those channels is a build option, so a sketch that only needs topics only pays for topics.
  • A rosserial-compatible API (ros::NodeHandle, advertise, spinOnce, the tf broadcaster), so an existing rosserial sketch mostly ports by changing its includes.
  • An X-macro topic list that keeps the topic table in flash, for when RAM is tight, and a plain C API for bare metal, CMake and PlatformIO projects.

How it works

Framing. Each frame is a topic id, a sequence number, the payload and a CRC-16, encoded with a reversed variant of COBS and terminated by a 0x00 byte. Plain COBS writes each code byte before its block, so the encoder has to look up to 254 bytes ahead, which on a small board means a transmit buffer. Reversed COBS writes the code byte after the block, so the board serializes, computes the CRC and encodes in a single pass straight to the UART. Overhead and resynchronization are the same as COBS. I benchmarked it on an Uno against COBS, SLIP and a length-prefixed framing: same wire size as COBS, CPU within about 10 percent of the others, and for a 128-byte frame the CPU cost (about 2.6 ms) is well under the time the bytes take on the wire at 115200 baud (about 11 ms).


Figure 2. One frame on the wire. A corrupted or lost frame is dropped and counted, and the next 0x00 resynchronizes the link.

Encoding. Messages travel packed, little-endian, with no padding and no header, and the bridge converts them to CDR using ROS type introspection. That saves real bytes on a serial link: a sensor_msgs/Imu is 161 bytes on the wire against 324 in CDR, and a small JointState is 48 against 108. It also means the bridge handles any message type installed on the host without being compiled against it. On AVR, where double is 32 bits, float64 fields travel as 32-bit floats and the bridge widens them.

Type safety. During the handshake the board announces each topic’s type name and the first 8 bytes of its REP-2011 type hash. The bridge checks them against the installed definitions and refuses a mismatched topic with a clear error, and the rest of the board keeps working.

Bounds. The board has no heap, so every string and sequence needs a fixed capacity. It comes from the .msg itself (string<=24) or from an override for definitions you cannot edit. Nothing is picked silently: an unbounded field fails generation and names the field, and r2s-gen limits prints the capacities the bundled types use.

Link resilience. Heartbeats run in both directions and the host assigns a session token, so a board reset is detected within one heartbeat (500 ms by default) without the board needing a random source or EEPROM. The bridge waits out the Uno’s reset-on-open and bootloader before it talks. Topics are best effort, while the handshake, parameters, services and actions use a small stop-and-wait reliable channel. The bridge rate-limits traffic toward the board, keeps only the latest message for topics like cmd_vel, and publishes link counters on /diagnostics. A publish on the board never blocks: if there is no room it returns an error and writes nothing.

The core. The board side is C99 with no malloc, no recursion, no function pointers and no floating-point arithmetic, which keeps it small and predictable on 8-bit parts and makes its worst-case stack something CI can compute.

How it is tested

The protocol has a written spec with an ID on every rule, and CI fails if a rule has no test. Shared byte-level vectors run against the C core, a Python reference and the bridge. The parsers are fuzzed with libFuzzer, the session is checked against a model with randomized event sequences, and fault injection corrupts and drops bytes between the two ends. End-to-end scenarios run the real firmware on a simulated Uno and Mega against the bridge on Fast DDS, Cyclone DDS and Zenoh, on Jazzy, Lyrical and Rolling. Flash, RAM and stack are budgeted per example and checked on every pull request, and mutation testing runs nightly.

Trying it

From a ROS 2 workspace with an Arduino on USB:

cd ~/ros2_ws/src && git clone https://github.com/apojomovsky/ros2serial.git
cd ~/ros2_ws && rosdep install --from-paths src --ignore-src -r -y
colcon build --packages-up-to r2s_bridge r2s_gen && source install/setup.bash

ros2 run r2s_gen r2s-arduino library --out firmware/ros2serial
ros2 run r2s_gen r2s-arduino compile --library firmware/ros2serial \
  --fqbn arduino:avr:mega --out firmware/build firmware/ros2serial/examples/button_led
arduino-cli upload --port /dev/ttyACM0 --fqbn arduino:avr:mega \
  --input-dir firmware/build firmware/ros2serial/examples/button_led

ros2 launch r2s_bridge r2s_bridge.launch.py port:=/dev/ttyACM0
ros2 topic echo /button std_msgs/msg/Bool

The README walks through the same steps for an Uno. If you prefer the Arduino IDE, the release has a ZIP you can add with Sketch > Include Library > Add .ZIP Library.

Where it stands

This is the first public alpha (v0.5.0), so a few things to know:

  • The wire protocol is not frozen yet. Use firmware and host packages from the same release.
  • I have validated it on a real Arduino Mega with an end-to-end board check: handshake, a steady 10 Hz topic with no gaps, zero link errors, and a subscription driving the LED. The same firmware runs on a simulated Uno in CI.
  • ESP32 support is in the works: it already builds in CI, and validating it on a real board is next. STM32, RP2040 and CH32V003 builds compile in CI too, which proves they build, not yet that they run on hardware.
  • Ports for more boards are planned, and there is a porting guide with a template: a port is four C functions and a host test.
  • Install is from source for now. Binary packages and the Arduino Library Manager are next.

Feedback and contributions

I would really like to hear what you would hook up first, which message types are awkward to fit on a small board, and anything that confused you in the first ten minutes. Trying it on a board I don’t have is one of the most useful things anyone can do right now, and issues, docs fixes, examples and ports are all welcome.

Repository and docs: GitHub - apojomovsky/ros2serial · GitHub

Thanks for reading!

4 Likes