swaitsandClaude Opus 4.7
44305a06db
First cut release. Snapshots ./src/ as ./versions/v0.1.0/ via `just cut-version v0.1.0` (22 files: 21 chapter MDs + SUMMARY.md). Deployed alongside `latest` at: https://swaits.github.io/meshcore-spec/v0.1.0/ Also: - CHANGELOG.md adopts Keep a Changelog-style version sections. Future entries land under [Unreleased] and graduate to a version heading when cut. The existing date-stamped pass entries stay put as a historical record of the work captured in v0.1.0. - README.md fixes a stale "per vX.Y.Z tag" mention left over from the tag-based versioning model, and links the current release explicitly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
# MeshCore Protocol Specification
|
|
|
|
## Section 20: Bridge Protocol
|
|
|
|
### Overview
|
|
|
|
The bridge protocol enables MeshCore packet forwarding over non-LoRa transports
|
|
such as RS232 serial links and ESP-NOW WiFi. It adds a simple framing layer
|
|
with a magic number and checksum around the raw MeshCore packet.
|
|
|
|
### Frame Format
|
|
|
|
```
|
|
┌──────────────┬──────────────┬──────────────┬──────────────┐
|
|
│ Magic (2B) │ Payload │ Checksum (2B)│ │
|
|
│ 0xC03E │ (variable) │ Fletcher-16 │ │
|
|
└──────────────┴──────────────┴──────────────┴──────────────┘
|
|
```
|
|
|
|
### Fields
|
|
|
|
| Field | Size | Type | Description |
|
|
|-------|------|------|-------------|
|
|
| Magic | 2 bytes | uint16 | `0xC03E` — identifies the frame as a MeshCore bridge packet |
|
|
| Payload | variable | raw | Raw MeshCore packet (as produced by `Packet::writeTo()`) |
|
|
| Checksum | 2 bytes | Fletcher-16 | Fletcher-16 checksum over the payload |
|
|
|
|
### RS232 Variant
|
|
|
|
The RS232 variant adds a length field between the magic and payload:
|
|
|
|
```
|
|
┌──────────────┬──────────────┬──────────────┬──────────────┐
|
|
│ Magic (2B) │ Length (2B) │ Payload │ Checksum (2B)│
|
|
│ 0xC03E │ uint16_le │ (variable) │ Fletcher-16 │
|
|
└──────────────┴──────────────┴──────────────┴──────────────┘
|
|
```
|
|
|
|
| Field | Size | Type | Description |
|
|
|-------|------|------|-------------|
|
|
| Length | 2 bytes | uint16_le | Length of the payload in bytes |
|
|
|
|
### Fletcher-16 Checksum
|
|
|
|
The Fletcher-16 checksum is computed over the payload bytes:
|
|
|
|
```
|
|
function fletcher16(data):
|
|
sum1 = 0
|
|
sum2 = 0
|
|
for byte in data:
|
|
sum1 = (sum1 + byte) mod 255
|
|
sum2 = (sum2 + sum1) mod 255
|
|
return (sum2 << 8) | sum1
|
|
```
|
|
|
|
### ESP-NOW Variant
|
|
|
|
For ESP-NOW transport, the frame format is the same as the basic format (magic +
|
|
payload + checksum) without the length field, since ESP-NOW provides its own
|
|
length framing.
|
|
|
|
### Cross-References
|
|
|
|
- [Section 1: Wire Format](01-wire-format.md) — Packet format within payload
|
|
|
|
### Reference Implementation
|
|
|
|
- Bridge handling in MeshCore firmware (board-specific implementations)
|