WireForge schema specification, schema_version: 1
Machine-readable form: schema/project.schema.json (root file) and schema/fragment.schema.json
(included files). This document is normative for behaviour that JSON Schema cannot express; the
semantic rules in section 13 are enforced by wireforge validate. Working examples: examples/.
1. Files and layout
- A project is a directory with a root file
project.yamlplus optional fragment files. - Root keys:
schema_version,schema_minor,generator,project,version,description,namespace,include,defaults,user_includes,bundle(export only), and the definition sections below.project/versionidentify the user's own project and ICD set;schema_version/schema_minor/generatoridentify the file format (section 11). includelists globs relative to the root file. Fragments contain only definition sections (defines, profiles, checksums, enums, types, messages, interfaces). Sections are merged; a name defined twice is an error (SR-1).- YAML 1.2 is used (
on/off/yes/nostay strings;0x..integers allowed). - Names (
identifier):[A-Za-z_][A-Za-z0-9_]*, must not be C++ keywords (SR-2).
2. Defaults and resolution
Effective value for endian, bit_order, range_check of a message as used on an interface:
message value, else interface value, else defaults, else built-in (big, msb_first,
encode: true, decode: true). Endianness and bit order are message-level only; there is no
per-field override. A message used on two interfaces with different effective endianness gets one codec
instantiation per endianness.
3. Built-in types and wire widths
| Type | Wire width | Notes |
|---|---|---|
bool |
8 bits (1..8 with bits) |
0 = false, nonzero decodes to true only when value is 1; other values are OutOfRange |
u8 u16 u32 u64 |
8/16/32/64 | unsigned |
i8 i16 i32 i64 |
8/16/32/64 | two's complement |
f32, f64 |
32/64 | IEEE-754 binary32/binary64 only, bit pattern via memcpy; no scale/offset |
char |
8 | unsigned byte holding ASCII/Latin-1; arrays of char map to fixed strings |
| enum name | width of its underlying integer type | decoded value must be one of the listed values (else OutOfRange when range check is on) |
| struct name | sum of its fields | serialized inline, no padding, no alignment, no hidden bytes |
| user type name | declared size_bytes |
opaque; wire format is entirely the user's own encode/decode free functions (section 14b) |
Multi-byte values are written byte by byte using the effective message endianness; no host layout is assumed.
4. Bit-fields
bits: n(1..64) narrows a field to n bits. Consecutive bit-fields form a bit group; a struct whose fields all havebitsis an inline bit group when used as a field.- Packing follows the message
bit_order:msb_firstfills each byte from bit 7 downwards,lsb_firstfrom bit 0 upwards. Fields larger than 8 bits continue across bytes in the same direction; byte order of a multi-byte group follows the message endianness. - A bit group must total a multiple of 8 bits (SR-10). Use
reserved: truefields to pad explicitly. - Signed bit-fields are two's complement of the declared width and sign-extended on decode.
occurson a bit-field is not allowed in v1 (SR-11).min/maxapply to the logical (decoded) value.
5. Field attributes
name, type, description, units (documentation only), scale, offset, bits, min, max, default, const,
reserved, occurs, checksum, role (header/trailer only), if, since, deprecated.
- default: initial value of init(); fields without default are zero-initialized. Arrays accept a list.
Enum defaults use the value name. A default must lie in [min, max] (SR-6).
- min/max: numbers or expressions; checked on encode and/or decode per range_check.
With range_check.decode: false, decoding succeeds and the caller can run validate().
- scale, offset: the physical value of a field is raw * scale + offset (defaults 1 and 0; scale is never 0). The
wire, min, max, default and const stay raw values. The generated code adds physical_<Struct>_<field>() and
set_physical_<Struct>_<field>(); the reference codec decodes the physical value as well. Allowed on plain integer
and floating-point fields only (SR-24).
- const: written as the declared value, decode fails with ConstMismatch on difference.
- reserved: written as default (or 0), ignored on decode unless also const.
6. Occurrence model: optional fields and arrays
occurs: {min, max, count | fill} unifies optional fields and arrays.
- max (required): capacity, integer or expression; drives static storage.
- count: expression giving the number present on the wire (a previous field, bool allowed as 0/1).
Count 0 means the field is absent. The count field must precede the field (SR-7).
- No count/fill: fixed array of exactly max elements (e.g. 3 on platformA, 5 on platformB).
- fill: true: elements fill the remaining payload; allowed on the last field of a message only and requires a
constant element size (SR-8). count and fill are mutually exclusive.
- Optional field = occurs: {max: 1, count: hasX}. min defaults to 0; count outside [min, max] is CountExceedsMax.
- C++ storage is count + static array (StaticVector-like). Nothing is allocated dynamically.
7. Expression language
Used in min, max, occurs.*, buffers.*, frame_size, max_frame_size, checksum-independent sizes.
- Literals: decimal, 0x hex, 0b binary, true/false.
- Names: defines, earlier fields of the same message (by name), enum members as Enum.member.
- Operators (C precedence): ?: || && | ^ & == != < <= > >= << >> + - * / % unary - ~ !.
- Functions: defined(NAME), min(a,b), max(a,b), ceil_div(a,b), sizeof(Type) (bytes; fixed-size types only).
- Arithmetic is 64-bit signed; booleans convert to 0/1; division by zero in a constant expression is an error.
- Exact semantics (wireforge.expr, D20): any intermediate result outside the int64 range is an error; / truncates toward
zero and % takes the sign of the dividend (C rules); shift counts must be 0..63 and the shifted value non-negative;
&&, || and ?: short-circuit; literals with a leading zero (012) are rejected (no octal); ceil_div rounds toward
positive infinity. Generated C++ widens every operand to std::int64_t and calls wireforge::expr::{min,max,ceil_div}
(runtime/include/wireforge/expr_support.hpp); if: conditions are emitted verbatim as #if expressions.
- if: conditions use the preprocessor subset: integers, defines, defined(), comparisons, && || !, parentheses.
They must not reference fields.
8. Defines, profiles and conditional layout
defines: named integer constants with default values. Generated headers emitdefines::kNAMEconstants that take the value of the macroNAMEwhen the build defines it (-DNAME=value) and the model default otherwise; in#ifconditions a define is written(defined(NAME) ? NAME : default). The generator itself defines no macros.profiles: named sets of defines (e.g.platformA). Profiles do not change the generated source; they tell tools which variants to analyze and test.if:on a field, struct, message or interface-message entry emits a real#ifin C++. The wire layout may differ per profile; each profile is analyzed separately.
9. Checksums
checksums declares reusable algorithms:
- {algo: crc32}: CRC-32/ISO-HDLC (poly 0x04C11DB7 reflected, init/xorout 0xFFFFFFFF, check 0xCBF43926).
- {algo: crc, width, poly, init, refin, refout, xorout, check?}: parametric CRC (Rocksoft model).
- {algo: custom, impl, include, size_bytes}: user type impl from header include satisfying the runtime checksum
contract (wireforge/checksum.hpp, D16): static constexpr std::size_t kSize (= size_bytes, 1..8), a copyable
State, static State init() noexcept, static void update(State&, wireforge::Span<const std::uint8_t>) noexcept,
static std::uint64_t finalize(const State&) noexcept; checked with static_assert(wireforge::is_checksum_v<impl>).
For generated C99 code a custom checksum also names c_impl, a C function
uint64_t f(const uint8_t *data, size_t length) over the covered bytes, and c_include, the header that declares it
(relative to an include directory). A user constant (user_includes.constants) used in an expression of generated C
has a c spelling, a macro or an enumerator; without it the C code uses value when the constant has no
profile_values. A header entry of user_includes.headers can name a c_path, the header the generated C code
includes in place of path (it defines the macros the c spellings stand for).
A field uses it with checksum: {use, covers}. covers is {from, to} (inclusive field range in the same struct)
or {scope: preceding | payload | header_and_payload}; the latter two are for header/trailer fields.
The field is computed on encode and verified on decode (ChecksumMismatch). Its width must equal the algorithm
width (SR-12). Checksums are optional everywhere.
10. Interfaces
An interface is one communication endpoint with a remote party (our_to_nodeA, nodeB_to_our, ...).
- version (semver, required): ICD version; may be carried on the wire by a role: protocol_version header field.
- direction: tx, rx, both (not allowed when the project defines nodes; see below). endian, bit_order, range_check: defaults for its messages.
- header: none or {fields}. Header field roles: sync (const marker), message_id, payload_length,
protocol_version, sequence. A header with message_id enables header-based dispatch.
- header: none means raw dispatch: the interface carries exactly one message type, or none (raw bytes) (SR-14).
- trailer: optional fields after the payload (typically a checksum).
- framing: none (each transport read is one frame), fixed (frame_size), sync_length (header has sync and
payload_length), length_prefixed (header has payload_length). Non-none kinds need max_frame_size
(drives static buffer sizes). length_counts says what the length field covers (default payload).
resync: true rescans after garbage or bad frames.
- messages: names or {name, from?, id?, if?, since?}; id overrides the message id on this interface.
- buffers.rx_bytes/tx_bytes: optional circular/linear buffer sizes; default derived from max_frame_size.
- allow_trailing_bytes: default false; leftover payload bytes give TrailingBytes.
- trim_trailing_zeros: default false; every payload is sent without its trailing zero bytes (the first byte always
stays) and the receiver reads the bytes it did not get as zeros (MAVLink 2). Needs messages of fixed size (SR-25);
changing it is a breaking change.
- nodes (interface): the units that take part, at least two without repeats (a shared line has more).
message_counters: default false; asks for a counter per message and direction in the generated code.
A project may define nodes, a map of unit name to {description?, language?} (language is cpp or c). The direction
of a message then belongs to the message: every interface lists its nodes, every message entry gives from (a unit or a
list of units) and the other participants receive it. Without nodes, direction stays the only direction information
and nodes/from are not allowed. Units that share no interface do not talk to each other.
11. Versioning and file identity
| Key | Meaning | Written by |
|---|---|---|
schema_version (int) |
file-format major; any incompatible change bumps it | tool, required in every file |
schema_minor (int, default 0) |
additive format changes inside a major (minor 1: requirements, reqs; minor 2: vectors; minor 3: nodes, from, message_counters) |
tool |
generator {name, version} |
WireForge release that wrote the file (informational) | tool on save/export |
version (semver, root) |
the user's project / ICD set | user |
interface.version (semver) |
one interface's ICD version, may travel on the wire | user |
Compatibility policy (wireforge.versioning, rule SR-19):
- format major newer than the tool supports: error, only this problem is reported (content cannot be trusted);
- format major older: error in normal loading; the file goes through wireforge import, which applies the registered
migration chain (register_migration(from_major, step), one step per major, run in order, result stamped with the
current format). A missing step is an error ("no migration path");
- same major, newer minor: error (the file uses features this tool does not know);
- generator newer than the tool: warning only.
Before the first official release the format is unstable (0.x tool versions may change it without migrations). From the release on, format 1 is frozen and every later major ships migrations from all earlier majors, so old interface files stay importable. Generated C++ carries the format version, tool version and model hash in its banner.
Interface compatibility (python -m wireforge.compat OLD NEW [--interface NAME], D26) compares each interface per
profile and classifies every difference:
- breaking (requires a major bump): any wire layout change of a header, trailer or message field (type, bits,
occurs, const, reserved, checksum, role), inserted/removed/reordered fields, changed min/max or enum values,
message id, effective endian or bit order, framing kind/sizes/length_counts, direction, removed messages;
fields appended to a message unless the old interface has allow_trailing_bytes: true;
- compatible (minor): renamed fields, changed defaults, added messages, resync or allow_trailing_bytes changes,
appended fields that old receivers ignore;
- doc (patch): descriptions and units.
The report fails when the new interface.version is not at least the required step above the old one.
12. Error model
Codec calls return Status values (docs/contracts/runtime-error-codes.md). Validation messages produced by tools
carry file, line and JSON pointer. NotForThisNode is a status of the generated receivers of a project with nodes: a
valid frame of a message that the unit only sends is not for it, and is not an error (the reference codec never returns it).
13. Semantic rules (beyond JSON Schema)
- SR-1 No duplicate names within a section across root and fragments.
- SR-2 Names are not C++ keywords and do not collide after C++ mangling.
- SR-3 Every
typeresolves to a builtin, enum, struct or user type; struct graphs are acyclic. - SR-4 Every checksum
use, interface message, enum default andcoversname resolves. - SR-5 Expressions parse; names resolve;
ifconditions reference no fields. - SR-6
default,constlie in[min, max]and fit the type/bit width;min <= max. - SR-7 Fields referenced by
occurs.countprecede the occurring field and are integer/bool. - SR-8
fillonly on the last message field with constant element size;maxis positive. - SR-9 Message ids are unique per interface (after overrides); ids fit the header id field.
- SR-10 Every bit group totals a multiple of 8 bits;
bitsdoes not exceed the type width. - SR-11
occursis not combined withbits. - SR-12 Checksum field width equals algorithm width;
coversranges are ordered and in the same struct. - SR-13
roleis used only in header/trailer;payload_lengthandmessage_idappear at most once per header. - SR-14 Raw interfaces (
header: none) have at most one message;sync_lengthrequiressync+payload_lengthheader fields,length_prefixedrequirespayload_length. - SR-15 Enum values are unique per enum and fit the underlying type.
- SR-16 Each profile evaluates every expression and
ifwithout error, producing consistent layouts. - SR-17 The layout adds no bytes beyond declared fields (no implicit padding is ever generated).
- SR-18 User constants: names unique and not colliding with defines or field names;
profile_valuesname existing profiles; withoutvalueeither every profile has a value or the constant is opaque: opaque constants may appear only in value ranges (min/max), never in anything that changes layout or buffer sizes (occurs, framing, buffers). - SR-19 Version stamps: every file passes the compatibility policy of section 11; fragments carry
schema_version. - SR-20 User header paths and include directories are relative, without
..segments (portable builds); this also covers a user type'sinclude. - SR-22 Requirement test vectors (section 18) are consistent: the message, interface and profile exist, the message is on
the interface,
expect.fieldsnames fields that exist on the wire value, an encoding vector gives every field, and the reference codec agrees with the vector in every profile it applies to. - SR-23 A field of an enum type without
default(and withoutconst) needs an enum member with the value 0, becauseinit()and the reference codec start every field at zero; a dynamic array starts empty and is exempt. - SR-24
scaleandoffsetare allowed only on a plain integer or floating-point field: not on enums,bool,char, structs, arrays, reserved or constant fields, roles and checksums. - SR-25 An interface with
trim_trailing_zerosdoes not usefixedframing, and every message it carries has a fixed wire size in every profile (no dynamic arrays or optional fields), because the receiver restores the trimmed zeros up to that size. - SR-26 Node names are identifiers that are not C or C++ keywords and are unique when case is ignored.
- SR-27 With
nodesin the project, every interface lists knownnodes, every message entry has afromnaming participants of that interface, anddirectionis not given. Withoutnodes, an interface hasdirectionand uses neithernodesnorfrom. - SR-28 (warning) A node that takes part in no interface, or neither sends nor receives on an interface it lists.
- SR-21 Every id in a
reqslist names an entry of therequirementscatalog (section 17). An unused catalog entry is not an error.
Implementation notes (wireforge.validate, D21-D23): every issue carries [SR-n], file, line and JSON pointer.
SR-10 also limits a bit group to 64 bits (D19) and checks pure bit-field types where they are used; SR-12 verifies the
check value of parametric CRCs and limits custom checksums to 8 bytes; SR-16 also requires every message to fit
frame_size/max_frame_size together with header and trailer (dynamic arrays at capacity) and sizes/buffers to be
positive; SR-17 rejects if: on a field inside a bit group. The negative corpus is tests/python/semantic_cases.yaml.
Run python -m wireforge.validate <project>.
14. User includes: the gateway to application code
user_includes (root file only) lets definitions use constants and headers that belong to the application.
user_includes:
include_dirs: [app/include] # added to include paths of generated build files
headers: # emitted as #include in the generated user prelude, in order
- { path: app/limits.hpp, style: quote } # quote | angle ; optional `if:` preprocessor condition
constants: # integer constants usable in any expression, by plain name
APP_MAX_FRAME:
cpp: app::kMaxFrameBytes # how generated C++ spells it (constexpr, enumerator or macro)
value: 128 # what the tools use (analysis, docs, tests, reference codec)
profile_values: { platformB: 192 } # per-profile override
prelude: # verbatim C++ lines after the headers (e.g. extern declarations)
- "extern const std::uint32_t kLinkSpeed;"
value is what analysis uses; the generated
user_prelude.hpp contains static_assert(static_cast<std::int64_t>(<cpp>) == <value>), so drift between model and
application fails at compile time (per profile in the generated per-profile test builds).
- Static memory needs compile-time constants. cpp must name a constexpr variable, enumerator or macro. A link-time
extern const may only be declared through prelude for runtime checks, never as a capacity (SR-18).
- Opaque constants (no value) are allowed in min/max: the check is emitted against the symbol, tools skip evaluation.
- cpp accepts only qualified identifiers (no expressions); header paths forbid quotes, angle brackets and newlines.
prelude lines are emitted verbatim, are not analysed, and are the user's responsibility under the zero-warning policy.
- Every generated header includes the single generated user_prelude.hpp first.
14b. User types: opaque field types backed by application code
user_types (root or fragment) lets a field's type be a user-owned C++ type whose wire form WireForge never
inspects — only its fixed size.
user_types:
Fixed16:
cpp: app::Fixed16 # fully qualified C++ type name
size_bytes: 2 # fixed, positive; same in every profile (not an expression)
include: app/fixed16.hpp # optional; added to the generated user prelude
style: quote # quote | angle, default quote
description: "Q8.8 fixed-point sample" # optional
void encode(const T&, wireforge::Encoder&) noexcept and void decode(T&, wireforge::Decoder&) noexcept,
found by ADL. WireForge generates only min_wire_size/max_wire_size (both equal to size_bytes, since the
size never varies); it never generates encode/decode for a user type. T must be default-constructible.
- Treated like a struct field everywhere else. occurs, arrays and nesting inside other types all work.
Opaque: bits, an occurs.count target, a checksum field, and min/max/default/const are all
rejected — already caught by the rules that reject every non-integer, non-bool field type (SR-6, SR-7,
SR-10, checksum field typing), no new rules needed.
- Python reference codec. A user-type field's value is raw bytes of exactly size_bytes; the default
value is size_bytes zero bytes. The reference codec never interprets the type's semantics.
- Generated tests. Per-field value assertions are not generated for a user-type field (its C++ value
cannot be expressed as a literal); only decode Status and wire-byte equality are checked.
- Wireshark dissector. Shown as raw hex (FT_BYTES); the dissector cannot run the user's C++, so the
value is never decoded or checked.
15. Export and import
wireforge export <project> -o bundle.yamlmerges all fragments into one ordinary single-file project (noinclude), stamped with the current format, plusbundle: {content_hash, source_files}. The sha256 covers definition content only (not stamps, not key order). Export refuses projects with structural or semantic errors.wireforge import <bundle> <dir>verifies the hash (mismatch is an error;--no-verifyoverrides), applies migrations for older formats, validates structure and unpacks into the standard layout (project.yaml,profiles/,types/,messages/, one file per interface), every file stamped.--single-filekeeps one file. A non-empty destination is refused.- A bundle is itself a valid project and can be loaded directly. Comments are not preserved by export (canonical form).
- Standard layout written by import:
project.yaml(project keys,defines,checksums,user_includes,include),types/types.yaml(enums,types),profiles/profiles.yaml,messages/messages.yaml,interfaces/<name>.yaml. The hash is verified before migrations run (it covers the content the exporter wrote). API:wireforge.bundle.
16. Encoding rules shared by the reference codec and generated code
wireforge.codec.ReferenceCodec (one instance per profile) is the executable form of these rules; generated C++ must
produce the same bytes and statuses (golden vectors in tests/golden/, regenerated with
python -m wireforge.golden <project> <file> [--plugins file.py]).
- Fields are written in declaration order; fields whose if: is false in the profile do not exist.
- const fields are written with their declared value; decoding another value is ConstMismatch. reserved fields are
written as default (or zero) and accepted with any value on decode.
- Occurrences: when count is a plain field name the encoder writes the element count into that field (the caller's
value is ignored); other count expressions must equal the element count. Counts outside [min, max] are
CountExceedsMax, checked before the range of the count field. Fixed arrays need exactly max elements; fixed char
arrays are zero padded (decode strips trailing zeros). fill consumes the rest of the payload, which must be a
multiple of the element size (InvalidLength).
- Values that do not fit the type or bit width are always OutOfRange; min/max and enum membership are checked when
range_check is on for that direction (opaque constants are checked only by generated code). A bool wire value
other than 0 or 1 is OutOfRange. NaN is outside every min/max range.
- Bit groups follow section 4 (one container per group, written with the message endian).
- Checksums: preceding covers the struct bytes before the checksum field, {from, to} the bytes of that field range,
payload/header_and_payload the frame parts; a mismatch is ChecksumMismatch. Custom algorithms need a plugin
(Python) or the impl type (C++).
- Frames: header, payload, trailer. message_id and payload_length header fields are filled by the encoder; a length
that does not match the frame is InvalidLength; fixed framing needs exactly frame_size bytes (no padding is ever
added) and every frame must fit max_frame_size. Decoding verifies the trailer checksum before looking up the id.
- Leftover payload bytes are TrailingBytes unless the interface sets allow_trailing_bytes.
- trim_trailing_zeros: the encoder leaves out the zero bytes at the end of the payload (the first byte always stays),
so the length field and the checksum cover the bytes that are sent; the decoder extends a shorter payload with zeros
to the size of the message before decoding it. A payload of the full size or longer is decoded as it is.
17. Requirements and traceability
The model can carry the user's high-level requirements (HLR) and tie model elements to them. WireForge derives the low-level requirements (LLR) from the model itself and links both to the generated tests.
requirements: # root or fragment; ids are unique across files (SR-1)
HLR-SNS-004:
text: The sensor link shall reject readings outside the sensor's calibrated range.
source: ICD-SNS-001 §4.2 # optional, free text
verification: test # optional: test (default) | analysis | review
_ . : -, and has at most 64 characters.
- reqs: [ID, ...] (at least one id, no repeats) is accepted on a field, types entry, message, enum, checksum, user
type, interface, its framing and an interface message given in object form. An unknown id is SR-21; a requirement
that no element uses is allowed. Projects without requirements or reqs behave exactly as before.
- The requirements section and the reqs lists are part of the model hash, so editing a requirement text changes
the hash in the banner of the generated code.
- A file that uses these keys needs format 1.1; an older WireForge rejects it (SR-19).
Low-level requirements are never stored. wireforge.llr.derive() writes down what the model implies; each has a key
built from names only (SensorReading.temperature.RANGE) and the displayed id LLR-<key>:
| Kind | Derived for |
|---|---|
VALUES, ALGORITHM |
every enum, every checksum |
LAYOUT, SIZE, TRUNCATED, TRAILING |
every type (LAYOUT) and message (all four) |
DEFAULT, RANGE, ENUM, BITS, COUNT, CHARS, CONST, CHECKSUM |
a field with that attribute (<Owner>.<field>.<KIND>, <Interface>.header.<field>.<KIND> for frame fields); RANGE, ENUM and BITS only where range checking is on |
FRAME_ENCODE, FRAME_MAX, DISPATCH, RAW |
every interface |
FRAME_SYNC, FRAME_LENGTH, FRAME_RESYNC, DISPATCH_UNKNOWN |
an interface with a sync field, a length (field or framing), framing other than none, a message_id field |
FRAME_TRIM |
an interface with trim_trailing_zeros |
The fields of a nested type belong to the type (Vec3.x.RANGE), not to each message that uses it. An LLR inherits the
HLRs of the elements it comes from (its field, its struct, the enum or checksum it uses, the interface and its
framing); one without any is derived. DISPATCH_UNKNOWN is verified by the runtime tests, not by the tests generated
for a project.
Every generated test records the LLRs it verifies as its first statement
(::testing::Test::RecordProperty("requirements", "LLR-...,LLR-...")), so gtest writes them into its XML result and
wireforge trace reads them from the test sources. The static size assertions of the layout analyzer are tests too
(TEST(<Message>, WireSize), TEST(Interface_<I>, WireSize)), so SIZE and FRAME_MAX have a test.
18b. What real protocols showed
Published protocols were written from their specifications (protocols/, docs/GUIDE.md), with vectors taken from
the examples of the specifications and compared with independent implementations (pymodbus, pyubx2;
tests/python/test_independent.py, tests/python/test_ubx.py). They found:
- A receiver must check the constants of the header and, on a link without a frame decoder (framing: none), the
checksum itself. It does now: the generated receiver refuses a frame with a wrong constant (ConstMismatch) or CRC
(ChecksumMismatch) before the handler sees it.
- A serial frame ends at a silence, not at a length. framing: none is how a driver that delivers one frame per read
is described.
- A checksum that must not cover the sync characters of the frame (UBX) is a custom checksum that skips the first two
bytes it is given: scope: header_and_payload starts at the first header field.
- A length field that counts bytes after fields that follow it (the unit and function code of Modbus TCP) leaves no
header-based dispatch by function code; such an interface carries one message.
- A count in bytes (Modbus byte count) is written as an expression (count: "byteCount / 2"); the byte count stays a
field that a vector names.
Protocols whose checksum needs more than the data (for example a seed byte per message) are described with a custom
checksum; that was not attempted.
18. Requirement test vectors
A vector is a test you write from the ICD: bytes, and what they must decode to (or what a value must encode to). It verifies high-level requirements directly, with an expected result that comes from you and not from the model.
vectors: # root or fragment
reading_nominal:
description: Nominal reading from ICD-SNS-001 example 3. # optional
interface: sensor_to_us # given: the bytes are a frame; absent: they are a payload
message: SensorReading
profile: ground # optional; absent: every profile (or the single configuration)
direction: decode # decode (default) | encode | both
bytes: "A5 5A 01 01 00 17 ..." # hex; spaces and underscores are ignored
expect:
fields: { sensorId: 3, state: ready, temperature: 21.5 } # or: { status: OutOfRange }
reqs: [HLR-SNS-004] # required, at least one
expect holds either fields or status; a status is a runtime status other than Ok. With fields the vector
must decode without error; fields may be a subset. Values have the shape of the decoded message: enum member names,
nested mappings, lists, strings for char arrays. Wire-only fields (constants, checksums, reserved, plain count
fields) cannot be named. f32 values are rounded to 32 bits before they are compared; the comparison is exact.
- direction: encode or both needs fields and a complete value (every field that is always present); the bytes
must be exactly what the value encodes to.
- A project is valid only when the reference codec agrees with every vector (SR-22), so a wrong vector or a wrong
model is found before code is generated. The agreement does not move the oracle: the generated C++ test
(hlr_vector_test.cpp) compares with the values written in the vector. Vectors that need a custom checksum are
skipped with a warning when no plugin is given.
- Vectors are separate from the golden vectors in tests/golden/, which the reference codec produces as a regression
baseline.