grb — the Go Reticulum Buddy
grb is the Go Reticulum Buddy: a sovereign, pocket-sized off-grid
survival communicator and field assistant in one executable.
The same application is designed to run on an ultra-low-power ESP32-C5 as
bare-metal firmware and, unchanged in behaviour, on a workstation. grb is the
workstation half of that promise, and it is the reference the firmware is
measured against. There is no second implementation to drift out of sync: the
field tools, the sensors, and the dashboard are one library
(github.com/gmlewis/go-reticulum/bot)
that both the appliance
and the RRC chat bot run.
The Golden Architecture Rule
Survival intelligence runs locally, in-process, with zero radio hops and zero airtime. A first-aid card, a repeater bearing, the sunset, or the position card must resolve in microseconds, in RAM, whether or not a single packet can be sent. Long-range radio is reserved for what radio is for: distress beacons, coordinating with rescue teams, peer messaging, and syncing with a hub only when a gateway happens to be reachable.
Important Safety, Emergency & Medical Notice
GRB is NOT a certified life-safety device, distress beacon, or medical device. Transmissions occur over best-effort unlicensed radio frequencies with NO guarantee of packet delivery, acknowledgement, or rescue. This system is NOT connected to official 911/112 dispatch, civil defense agencies, or search-and-rescue satellites. Under no circumstances should this system be used as a primary or sole means of summoning emergency rescue or medical assistance. Always carry certified primary safety equipment (EPIRB/PLB, paper maps, magnetic compass). Read the full Legal, Safety, Emergency, and Medical Disclaimer below before building or operating this device.
What it runs
One grb process brings up four things, in this order:
| Subsystem | What it is | When it runs |
|---|---|---|
| Reticulum | A local RNS stack, configured by rns.config_path |
Always |
| Sensors | A pure-Go NMEA-0183 GNSS receiver and electronic compass, or their static fallbacks | When a port or a static value is configured |
| Field assistant | The shared in-process command engine (bot.Engine): whereami, med, tower, sun, moon, sos, checkin, morse, conv, firstaid, and the rest |
Always |
| Captive dashboard | An HTTP dashboard and JSON API for a smartphone browser | When portal_addr is set |
Shutdown is the reverse, so nothing is left reading a device or holding a
socket. grb exits 0 on a clean exit, 1 on an operational failure, and
2 on a usage error.
The sovereign appliance model
Commercial satellite messengers cost $300–$600 and charge $15–$65 per month; if the subscription lapses, the emergency hardware is remotely deactivated. They also cannot tell you what to do about hypothermia, cannot find the nearest amateur repeater, and cannot function without a satellite link.
grb inverts all three properties:
- No subscription, no account, no app store. The knowledge is compiled in.
- No vendor silo. It speaks Reticulum, so it talks to any Reticulum peer, any RRC hub, any LXMF destination, and any amateur operator running the same open stack.
- No link required for the answers that matter. The survival tools are pure mathematics and embedded static tables, so a canyon, a wet tree canopy, or a ridgeline between you and the nearest relay changes nothing about the first-aid card or the position card.
The zero-hardware UI paradigm
Sourcing a custom LCD, a physical keyboard, and an injection-moulded case is what drives open communicators to $80–$150 and produces fragile gadgets with tiny keys. Almost every traveller already carries a better terminal: a phone with a high-resolution touchscreen and a modern browser, whose Wi-Fi and browser keep working in airplane mode with zero cellular coverage.
So grb serves the dashboard over HTTP and lets the phone be the screen:
- On the ESP32-C5 target, the appliance brings up a Wi-Fi 6 SoftAP
(
Reticulum-Buddy-[ID]); the phone joins it and its operating system pops the dashboard up by itself. - On a desktop workstation,
grbhosts the same dashboard onportal_addrwith no root privileges and without touching the host's Wi-Fi adapters. Open http://localhost:9111/ in any browser — including the one on the phone next to you, when you bind0.0.0.0:9111.
Either way the URL routing is identical, because every captive-probe route the
common operating systems already request answers with 302 Found → /:
| Probe route | Requested by |
|---|---|
/generate_204, /gen_204 |
Android |
/hotspot-detect.html |
Apple iOS and macOS |
/ncsi.txt, /connecttest.txt |
Windows |
The dashboard
| Card | What it shows |
|---|---|
| Where Am I | Plus Code (with a copy button), coordinates, Maidenhead grid, elevation, GNSS fix quality, local solar time, and the sunset countdown |
| Compass & Direction Finding | A live compass rose with a second needle vectored at the nearest repeater, cell site, or active distress beacon, and the relative turn that aims an antenna at it |
| Emergency | A single-button SOS that raises a distress beacon at the verified position |
| Field Assistant | A query box that runs the same offline commands the radio answers, with zero hops |
JSON API
The dashboard is a client of its own API, so a widget, a second screen, or a script can poll the same facts:
| Method | Path | Answer |
|---|---|---|
GET |
/api/whereami |
The operational card as JSON, including plus_code, coordinates, maidenhead, sunset_countdown, lines (the card exactly as the radio renders it), and a live heading |
GET |
/api/compass |
The live heading: magnetic, true, the local variation, the cardinal sector, and the nearest site or beacon |
POST |
/api/query |
Runs one offline command. Body: {"command": "med hypothermia"} (or {"text": "..."}) |
$ curl -s http://localhost:9111/api/whereami | python3 -m json.tool
$ curl -s -X POST http://localhost:9111/api/query \
-d '{"command":"tower near"}' | python3 -m json.tool
Quick start on a desktop
grb writes a fully commented ~/.grb/config.toml on the first run and keeps
running — it needs no editing to be useful. Open
http://localhost:9111/ and the dashboard is live.
With no hardware attached at all, the appliance still works: set a
static_fix and a static_heading and every position-aware tool answers from
them. That is how the same configuration serves a desk and a trail.
# A rehearsed appliance on a desk, with a static position and heading:
$ ./bin/grb --gps-port '' --portal-addr 0.0.0.0:9111
To see exactly which file and which devices an appliance resolved:
$ ./bin/grb --verbose
2026/01/01 12:00:00 grb: configuration /Users/you/.grb/config.toml: callsign GRB-NOMAD, ...
2026/01/01 12:00:00 grb: static GNSS fix 37.7553,-122.4527
2026/01/01 12:00:00 grb: static compass heading 042
2026/01/01 12:00:00 grb: captive portal on http://127.0.0.1:9111/
Command-line flags
| Flag | Meaning |
|---|---|
-config PATH |
Configuration file to use. Default: $GRB_HOME/config.toml, or ~/.grb/config.toml |
-portal-addr ADDR |
Dashboard listen address, like 127.0.0.1:9111 or 0.0.0.0:9111. An empty value disables the dashboard |
-gps-port PORT |
GNSS receiver serial port, like /dev/tty.usbserial-0001 or /dev/ttyUSB0 |
-compass-port PORT |
Electronic compass serial port, like /dev/tty.usbserial-0002 or /dev/ttyUSB1 |
-quiet |
Only report errors |
-verbose |
Print the resolved configuration and run the Reticulum log at INFO |
-version, -V |
Print the version and exit |
-h, -help |
Print the usage text and exit |
Every flag is an override: a flag that is not given leaves the configuration file's value alone, and an override is validated with exactly the same wording as a bad file, so a typo on the command line is reported before anything binds.
GRB_HOME overrides the appliance's home directory (used literally, with no
expansion). It is how a second appliance — or a test — stays isolated on one
workstation.
Configuration reference
~/.grb/config.toml is a TOML document. Every value below is the built-in
default, and the file grb generates is those defaults, with comments. A
configuration with no file at all still runs.
A leading ~ expands to your home directory in storage_dir,
rns.config_path, gnss.port, and compass.port.
[device]
| Key | Default | Meaning |
|---|---|---|
callsign |
"GRB-NOMAD" |
The name the appliance answers to on the mesh. The default is deliberately fictional — replace it before transmitting |
nickname |
"" |
An optional shorter name used on the air. Empty means "use the callsign" |
storage_dir |
~/.grb/storage |
Where the appliance keeps distress beacons, situation reports, check-in timers, and saved history |
[portal]
| Key | Default | Meaning |
|---|---|---|
portal_addr |
"127.0.0.1:9111" |
The dashboard's listen address. Empty disables it entirely — no listener is bound |
| Value | Effect |
|---|---|
127.0.0.1:9111 |
Desktop testing mode. Reachable only from this workstation, at http://localhost:9111/. Nothing is exposed to the local network |
0.0.0.0:9111 |
Field / LAN mode. Reachable from every device on the same network at http://<this-host>:9111/. Use this to test the real smartphone experience before you have hardware |
:9111 |
Reachable on every interface and address family |
| (empty) | No dashboard at all. The field assistant is still complete and still answers |
[gnss]
| Key | Default | Meaning |
|---|---|---|
port |
"" |
The NMEA-0183 receiver device, e.g. /dev/tty.usbserial-0001 (macOS) or /dev/ttyUSB0 (Linux) |
baud |
9600 |
The receiver's line speed. See the note below |
static_fix |
"" |
A fixed position in any notation whereami accepts, e.g. "37.7553,-122.4527". Used when no receiver is attached (or when no port is set) |
Line speed
The shared NMEA reader opens the device read-only without reconfiguring
its line speed, because changing it requires platform-specific termios
ioctls that the standard library does not expose. A fresh USB-UART adapter
is conventionally already at 9600, which is the default here. If your
receiver needs another speed, set it on the device (stty -f /dev/ttyUSB0
38400) or rely on the receiver's own auto-baud. baud records the intended
hardware profile, and is the value the ESP32-C5 firmware's UART setup uses,
so one configuration describes both targets.
[compass]
| Key | Default | Meaning |
|---|---|---|
port |
"" |
The NMEA-0183 compass device, e.g. /dev/tty.usbserial-0002 or /dev/ttyUSB1 |
baud |
9600 |
The compass's line speed (same note as above) |
static_heading |
"" |
A fixed magnetic heading in degrees, e.g. "042". Used when no compass is attached |
A magnetic heading is converted to true north with the World Magnetic Model at the device's own position, so the dashboard and the field tools never disagree about which way you are facing.
[rns]
| Key | Default | Meaning |
|---|---|---|
config_path |
"" |
The Reticulum configuration directory this appliance uses. Empty means the Reticulum default, ~/.reticulum |
[mesh]
| Key | Default | Meaning |
|---|---|---|
rooms |
["general", "emergency"] |
The RRC rooms this appliance joins when a hub is reachable, and serves from its own local broker when one is not |
Hardware wiring on a desktop
Both peripherals are ordinary USB-UART serial adapters. No driver, no
library, no Cgo: grb reads NMEA-0183 ASCII sentences directly.
| Platform | Typical device names |
|---|---|
| macOS | /dev/tty.usbserial-*, /dev/tty.usbmodem-*, /dev/cu.usbserial-* |
| Linux Mint / Ubuntu | /dev/ttyUSB*, /dev/ttyACM* |
Find yours by listing the device nodes before and after plugging the adapter in:
Then name them in the configuration:
[gnss]
port = "/dev/ttyUSB0"
baud = 9600
static_fix = "37.7553,-122.4527" # ignored while port is set
[compass]
port = "/dev/ttyUSB1"
baud = 9600
static_heading = "042" # ignored while port is set
Notes for the bench:
static_fixandstatic_headingremain in the file while a port is set. The port wins, so unplugging the receiver degrades to the last known position instead of to nothing.- On macOS prefer the callout device (
/dev/cu.usbserial-*) if the callin device (/dev/tty.usbserial-*) reportsEBUSYwith nothing holding it — the callin device waits on the modem-control lock. - Permissions: on Linux, add yourself to the
dialoutgroup (then log back in) rather than runninggrbas root. - Both peripherals are optional and independent. A receiver with no compass gives the position card; a compass with no receiver gives the heading, since a compass works standing still and a receiver that has not locked does not.
- The reader expects the conventional 9600 8N1 NMEA stream:
$GNRMC/$GNGGAfor position and$HCHDG/$HCHDMfor heading.
The appliance in the field
- The appliance sits in a pocket or carabiner-clipped to a pack, listening.
- The traveller opens Wi-Fi settings and taps
Reticulum-Buddy-[ID]. - The phone's captive-portal probe is answered with a redirect, so the dashboard pops up by itself — no app, no store, no account.
- The traveller reads the Plus Code aloud to a rescue team, steers an antenna
at the nearest repeater, or asks the assistant
med snakebite. - The phone goes back in the pocket; the appliance keeps listening, caching what arrives.
To rehearse step 2–3 before you have hardware, bind 0.0.0.0:9111 on a laptop
and open http://<laptop-ip>:9111/ from the phone.
Architecture: the shared bot package
grb contains almost no survival logic of its own. Everything it answers with
lives in github.com/gmlewis/go-reticulum/bot, which is also
what gorrcbot runs — so the radio reply and the dashboard answer can never
drift apart:
go-reticulum/
├── bot/ # the shared engine: sensors, geodetics, field tools, portal
│ ├── bot.go # package documentation and the RRC engine
│ ├── engine.go # Engine.Eval — the zero-hop in-process evaluator
│ ├── run.go # Options/Run — the whole RRC bot appliance
│ ├── commands.go # the command registry and its policy
│ ├── gps.go, compass.go # NMEA-0183 readers (or static providers)
│ ├── declination.go # WMM2025 magnetic declination
│ ├── geo.go, olc.go # geodetics, Maidenhead grids, Plus Codes
│ ├── whereami.go # the operational card and its JSON form
│ ├── portal.go # the captive HTTP daemon and JSON API
│ └── portal-page.go # the mobile dashboard
├── cmd/
│ ├── gorrcbot/ # a thin CLI wrapper: flags + bot.Run
│ └── grb/ # the appliance: flags, config, and App
grb's own code is only the parts that are specific to being an appliance:
| File | What it does |
|---|---|
main.go |
Flags, configuration loading and overrides, signal handling, exit codes |
flags.go |
The CLI contract: usageText and a package-local parser |
config.go |
~/.grb/config.toml: parsing, defaults, validation, ~ expansion |
app.go |
The lifecycle: Reticulum → sensors → engine → dashboard, and back down |
Because bot.Engine opens no socket and starts no goroutine, an appliance whose
dashboard is switched off still has a complete offline field assistant
available to any caller, and an appliance whose radio cannot start is reported
rather than silently downgraded.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
could not start Reticulum |
rns.config_path names a directory Reticulum cannot use. An empty value means ~/.reticulum |
| Dashboard unreachable from a phone | portal_addr is still 127.0.0.1:9111 (this workstation only). Set 0.0.0.0:9111 |
listen ... address already in use |
Another process holds the port (often a previous grb). Change portal_addr, or find the holder with lsof -i :9111 |
whereami says no fix |
No receiver is attached and no static_fix is set. Set one, or check the port and permissions |
| Heading is magnetic-only | A compass is attached but there is no position, so the WMM correction has nothing to work from. Set a fix |
portal.portal_addr: want host:port |
A typo such as localhost or 127.0.0.1 with no port. Use host:port |
Security notes
- The configuration file is created mode
0600and is never rewritten once it exists, so an operator's edits are the only source of truth. - The default
portal_addrbinds the loopback interface only. Nothing about your position or heading is exposed to the local network until you deliberately choose0.0.0.0or a specific interface. - The dashboard is a read-mostly local surface: it runs only the commands that compute their answer in-process. A command that needs a live hub link says so rather than failing.
- The appliance holds its own cryptographic identity via Reticulum; there is no account, no telemetry, and no vendor service in the path.
Legal, Safety, Emergency, and Medical Disclaimer
PLEASE READ THIS DISCLAIMER CAREFULLY BEFORE USING ANY SOFTWARE, HARDWARE DESIGNS, OR DOCUMENTATION CONTAINED IN THIS REPOSITORY.
1. NOT A CERTIFIED LIFE-SAFETY DEVICE / NO GUARANTEE OF RESCUE
The software and hardware designs in this repository (including, but not limited to, the Go Reticulum Buddy (GRB), cmd/grb, cmd/gorrcbot, cmd/gobot, and associated Reticulum/LXMF implementations):
- Operate on Unlicensed, Best-Effort Frequencies: Transmissions occur over unlicensed, low-power Industrial, Scientific, and Medical (ISM) radio bands (such as 868 MHz / 915 MHz LoRa) and ad-hoc wireless networks. Communications are subject to packet loss, radio frequency interference, terrain blockage, antenna limitations, battery depletion, and complete network unavailability.
- NO Guaranteed Delivery or Acknowledgement: Delivery of any message, emergency beacon, packet, or distress call (
/sos) is never guaranteed. - NOT Connected to Official Emergency Dispatch: This system is NOT connected to official 911/112 Public Safety Answering Points (PSAPs), government emergency services, civil defense agencies, or COSPAS-SARSAT search-and-rescue satellites.
- NOT a Certified Distress Beacon: This system is NOT a certified Emergency Position Indicating Radio Beacon (EPIRB), Personal Locator Beacon (PLB), or certified commercial satellite emergency notification device (such as Garmin inReach® or SPOT®).
- DO NOT RELY ON THIS SYSTEM FOR LIFE SAFETY: Under no circumstances should this system be used as a primary, sole, or dependable means of summoning emergency rescue, medical assistance, or disaster evacuation. Always carry certified emergency signaling devices and register travel plans with appropriate authorities.
2. NOT A CERTIFIED MEDICAL DEVICE / INFORMATIONAL DECISION SUPPORT ONLY
The medical reference protocols, first-aid decision cards, cold water survival estimates, and triage guidelines provided within this software (including, but not limited to, the med and firstaid commands):
- Informational & Educational Reference Only: Content is compiled from general public wilderness medicine guidelines and is intended solely for offline educational and informational reference in remote situations where professional care is unavailable.
- NOT Professional Medical Advice: The software does NOT provide medical diagnosis, clinical prognosis, prescription, or certified medical treatment.
- NO Patient-Provider Relationship: Use of this software does not create a doctor-patient, provider-patient, or first-responder duty or relationship of any kind.
- Always Seek Professional Medical Attention: In any emergency, immediately seek professional medical assistance from licensed medical personnel as soon as possible.
3. NOT FOR PRIMARY NAVIGATION / DATA ACCURACY DISCLAIMER
The navigation, geodetic, ephemeris, and radio-frequency guidance provided by this software (including, but not limited to, /whereami, Open Location Code (OLC) Plus Codes, Maidenhead grid locators, astronomical calculations (sun, moon), magnetic declination estimates (WMM), offshore weather buoy coordinates, tide stations, and cellular/repeater tower catalogs (tower near)):
- Subject to Inaccuracy and Drift: GNSS/GPS fixes may suffer from multipath distortion, atmospheric degradation, jamming, or loss of lock. Electronic compasses and magnetic declination models are subject to local magnetic anomalies, tilt errors, and calibration drift. Astronomical and tidal approximations may differ from local observed conditions.
- Static Catalogs May Be Stale or Inaccurate: Tower, repeater, buoy, and airfield databases are static reference snapshots and may not reflect decommissioned sites, changed frequencies, CTCSS tone modifications, or temporary outages.
- NOT for Primary Navigation: Never use this system as your sole or primary tool for maritime, aeronautical, mountaineering, or wilderness navigation. Always carry dedicated primary navigation equipment, including official up-to-date topographical paper charts, a calibrated magnetic lensatic compass, and an altimeter.
4. RF AND REGULATORY COMPLIANCE
Radio frequency transmission equipment constructed or operated using software or hardware specifications from this repository must strictly comply with local, national, and international telecommunications regulations (such as FCC Part 15 / Part 97 in the United States, ETSI in the European Union, etc.):
- Operator Responsibility: The operator bears sole responsibility for verifying frequency allocations, maximum effective radiated power (ERP), duty cycle limits, channel bandwidth, antenna gain, and amateur radio licensing requirements.
- NO Representation of Compliance: The authors and contributors make no representations or warranties that any configuration complies with radio transmission regulations in your jurisdiction.
5. HARDWARE AND BATTERY HAZARDS
Hardware prototypes, breadboards, printed circuit boards (PCBs), and battery systems described in documentation (including lithium-ion 18650 cells, charging modules, and antennas):
- Fire and Explosion Risk: Lithium-ion batteries carry inherent risks of thermal runaway, fire, toxic gas release, and explosion if short-circuited, punctured, overcharged, overheated, or improperly managed.
- User Assumes All Fabrication Risks: The user assumes all risks associated with soldering, assembly, component sourcing, wiring, power supplies, and field deployment.
6. EXPRESS ASSUMPTION OF RISK AND TOTAL RELEASE OF LIABILITY
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW:
- AS-IS PROVISION: All software, source code, hardware designs, firmware, datasets, and documentation are provided "AS IS" and "AS AVAILABLE," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, ACCURACY, COMPLETENESS, RELIABILITY, TITLE, OR NON-INFRINGEMENT.
- TOTAL RELEASE OF LIABILITY: IN NO EVENT SHALL THE AUTHORS, CONTRIBUTORS, COPYRIGHT HOLDERS, OR DISTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, CONSEQUENTIAL, OR COMPENSATORY DAMAGES WHATSOEVER (INCLUDING, BUT NOT LIMITED TO, LOSS OF LIFE, PERSONAL INJURY, BODILY HARM, ILLNESS, PAIN AND SUFFERING, EMOTIONAL DISTRESS, WRONGFUL DEATH, PROPERTY DAMAGE, LOSS OF RESCUE OPPORTUNITY, SEARCH-AND-RESCUE EXPENSES, LOSS OF DATA, EQUIPMENT FAILURE, OR BUSINESS INTERRUPTION), REGARDLESS OF CAUSE AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR GROSS NEGLIGENCE), ARISING IN ANY WAY OUT OF THE USE OF, RECONSTRUCTION OF, OR RELIANCE UPON THIS SOFTWARE, HARDWARE, DATA, OR DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- INDEMNIFICATION: BY USING, BUILDING, RUNNING, OR DISTRIBUTING THIS SYSTEM, YOU AGREE TO INDEMNIFY, DEFEND, AND HOLD HARMLESS THE AUTHORS AND CONTRIBUTORS FROM ANY AND ALL CLAIMS, LAWSUITS, DEMANDS, LIABILITIES, OR COSTS ARISING FROM YOUR USE, MISUSE, OR DEPLOYMENT OF THIS SYSTEM.
See also
- gorrcbot — the same engine as an always-on RRC chat bot
- gobot — one-shot CLI for asking a live bot a single question
- GRB Hardware Project Plans — full GRB puck architecture, BOM table, and ESP32-C5 pinout
- Hardware guides — LoRa RNodes, carrier boards, and serial adapters
- ASIC Plans §6.9–§6.12 — the full GRB design, BOM, and pinout