Home

meshbeacon-firmware wiki

meshbeacon-firmware is the field-device (node) firmware for MeshBeacon, an offline LoRa mesh communication system. It is built on top of the ClusterDuck Protocol (CDP), a low-bandwidth LoRa mesh networking protocol originally created by OWL Integrations (formerly Project OWL) under the Linux Foundation. Full credit to the upstream CDP project for the base mesh protocol, "Duck" node model, and Arduino/PlatformIO library structure this firmware extends.

On top of stock CDP, this repository adds:

• A layered end-to-end encryption design (per-device X25519 identity keys, ChaCha20-Poly1305 AEAD, sealed uplinks, authenticated downlinks, peer sessions, group-broadcast encryption, replay protection, and rejection telemetry).
• Runtime-selectable regional LoRa frequency presets and uplink channel spreading for gateway concentrators.
• Serial-based field provisioning for deployment-specific secrets (MeshBeacon Ops public key, mesh group key, radio region) without a firmware reflash.

This wiki documents the firmware as it exists in this repository. It does not cover the agriculture-deployment-architecture design document (see docs/agriculture-deployment-architecture.tex in the repo for that separate write-up).

Contents

• Getting Started — prerequisites, building with PlatformIO, the EXAMPLE_DIR mechanism, running tests.
• Architecture Overview — the Duck class hierarchy, CDP network join/routing lifecycle, project layout.
• Duck Types — MamaDuck, PapaDuck, DuckLink, and DetectorDuck: what each one is for.
• Packet Format and Topics — the on-air CdpPacket wire format, the topics/reservedTopic enums, and the protobuf application payloads.
• Routing and Mesh — RREQ/RREP route discovery, the routing table, bloom-filter dedup, and signal scoring.
• Radio and Regions — DuckLoRa, runtime region presets, and uplink channel spreading.
• Security and Encryption — identity keys, the encryption modes, field provisioning, and known limitations.
• Supported Boards — supported hardware and the PlatformIO environments for each.
• Examples — tour of the examples/ directory and example sketches.
• Contributing — how to propose changes and the project's contribution process.

Related repositories

MeshBeacon is split across three repositories:

• meshbeacon-firmware (this repo) — Arduino/PlatformIO node firmware.
• meshbeacon-uplink — a gateway daemon (clusterduckd) bridging an SX1302 LoRa concentrator to MQTT.
• MeshBeacon Ops — a self-hosted Laravel operator dashboard (map, mesh topology, device health, incidents, SOS acknowledgment, SMS/Telegram alerting).

License

Apache License 2.0, same as upstream CDP.