Skip to content

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, where grb — the Go Reticulum Buddy appliance — runs the very same code in-process. cmd/gorrcbot is only the command line and the Reticulum wiring, so a radio reply and a dashboard answer can never drift apart, and bot.Engine.Eval evaluates a command with zero hops and zero airtime.
  • Single Identity Everywhere: gorrcbot generates 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 help listing 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, and list find 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_lines budget, every page carries the exact command that asks for the next one, and more / next continue 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:

gorrcbot

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:

gorrcbot --check-config

3. Normal Execution

gorrcbot

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&parameterCd=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 gobot CLI 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, so gobot help reaches the official @gobot out of the box.

  1. 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, or kjv) take several seconds to transmit. Running them privately keeps shared room airtime clear for human peer conversation.
  2. Operational Security (OPSEC) & Coordinate Privacy: Commands such as loc, proj, dist, sun, weather, and especially checkin or sitrep involve 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.
  3. 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 with K_DST set 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 help Both 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 modern rrcd and gorrcd hubs provide. If a hub cannot deliver direct notices, gorrcbot safely 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.delivery is where messages go; nomadnetwork.node is the node to browse; rrc.hub belongs 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 addr prints 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, and metar tables are the providers' catalogs in full, not a selection: a station is carried because it meets the filter in its file's header, so near answers with the genuinely nearest station anywhere on earth and search / list page through the rest. Only tower is 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. The tower table is the one dataset the tool does not touch.

[!NOTE] A metar region may be a state code or a country code, and the two can collide (CO is both Colorado and Colombia). A state always wins: metar list CO lists Colorado, and Colombia's fields are reached by name — metar list colombia. The same rule applies to AR, CA, DE, ID, IN, MA, and TN. 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_lines lines 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 more shortcut: [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> 2 and <cmd> list CA 2 reach page 2 directly, so a page can be quoted, shared, and re-read. A page past the end answers page 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.
  • more and next are 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.

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

  1. 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 near prints.
  2. 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.
  3. 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.
  4. 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: (or gcj02:) 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.
/msg gobot tower near gcj:39.9069,116.4038
/msg gobot loc gcj:39.9069,116.4038

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 CA is California rather than Canada, and tower list DE is 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 SC covers South Carolina and Sichuan, and tower list SD, NM, and HI similarly 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.
  • type is RPT, CELL, EMERG, or MAR (the words repeater, cellular, emergency, and maritime are accepted too).
  • lat and lng are WGS-84 decimal degrees; the GCJ-02 conversion is applied on display.
  • A row whose id matches an embedded one replaces it, so a corrected frequency is corrected everywhere at once; a new id is 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:

  1. The variation field of the sentence itself ($HCHDG), which the instrument measured where it stands.
  2. The World Magnetic Model at the node's live GNSS fix, which is what turns a $HCHDM magnetic heading into a true one with no operator input.
  3. 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:

# "127.0.0.1:8080" while testing, ":80" in the field. Empty binds nothing.
portal_addr = ":80"

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:

                     SOS RED beacon · 0.6 km at 088° [Turn 46° RIGHT · 2 o'clock]

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:

sudo systemctl daemon-reload
sudo systemctl enable --now gorrcbot
sudo journalctl -u gorrcbot -f