Decisions · ADR 0011

The mesh speaks MeshCore, with upstream's protocol core vendored

Supersedes in part ADR 0001: the device's mesh protocol is MeshCore, not Meshtastic. The rest of ADR 0001 still holds: this is our own firmware, built from libraries, not a fork of anyone's node firmware.

Supersedes in part ADR 0001: the device's mesh protocol is MeshCore, not Meshtastic. The rest of ADR 0001 still holds: this is our own firmware, built from libraries, not a fork of anyone's node firmware.

ADR 0001 chose Meshtastic because it was the obvious network to join, and kept "room for other mesh protocols (e.g. MeshCore) later". What M3 heard decided it the other way: an hour of LongFast by a window heard nothing, while the MeshCore preset (869.618 MHz, 62.5 kHz, SF8, CR 4/8) heard packets within minutes (M3, Q95). A messenger for a network nobody nearby uses is a messenger with nobody to talk to. Supporting both behind one Mesh Service would roughly double M4 for the network that isn't there.

How it works

  • Upstream's protocol core is vendored, not rewritten: Dispatcher, Mesh, Packet, Identity, Utils and BaseChatMesh from github.com/meshcore-dev/MeshCore (MIT), at a pinned commit, about 3,500 lines. The hardware sits behind its small abstract classes (mesh::Radio, the clocks, RNG, PacketManager); we write those adapters on top of our Radio Service. Routing, path return, ACKs, retries and airtime pacing then behave exactly as the rest of the network expects.
  • This isn't the fork ADR 0001 rejected. That was a whole node firmware, built around being one thing. This is a protocol library under our own services and UI, like RadioLib under the Radio Service.
  • Bumped by hand. Each bump is its own pull request with upstream's changes summarised and the test vectors re-run. Our changes to upstream files stay in the adapters; anything else is listed in PATCHES.md next to the code.
  • Ed25519 and X25519 come from libsodium, already linked for WireGuard, instead of upstream's bundled orlp/ed25519 and its 98 KB table. Signatures and shared secrets are proven byte-identical to upstream's by host tests on vectors taken from upstream.
  • A chat node only until M7: it never relays, like upstream's own companion nodes (disable_fwd).
  • Meshtastic stays in the LoRa Scanner: its presets and its header decoder. Nothing more.

Consequences

  • We follow upstream's wire format, not a standard: a change upstream that breaks compatibility reaches us only when we bump, and then we have to.
  • Upstream's code is Arduino-flavoured (Arduino.h, Stream); a small shim lets it build for the host tests (test/ reaches lib/ only).
  • Swapping its crypto for libsodium is a patch we carry. The test vectors are what make it safe; a bump that changes Identity re-checks them.
  • Meshtastic users can't message the device. The Scanner still shows their packets.
  • The phone companion protocol is left for M6, the repeater and room-server modes for M7.

This page is generated from docs/adr/0011-the-mesh-speaks-meshcore.md in the repository. To change it, change that file and run site/tools/gen_dev_docs.py.