0 Fork 0

Files

T

spec: link corpus references to GitHub, version-aware

Every "Test vectors: \`corpus/...\`" mention in the spec is now a
markdown link pointing at the corresponding file or directory on
GitHub. Each version build resolves its links to the correct git
ref:

  - /latest/ -> https://github.com/swaits/meshcore-spec/tree/main/corpus/...
  - /v0.1.0/ -> https://github.com/swaits/meshcore-spec/tree/v0.1.0/corpus/...
  - future /vX.Y.Z/ -> /tree/vX.Y.Z/corpus/...

Two changes:

1. src/*.md (18 files): the inline-code corpus paths in each
   "Cross-References" section are now markdown links. Directories
   point at /tree/main/corpus/..., individual .json files point at
   /blob/main/corpus/.... CHANGELOG and other non-corpus main links
   are intentionally left pointing at main — the canonical history
   lives there regardless of which version you're reading.

2. justfile: `cut-version` now also runs a sed over the snapshot's
   *.md files replacing /tree/main/corpus -> /tree/<VERSION>/corpus
   and /blob/main/corpus -> /blob/<VERSION>/corpus. So a freshly-cut
   version is self-consistent.

versions/v0.1.0/* regenerated by re-running
`just cut-version v0.1.0` after the new src/ links + recipe sed
landed.

Tagging the release commit (`git tag v0.1.0`) is now REQUIRED — not
"optional" — because the rendered /v0.1.0/ pages reference
/tree/v0.1.0/corpus/... on GitHub. Without the tag the links 404.
cut-version's output now says so.

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

2026-05-12 10:35:09 -06:00

3.2 KiB

Raw Blame History

MeshCore Protocol Specification

Section 18: Companion Protocol

Overview

The companion protocol enables BLE (Bluetooth Low Energy) and serial communication between a MeshCore radio and a companion app (phone, tablet, or computer). It uses a binary framing format over the Nordic UART Service (NUS) BLE profile.

BLE Service

UUID	Description
`6E400001-B5A3-F393-E0A9-E50E24DCCA9E`	Nordic UART Service
`6E400002-...`	RX Characteristic (app writes to radio)
`6E400003-...`	TX Characteristic (radio notifies app)

Frame Format

Each companion protocol frame consists of a 1-byte type identifier followed by variable-length data:

[type(1)][data(0-171)]

Maximum frame size is 172 bytes.

Message Types (Radio to App)

Type	Value	Description
PACKET_CHANNEL_MSG_RECV	0x01	Channel message received
PACKET_CONTACT_MSG_RECV	0x02	Contact message received
PACKET_ADV_RECV	0x03	Advertisement received
PACKET_CONTACT_MSG_RECV_V3	0x04	Contact message V3 (includes SNR)
PACKET_CHANNEL_MSG_RECV_V3	0x05	Channel message V3 (includes SNR)

Command Types (App to Radio)

Command	Value	Description
CMD_APP_START	0x01	Initialize connection
CMD_DEVICE_QUERY	0x02	Query device info
CMD_SET_CHANNEL	0x03	Set active channel
CMD_SEND_CHANNEL_MESSAGE	0x04	Send message to channel
CMD_SEND_CONTACT_MESSAGE	0x05	Send message to contact
CMD_GET_CONTACTS	0x06	Get contact list
CMD_GET_CHANNELS	0x07	Get channel list
CMD_SET_TIME	0x08	Set device time
CMD_ADD_CONTACT	0x09	Add a contact
CMD_ADD_CHANNEL	0x0A	Add a channel
CMD_SEND_LOGIN	0x0B	Login to room/repeater
CMD_GET_SETTINGS	0x0C	Get device settings
CMD_SET_SETTINGS	0x0D	Set device settings
CMD_REMOVE_CONTACT	0x0E	Remove a contact
CMD_REMOVE_CHANNEL	0x0F	Remove a channel
CMD_SHARE_CONTACT	0x10	Share contact info
CMD_SET_ADV_NAME	0x11	Set advertisement name
CMD_REBOOT	0x12	Reboot device
CMD_SEND_RAW	0x13	Send raw packet

Connection Sequence

Scan for BLE devices advertising the Nordic UART Service.
Connect and discover services.
Enable notifications on the TX characteristic.
Send CMD_APP_START to initialize.
Send CMD_DEVICE_QUERY to get device info.
Send CMD_SET_TIME to synchronize clock.
Send CMD_GET_CONTACTS and CMD_GET_CHANNELS to fetch state.

Byte Order

All multi-byte integers in the companion protocol are little-endian, except for CayenneLPP sensor data which uses big-endian.

Message Length Limit

Text messages are limited to 133 characters.

MTU Considerations

The default BLE MTU is 23 bytes (20 bytes of payload). For complex operations, implementations SHOULD request a larger MTU (up to 512 bytes).

Cross-References

Section 1: Wire Format — Underlying packet format
Test vectors: corpus/companion/

Reference Implementation

docs/companion_protocol.md in the MeshCore repository

3.2 KiB Raw Blame History