gorrcbot — Autonomous RRC Bot & Field Assistant
gorrcbot is a headless, always-on RRC (Reticulum Relay Chat) bot and autonomous off-grid assistant. It operates as a client, not a hub: it connects to one or more RRC hubs simultaneously, joins configured rooms, maintains connectivity across link drops, and serves requests addressed to its nick or cryptographic identity hash.
Architecture & Principles
- A Thin CLI Over a Shared Engine: The sensors, the geodetic maths, the
field tools, the command registry, and the captive portal all live in the
library package
github.com/gmlewis/go-reticulum/bot, wheregrb— the Go Reticulum Buddy appliance — runs the very same code in-process.cmd/gorrcbotis only the command line and the Reticulum wiring, so a radio reply and a dashboard answer can never drift apart, andbot.Engine.Evalevaluates a command with zero hops and zero airtime. - Single Identity Everywhere:
gorrcbotgenerates one 64-byte Reticulum private identity (bot_identity) and uses it across all connected hubs. Its identity hash is identical on all hubs, allowing users to reach it using consistent address prefixes. - Strict Addressing Contract: The bot is completely silent unless addressed directly. It will never spam channels, and it completely ignores chat traffic not directed at it.
- Rate-Limiting & Cooldowns: A built-in per-identity cooldown answers a repeated question once inside its window, so a client that repeats a request cannot flood a room over a low-bandwidth LoRa link. A different question is always answered, a private request is held to a much shorter one-reply-per-second floor, and the
helplisting states the rule. - Offline First: The vast majority of tactical and field assistant commands (Plus Codes, geodesy, dead reckoning, sun/moon ephemeris, wilderness medicine cards, Morse code, unit conversions, and the cell/repeater finder with its built-in WGS-84 ↔ GCJ-02 conversion) compute entirely in-process with zero internet connection required. The marine, aviation, navigation, and communications-site catalogs are embedded too, so
search,near, andlistfind a station id before any provider is configured and while a provider is unreachable. - Low-Bandwidth by Design: Long answers are paginated to the operator's
max_reply_linesbudget, every page carries the exact command that asks for the next one, andmore/nextcontinue a walk through a catalog without retyping the query. - Graceful Telemetry Degradation: For commands that query external live telemetry (weather, marine tides, buoys, river gauges, flight tracking, space weather), providers are queried through sanitized HTTP/HTTPS templates. If an endpoint is unconfigured or unreachable, the bot reports honest failure without guessing or hallucinating.
Quickstart
1. First Run Bootstrap
Run gorrcbot without arguments:
On its very first invocation, gorrcbot:
1. Creates the storage directory ~/.gorrcbot/storage/.
2. Generates a fresh 64-byte private key file ~/.gorrcbot/bot_identity with restrictive permissions (0600).
3. Writes a fully documented, pre-populated default configuration file to ~/.gorrcbot/config.toml.
4. Prints a notice and exits cleanly with code 0, allowing you to review and configure hubs before establishing network connections.
2. Check Configuration
Perform a dry-run check without connecting to any hubs:
3. Normal Execution
Use --log-level DEBUG or --log-file /var/log/gorrcbot.log as desired.
Configuration Reference (~/.gorrcbot/config.toml)
Here is the complete configuration format with verified, working default providers:
# Top level: paths to identity and client storage
identity_path = "~/.gorrcbot/bot_identity"
storage_dir = "~/.gorrcbot/storage"
[bot]
# Advertised nickname and default trigger nick
nick = "gobot"
# Reply routing policy:
# "auto" - direct notices reply by direct notice; room queries reply to room
# "direct" - all replies are sent via direct notice (K_DST)
# "room" - all replies are posted to the room
reply = "auto"
# Minimum seconds between replies to the same user identity for the same
# request. A repeated request inside the window is not answered again; a
# different question is. A private request has its own one-second floor, and a
# page turn is never held.
cooldown_s = 8.0
# Introduce itself when joining rooms
announce_on_join = false
# Maximum reply lines before truncation occurs. A command whose whole answer is
# one indivisible picture (qr) declares its own budget and is not bound by this:
# a half-sent picture is not a shorter answer, it is an unreadable one.
max_reply_lines = 12
# Render the discovery rows (search/near/list) as clickable Micron links,
# which a NomadNet client shows as buttons and every other client shows
# literally. Leave false unless the room reads Micron.
micron_links = false
# ---------------------------------------------------------------------
# Live Telemetry & API Provider Templates
# ---------------------------------------------------------------------
# Weather via plain-text wttr.in endpoint (HTTP avoids expired TLS cert)
weather_url = "http://wttr.in/{place}?format=%l:+%C+%t+%w+%h"
# NOAA Tides & Currents API: 48-hour high/low water predictions
tide_url = "https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?product=predictions&datum=MLLW&time_zone=gmt&units=english&interval=hilo&format=json&station={place}&begin_date={date}&range=48"
# NOAA National Data Buoy Center: real-time sea state from ocean buoys
buoy_url = "https://www.ndbc.noaa.gov/data/realtime2/{place}.txt"
# USGS Streamflow & Gauge Height: instantaneous stage and discharge
river_url = "https://waterservices.usgs.gov/nwis/iv/?sites={place}&format=json¶meterCd=00065,00060&period=P1D"
# NOAA National Water Prediction Service: official flood stages
river_flood_url = "https://api.water.noaa.gov/nwps/v1/gauges/{place}"
# NOAA Space Weather Prediction Center: planetary K-index & geomagnetic storms
space_weather_url = "https://services.swpc.noaa.gov/products/noaa-planetary-k-index.json"
# Aviation Weather Center: raw METAR reports for airport ICAO codes
metar_url = "https://aviationweather.gov/api/data/metar?ids={place}&format=raw"
# National Weather Service: active weather alerts & warnings
weather_alert_url = "https://api.weather.gov/alerts/active?area={place}"
# The Space Devs: upcoming and past orbital rocket launches
launch_url = "https://ll.thespacedevs.com/2.3.0/launches/{mode}/?limit={limit}"
# ADSB.lol & ADS-B DB: live flight tracking and route decoding
flight_url = "https://api.adsb.lol/v2/callsign/{flight}"
flight_route_url = "https://api.adsbdb.com/v0/callsign/{flight}"
# ---------------------------------------------------------------------
# Offline Text, LXMF & Emergency Dispatch
# ---------------------------------------------------------------------
# Path to King James Bible text file (one verse per line).
# Full kjv.txt file available for download here:
# https://github.com/gmlewis/kjv-ref/blob/master/kjv.txt
kjv_txt_file = ""
# Optional local dataset for the tower/repeater/cell finder, merged over the
# cell, repeater, and emergency-site catalog embedded in the binary. The column
# order is fixed:
# id,name,type,lat,lng,freq,offset,tone,operator,city,region,country,elev
# type is RPT, CELL, EMERG, or MAR; coordinates are WGS-84 decimal degrees; a
# row whose id matches an embedded one replaces it, and a new id is added. The
# file may simply be dropped in at this path; it need not exist, and the
# command stays fully offline either way.
towers_path = "~/.gorrcbot/towers.csv"
# LXMF messaging support (msg/lxmf command)
lxmf_enabled = false
lxmf_propagation_node = ""
lxmf_announce_minutes = 360
# Optional 32-hex LXMF destination hash for emergency SOS beacons
emergency_lxmf_destination = ""
# ---------------------------------------------------------------------
# Go Reticulum Buddy (GRB): GNSS & the captive survival portal
# ---------------------------------------------------------------------
# GNSS receiver streaming NMEA-0183 sentences, for example /dev/ttyUSB0 or
# /dev/ttyACM0. It supplies the position that /whereami, "tower near",
# "tide near", "sun", and /sos use automatically.
gps_port = ""
# Static position for a node with no receiver (any location notation).
gps_fix = ""
# Electronic compass streaming NMEA-0183 heading sentences ($HCHDG, $HCHDM,
# $HCHDT), for example a QMC5883L or LSM303 magnetometer behind a serial
# bridge. It supplies the heading a GNSS receiver cannot while standing still.
compass_port = ""
# Static magnetic heading for a node with no compass sensor: degrees ("042")
# or a compass point ("NE"). The World Magnetic Model converts it to true north
# from the node's position.
compass_heading = ""
# Captive survival dashboard for any phone that joins this node's Wi-Fi:
# "127.0.0.1:8080" while testing, ":80" in the field. Empty binds nothing.
portal_addr = ""
# ---------------------------------------------------------------------
# Connected Hubs & Rooms
# ---------------------------------------------------------------------
[[hubs]]
name = "gonomadnet Public Hub"
destination = "a012129c10205c0b9441fcd2b755b2a7"
rooms = ["general"]
nick = ""
respond_to = { general = "gobot" }
How to Address the Bot
The bot answers when addressed in any of the following manners:
| Method | Example | Behavior |
|---|---|---|
| Room message with nick prefix | @gobot help |
Works in any room where the bot is present. Tolerates : or , suffix (@gobot: ping). |
| Room message with hash prefix | @a012129c help |
Addressed by the first 6+ hex characters of the bot's identity hash. |
Direct Notice (K_DST) |
/notice @gobot help or /msg gobot help |
Direct notices do not require typing @gobot. The bot replies directly back to the sender. |
Private Messaging to @gobot
While @gobot can be triggered publicly inside any room it has joined, private direct messaging is strongly recommended for most commands:
/msg gobot help
/msg gobot wx Denver
/msg gobot loc 849VCWC8+R9
/msg gobot sun 37.422,-122.084
/msg gobot checkin 849VCWC8+R9 overdue 4h Trail run to summit
From a shell: the
gobotCLI performs exactly this exchange without a chat client — it joins the hub, sends one/msg gobot ...line, prints the reply to stdout, and exits. Its hub destination is hard-coded to the official gonomadnet Public RRC Hub, sogobot helpreaches the official@gobotout of the box.
Why Private Messaging is Recommended
- Bandwidth Preservation on LoRa & Radio Meshes:
Reticulum channels often operate over bandwidth-constrained radio networks (such as LoRa at 1–5 kbps or VHF packet radio). Commands with verbose or multi-line responses (such as
help,metar,sun,weather,tide,loc,buoy, orkjv) take several seconds to transmit. Running them privately keeps shared room airtime clear for human peer conversation. - Operational Security (OPSEC) & Coordinate Privacy:
Commands such as
loc,proj,dist,sun,weather, and especiallycheckinorsitrepinvolve exact geographic coordinates, personal waypoints, or overdue travel timelines. Querying privately ensures that your physical location and itinerary are not broadcast to every listener on a public hub. - Channel Courtesy:
Queries for space weather (
spacewx), flight tracking (flight), marine buoys (buoy), or unit conversions (conv) generate chatter that may distract or interrupt other room participants.
(Note: Emergency distress beacons like @gobot sos should typically still be sent publicly to rooms so fellow operators and rescuers are alerted!)
How Private Addressing & Reply Routing Work
- Addressing Flexibility: In RRC,
/msg gobot <command>(or/dnotice gobot <command>) packages the message into a direct notice envelope withK_DSTset directly to the bot's 16-byte identity hash. Because the envelope itself addresses the bot, the trigger prefix is optional: /msg gobot help/msg gobot @gobot helpBoth work identically.- Strict Private Reply Guarantee: When a request arrives via direct notice (
K_DST),gorrcbot's reply routing policy always transmits the response as a direct notice back to the sender's cryptographic identity hash (msg.Src). The response never leaks or appears in any public room. - Direct Notice Capabilities (
CAP_DIRECT_NOTICE): Direct messaging requires that the connected hub supports RRC direct notice routing (CAP_DIRECT_NOTICE = 2), which all modernrrcdandgorrcdhubs provide. If a hub cannot deliver direct notices,gorrcbotsafely drops the direct reply rather than leaking it into a public channel.
Addresses & Scannable QR Codes (addr, qr)
Every RNS service a node runs is published from one identity, so one node has one identity hash and a different destination hash for each service. That is the single most confusing thing about Reticulum addresses, and it is the reason these two commands exist:
- The identity hash is what a hub knows a client by. It is not an address
you can send anything to; it is the name a destination is derived from. In a
room you reach a peer by typing
@<hash prefix>. - Each destination hash is the address of one service that identity
publishes.
lxmf.deliveryis where messages go;nomadnetwork.nodeis the node to browse;rrc.hubbelongs to a hub itself.
A destination hash covers the destination's name and the publishing identity's hash, and nothing else — so the bot can derive any peer's addresses from the identity hash alone, with no announce and no path required.
addr — every address a peer publishes
@gobot addr me
addr gonomadnet on MacM2Max: identity @0a8b370a62de4c5464b7ef7f56ff33c8 (the RNS identity, not a destination)
lxmf@2a6105f57145860441a62fe3b2a1352c (lxmf.delivery, where LXMF messages go)
bc37348ec27fafad10f3fd2e92ecf5f5 (nomadnetwork.node, the node to browse)
Every address is printed in the form a client acts on, because the RRC chat grammar already defines those forms and a client that knows them underlines them:
| Printed | What it is | Clicking it |
|---|---|---|
@<hash> |
an identity, the way a hub mention addresses a client | nothing — plain text, which is why addr prints it this way |
lxmf@<hash> |
an LXMF address | opens (or starts) the conversation |
<hash> |
a NomadNet node | opens the node browser |
#room |
a room on the hub you are already on | joins and selects that room |
rrc://<hub>[:<dest name>]/<room> |
a hub, and optionally a room on it | shows the Channels view and selects the hub or room; a hub you do not have yet is offered for confirmation before it is added |
The last two rows are links a person can type; rrc:// is the form a Micron page
uses, and a client that renders page links makes it clickable in chat too. A bare
hash is a link to a node, so printing a message address that way would invite
a reader to click it and be told the node does not exist — hence the sigils.
path <who> reports the route to the same destinations, with hops, next hop,
interface and path age.
qr — the same address as a picture a phone can scan
@gobot qr me
lxmf.delivery address for gonomadnet on MacM2Max (scan the picture below, or copy the address):
███████████████████████████
███▀▀▀▀▀▀▀████▀▀██▀▀█▀▀▀▀▀▀▀███
… 14 lines, one text line per two module rows …
████████████████████████████
< lxmf@2a6105f57145860441a62fe3b2a1352c >
full destination specifier: lxmf.delivery.0a8b370a62de4c5464b7ef7f56ff33c8:2a6105f57145860441a62fe3b2a1352c
qr [<nick|hash|me>] [identity|lxmf] draws the asker's own address by default,
or a named peer's, and encodes the bare address: what a camera reads is the
32-character hex string itself, which imports into any Reticulum client. The line
beneath the picture carries the sigil so a click does the right thing, and the
full specifier is printed for tools and configuration files.
What a reader has to know:
- The picture is text. Each cell is one QR module wide and half a module tall, so the usual 1:2 terminal cell draws a square module and a 25×25 code fits in 14 lines. It renders dark modules on a light field, which is what a camera expects on the light-on-dark terminal palette.
- It needs a message pane about 42 columns wide — 27 cells plus the timestamp and icon gutter. A narrower pane wraps the rows, which destroys the code rather than degrading it; hide the channel list, or widen the window, and the picture re-renders correctly because the client re-wraps the stored message text.
- It arrives whole. A picture is one indivisible answer, so it is sent under
its own line budget instead of
max_reply_lines; a truncated picture would not be a shorter answer but a wrong one. - The address line is copyable as well as scannable, and
addrprints the same addresses as text.
Station Discovery & Search (search, near, list)
Three of the field assistant's commands are useless without an identifier: tide
takes a 7-digit NOAA station id, buoy takes a 4–8 character NDBC station id,
and metar takes a 4-letter ICAO code. None of them can be guessed. Rather than
leave an operator to find one on another device, every one of those catalogs is
embedded in the binary and searched offline:
| Form | What it does | Example |
|---|---|---|
<cmd> search <query> [page] |
Case-insensitive match on the identifier, the name, the state or region, and (for metar) the city and IATA code. Every word of the query must appear somewhere in the row. |
@gobot tide search san francisco |
<cmd> near <place\|coords\|pluscode> |
The three rows closest to a position, nearest first, with the distance in nautical miles and the compass bearing. The argument may be a position in any of the five notations, a Plus Code, or a name or identifier from the catalog itself. | @gobot buoy near 37.8,-122.4 |
<cmd> list [state\|region] [page] |
Every row, or only those in a state (CA, OR, WA), a state's own name (california), or a basin or country code (GOM, ATL, CAR, GB). |
@gobot metar list CO |
The catalogs are data, not guesses, and they are read without touching the
network — which is the point. A station id is discoverable before the
operator has configured tide_url, buoy_url, or metar_url, and while that
provider is unreachable:
/msg gobot tide search san francisco
Tide stations matching "san francisco" (Page 1 of 1):
9414290: San Francisco (Golden Gate), CA
[Page 1 of 1: end of results]
/msg gobot tide near 849VCWC8+R9
Tide stations near 849VCWC8+R9 (Page 1 of 1):
9414750 (23.4 nmi NNW): Alameda, CA
9414764 (24.3 nmi NNW): Oakland Inner Harbor, CA
9414290 (29.4 nmi NW): San Francisco (Golden Gate), CA
[Page 1 of 1: end of results]
/msg gobot buoy list HI
Weather buoys in HI (Page 1 of 3):
51000: Northern Hawaii One, HI
51001: Northwestern Hawaii One, HI
51002: Southwest Hawaii, HI
51004: Southeast Hawaii, HI
[Page 1 of 3: ask "buoy list HI 2" or "more" for next]
/msg gobot metar search denver
Airports matching "denver" (Page 1 of 1):
KDEN: Denver International (CO)
KBJC: Rocky Mountain Metropolitan (CO)
[Page 1 of 1: end of results]
Once an id is known, the original form is unchanged and answers with live
telemetry: @gobot tide 9414290, @gobot buoy 46026, @gobot metar KDEN.
What Each Catalog Covers
| Command | Catalog | Size | Region codes |
|---|---|---|---|
tide |
Every NOAA CO-OPS tide-prediction station the provider publishes | ~3,500 stations | US state codes, plus PR, VI, GU, AS, MP |
buoy |
Every NDBC station that reports meteorological data, worldwide: Pacific, Atlantic, Gulf, Caribbean, Hawaii, Alaska, and the Great Lakes | ~900 stations | US state codes, plus ATL, GOM, CAR, PAC |
metar |
Every OurAirports field with an IATA code and scheduled service, worldwide | ~5,100 airfields | US state codes, plus two-letter country codes (GB, FR, JP, …) |
tower |
Hand-maintained mountain-top and regional communications sites: amateur repeaters, cellular masts, public-safety relays, and marine VHF stations, balanced between the United States and China with major international hubs | ~220 sites | US state codes, Chinese province codes (BJ, GD, SC, XJ, …), and country codes (US, CN, GB, JP, …) |
[!IMPORTANT] The
tide,buoy, andmetartables are the providers' catalogs in full, not a selection: a station is carried because it meets the filter in its file's header, sonearanswers with the genuinely nearest station anywhere on earth andsearch/listpage through the rest. Onlytoweris assembled by hand, because no public feed publishes a comparable site list.They are refreshed from the live public sources by
update-offline-data, which rewrites a table only when upstream differs and then reports it up to date. Thetowertable is the one dataset the tool does not touch.[!NOTE] A
metarregion may be a state code or a country code, and the two can collide (COis both Colorado and Colombia). A state always wins:metar list COlists Colorado, and Colombia's fields are reached by name —metar list colombia. The same rule applies toAR,CA,DE,ID,IN,MA, andTN. Every country code that does not collide works unchanged.
A station id that is not in a catalog is still accepted by its command, because each provider is authoritative about its own stations; the embedded catalog is a shortcut for finding the right one, not a filter on what may be asked.
Low-Bandwidth Pagination & more / next
A catalog answer is deliberately bite-sized. On a 1–5 kbps LoRa link a long
reply is not merely slow, it is truncated: the reply policy emits one NOTICE
per line and cuts anything past max_reply_lines. A page is therefore sized from
that same budget:
- Page size follows the budget. The bot reserves two of the
max_reply_lineslines for the header and the footer, and puts at most four rows on a page (max_reply_lines = 12→ 4 rows;max_reply_lines = 4→ 2 rows;max_reply_lines = 3→ 1 row). Raising the budget widens every page with no command change. - Every page says where it is. The first line names the query and the
position —
Tide stations in CA (Page 1 of 3):. - Every page says how to continue. The last line carries the exact command
for the next page, and the
moreshortcut:[Page 1 of 3: ask "tide list CA 2" or "more" for next]. The last page ends with[Page 3 of 3: end of results]. - Pages are explicit and repeatable.
<cmd> search <query> 2and<cmd> list CA 2reach page 2 directly, so a page can be quoted, shared, and re-read. A page past the end answerspage 9 not found (total 3 pages)instead of an empty reply.
The more and next Shortcuts
For a one-to-one private session, /msg gobot more (or /msg gobot next)
answers the page after the one just sent, with no need to retype the query:
/msg gobot tide list CA
Tide stations in CA (Page 1 of 3):
9410135: South San Diego Bay, CA
9410660: Los Angeles (Outer Harbor), CA
9410840: Santa Monica, Municipal Pier, CA
9410678: Long Beach Fire Boat Pier, CA
[Page 1 of 3: ask "tide list CA 2" or "more" for next]
/msg gobot more
Tide stations in CA (Page 2 of 3):
...
[Page 2 of 3: ask "tide list CA 3" or "more" for next]
- The pending page is remembered per identity, in memory only, for five minutes and for at most 256 requesters. Nothing is written to disk, a restart forgets every pager, and one asker's page is never handed to another.
- The cache holds the command for the next page, not the page itself, so a walk through a hundred rows costs a few bytes per asker and every page is rendered with its own correct footer.
- With nothing pending, or after the timeout, the answer is
no more pages or search expired. moreandnextare exempt from the per-identity cooldown, because a page turn answers a page the asker was just told to ask for and can only produce offline catalog rows. A private request is held to a one-second floor instead of the room cooldown, which never holds a person up but bounds an automated client. A repeated question inside the window is still answered only once; a different question is always answered.
Clickable Micron Links (micron_links)
A NomadNet client renders Micron markup, so the bot can offer the same pages as
buttons instead of as commands to retype. Set micron_links = true in
config.toml to render each row as a link to the command that fetches it, and
the footer as a Next Page link:
/msg gobot tide list OR
Tide stations in OR (Page 1 of 1):
["9432845":/msg gobot tide 9432845]: Coos Bay, OR
["9435308":/msg gobot tide 9435308]: Weiser Point, Yaquina River, OR
["9439040":/msg gobot tide 9439040]: Astoria (Tongue Point), Oreg., OR
["9439221":/msg gobot tide 9439221]: Portland Morrison Street Bridge, OR
[Page 1 of 1: end of results]
The option is off by default: an RRC NOTICE is plain text to every reader except a NomadNet one, and a link that is not rendered is just noise. The links address the nick the bot really answers to, so they work as written in the room they were sent to.
Cell & Radio Tower Finder (tower, repeater, cell)
tower answers the question that decides whether an off-grid party can
communicate at all: what transmits near here, which way is it, and how far?
The catalog, the geometry, and the coordinate conversion are all embedded in the
binary, so the answer is available with no network connection of any kind.
Why it matters
- Aiming a directional antenna. With a weak or unusable signal on a
rubber-duck antenna, a Yagi, log-periodic, or grid antenna pointed at the
right mast can hold an emergency uplink. What the operator needs is not a map
but a bearing and a distance — which is exactly what
tower nearprints. - Choosing a direction to walk. A stranded driver or hiker who has lost coverage needs to know which way regains it, and how far the walk is.
- Amateur radio when the cellular network is gone. Mountain-top VHF/UHF repeaters are frequently solar- and battery-backed and survive the event that took the commercial network down — but only if the operator knows the frequency, the offset, and the CTCSS/PL tone.
- Public safety and marine channels. Search-and-rescue relays and coastal marine VHF stations are in the same catalog, so the same query reaches the people whose job the emergency is.
Syntax
tower near <place|coords|pluscode>
tower search <query> [page]
tower list [country|region] [page]
tower info <id>
more / next
repeater narrows the same catalog to amateur repeaters and cell (alias
mast) to cellular masts; every other sub-command works the same way.
Examples
A proximity answer names the three closest sites, with the distance, the bearing and compass point, the service, and the radio details needed to use the site:
/msg gobot tower near 37.7553,-122.4527
Tower sites near 37.7553,-122.4527 (Page 1 of 1):
W6PW-2M (0.0 km 0° N) [RPT]: 145.150 MHz -0.6 (PL 114.8) - Sutro Tower, San Francisco, CA
W6PW-70C (0.0 km 0° N) [RPT]: 442.700 MHz +5.0 (PL 114.8) - Sutro Tower 70cm, San Francisco, CA
US-CA-T042 (0.0 km 218° SW) [CELL]: Band 2/4/12/71 - Sutro Cell Mast, San Francisco, CA
[Page 1 of 1: end of results]
With a live compass heading and no typed argument, each row adds the relative steering instruction that aims an antenna at the site without arithmetic — see Radio direction finding:
/msg gobot tower near
W6PW-2M (14.2 km 144° True SE) [RPT]: 145.150 MHz -0.6 (PL 114.8) - Sutro Tower, San Francisco, CA [Turn 15° RIGHT · 1 o'clock]
Search and list are offline lookups over the whole catalog, and both paginate to the reply budget:
/msg gobot tower search sutro
Tower sites matching "sutro" (Page 1 of 1):
W6PW-2M: Sutro Tower, San Francisco, CA
W6PW-70C: Sutro Tower 70cm, San Francisco, CA
US-CA-T042: Sutro Cell Mast, San Francisco, CA
[Page 1 of 1: end of results]
/msg gobot tower list BJ
Tower sites in BJ (Page 1 of 2):
BJ-RPT-01: Xiangshan Relay, Beijing, BJ
BJ-RPT-02: Miaofengshan Relay, Beijing, BJ
BJ-RPT-03: Beijing Central Radio Tower, Beijing, BJ
BJ-RPT-04: Wuling Mountain Relay, Beijing, BJ
[Page 1 of 2: ask "tower list BJ 2" or "more" for next]
tower info renders one site in full — both datums, the Maidenhead grid an
operator signs with, the elevation, and every radio detail:
/msg gobot tower info W6PW-2M
W6PW-2M [RPT]: Sutro Tower, San Francisco, CA
WGS-84 37.755300, -122.452700 | Maidenhead CM87ss | elevation 254 m | Amateur repeater
145.150 MHz, offset -0.6 MHz, tone 114.8 Hz, operator W6PW
International parity: the United States and China
The catalog is deliberately balanced between the United States and China, with a selection of major international hubs, because the same tool has to be as useful on the Sichuan–Tibet highway as it is on a Colorado fourteener. Chinese entries carry province codes and pinyin place names, so an operator who thinks in English and an operator who knows the two-letter code both reach the same rows:
/msg gobot tower search beijing
/msg gobot tower search sichuan
/msg gobot tower list GD
/msg gobot tower near 30.05,101.96
WGS-84 ↔ GCJ-02 ("Mars coordinates") conversion. China mandates that domestic maps publish coordinates in GCJ-02, which is GPS with a deliberately non-linear offset of several hundred meters. A coordinate copied out of Amap, Gaode, Tencent Maps, or WeChat and fed to a GPS receiver lands in the wrong street, and a GPS coordinate dropped into Amap lands several hundred meters away. The bot handles both directions:
- A site inside China prints its GCJ-02 coordinate alongside the WGS-84 one, ready to paste into a Chinese map app:
/msg gobot tower near 39.9055,116.3976
Tower sites near 39.9055,116.3976 (Page 1 of 1):
CN-BJ-T001 (0.4 km 359° N) [CELL]: Band 3/8/41 - China Mobile Beijing Mast, Beijing, BJ, CN
BJ-E001 (0.8 km 100° E) [EMERG]: 439.000 MHz -5.0 (PL 88.5) - Beijing Emergency Comms, Beijing, BJ, CN
BJ-RPT-03 (6.1 km 76° ENE) [RPT]: 438.500 MHz -5.0 (PL 88.5) - Beijing Central Radio Tower, Beijing, BJ, CN
GCJ-02 CN-BJ-T001 (paste into Amap/Gaode/WeChat): 39.910204, 116.403744
[Page 1 of 1: end of results]
- A GCJ-02 coordinate is handed back to the bot with a
gcj:(orgcj02:) prefix, anywhere a location is accepted, and is converted to the GPS position behind it first. Nothing outside China is ever moved: the conversion is applied only inside the mandated bounding box, so every foreign coordinate round-trips bit-for-bit.
The inverse transform is recovered by fixed-point refinement of the published forward equations, converging to better than a centimeter.
Region and country filters
tower list accepts a region code (CA, CO, BJ, GD, SC, XJ), a US
state's name (california), a country code (US, CN, GB, JP), or a
country's name (china, germany, canada).
[!NOTE] A two-letter code that is a US state names the state, so
tower list CAis California rather than Canada, andtower list DEis Delaware rather than Germany — those countries are reached by name (tower list canada,tower list germany). A Chinese province that shares a US state's code is still listed beside it, because the region itself matches:tower list SCcovers South Carolina and Sichuan, andtower list SD,NM, andHIsimilarly cover both countries' regions of that name.
Using a local dataset (towers.csv)
The embedded tower list is a planning reference, not a live directory. An operator
who needs micro-cell density — for example an OpenCelliD extract reduced to the
area of operations — drops a CSV at the path configured as towers_path
(by default towers.csv beside config.toml) and every query sees it:
id,name,type,lat,lng,freq,offset,tone,operator,city,region,country,elev
W6PW-2M,Local Sutro Repeater,RPT,37.7600,-122.4500,146.100 MHz,-0.6 MHz,100.0 Hz,W6LOCAL,San Francisco,CA,US,250
ZZ-OP-0001,Ops Ridge Mast,CELL,39.0000,-120.0000,Band 2/4/12,,,OpsNet,Testville,CA,US,1200
- The column order is fixed:
id,name,type,lat,lng,freq,offset,tone,operator,city,region,country,elev. typeisRPT,CELL,EMERG, orMAR(the wordsrepeater,cellular,emergency, andmaritimeare accepted too).latandlngare WGS-84 decimal degrees; the GCJ-02 conversion is applied on display.- A row whose
idmatches an embedded one replaces it, so a corrected frequency is corrected everywhere at once; a newidis added. - The header line is optional,
#comments are ignored, and a malformed row is skipped with a log line naming it rather than silently shortening the file. - An absent file is normal, and an unreadable one degrades to the embedded catalog: a bad export can never cost the tool its built-in data.
Offline guarantee
Nothing in a tower query touches the network. There is no provider URL for
this command and no configuration it needs: the catalog is compiled into the
binary, the distance, bearing, and datum arithmetic are closed form, and the
only file it ever reads is an optional local dataset. It is the one discovery
command that is fully useful before its operator has configured anything at all.
The Go Reticulum Buddy (GRB)
The Go Reticulum Buddy (GRB) is the role gorrcbot plays on a
pocket-sized, off-grid survival communicator: a device that replaces a
$300–$600 commercial satellite messenger and its monthly subscription with an
inexpensive, open-source node that works when every link has already failed.
The appliance itself is grb
This section describes the survival intelligence gorrcbot shares with the
appliance. To run the whole appliance — Reticulum, the GNSS receiver and
compass, the zero-hop field assistant, and the captive dashboard the phone
reads — use grb, which mounts the very same
bot engine
in-process.
It obeys one rule above all others, the Autonomous Local Intelligence Rule:
Survival intelligence must run locally, in-process. Emergency medicine, nearby masts, the sun, and "where am I?" answer in microseconds with 0 radio hops, 0 airtime, and 0 RF emissions.
Everything in this section therefore works with the radio switched off, with no internet, and with no account.
GNSS / GPS receiver integration
gorrcbot speaks NMEA-0183 directly, with no Cgo driver and no third-party
library. It reads $GNRMC / $GPRMC (position, time, date, validity, speed,
course) and $GNGGA / $GPGGA (fix quality, satellites, HDOP, altitude,
geoidal separation), validates the XOR checksum of every sentence byte-for-byte,
and merges the rotation of sentences a receiver emits into one live fix. A
sentence that fails validation is dropped silently: a corrupted sentence is a
wrong position, and a wrong position is worse than no position at all.
Two [bot] keys configure the source:
# A streaming receiver, for example /dev/ttyUSB0 or /dev/ttyACM0.
# The port must already be configured for the receiver's line speed.
gps_port = ""
# A static position for a headless node, a fixed relay, or an operator
# rehearsing the field tools. Accepts every location notation below.
gps_fix = "37.7553,-122.4527"
With neither key set, the node simply has no position, and every command that
would use one says so instead of guessing. With gps_port set, the sentences
are parsed in the background as they arrive; with gps_fix, the position is
constant and no device is opened.
Every position-aware command shares one receiver, so the radio reply and the web dashboard can never disagree about where the device is.
Electronic compass, true north & direction finding
A GNSS receiver has one blind spot that matters most exactly when it hurts: it derives course over ground from motion, so an operator who is standing still — injured, pinned down by weather, lost in fog, or aiming a Yagi at a mountain-top repeater — has no heading at all. The receiver reports the last course it saw, noise, or nothing.
Pairing the node with an inexpensive 3-axis magnetometer (a QMC5883L or an
LSM303 on I2C, behind any serial bridge) removes that blind spot. gorrcbot
reads the standard marine/electronic heading sentences directly, with the same
pure-Go NMEA parser and the same byte-for-byte XOR checksum validation it uses
for the receiver:
| Sentence | Carries | Example |
|---|---|---|
$HCHDG |
Magnetic heading, deviation, and variation | $HCHDG,101.1,,,13.1,E*1B → 101.1° magnetic, +13.1° east → 114.2° true |
$HCHDM |
Magnetic heading only | $HCHDM,101.1,M*28 |
$HCHDT |
True heading only | $HCHDT,114.2,T*2F |
A sentence that fails its checksum is dropped in silence, because a corrupted heading is a wrong direction, and a wrong direction is worse than none.
# A streaming compass, for example /dev/ttyUSB1 or /dev/ttyACM1.
compass_port = ""
# Or a static magnetic heading for a node with no sensor.
compass_heading = "042" # or "NE"
With neither key set, the node simply has no heading, and every answer that
would use one says so instead of guessing. With compass_port set, the
sentences are parsed in the background as they arrive; with compass_heading,
the bearing is constant and no device is opened.
True north, automatically. A magnetic compass points at magnetic north,
which is not the north a map, a bearing, or a rescue grid uses — the difference
ranges from a fraction of a degree to more than twenty depending on where the
operator stands, and thirteen degrees of error at fourteen kilometers is more
than three kilometers of error. gorrcbot therefore converts every magnetic
heading to true north with the World Magnetic Model (WMM2025), evaluated in
pure Go from the published spherical-harmonic coefficient table: no data files,
no network, no third-party library. The model reproduces its own published test
vectors to the precision they are printed at, and its declination is checked
against the reference values for San Francisco, Denver, Boston, London, and
Tokyo.
Three sources of variation are used in that order of preference:
- The variation field of the sentence itself (
$HCHDG), which the instrument measured where it stands. - The World Magnetic Model at the node's live GNSS fix, which is what
turns a
$HCHDMmagnetic heading into a true one with no operator input. - Nothing at all, when the node has neither — in which case the heading is reported as magnetic and labelled as such everywhere, never passed off as true north.
/whereami — the operational location card
whereami (also typed /whereami) prints the card an operator reads before
moving, assembled entirely from the in-tree geodetic engines:
/whereami
------------------------------------------------------------
Plus Code (OLC) : 849VQG4W+4W (Area: ~14m x 14m)
Coordinates : 37.75532° N, 122.45272° W
Maidenhead Grid : CM87ss (Amateur Radio QTH)
Elevation : 142 m (467 ft) MSL
Heading / Course : 042° True (029° Mag, Var: +13.0° E) · NE
GNSS Fix Status : 3D Fix (9 satellites, HDOP 0.8)
Local Solar Time : 12:45 UTC-8 (Solar noon: 12:04)
Sunset Countdown : Sunset at 18:15 (5h 29m daylight remaining)
------------------------------------------------------------
The Heading / Course line appears only when the device actually has a heading, and only on the card about the device's own position — a heading describes which way the operator is facing, so printing it beside a remote coordinate would invite the reader to think the two belong together. The line never claims more than it knows:
| State | Line |
|---|---|
| Variation known (sentence or WMM) | 042° True (029° Mag, Var: +13.0° E) · NE |
True only ($HCHDT) |
042° True · NE |
| Magnetic only (no position) | 029° Mag · NNE |
| No compass at all | the line is omitted cleanly; the card is unchanged |
Every notation is there because somebody else needs it: a Plus Code is what a dispatcher can paste into a map, a Maidenhead square is what an amateur operator logs, decimal degrees are what a GPS unit takes, and — inside China — the GCJ-02 pair is the only form Amap, Gaode, Tencent Maps, and WeChat accept, so the card adds that line for a position in China.
| Form | Example | Notes |
|---|---|---|
| No argument | @gobot whereami |
Uses the live GNSS fix, or reports that it is acquiring one. |
| Coordinates | @gobot whereami 37.7553,-122.4527 |
Places a remote position; the card says manual position and shows no altitude, because no receiver reported one. |
| Plus Code | @gobot whereami 849VQG4W+4W |
Any notation loc accepts works. |
| Maidenhead grid | @gobot whereami CM87ss |
The square's own center. |
The eleven-character high-precision Plus Code (about 3 m by 3 m) is computed alongside the ten-character code and is carried by the dashboard's JSON API rather than printed on the card.
The local solar time is the zone the position's own longitude defines —
round(longitude / 15) hours — because a node with no timezone database cannot
honestly claim to know an operator's civil zone or whether summer time is in
force. Solar noon and the sunset countdown are computed against that same clock,
for the operator's local calendar day.
Zero-argument automatic context injection
A person with cold hands, in the dark, does not want to type coordinates. When a GNSS fix is live, the field commands inherit it automatically:
| Command | With a fix | Without a fix |
|---|---|---|
tower near |
The three closest masts and repeaters to the operator's own position — and, with a live compass heading, the relative turn that aims an antenna at each one. | Asks for <place\|coords\|pluscode>. |
cell near, repeater near, mast near |
Same, for one service. | Same. |
tide near |
The three closest tide stations, offline. | Asks for a location. |
sun |
The almanac at the current position; sun 2026-06-21 keeps the date and takes the position from the fix. |
Asks for a location. |
sos |
Raises a RED beacon at the verified position. | Asks for <loc> <TRIAGE> <details>. |
sos RED two hikers, one leg fracture |
Raises the beacon at the fix with the triage and details given. | Same as above. |
A beacon raised from the fix attaches the receiver facts to the record and to the reply — satellites, HDOP, altitude, fix quality, and the receiver's own timestamp — so a rescue party reading the registry after the link has failed knows not just where the beacon is but how much the position can be trusted:
[SOS #1 RECORDED] RED @ 849VQG4W+4W by @gobot: two hikers, one leg fracture | Alerted 2 rooms
GNSS fix: 3D fix, 9 satellites, HDOP 0.8, 142 m MSL, fix quality 1, 2026-09-16T20:45:33Z
A typed location always wins: sos 39.7392,-104.9903 RED climber hurt stays
about the climber in Denver, never about the device's own position. And with no
fix at all, the automatic fallback never fires, so a mistyped request can never
become a beacon somewhere arbitrary.
Radio direction finding: aiming an antenna in one step
A bearing is a fact; a turn is an instruction. With a live heading, a
zero-argument tower near stops printing a bearing to interpret and starts
printing the turn to make:
/msg gobot tower near
Tower sites near 849VQG4W+4W (Page 1 of 1):
W6PW-2M (14.2 km 144° True SE) [RPT]: 145.150 MHz -0.6 (PL 114.8) - Sutro Tower, San Francisco, CA [Turn 15° RIGHT · 1 o'clock]
W6PW-70C (14.6 km 148° True SSE) [RPT]: 442.700 MHz +5.0 (PL 114.8) - Sutro Tower 70cm, San Francisco, CA [Turn 19° RIGHT · 2 o'clock]
US-CA-T042 (15.1 km 139° True SE) [CELL]: Band 2/4/12/71 - Sutro Cell Mast, San Francisco, CA [Turn 10° RIGHT · 1 o'clock]
[Page 1 of 1: end of results]
The instruction is a real clock face — twelve straight ahead, three to the right, six behind, nine to the left — so it can be acted on in the dark without arithmetic:
| Relative bearing | Instruction |
|---|---|
| within ±5° | [Ahead · 12 o'clock] |
| +5° to +165° | [Turn X° RIGHT · N o'clock] |
| −165° to −5° | [Turn X° LEFT · N o'clock] |
| beyond ±165° | [Behind · 6 o'clock] |
The steering appears only when it is meaningful, which is a deliberately narrow condition: the answer must be about the device's own position (a live or static fix, no typed argument) and the heading must be true, never magnetic. A target bearing is a true bearing, so steering against an uncorrected magnetic heading would send the operator off by the local variation. A named place, or a node with no compass, gets exactly the distance-and-bearing answer it always got.
Captive portal & smartphone dashboard
Set one key and the device serves a survival dashboard to any phone that joins its Wi-Fi:
Nothing is installed, because the page is the binary: one self-contained HTML document with inline CSS and JavaScript and zero external references — no stylesheet, font, image, or script from a network. A traveler's phone in airplane mode opens it with the browser it already has.
The portal answers the captive-network probes the operating systems use, so the phone's native captive browser opens the dashboard by itself instead of reporting "connected, no internet":
| Probe | Operating system |
|---|---|
/hotspot-detect.html |
Apple iOS and macOS |
/generate_204, /gen_204 |
Android |
/ncsi.txt, /connecttest.txt |
Windows |
Each probe is answered with a 302 redirect to / and Cache-Control:
no-store.
| Endpoint | Method | Purpose |
|---|---|---|
/ |
GET |
The dashboard: the large Plus Code with a Copy Plus Code button, coordinates, grid, elevation, fix status, the local solar clock, the sunset countdown, the live compass rose, the red SOS button (with a confirmation dialog), and the field-assistant chat box. |
/api/whereami |
GET |
The current fix and its full geodetic synthesis as JSON: both Plus Codes, the grid, the coordinates, altitude, speed, course, satellites, HDOP, fix quality, the local solar clock, the sunset, the GCJ-02 pair inside China, the live heading, and the card's own lines. |
/api/compass |
GET |
The live compass reading as JSON, with the nearest communications site the rose vectors toward: {"valid": true, "mag_deg": 29, "true_deg": 42, "declination_deg": 13, "cardinal": "NE", "target": {"kind": "site", "id": "W6PW-2M", "name": "Sutro Tower", "bearing_deg": 144.4, "distance_km": 0.0, "steering": "[Turn 102° RIGHT · 3 o'clock]"}}. It answers even with no GNSS fix, because a compass works standing still. |
/api/query |
POST |
Runs one local command and returns its reply lines: {"command": "med hypothermia"} → {"command": "med hypothermia", "lines": ["[HYPOTHERMIA] …"]}. An addressed nick and a leading slash are both accepted, so @gobot med hypothermia, /med hypothermia, and med hypothermia are the same request. |
The live compass rose
The dashboard carries a north-up compass dial: a blue needle at the device's own heading and a red needle at the nearest repeater — or at an active SOS beacon, which outranks every routine site, because an operator looking at the phone is looking for a person — together with the digital true and magnetic readouts, the local variation, and the target's distance, frequency, and steering instruction:
Compass & Direction Finding
N
W E 042° NE
S True 042° (var +13.0° E)
Mag 029°
Sutro Tower · 14.2 km at 144° · 145.150 MHz -0.6 (PL 114.8) [Turn 102° RIGHT · 3 o'clock]
■ Your heading ■ Beacon or nearest site
With an unresolved beacon in the registry the red needle and the vector line switch to it instead:
The dial is drawn entirely with inline SVG and CSS — no image, no external font, no script from a network — so it renders on a phone in airplane mode with the browser it already has. It refreshes on the same ten-second cadence as the rest of the page, and a node with no compass shows a sentence in place of the dial rather than a needle pointing at nothing.
The chat box is restricted to the commands whose answers are computed
in-process — med (first aid), tower near, tide near, sun, whereami,
morse, conv, and the rest of the offline field set. A command that needs a
live radio link answers with a line saying exactly that, rather than failing
obscurely.
The SOS button asks for confirmation, then raises a RED beacon through the same registry command the radio uses: the beacon is persisted, every room of every live hub session is alerted, and the LXMF dispatch copy is queued when one is configured. A device with no hub currently connected still records the beacon and says that no room could be alerted.
Complete Command Reference
Core & Administration
| Command | Syntax | Description & Example |
|---|---|---|
help |
@gobot help [category\|command] |
Lists the command categories, lists one category's commands, or provides comprehensive help for a specific command (e.g. @gobot help loc, @gobot help messaging). An abbreviated name works when it begins exactly one category, command or alias (@gobot help env is the environment group, @gobot help where is whereami); a name that could mean several lists them, and a name that means none still answers with the one-line hint rather than nothing. |
ping |
@gobot ping |
Responds pong to verify link liveness and latency. |
uptime |
@gobot uptime |
Reports bot uptime, hub connection duration, and hub identity hash. |
whoami |
@gobot whoami |
Displays your nickname and full 32-character identity hash as seen by the current hub. |
botinfo |
@gobot botinfo |
Details the bot's identity hash, @hash-prefix alias, version, connected hubs, and active rooms (alias id). |
rooms |
@gobot rooms [room] |
Lists the rooms the bot is participating in; with a room named, lists the members the hub reports in it (alias members). |
addr (alias address, addresses) |
@gobot addr [<nick\|hash\|me>] |
Lists every address the peer's identity publishes — the identity hash a hub knows them by, then lxmf.delivery and nomadnetwork.node — each in the form a client turns into a working link (see Addresses & Scannable QR Codes). |
qr |
@gobot qr [<nick\|hash\|me>] [identity\|lxmf] |
Draws that address as a scannable black-and-white picture with the address and its full specifier beneath it; lxmf (the default) draws the message address and identity the RNS identity hash (see Addresses & Scannable QR Codes). |
seen |
@gobot seen <nick\|hash> |
Shows the timestamp when a given nick or identity hash was last seen speaking in joined rooms. |
more |
@gobot more |
Shows the next page of the last search, near, or list answer (alias next; see Low-Bandwidth Pagination). The pending page is remembered per identity for 5 minutes; with nothing pending the answer is no more pages or search expired. |
Private & Direct Messaging
| Command | Syntax | Description & Example |
|---|---|---|
dnotice (alias dn) |
@gobot dnotice <nick\|hash\|me> <text> |
Sends an encrypted direct notice (K_DST) to the specified client. |
dnoticecap |
@gobot dnoticecap [target] |
Checks if the current hub supports direct notice delivery, and checks if a target user is online. |
dnoticeme |
@gobot dnoticeme <text> |
Sends a direct notice to your own identity (tests private path functionality). |
msg (alias lxmf) |
@gobot msg <nick\|hash> <text> |
Queues an asynchronous LXMF message to an offline peer via propagation nodes. |
Network & Mesh Diagnostics
| Command | Syntax | Description & Example |
|---|---|---|
path |
@gobot path <nick\|hash\|name> |
Queries the Reticulum routing table to report hops, next-hop interface, and path age to every destination a peer's identity publishes. A name is one the bot has heard announce. |
watch |
@gobot watch <name\|hash> [ttl] |
Requests a direct notice when a peer, node, or hub announces on the network. |
unwatch |
@gobot unwatch <n\|all> |
Cancels an active watch. |
watches |
@gobot watches |
Lists your active announce watches and remaining TTLs. |
net |
@gobot net [hops] [near <loc>] |
Mesh directory: every announced hub, LXMF node, and NomadNet node with its hop count and the interface its path leaves by. The hop limit defaults to 3. near <loc> is accepted, but an announce carries no position, so it explains why the list cannot be filtered by distance instead of pretending to filter it. |
catchup |
@gobot catchup [room] [window] |
Delivers messages from joined rooms that were missed while you were offline. <window> is a duration like 30m, 2h, or 1d and defaults to 24 h; <room> limits the digest to one room. Either may be given on its own and in either order: a duration-shaped word is the window, and any other word names a joined room. |
search |
@gobot search <term> [#room] |
Searches recent room history for messages containing the given keyword. |
Offline Geodesy & Navigation
All location commands accept 5 coordinate notations without network connectivity:
1. Open Location Code / Plus Codes: 849VCWC8+R9
2. Decimal Degrees: 37.42205, -122.08409 or N37.42205 W122.08409
3. Degrees & Decimal Minutes (DDM): 37°25.323'N 122°05.048'W
4. Degrees, Minutes & Seconds (DMS): 37°25'19"N 122°05'03"W
5. Maidenhead Grid Locator: CM87uk
A sixth input form is a GCJ-02 "Mars coordinate" copied from a Chinese map
app (Amap/Gaode, Tencent, WeChat), marked with a gcj: or gcj02: prefix:
loc gcj:39.9069,116.4038 or tower near gcj:39.9069,116.4038. It is converted
back to the WGS-84 GPS position before anything else is computed. See
Cell & Radio Tower Finder.
A Plus Code may also arrive shortened, the way a phone screen shows it and a
person reads it out: CWC8+R9, or CG4J+32P with its last digit. The leading
characters that name the region have been dropped, so the node completes them
against its own live GNSS fix — which is the search-and-rescue case the notation
exists in: a position read off the missing party's screen has to land on the map
of the team searching for them. On a node with no receiver there is nothing to
complete the code against, and the reply says exactly that instead of calling a
valid code unreadable; the full code, or a coordinate pair, works either way.
A shortened code is placed in the matching cell nearest the reader, so it resolves to the sender's own region while the two are within about half a degree of each other — some tens of kilometres. A code that has travelled further than that cannot say which region was meant, so a position being passed over a long link should be sent in full; the answer always prints the full code it resolved, which is how a reader sees the region that was picked.
| Command | Syntax | Description & Example |
|---|---|---|
loc |
@gobot loc <pluscode\|coords\|grid> |
Converts any supported coordinate format and outputs it in all five notations simultaneously. A position inside China also prints the GCJ-02 "Mars coordinate" that Amap and Gaode expect. |
dist |
@gobot dist <from> <to> |
Calculates great-circle distance (km, statute miles, nautical miles) and forward/reverse bearings between two points. |
proj |
@gobot proj <origin> <bearing°> <distance> |
Dead reckoning: calculates the destination coordinate from a starting location, course, and distance (e.g. @gobot proj CM87uk 045 15km). |
whereami |
@gobot whereami [pluscode\|coords\|grid] |
The operational location card: Plus Code, coordinates, Maidenhead grid, elevation, the heading, fix status, local solar time, and the sunset countdown. With no argument it uses the live GNSS fix, and every notation loc accepts works as an argument. Also accepted as /whereami. See The Go Reticulum Buddy. |
Celestial & Ephemeris
| Command | Syntax | Description & Example |
|---|---|---|
sun (alias solar) |
@gobot sun <pluscode\|coords\|grid> [date] |
Computes UTC sunrise, sunset, civil twilight dawn/dusk, and total daylight hours for any location on Earth. With no location it uses the live GNSS fix, and a bare date (sun 2026-06-21) keeps the date while taking the position from the fix. The solar alias names this command, where the word reads as a reader expects; space weather is spacewx. |
moon |
@gobot moon [place\|pluscode\|coords] [date] |
Reports moon phase, illumination percentage, lunar age, moonrise/moonset, nighttime illumination rating, and upcoming spring/neap tides. With no place it reports the phase alone. |
Emergency, Search & Rescue, and Field Operations
| Command | Syntax | Description & Example |
|---|---|---|
sos |
@gobot sos [loc] [RED\|YELLOW\|GREEN\|INFO] [details] |
Broadcasts an emergency distress beacon across all rooms, confirms receipt to sender, persists beacon to disk, and dispatches via LXMF to emergency responders. With no location, and with a live GNSS fix, the beacon is raised at the operator's own position (RED by default) and the receiver facts are attached. |
sos list |
@gobot sos list |
Lists all active distress beacons. |
sos clear |
@gobot sos clear <id> |
Resolves and clears an SOS beacon (restricted to the original sender). |
checkin |
@gobot checkin <loc> overdue <duration> <note> |
Arms an overdue dead-man timer (e.g. overdue 4h). If not cleared before expiry, the bot raises an automatic overdue alarm. |
checkin ok |
@gobot checkin ok |
Clears your active overdue check-in timer. |
sitrep add |
@gobot sitrep add <loc> <HAZARD\|RESOURCE\|SHELTER\|ROAD\|INFO> <text> |
Files a geolocated situation report to the 7-day tactical board. |
sitrep near |
@gobot sitrep near <loc> [radius_km] |
Finds situation reports within the specified radius, sorted nearest-first. |
Wilderness Medicine & Tactical Survival
| Command | Syntax | Description & Example |
|---|---|---|
firstaid (aliases rx, med, triage) |
@gobot firstaid <topic> |
Offline clinical decision-support cards for wilderness medicine: bleed, cpr, triage, shock, hypo (hypothermia), heat, burns, water, snake. med is the short name the field guides and the portal chat box use. |
coldwater (alias immersion) |
@gobot coldwater [temp_f\|temp_c] |
1-10-1 cold water survival rule and swim failure timelines for water temperatures (e.g. @gobot coldwater 48F). |
signal |
@gobot signal [air\|sound\|light] |
Distress signaling standards: ground-to-air visual markers (V, X, N, Y), whistle cadences, mirror/torch patterns. |
morse |
@gobot morse <text> / @gobot morse -d <code...> |
Bidirectional Morse code encoder and decoder. |
conv |
@gobot conv <val><unit> <target> |
Tactical unit conversions: barometric pressure (29.92inHg → hPa), distance, speed, fuel/water weight, and battery watt-hours (5000mAh@3.7V → Wh). |
Marine, Aviation & Space Telemetry
| Command | Syntax | Description & Example |
|---|---|---|
weather (alias wx) |
@gobot weather <location> |
Live conditions from plain-text weather feed. |
tide |
@gobot tide <station\|coords\|place> [date] |
48-hour high/low water predictions, Rule of Twelfths hourly depth interpolation, and spring/neap tide classification. |
tide search |
@gobot tide search <query> [page] |
Finds a station offline by name, state, or id, four per page. |
tide near |
@gobot tide near [place\|coords\|pluscode] |
The three closest stations, with distance in nautical miles and bearing. With no argument it uses the live GNSS fix. |
tide list |
@gobot tide list [state] [page] |
Every station, or one state's (CA, OR, WA, AK, HI, …). |
buoy |
@gobot buoy <buoy_id> |
Real-time ocean buoy sea state: wave height, dominant wave period, swell vs chop classification, water temp, pressure trend. |
buoy search |
@gobot buoy search <query> [page] |
Finds a buoy offline by place, id, region, or state. |
buoy near |
@gobot buoy near <place\|coords\|pluscode> |
The three closest buoys, with distance in nautical miles and bearing. |
buoy list |
@gobot buoy list [region\|state] [page] |
Every buoy, or one region's (CA, HI, AK, GOM, ATL, …). |
river |
@gobot river <usgs_gauge_id> |
Stream gauge stage, discharge rate, 3-hour trend, and official NOAA river forecast flood categories. |
metar |
@gobot metar <ICAO> |
Decodes raw aviation weather reports into wind, visibility, temperature, dewpoint, and altimeter setting in both units. |
metar search |
@gobot metar search <city\|name\|code> [page] |
Finds an airfield offline by city, airport name, ICAO code, or IATA code (denver, heathrow, KDEN, LHR). |
metar near |
@gobot metar near <place\|coords\|pluscode> |
The three closest airfields, with distance in nautical miles and bearing. |
metar list |
@gobot metar list [state\|country] [page] |
Every airfield, or one state's or country's (CO, CA, TX, GB, JP, …). |
alerts (alias wxalert) |
@gobot alerts <place\|area> |
Queries active National Weather Service severe weather warnings and advisories. |
spacewx |
@gobot spacewx [set sfi=N ssn=N kp=N] |
Reports Solar Flux Index (SFI), Sunspot Number (SSN), K-index, geomagnetic storm levels, and recommended HF propagation bands. The reading is cached for an hour, and with no provider reachable it reports the last reading it has; set overrides the observed indices by hand, which is what an operator does when the feed is unreachable and the numbers came in over a voice net. |
launches |
@gobot launches [upcoming\|past] [1-5] |
Schedules and status of upcoming orbital space launches, or the most recent ones. |
flight |
@gobot flight <number> |
Real-time ADS-B flight telemetry: route, altitude, groundspeed, climb rate, and squawk code. |
Cell & Radio Tower Finder
| Command | Syntax | Description & Example |
|---|---|---|
tower |
@gobot tower near [place\|coords\|pluscode] |
The three closest communications sites, with the distance in kilometers, the bearing, the service, the frequency with its offset and tone, and the place. Entirely offline; a site inside China also prints the GCJ-02 coordinate for Amap/Gaode/WeChat. With no argument beyond near it uses the live GNSS fix, and with a live compass heading it adds the relative steering instruction that aims an antenna — [Turn 15° RIGHT · 1 o'clock]. See Cell & Radio Tower Finder and Radio direction finding. |
repeater |
@gobot repeater near [place\|coords\|pluscode] |
The same finder narrowed to amateur repeaters (RPT sites) only, so "the nearest repeater" is one word. repeater search and repeater list work as tower's do. |
cell (alias mast) |
@gobot cell near [place\|coords\|pluscode] |
The same finder narrowed to cellular base stations (CELL sites) only. cell search and cell list work as tower's do. |
tower search |
@gobot tower search <query> [page] |
Finds a site offline by callsign, identifier, name, city, pinyin place name, state or province, frequency, or operator (sutro, beijing, sichuan, 145.150, china mobile). |
tower list |
@gobot tower list [country\|region] [page] |
Every site, or one country's (US, CN, GB), one country's by name (china, germany), one US state's (CA, CO) or its name, or one Chinese province's (BJ, GD, SC, XJ). |
tower info |
@gobot tower info <id> |
One site in full: the exact WGS-84 position, the GCJ-02 position when the site is in China, the Maidenhead grid, the elevation, the frequency, the offset, the tone, and the operator. |
Reference & Texts
| Command | Syntax | Description & Example |
|---|---|---|
kjv |
@gobot kjv <reference\|words\|regex> |
Looks up a Bible verse or searches the King James text. A reference (jn3:16, Psalm 23:1-6, ps23, 1 jn 2 1) prints the whole verse with its label; words (shepherd, love of god, "the love of God" for a phrase) search for verses containing them; love\|charity, lov*, l?ve and l[ai]ve search with alternation and wildcards, love -hate excludes verses, and love.*life is a regexp. Needs kjv_txt_file in config.toml pointing at a King James text file, one verse per line. |
Deploying as a Systemd Service
To run gorrcbot as a persistent Linux service:
Create /etc/systemd/system/gorrcbot.service:
[Unit]
Description=Go Reticulum RRC Bot Daemon
After=network.target
[Service]
Type=simple
User=reticulum
Group=reticulum
ExecStart=/usr/local/bin/gorrcbot --bot-config /var/lib/gorrcbot/config.toml
Environment=GORRCBOT_HOME=/var/lib/gorrcbot
Restart=always
RestartSec=10
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
Enable and start the service: