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

Contributing to Wirestead

Thanks for your interest in contributing. This guide covers the human contributor workflow: environment setup, local verification, commit/PR conventions, and review expectations.

AI coding agents working in this repository should follow CLAUDE.md (or AGENTS.md / GEMINI.md) instead - those files define the agent-specific rules and final-report format.

Getting started

./scripts/setup_dev_env.sh
cmake --preset dev-linux-x64
cmake --build --preset dev-linux-x64

setup_dev_env.sh bootstraps a repository-local vcpkg/ checkout and installs Boost/spdlog through it. Delete vcpkg/ any time to reclaim space; rerun the script to recreate it. Set VCPKG_ROOT first if you want to reuse an existing vcpkg installation.

dev-linux-x64 is the recommended starting preset. See CMakePresets.json for the full list of platform-specific presets (dev-linux-arm64, dev-macos-arm64, dev-macos-x64, dev-windows-x64, release-linux-x64). Presets require CMake 3.21+; a plain (non-preset) build only needs CMake 3.12+.

Running tests

See test/README.md for the full test layout (unit/integration/e2e) and the CTest label taxonomy for running subsets. The short version:

cmake -S . -B build -DWIRESTEAD_BUILD_TESTS=ON
cmake --build build -j2
ctest --test-dir build --output-on-failure

Prefer -j2 for build parallelism by default; drop to -j1 on memory-constrained environments (WSL, VMs, small CI runners).

Verifying before you push

./scripts/verify.sh runs the same formatting, build, and test steps as CI. Run it locally before opening a PR:

./scripts/verify.sh              # full check: format + build + tests
./scripts/verify.sh --tests-only # skip formatting, build + test only
./scripts/verify.sh --skip-format
./scripts/verify.sh --tsan       # enable ThreadSanitizer, matches the tsan CI job

Formatting is enforced by .clang-format and .cmake-format.py. Use scripts/apply_clang_format.sh and scripts/apply_cmake_format.sh to fix formatting automatically before committing.

Commit messages

Use Conventional Commits:

<type>[optional scope]: <description>

Common types: feat, fix, docs, test, refactor, style, perf, build, ci, chore. Use ! after the type/scope or a BREAKING CHANGE: footer for compatibility-breaking changes. Keep the subject concise, lowercase, imperative mood, no trailing period.

Opening a pull request

• Keep changes scoped to a single concern; avoid bundling unrelated refactors with a feature or fix.
• Fill out .github/pull_request_template.md (auto-populated when you open a PR): description, key changes, related issues, and the checklist (verify.sh run, tests updated, docs updated, style followed).
• Do not rename public APIs, files, or user-facing concepts unless the PR is explicitly about that change - see docs/api_stability.md for what is and isn’t covered by the compatibility guarantee.
• Add or update tests for behavior changes. If you intentionally didn’t, say why in the PR description.
• CI runs the full compile matrix (Linux/macOS/Windows/ARM), unit/ integration/e2e suites, memory-safety jobs (ASan/UBSan/LSan), CodeQL, and a code-quality job that checks clang-format/cmake-format compliance. All of these must pass before merge.

Where things live

• In-repo docs (docs/) cover repository-local topics: quickstart, error model, callback lifetime, API stability, security model. Full tutorials and runnable examples still live in legacy locations until those repositories are moved: wirestead-docs and wirestead-examples.
• Bug reports and feature requests: open a GitHub issue in this repository.
• Security issues: see docs/security.md before filing a public issue.