Off-grid mesh messaging · pre-alpha
Bramble is a from-scratch LoRa mesh protocol and firmware for off-the-shelf ESP32-S3 radios. Authenticated traffic, end-to-end direct messages, confirmable delivery, and location sharing you actually control. No accounts, no servers, nothing phones home.
01 What it is
Bramble carries text and location between small radios over long-range LoRa, hopping node to node so a message reaches people well beyond direct range. It routes reactively with AODV by default and can fall back to an opt-in flood transport for group traffic. Every claim on this page is backed by code you can read: firmware, a Go SDK, a command-line client, and a web companion app with an Electron desktop shell.
The threat model is written down and kept honest. Payloads are encrypted, control traffic is authenticated, identities are pinned on first contact, and the parts that are not solved yet are named as gaps rather than dressed up as features.
02 Features
Routing and reliability control traffic (route replies, errors, acks, delivery receipts, beacons) carries a network-key HMAC plus a per-message freshness sequence. There is no public fallback key: an unprovisioned node is inert and fails closed, so a keyless outsider can neither forge nor replay control frames.
Unicast DMs run over a per-peer X25519 handshake, never a shared channel key. Each session ratchets, so a key recovered from one message will not decrypt earlier or later ones (per-message forward secrecy). Peers confirm a 7-digit safety number out of band, and a changed identity key clears the verified mark.
Messages ride one of three reliability tiers. Normal traffic retries up to 3 times; critical traffic such as key exchange retries up to 8. The sender sees a real terminal state (Delivered, Pending, or Failed) driven by authenticated acks and delivery receipts, not a hopeful fire-and-forget.
Location shares at one of three tiers: presence only, a roughly 1 km grid square, or exact coordinates. The payload is AES-256-GCM encrypted end to end, and every tier pads to one canonical ciphertext size so an eavesdropper cannot tell from packet length how precisely you shared.
Opt-in mailbox mode holds a message for an offline neighbor and flushes it when that node reappears. Storage is a bounded RAM buffer with a 24-hour expiry, and it only ever holds ciphertext it could not read anyway. Off by default; a node stores nothing for anyone unless its operator turns it on.
Every transmission passes a single airtime gate that costs each frame by its real time on air and debits a per-tier token budget. Frequency plans are region-aware (US915, EU868, AU915); where the region requires it, as in EU868 at 1%, a regulatory duty-cycle cap scales the whole budget down to stay legal.
Route requests travel under a per-discovery pseudonym rather than the originator's address, and payloads never carry a cleartext channel identifier: membership is proven by which key decrypts a frame, not by a label on the wire.
03 Clients
The web companion app talks to a node over USB, BLE, or your local network and never depends on a backend to work. Send direct and channel messages, watch delivery state land, verify a contact's safety number, manage channels, and share location at the tier you choose. The same app ships as an Electron desktop build.
bramble-cli ships a chat TUI in the spirit of the IRC clients of the 90s: join from a serial port, watch delivery marks land in real time, and yes, /slap is implemented. The same binary scripts every node function (send, flash, monitor, mesh tests) for people who would rather pipe than click.
04 Hardware
Bramble targets ESP32-S3 boards with a Semtech SX1262 LoRa radio. Flash a supported dev board from the browser in a couple of minutes, or build from source.
| Board | MCU | Radio | Status |
|---|---|---|---|
| Heltec WiFi LoRa 32 V3 | ESP32-S3 | SX1262 | Running target |
| LilyGo T-Deck Plus | ESP32-S3 | SX1262 | Running, full LVGL v9 GUI |
| Heltec WiFi LoRa 32 V4 | ESP32-S3 | SX1262 (+ optional L76K GNSS) | Running, GNSS |
| Bramble Pager v1 (custom PCB) | ESP32-S3-WROOM-1 | SX1262 + ATGM336H GNSS | Design complete, boards not yet ordered |
Build and flash instructions live in the building guide.
05 Status, honestly
Bramble runs on real hardware today: a bench mesh of ESP32-S3 boards passing real LoRa traffic, with mesh routing, direct messages, delivery confirmation, BLE, Wi-Fi, GPS, location sharing, store-and-forward, OTA updates, and the web app all verified on-device. What it does not have yet is scale: no field deployments and no users beyond the developer's own bench. Treat it as a project you can read, build, and break, not as something to trust with your safety.
The scale numbers are kept honest too, and they come from simulation (the real firmware running against a simulated ether). On a single SF10 channel, message delivery is about 95% at 10 nodes and then collapses as the shared channel saturates with control traffic: roughly 12% at 50 nodes and 0% at 200. Fixing that scaling ceiling is the active line of work, and the measurements are published rather than buried.
Meshtastic and MeshCore are the established projects in this space and are worth your time. A technical comparison of all three, re-verified against upstream releases, is kept in the repo.
