swaitsandClaude Opus 4.7
ce358996ad
Two additions to the TXT_MSG section: 1. Attempt Counter Semantics. Spells out that bits 0-1 of txt_type_attempt carry attempt & 3, the input the ACK CRC depends on. For attempt > 3, upstream appends a [NUL][attempt_full] tail after the text (BaseChatMesh.cpp:410-412), recovering the full attempt value at the cost of 2 bytes of text capacity. The tail is NOT part of the ACK CRC input, so attempt=4 and attempt=0 collide on CRC and senders relying on >3 must verify the trailing byte. 2. Reliable DM Delivery. Documents the sender-side ACK tracking contract: maintain a pending-ACK table keyed by expected CRC, retry with attempt incremented, consume MULTIPART-wrapped or plain ACKs identically, and the receive-side option to cache replies per peer for duplicate-DM loss recovery. Validated against upstream meshcore-dev/MeshCore @ 1a7b361 (BaseChatMesh::composeMsgPacket, onPeerDataRecv TXT_MSG handling). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
MeshCore Spec
A comprehensive specification and conformance test suite for the MeshCore mesh networking protocol.
MeshCore Spec aims to be the authoritative, machine-readable definition of the MeshCore wire format — much like RubySpec became the definitive specification of the Ruby language. Any implementation that passes the full test corpus can claim bit-perfect MeshCore compatibility.
What's Here
spec/— RFC-style protocol specification in Markdown, covering every layer from packet framing to cryptographic operations.corpus/— JSON test vectors organized by protocol layer. Each vector pairs a structured representation with its exact binary encoding, enabling any implementation to verify encode and decode correctness.tools/— Validation and generation utilities.
Test Vector Format
Test vectors are JSON files. Binary data is represented as uppercase hex strings (whitespace allowed for readability). Each file contains an array of vectors in one of three modes:
encode_decode— Structured input paired with expected binary output. Implementations MUST produce the given binary when encoding, and MUST recover the given structure when decoding.decode_only— Binary input with expected structured output. Used for alternate valid encodings that an encoder need not produce but a decoder MUST accept.invalid— Binary input that MUST be rejected by a conforming decoder.
See corpus/schema/test-vector.schema.json for the full schema.
Using the Corpus
- Parse each JSON file in
corpus/. - For
encode_decodevectors: encode thestructuredform and compare tobinary; decodebinaryand compare tostructured. - For
invalidvectors: attempt to decodebinaryand verify failure.
No special tooling is required — just a JSON parser and your MeshCore implementation.
Project Status
This project is under active development. The specification and corpus are being built from the official MeshCore firmware source code.
Protocol Versions
The corpus covers all known MeshCore protocol versions. Each test vector file
includes a protocol_version field. Version 1 (the current production version)
has the most comprehensive coverage.
License
MIT — see LICENSE.
Contributing
See CONTRIBUTING.md.
Acknowledgments
Based on the MeshCore firmware by the MeshCore developers. Protocol documentation derived from the official MeshCore docs.