Wirestead™

Robust, simple async communication for modern C++20.

Serial · TCP · UDP · UDS — one API for all four, on Linux, macOS and Windows, x64 and arm64.

Description

wirestead provides a unified interface for asynchronous communication across different transports, allowing applications to switch between Serial, TCP, UDP, and UDS with minimal code changes. The public C++ API exposes builders and wrappers for all four transport families.

The project prioritizes API clarity, predictable runtime behavior, and stability over rapid feature expansion.

#include <iostream>
#include <wirestead/wirestead.hpp>

auto client = wirestead::tcp_client("127.0.0.1", 8080)
    .max_retries(3)
    .on_data([](const wirestead::MessageContext& ctx) {
        std::cout << "received " << ctx.data().size() << " bytes\n";
    })
    .build();

client->start_sync();
client->send("hello");

The same shape builds a serial port, a UDP socket or a UDS endpoint — see Quick Start.

Security note: transports send data in plaintext by default. TCP can do TLS in a build configured with -DWIRESTEAD_ENABLE_TLS=ON - server and client, with the client verifying the server; UDP, Serial and UDS cannot, and DTLS is not supported. See Security and Threat Model before using wirestead over an untrusted network.

How Wirestead compares

Wirestead is a multi-transport async library. Most alternatives are either a single-transport library or a set of ready-to-run ROS nodes, so the useful question is usually which shape you need rather than which has more features.

Wirestead fits best when one application speaks over more than one transport — a serial sensor, a TCP command server, a UDP telemetry feed — and you would otherwise write reconnect, buffering and framing three times against three different APIs. The four transports share one API, so switching between them is a builder change rather than a rewrite. It runs on Linux, macOS and Windows alike, which the serial-only libraries above do not, and latency is published per release on real hardware: see the benchmark releases. The Feature Highlights below cover what it adds on top of Asio.

When to use something else

• You only need serial, on Linux. apt install libserial-dev and you are done. Wirestead pulls in Boost and asks you to build it; that is a poor trade for one serial port.
• You want the smallest possible dependency. serialib is two files with no dependencies at all.
• You are on ROS 2 and want a bridge, not a library. transport_drivers ships serial_bridge and udp_bridge_node_exe — running executables that move bytes between a device and a topic. Wirestead gives you a library to write your own node against; wirestead_ros provides a lifecycle shutdown gate, RuntimeStats reporting onto diagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need, transport_drivers is less work.
• You know Asio well and want direct control. Any wrapper is in your way. Wirestead is a wrapper.

Feature Highlights

• Unified transport surface: Consistent builders and wrappers for TCP client/server, UDP, Serial, and UDS.
• Callback-scoped data views: Avoid unnecessary copies during callbacks, with explicit ownership-copy helpers for stored data. Each payload carries the time it arrived, so a timestamp does not have to be taken after the fact.
• Message framing: Line-delimited, start/end pattern, and length-prefixed framers, or your own IFramer.
• Optional TLS: TCP client and server in a build configured with -DWIRESTEAD_ENABLE_TLS=ON, with the client verifying the server.
• Fluent API with CRTP Builders: Type-safe configuration with improved method chaining.
• Built for devices: Serial low-latency mode and RS-485, UDP multicast, a per-channel silence age for spotting a sensor that stopped talking, and a hook for putting the io threads on a real-time policy. See Tuning.
• Tested runtime behavior: Unit, integration, and end-to-end test suites are part of the repository and documented in test/.

Requirements

• C++20 compiler: GCC 10+, Clang 14+, or MSVC 2022. CMake enforces these and fails the configure step below them. CI builds GCC on Ubuntu 22.04 and 24.04, Clang on Ubuntu 24.04 and macOS, and MSVC on Windows, each on x64 and arm64.
• CMake 3.12 or later for plain builds; CMake 3.21 or later for the repository presets
• Boost 1.74.0 or later, which covers the system packages on Ubuntu 22.04 (1.74), RHEL 9 (1.75) and Ubuntu 24.04 (1.83). vcpkg remains the recommended dependency supplier; CI builds against the 1.74 floor as well as current Boost.

📦 Installation

vcpkg (recommended)

vcpkg install wirestead

CMake FetchContent

include(FetchContent)
FetchContent_Declare(wirestead
    GIT_REPOSITORY https://github.com/wirestead/wirestead.git
    GIT_TAG v0.9.6)
FetchContent_MakeAvailable(wirestead)
target_link_libraries(your_target PRIVATE wirestead::wirestead)

Python

pip install wirestead

File truncated at 100 lines see the full file

Changelog

All notable changes to Wirestead are documented in this file.

This project follows the Keep a Changelog section names where practical. The core C++ API is still pre-1.0; see docs/api_stability.md for compatibility and ABI policy.

Unreleased

Fixed

• The CPack Debian package named the wrong Boost package.

  It required only libboost-system-dev. The package ships the headers as well as the shared library, and those headers reach boost/asio, so it also needs libboost-dev. libboost-system-dev stays, because wiresteadConfig.cmake calls find_dependency(Boost COMPONENTS system) and that needs the component’s CMake files. These are the same two keys package.xml has declared since v0.9.6; the CPack side was missed then because only the ROS packaging was in view.

  A CPack package has never been published, so nothing installed is affected.

Removed

• AsyncLogConfig::batch_size and AsyncLogConfig::enable_batch_processing, and the three-argument AsyncLogConfig constructor that took a batch size.

  Neither field was ever read. Setting batch_size did nothing and said nothing, which is worse than not offering it, and the field sat in the middle of a public constructor’s parameter list where a caller had to pass something for it. enable_batch_processing was referenced nowhere at all. spdlog manages its own batching behind the async logger, so there was never anything for either to control.

  The constructor had no callers anywhere in the repository. Anyone who used it can construct the struct and assign the two fields that remain.

• The CPack RPM generator.

  packaging/wirestead.spec is the supported RPM path as of that file landing. It splits runtime from -devel the way an RPM distribution expects, and it is built by the distribution’s own toolchain. A CPack RPM is a single combined package built by whatever host runs cpack, so one produced on Ubuntu carries Ubuntu’s glibc dependencies and will not install on an RPM distribution.

  Nothing ran it: release.yml passes TGZ on every Linux row, so the RPM settings had never executed, which is how they came to require boost-system

  • a package with no headers - without anyone noticing. Two RPM paths that disagree is the condition that let that survive.

Changed

• The minimum supported spdlog version is now 1.8, down from 1.9.

  1.9 was never an API floor. It is where spdlog::sinks::callback_sink arrived, which is the likely origin of the number, but this library derives its own callback sink from spdlog::sinks::base_sink and has done since that code was written. Every other spdlog name it uses predates 1.1.

  Nothing under wirestead/ compiles conditionally on SPDLOG_VERSION, so an older spdlog cannot quietly remove a feature and leave a passing build behind. .github/workflows/spdlog-floor.yml builds and runs the unit suite against 1.8.2 on Ubuntu 22.04 amd64 and arm64 and on CentOS Stream 9, and is the thing that keeps the floor true from here.

  Lowering a floor cannot break an existing consumer - anyone who satisfied 1.9 satisfies 1.8. What it opens is platforms whose vendored spdlog sits below 1.9, which includes RPM-based embedded targets.

v0.9.6 - 2026-08-30

Added

• backpressure_threshold() and backpressure_strategy() on Serial, TcpClient, TcpServer, UdpClient, UdpServer, UdsClient, and UdsServer.

  server.backpressure_threshold(8192);
  const size_t configured = server.backpressure_threshold();  // 8192
  

Both settings were write-only. The setters have been there all along, but nothing read them back, so a caller could not log the configuration it was running under, round-trip it, or assert on it from a test without tracking the value separately alongside the transport.

v0.9.4 added RuntimeStats because backpressure could be configured with no way to observe what it produced. That covered the runtime half; the setting itself stayed unreadable. This covers the other half.

The Python bindings raised AttributeError: backpressure_threshold is write-only on read for the same reason, and can now expose real properties.

Fixed

• set_io_thread_init() is reachable from the umbrella header.

File truncated at 100 lines see the full file