Wirestead ROS

ROS 2 integration for the Wirestead asynchronous C++ communication library.

The repository is intentionally split from the ROS-independent Wirestead core. Real device drivers link Wirestead directly through the wirestead_ros package and publish semantic ROS messages. Raw byte bridge packages will remain optional so production drivers do not pay for an unnecessary DDS hop.

Packages

Wirestead core is expected to be released separately as the ROS package wirestead, producing the Debian package ros-<distro>-wirestead.

What wirestead_ros provides today

• CallbackGate - admits and drains transport callbacks so none outlives the ROS objects it publishes through.
• report_channel_stats() - maps a channel’s RuntimeStats onto diagnostic_updater, including a STALE level for a link that is connected but has stopped receiving.
• serial_line_driver - the reference driver for third-party authors: a lifecycle node that parses on the callback-scoped view, stamps from the payload’s arrival time, orders shutdown through CallbackGate, and publishes a semantic sensor_msgs/Temperature rather than raw bytes. Its lifecycle and I/O are covered by a pseudo-terminal test.

Source workspace

Until the core package is available from the ROS package repository, install Wirestead core with plain CMake and then build the ROS package. The manifest resolves the released core tag, so a source workspace builds what the ROS release describes; CI separately tracks core main, which is what catches integration regressions before the next tagged release.

mkdir -p ~/wirestead_ws/src
cd ~/wirestead_ws
git clone https://github.com/wirestead/wirestead-ros.git src/wirestead-ros
vcs import src < src/wirestead-ros/wirestead_ros.repos

cmake -S src/wirestead -B build/wirestead-core \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="$PWD/install/wirestead-core" \
  -DWIRESTEAD_BUILD_STATIC=OFF \
  -DWIRESTEAD_BUILD_TESTS=OFF
cmake --build build/wirestead-core -j2
cmake --install build/wirestead-core

source /opt/ros/jazzy/setup.bash
export CMAKE_PREFIX_PATH="$PWD/install/wirestead-core:$CMAKE_PREFIX_PATH"
rosdep install --from-paths src/wirestead-ros/wirestead_ros \
  --ignore-src --rosdistro jazzy --skip-keys wirestead -r -y
colcon build --base-paths src/wirestead-ros/wirestead_ros --symlink-install

The --skip-keys wirestead exception is temporary. Remove it when Wirestead is available through rosdistro. Release manifests must replace main with an immutable core tag before a public release.

The completed implementation, validation results, and remaining registration work are tracked in Implementation Status.

Supported ROS distributions

• ROS 2 Jazzy on Ubuntu 24.04 is the primary target and the required CI row.
• ROS 2 Humble on Ubuntu 22.04 is a required CI row as well. Wirestead lowered its Boost minimum to 1.74, which is what Ubuntu 22.04 supplies, so the dependency that used to rule Humble out is gone. Humble’s uncrustify wants different line wrapping than Jazzy’s, so that one linter is excluded on that row; every other test runs.
• ROS 2 Lyrical support requires a separate Ubuntu 26.04 CI result before release.

License

Apache License 2.0. See LICENSE.

Contributing

Build

Source ROS and make an installed Wirestead package available through the same workspace or CMAKE_PREFIX_PATH, then run:

colcon build --symlink-install --event-handlers console_direct+
colcon test
colcon test-result --verbose

Scope

• Keep the Wirestead core ROS-independent.
• Prefer standard ROS messages in real device drivers.
• Keep raw byte bridge interfaces optional.
• Do not add unbounded queues or blocking sends to executor callbacks.
• Preserve callback payload ownership before work leaves the Wirestead I/O callback.

Commits

Use Conventional Commits:

<type>[optional scope]: <description>