Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |
Launch files
Messages
Services
Plugins
Recent questions tagged wirestead at Robotics Stack Exchange
Package Summary
| Version | 0.10.2 |
| License | Apache-2.0 |
| Build type | CMAKE |
| Use | RECOMMENDED |
Repository Summary
| Checkout URI | https://github.com/wirestead/wirestead.git |
| VCS Type | git |
| VCS Version | main |
| Last Updated | 2026-11-21 |
| Dev Status | DEVELOPED |
| Released | RELEASED |
| Contributing |
Help Wanted (-)
Good First Issues (-) Pull Requests to Review (-) |
Package Description
Additional Links
Maintainers
- Jinwoo Sung
Authors
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 usingwiresteadover 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.
| Transports | Async | Platforms | Install | |
|---|---|---|---|---|
| Wirestead | Serial, TCP, UDP, UDS | yes, one io_context model across all four |
Linux, macOS, Windows — x64 and arm64 | vcpkg, FetchContent, PyPI |
| transport_drivers | Serial, UDP | yes (standalone Asio) | Linux (ROS 2) | rosdep / apt |
| libserial | Serial | no | Linux only | apt install libserial-dev |
| serialib | Serial | no | Linux, Windows | copy two files |
| Boost.Asio directly | everything | yes | everywhere | you already have it |
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-devand 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_driversshipsserial_bridgeandudp_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_rosprovides a lifecycle shutdown gate,RuntimeStatsreporting ontodiagnostic_updater, and a reference lifecycle driver, but no drop-in bridge node. If a bridge is all you need,transport_driversis 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.10.2)
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.
v0.10.2 - 2026-11-21
Fixed
- An idle timeout no longer closes a connection right after data that arrived
before the deadline. Re-arming the timer could not abort an expiry asio had
already queued, so a long user callback or a read completing in the same
reactor pass as the expiry triggered an idle close with no idle gap. Affects
TcpServerSession,UdsServerSession,TcpClientandSerial, only when an idle timeout is enabled (#726). -
LineFramerdelivers a line of exactlymax_lengthwhen its multi-byte delimiter is split across reads. It was discarded depending only on where the transport segmented the bytes (#727). - Calling
reset()fromon_message()no longer reads freed or out-of-range memory inLineFramerandLengthPrefixFramer; processing stops after the reset, asPacketFrameralready did. The wrapper receive path is unaffected, since it runs user callbacks after framing finishes (#728).
Performance
- The receive staging buffer grows geometrically, capped at
max_frame_bytes, instead of to the exact size on each 4 KiB step. Staging a 1 MiB frame drops from 139 MiB of allocation to 27 MiB. A receive budget too tight for the headroom falls back to exact growth, so it accepts the same input as before (#725).
v0.10.1 - 2026-10-29
Added
- Opt-in Linux serial
keep_dtr_on_close()retains DTR across close and reopen by clearing HUPCL. The default close policy stays unchanged. The option cannot prevent resets on first open or physical disconnect; it conflicts withdtr(false)and fails the connection if retention is unavailable (#710).
Fixed
-
TcpClient::get_executor()returns the client’s strand instead of copying the socket’s executor, whichstart()replaces on the strand. A concurrent call could copy an executor while it was freed; on Windows ARM64 this corrupted the heap and failed later with0xc0000374(#717). - Destroying a running wrapper now completes its shutdown on the destroying thread. A callback in flight could otherwise hold the last reference, so the transport was torn down on its own io thread, detached it and destroyed the io_context it was still running - an intermittent segfault at process exit (#613).
- Move-assigning over a running wrapper completes the previous object’s shutdown on the assigning thread, as destruction does.
- Correct the serial DTR documentation:
dtr(false)does not stop an Arduino from rebooting when the port opens, since Linux asserts DTR before the setting applies, and every reopen reboots it again.docs/tuning.mdnow also says to setrx_idle_timeoutabove such a board’s reboot time (#710).
v0.10.0 - 2026-10-02
For publication, downstream package availability and remaining distribution checks, see the dated release status.
Changed
- Amortize Serial and TCP/UDS server-session send-accounting locks over each gather batch, preserving request boundaries, reset epochs and stop/loss causes.
-
Clarify that callback/executor stop is request-only; outside concurrent stop callers wait for completion before destruction, restart or stopped-only settings.
-
Reduce TCP/UDS client send-accounting lock acquisitions to once per gather batch at handoff and completion, preserving partial-prefix, reset-epoch and stop/loss accounting.
-
Restore send throughput lost since v0.9.6 without changing send or accounting policies. No transport holds its admission lock across a write system call, and TCP/UDS client write handoff and successful completion no longer take it at all: the send-accounting ledger fences handoff against stop and connection loss. The ledger’s per-request bookkeeping is O(1) and briefly spins instead of sleeping under contention. Unpressured wrapper sends avoid redundant capacity-wait preparation and channel reference-count updates.
-
Index send-accounting entries by request identity in a reusable ring instead of a hashed node map. Steady traffic no longer allocates or hashes per request; accounting semantics are unchanged. Sparse retention bounds metadata when rollback or UDP expiry retires later requests behind an older pending write.
-
Cache TCP client write-submission executor properties instead of adapting the strand on every send. Enqueue handlers remain asynchronous, serialized on the same strand and owning the transport.
-
Defer TCP/UDS client blocking-send executor checks and owning connection references to the capacity-wait path. Rejection reasons and the connection pinned at entry are unchanged.
- Breaking behavior: invalid configuration is rejected before application; native construction no longer silently clamps it. Settings outside the explicit
File truncated at 100 lines see the full file
Package Dependencies
System Dependencies
Dependant Packages
| Name | Deps |
|---|---|
| wirestead_ros |