WireForge turns a description of binary messages (YAML, edited by hand, in the web UI or by an AI agent) into C++17 or C99 code that serializes, validates, frames and dispatches them without heap, exceptions or RTTI, plus a GoogleTest project that checks the code against a reference codec. The wire format is the one you describe: the generator never adds bytes.
New to WireForge? The tutorial builds a MAVLink 2 drone link step by step: the web UI, the code in an application, the tests, CI, Wireshark and AI agents.
Python 3.10 to 3.13.
pip install "wireforge[server,mcp,import]" # or, in a checkout: pip install -e ".[server,mcp,import]"
pip install "wireforge[oidc]" # OIDC login for the server (docs/SERVER.md)A C++17 compiler, CMake 3.21+ and (for the tests) Ninja or Make are needed to build generated code. Docker:
docker build -t wireforge . && docker run -p 8000:8000 -v "$PWD/projects:/workspace" wireforge serves the web UI and
API on port 8000 with the toolchain inside; it has no token by default, so read
Deployment and operation before exposing it.
wireforge ci <project> --base <revision> --test validates the project, compares it with the base of a pull request
(wire compatibility and the version bump each changed interface needs) and builds and runs the generated tests, with one
Markdown summary. The repository has a GitHub action for it and a GitLab example (docs/integration/github_actions.md).
- Start from a template or a published protocol (or skip to step 1 with your own ICD):
The template is a working project with comments; change the names, fields and limits to match your protocol. The web UI has the same start under "New project"; its "Generate" tab shows the generated code and downloads it with the test project.
wireforge init demo --template telemetry # also: command, raw; --list shows them wireforge init gps --protocol ubx # a published protocol, see "Published protocols" wireforge validate demo && wireforge test demo -o build/demo
- Describe messages. Write a
project.yaml(docs/SCHEMA_SPEC.md,examples/), or import an ICD table, a C header, a CAN database (wireforge import-dbc) or a MAVLink XML dialect (wireforge import-mavlink, docs/IMPORT.md):wireforge import-icd examples/icd/telemetry_icd.csv demo --name telemetry --namespace demo::imu --endian little
- Add an interface (header, framing, the messages it carries):
wireforge upsert demo interfaces imu_link '{ version: "1.0.0", direction: rx, header: { fields: [{ name: msgId, type: u16, role: message_id }, { name: length, type: u8, role: payload_length }] }, framing: { kind: length_prefixed, max_frame_size: 64 }, messages: [ImuSample, Heartbeat] }'
- Validate and inspect:
wireforge validate demo,wireforge analyze demo(sizes, offsets, bit maps, frame and buffer sizes per profile),wireforge encode demo ImuSample '{ sensorId: 3 }' --interface imu_link. - Generate and test:
wireforge test demo -o generatedgenerates the code and the test project, builds it and runs every test;--coverageruns the coverage target instead. - Use it in your build:
find_package(WireForge 0.1 REQUIRED) # -DWireForge_DIR=$(wireforge cmake-dir), or an installed prefix wireforge_generate(imu_model PROJECT ${CMAKE_SOURCE_DIR}/demo) target_link_libraries(my_app PRIVATE imu_model)
LANGUAGE cgives a C99 library instead (docs/CODEGEN.md). Seeexamples/cmake_consumer/(quality/run_quickstart.shruns all of the above from a fresh wheel and checks that it takes less than 15 minutes).
- Files are the source of truth (docs/CLI.md): edit YAML by hand, with
wireforge set/upsert/remove, in the web UI or through MCP;wireforge fmtkeeps one canonical layout so every way of editing gives minimal diffs. - Profiles select platform variants (
defines,if:conditions); every tool works per profile. - Versions:
interface.versionfollows semver;wireforge compat old/ new/(or the UI's Versions tab) tells whether a change is breaking, compatible or documentation only. - Team server:
wireforge serve --workspace projects/(docs/SERVER.md, docs/UI.md). - AI agents:
wireforge mcp --workspace projects/(docs/MCP.md). - Wireshark:
wireforge wireshark demo -o demo.luawrites a Lua dissector plugin for every interface (docs/WIRESHARK.md).
Describe the whole system in one model: nodes (the units, each with an optional language), an interface with the
nodes that take part in it, and for every message of an interface from, the unit or units that send it. Units
that share no interface never talk. wireforge generate <project> -o out then writes out/nodes/<unit>/ for every
unit, with only its own messages, callbacks, tests and documents, and out/system/ with the system ICD and (with
--tests) a test of every sender's encoder against every receiver's decoder. --node <unit> generates one unit with
the same files as the full run. wireforge compat old new --node <unit> says whether a change affects that unit, and
the unit hash in the banner only changes with what reaches the unit. Split the model into files with include so that
a change in one link does not move the source lines in the files of the units that are not in it. Chapter 12 of the
tutorial walks through it; examples/08_system is a larger model.
With --language c the code is C99 instead (model.h, model.c; docs/CODEGEN.md, runtime in runtime/include/wireforge/c/).
model.hpp (types with defaults, validate(), sizes, serialize()/deserialize()), one header per interface (ids,
encode_frame(), Handler, Endpoint, Link) and user_prelude.hpp; see docs/CODEGEN.md. The runtime is
header-only (runtime/include/wireforge/, docs/RUNTIME.md). Bare-metal builds define WIREFORGE_NO_STD_MUTEX.
Zero warnings from the compilers and analyzers that gate CI, a 100 % line, branch and function coverage gate on generated code, differential and fuzz testing against the reference codec, big-endian and 32-bit test runs, no-heap evidence and a trace report from model rows to code and tests (quality/QUALITY_POLICY.md, docs/SAFETY.md).
wireforge init <dir> --protocol <name> (or the same choice under "New project" in the web UI) copies the model of a
published protocol that is written from its public documents and checked against an independent implementation of it
(byte for byte, in tests/python/). Each model has a README with its source, what it covers and what it does not.
| Protocol | Covers | Independent check |
|---|---|---|
modbus_rtu |
Modbus RTU: read holding registers, write single register, exceptions; CRC-16/MODBUS sent low byte first; vectors from the examples of the specification | pymodbus |
modbus_tcp |
Modbus TCP: the MBAP header with a length, one message per interface | (vectors of the specification) |
crsf |
CRSF (radio link to flight controller): the frame and HEARTBEAT, BATTERY_SENSOR, LINK_STATISTICS, one message per interface | crsf-parser |
j1939 |
SAE J1939: the identifier word (priority, PGN, source address) and the groups EEC1, CCVS, ET1 | cantools |
mavlink1 |
MAVLink 1: the frame and HEARTBEAT, ATTITUDE, GLOBAL_POSITION_INT, COMMAND_LONG; a checksum that adds the CRC_EXTRA byte of the message | pymavlink |
mavlink2 |
MAVLink 2 (what current autopilots speak): the frame with the 24-bit message id, payloads without their trailing zero bytes, HEARTBEAT, GPS_RAW_INT and COMMAND_ACK with extension fields, ATTITUDE, GLOBAL_POSITION_INT, COMMAND_LONG; a Lua checksum hook for Wireshark | pymavlink |
ubx |
u-blox UBX: the frame, ACK-ACK, ACK-NAK, CFG-RATE, NAV-PVT, MON-VER; Fletcher-8 that skips the sync characters | pyubx2 |
| Example | Shows |
|---|---|
examples/01_basic_telemetry |
one interface: sync/id/length header, CRC-32 trailer, enum, nested struct, counted array |
examples/02_multi_interface_avionics |
avionics-style node: three interfaces (sync+length with CRC-16, raw, length-prefixed), platform profiles with conditional fields, lsb-first bit-fields, optional field, fill array, user-defined checksum, application constants |
examples/03_edge_cases |
corner cases: zero counts, nested optional, signed bit-fields, u64, wire constants |
examples/04_user_type |
an opaque field type backed by application code |
examples/07_can_dbc |
a CAN network imported from a DBC file: Intel and Motorola signals, factor and offset, value tables as enums, an extended identifier (wireforge import-dbc) |
examples/08_system |
five units (C++ and C) over four interfaces (two way, one way, a shared line), one file per interface, counters per message; wireforge generate examples/08_system -o build/system --tests |
examples/icd/ |
ICD sources for the importers (CSV table, C header) |
examples/cmake_consumer/ |
an application built with find_package(WireForge) |