0 Fork 0

T

docs(changelog): add 2026-05-12 publication-readiness entry

Record this pass at the top of CHANGELOG.md:

- Upstream baseline: meshcore-dev/MeshCore @ 1a7b361 (2026-04-28).
  Every normative claim was cross-checked against this commit.
- Process: adopted conventional commits; established
  "upstream-firmware-is-the-golden-source-of-truth" as a load-bearing
  principle for the project.
- Added: ack-crc test vectors; explicit ACK CRC algorithm; attempt
  semantics including tail-byte encoding for attempt > 3; reliable
  DM delivery; multipart direct-only and finalizer plain-ACK;
  sender-behavior/transmission-priority section in routing; README
  provenance + Author.
- Clarified: AES plaintext zero-padding scheme; MULTIPART chain
  descending count + plain finalizer.
- Corrected: 17-routing previously misrepresented upstream's
  path-replacement as a hash-size/SNR heuristic; upstream actually
  replaces unconditionally.
- Out of scope: ai-bot-specific values (route TTL, SNR margin,
  1-byte hash rejection, 150ms PATH_RETURN, 0x1424 sync word,
  pending-ACK 64/125s) were considered and dropped since they are
  not upstream behavior. Radio/hardware-state firmware items also
  excluded as out of protocol scope.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-12 09:27:07 -06:00

corpus

corpus(crypto): add ack-crc test vectors

2026-05-12 09:22:41 -06:00

spec

spec(routing): align path-learning with upstream and document PATH_RETURN delay

2026-05-12 09:25:50 -06:00

tools

Add comprehensive spec audit results and pyMC_core issue reports

2026-04-01 21:37:57 -06:00

.gitignore

Add comprehensive spec audit results and pyMC_core issue reports

2026-04-01 21:37:57 -06:00

CHANGELOG.md

docs(changelog): add 2026-05-12 publication-readiness entry

2026-05-12 09:27:07 -06:00

CLAUDE.md

Add comprehensive spec audit results and pyMC_core issue reports

2026-04-01 21:37:57 -06:00

CONTRIBUTING.md

Add comprehensive spec audit results and pyMC_core issue reports

2026-04-01 21:37:57 -06:00

LICENSE

Add comprehensive spec audit results and pyMC_core issue reports

2026-04-01 21:37:57 -06:00

PYMC_CORE_ISSUES.md

Add comprehensive spec audit results and pyMC_core issue reports

2026-04-01 21:37:57 -06:00

README.md

docs(readme): add prominent Provenance disclosure and Author section

2026-05-12 09:26:28 -06:00

README.md

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.

Provenance

This is an independent, AI-authored project. It is not affiliated with, endorsed by, or maintained by the upstream MeshCore project. Read this section before relying on the spec for anything load-bearing.

Authorship. The spec, the corpus, and the tooling were written by Claude (Anthropic, primarily Opus 4.x) under the direction of Stephen Waits. Substantive edits — additions, clarifications, audit passes — are produced through model-driven analysis of the official MeshCore source and reviewed before commit.
Source of truth. The official MeshCore firmware at meshcore-dev/MeshCore is the golden source of truth for all protocol behavior. Whenever this spec and the upstream C++ disagree, upstream wins — this spec is downstream and the canonical text is the C++. Each substantive change in CHANGELOG.md records the upstream commit hash it was validated against.
Refined through DongLoRa. Clarifications and edge-case detail in this spec have been driven in part by observations from building DongLoRa firmware and apps against live MeshCore deployments. Where DongLoRa behavior diverges from upstream, this spec follows upstream and treats the DongLoRa side as a follow-up bug, not a spec change.
Use it carefully. Conformance against this corpus is a useful signal but not a substitute for cross-checking against upstream firmware for any behavior that affects interoperability. If you find a divergence from upstream, please file an issue — that is exactly the kind of report this project exists to catch.

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_decode vectors: encode the structured form and compare to binary; decode binary and compare to structured.
For invalid vectors: attempt to decode binary and verify failure.

No special tooling is required — just a JSON parser and your MeshCore implementation.

Project Status

This project is under active development. See Provenance above for how the spec is produced and what to verify against.

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

This spec would not exist without the MeshCore firmware by the MeshCore developers and the official MeshCore docs, which together are the authoritative reference this spec derives from.

Author

Stephen Waits steve@waits.net