Reticulum Protocol & Micron Markup Extensions
This document defines extensions introduced by the Go Reticulum and Go NomadNet projects to the RRC (Reticulum Relay Chat) protocol and the Micron page markup language.
All extensions are designed with strict backward compatibility:
- Systems that support the extensions gain new capabilities.
- Legacy clients and hubs gracefully ignore or cleanly degrade without errors or dropped packets.
- Complete Python reference implementation guides are provided so that authors of rrcd and nomadnet can easily back-port these features.
1. RRC Capability: CAP_PRIVATE_COMMAND = 3
1.1 Overview & Motivation
Standard RRC (rrcd) defines four operator slash commands — /who (alias /names), /list, /stats, and /reload — and has no private-message command at all. Slash commands could only be issued from within an active chat room, and reaching another participant directly required knowing their raw 16-byte cryptographic destination hash. While the hub intercepts slash commands before room fanout, this design had significant drawbacks:
1. A client had to join a room before issuing administrative or query commands.
2. In buggy or third-party client implementations, private slash commands could accidentally leak into public room history.
3. A client could not send a direct message simply by knowing a user's nickname; the hub had to resolve it, and stock rrcd offered no way to ask.
CAP_PRIVATE_COMMAND = 3 introduces a private out-of-band command channel between a client and an RRC hub using direct notices (T_NOTICE, type 21) addressed to the hub's own identity.
1.2 Capability Advertisement
In the RRC WELCOME envelope body key 2 (BWelcomeCaps, CBOR map of integer capability IDs to booleans):
Standard RRC Hub Capabilities:
0: CAP_RESOURCE_ENVELOPE (Resource envelope transfer)
1: CAP_ACTION (IRC-style /me actions)
2: CAP_DIRECT_NOTICE (Client-to-client direct notices via K_DST)
Extension:
3: CAP_PRIVATE_COMMAND (Hub accepts direct notices as private commands)
When enabled on the hub, the capabilities map sent in WELCOME contains:
Clients MUST check HasCapability(3) before attempting to send private commands to a hub. If a hub does not advertise capability 3, direct notices addressed to the hub identity will be rejected as "destination not connected".
1.3 Command Names & Target Resolution
The capability exposes one family of client commands. The canonical name is
/dnotice; /dn and /msg are accepted aliases, and /msg is the spelling the
gonomadnet client uses:
| Command line | Example | Behaviour |
|---|---|---|
/dnotice <target> <text> (aliases /dn, /msg) |
/msg alice Meeting at 18:00 UTC |
Delivers one direct notice to <target> alone. |
/dnoticeme <text> |
/dnoticeme on my way |
Delivers one direct notice to the sender's own link. |
/dnoticecap |
/dnoticecap |
Reports whether the hub advertises CAP_PRIVATE_COMMAND. |
<target> is resolved by the hub and accepts, in order:
- a full 32-hex-character identity hash;
- an unambiguous hex prefix of at least six characters;
- a participant nickname.
Resolution is exact. A token that matches more than one participant is
reported with nothing sent, and there is no fuzzy matching, so a private
message cannot reach a participant the sender did not name. A nickname that
contains spaces must be quoted — /msg 'gonomadnet on MiniPC' yo dude — because
the argument is forwarded exactly as typed.
These are ordinary client commands, so a user may also type them from inside a
room; the hub's confirmation then lands in that room rather than in a private
view. In gonomadnet, /msg <nick|hash> <text> echoes the line you typed
exactly as typed, and an arriving private notice renders as private from
<nick>.
1.4 Wire Protocol & Message Flow
+--------+ +--------+
| Client | | Hub |
+--------+ +--------+
| |
| 1. Connect & WELCOME (captures hub identity hash) |
|<----------------------------------------------------------|
| WELCOME carries Caps: {..., 3: True} |
| |
| 2. Direct Notice to Hub Identity: |
| T_NOTICE (21) |
| KSrc = <client_identity_hash> |
| KDst = <hub_identity_hash> |
| KRoom = nil |
| KBody = "/dnotice alice Meeting at 18:00 UTC" |
|---------------------------------------------------------->|
| | [Hub resolves "alice"]
| | [Routes to Alice's link]
| 3. Direct Notice Reply from Hub: |
| T_NOTICE (21) |
| KSrc = <hub_identity_hash> |
| KDst = <client_identity_hash> |
| KBody = "Direct notice delivered to alice" |
|<----------------------------------------------------------|
Envelope Specification
When transmitting a private command, the client constructs a standard RRC T_NOTICE (21) envelope:
| Key | CBOR Key Index | Type | Value / Description |
|---|---|---|---|
KSrc |
4 |
bytes |
Sender's 16-byte Reticulum identity hash. |
KDst |
8 |
bytes |
Hub's 16-byte identity hash (extracted from WELCOME source). |
KRoom |
5 |
nil |
Must be omitted or nil. Direct notices never specify a room. |
KNick |
7 |
text |
Sender's nickname (optional; normalized by hub). |
KBody |
6 |
text |
Command string starting with / (e.g. /msg alice hi, /dnotice alice hi, /who, /stats). |
KID |
2 |
bytes |
8-byte unique random message ID. |
KTS |
3 |
int |
Millisecond Unix timestamp. |
Hub Processing Rules
- When a hub receives a
T_NOTICEenvelope withKDstmatchinghub_identity_hash: - If
enable_private_commandsis false or capability 3 is not enabled, return an error notice:"destination not connected". - If
KRoomis present, reject with error notice:"direct notice must not include room". - If
KBodyis a text string starting with/:- Dispatch
KBodyto the hub's operator command handler (HandleOperatorCommand). - Route command output directly back to the sender's link via direct notice (
KDst = client_hash). - Neither the command line nor any reply is ever posted to any room.
- Dispatch
- If
KBodydoes not start with/or is unrecognized, return an error notice directly to the sender.
1.5 Python rrcd & RRC.py Reference Back-Port
In rrcd / Hub Daemon (RRC.py):
# 1. Define the capability constant:
CAP_PRIVATE_COMMAND = 3
# 2. In Hub configuration (config.py / __init__):
self.enable_private_commands = True # or read from config: config.get("enable_private_commands", True)
# 3. In Hub's WELCOME envelope generator:
caps = {
CAP_RESOURCE_ENVELOPE: True,
CAP_ACTION: True,
CAP_DIRECT_NOTICE: True,
}
if self.enable_private_commands:
caps[CAP_PRIVATE_COMMAND] = True
welcome_envelope[B_WELCOME_CAPS] = caps
# 4. In Hub's _handle_direct_notice method:
def _handle_direct_notice(self, link, env):
dst = env.get(K_DST)
if dst == self.identity.hash:
if self.enable_private_commands:
body = env.get(K_BODY)
if isinstance(body, str) and body.strip().startswith("/"):
# Handle command directly on link without room context:
handled = self.handle_operator_command(link, env.get(K_SRC), None, body.strip())
if not handled:
self.send_direct_notice(link, "Unrecognized command")
return
self.send_error(link, "destination not connected")
return
# ... regular peer-to-peer direct notice forwarding ...
In Client (RRC.py / Channels.py):
def send_private_command(self, text):
"""Sends a private slash command to the hub without entering any room."""
if not self.has_capability(CAP_PRIVATE_COMMAND):
raise RuntimeError("Hub does not support CAP_PRIVATE_COMMAND")
if not self.hub_identity:
raise RuntimeError("Hub identity unknown; wait for WELCOME")
# Construct direct notice envelope addressed to hub's identity hash
env = {
K_TYPE: T_NOTICE,
K_SRC: self.identity.hash,
K_DST: self.hub_identity,
K_NICK: self.effective_nick,
K_BODY: text,
K_MSGID: os.urandom(8),
K_TS: int(time.time() * 1000)
}
self.send_envelope(env)
2. Micron Extension: `T (Timestamp Localization)
2.1 Overview & Motivation
Micron pages travel over Reticulum across global timezones. A static timestamp written into a page (e.g. Updated: Sep 15 20:00 UTC or Meeting at 14:00 EST) forces every reader to calculate timezone offsets manually.
The `T extension allows pages to embed epoch timestamps in UTC seconds along with a standard strftime formatting template. The reader's NomadNet client renders the timestamp in the reader's own local timezone.
2.2 Syntax & Grammar
- Opening & Closing Delimiters:
`T(backtick followed by capitalT). <unix-seconds>: Base-10 integer Unix epoch seconds (UTC).<strftime-format>: Optional POSIXstrftimeformat string. If omitted, defaults to:"%a %b %d, %Y %-I:%M:%S%p %Z"(e.g.Tue Sep 15, 2026 8:46:25PM EDT).
Grammar (ABNF)
timestamp-directive = "`T" unix-seconds [ "|" strftime-format ] "`T"
unix-seconds = 1*12( %x30-39 ) ; 1 to 12 digits
strftime-format = 1*64( VCHAR / WSP ) ; format tokens
2.3 Supported strftime Tokens
| Token | Meaning | Example Output |
|---|---|---|
%Y |
4-digit year | 2026 |
%y |
2-digit zero-padded year (00-99) | 26 |
%m |
2-digit zero-padded month (01-12) | 09 |
%b, %h |
Abbreviated month name | Sep |
%B |
Full month name | September |
%d |
2-digit zero-padded day of month (01-31) | 15 |
%e |
2-character space-padded day of month ( 1-31) | 5 |
%H |
2-digit 24-hour clock hour (00-23) | 20 |
%I |
2-digit 12-hour clock hour (01-12) | 08 |
%M |
2-digit zero-padded minute (00-59) | 46 |
%S |
2-digit zero-padded second (00-59) | 25 |
%p |
AM or PM indicator | PM |
%a |
Abbreviated weekday name | Tue |
%A |
Full weekday name | Tuesday |
%j |
3-digit day of the year (001-366) | 258 |
%z |
UTC offset (+HHMM or -HHMM) |
-0400 |
%Z |
Timezone abbreviation | EDT |
%s |
Unix epoch seconds | 1789519585 |
%F |
ISO 8601 date (%Y-%m-%d) |
2026-09-15 |
%T |
24-hour time (%H:%M:%S) |
20:46:25 |
%R |
24-hour time without seconds (%H:%M) |
20:46 |
%D |
Date (%m/%d/%y) |
09/15/26 |
%% |
Literal percent sign | % |
%- |
Modifier: strips leading padding (e.g. %-I, %-d, %-m) |
8 (instead of 08) |
A conversion this table does not list is passed through verbatim, percent
sign included, rather than being silently dropped or replaced by the default
format. A typo such as `T1789519585|%Q`T therefore renders as %Q and is
visible to the page's author instead of vanishing. The %- no-pad modifier is
the one addition this format language makes to POSIX strftime.
2.4 Backward Compatibility & Degradation
- Clients with no
`Tsupport strip the delimiters and display the raw payload (e.g.1789519585|%F %T), ensuring no text is lost. - Malformed inputs (non-integer seconds) fall back to displaying the raw text verbatim without crashing the parser.
2.5 Python nomadnet Reference Back-Port
In nomadnet/ui/textui/MicronParser.py:
import datetime
import re
TIMESTAMP_PATTERN = re.compile(r'`T(\d+)(?:\|([^`]*))?`T')
DEFAULT_TIME_FORMAT = "%a %b %d, %Y %-I:%M:%S%p %Z"
def expand_timestamps(text):
def _replace(match):
secs = int(match.group(1))
fmt = match.group(2) if match.group(2) else DEFAULT_TIME_FORMAT
# Convert UTC seconds to local time
dt = datetime.datetime.fromtimestamp(secs).astimezone()
try:
return dt.strftime(fmt)
except Exception:
return dt.isoformat()
return TIMESTAMP_PATTERN.sub(_replace, text)
3. Micron Extension: `L (Location / Plus Code Offline Geo-Rendering)
3.1 Overview & Motivation
NomadNet pages frequently display coordinates for radio repeaters, emergency shelters, water sources, or trailheads. However, bare geographic coordinates or raw Open Location Codes (Plus Codes) fail to answer a traveler's most critical questions: - How far away is it? - In what direction should I go?
The `L extension renders an Open Location Code, computes the great-circle distance and 16-point compass bearing from the client's current location, and presents rich guidance offline using zero internet connection. It is implemented in the github.com/gmlewis/go-reticulum/geo package (Open Location Code decoding and the geodesy primitives) and rendered by the gonomadnet Micron client, which takes the reader's position from an optional [location] config section (§3.6).
3.2 Syntax & Grammar
- Opening & Closing Delimiters:
`L(backtick followed by capitalL). <code>: An Open Location Code (Plus Code) with its+separator. A full code is 8 to 11 significant characters (e.g.849VCWC8+R9,8FW4V75V+8R) and is self-contained. A shortened code places the+earlier and omits the digits naming its region; it is only meaningful next to a reference location, so it is rendered as written rather than guessed at (see §3.6).<format>: One of five format tokens (%default,%c,%d,%b,%ll). Defaults to%defaultif omitted.
Grammar (ABNF)
location-directive = "`L" code [ "|" format ] "`L"
code = 2*15( olc-char )
olc-char = %x30-39 / %x41-5A ; 0-9, A-Z (excluding I, L, O, U)
format = "%default" / "%c" / "%d" / "%b" / "%ll"
3.3 Format Tokens & Rendering
| Token | Description | Rendered Example |
|---|---|---|
(none), %default |
Code, followed by distance and bearing when client position is known. | 849VCWC8+R9 (3.2 km, bearing 048° NE) |
%c |
Bare Plus Code alone. | 849VCWC8+R9 |
%d |
Distance alone when position is known. Empty string if unknown. | 3.2 km |
%b |
3-digit bearing and 16-point compass name. Empty string if unknown. | 048° NE |
%ll |
Decimal degrees latitude/longitude, six decimal places. Always computes (needs no client fix), but only for a full code. | 37.422062, -122.084063 |
3.4 Geodetic Formulas & Units
1. Coordinate Decoding
The code is decoded to its bounding box centroid $(\phi_2, \lambda_2)$ in decimal degrees and converted to radians.
2. Great-Circle Distance (Haversine Formula)
Using the standard mean spherical Earth radius $R = 6,371,000\text{ meters}$:
$$\Delta\phi = \phi_2 - \phi_1, \quad \Delta\lambda = \lambda_2 - \lambda_1$$
$$a = \sin^2\left(\frac{\Delta\phi}{2}\right) + \cos(\phi_1)\cos(\phi_2)\sin^2\left(\frac{\Delta\lambda}{2}\right)$$
$$c = 2 \cdot \operatorname{atan2}\left(\sqrt{a}, \sqrt{1-a}\right)$$
$$d = R \cdot c$$
3. Initial Forward Bearing (Azimuth)
$$y = \sin(\Delta\lambda)\cos(\phi_2)$$
$$x = \cos(\phi_1)\sin(\phi_2) - \sin(\phi_1)\cos(\phi_2)\cos(\Delta\lambda)$$
$$\theta = \left(\operatorname{atan2}(y, x) \cdot \frac{180}{\pi} + 360\right) \pmod{360}$$
4. 16-Point Compass Rose Mapping
The bearing $\theta$ is mapped to a 16-point compass name using $22.5^\circ$ sectors:
$$\text{index} = \left\lfloor \frac{\theta + 11.25}{22.5} \right\rfloor \pmod{16}$$
Names: N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW.
5. Distance Formatting Rules
- Below $1,000\text{ m}$: Integer meters with space (
850 m). - Between $1,000\text{ m}$ and $1,000\text{ km}$: Kilometers with one decimal place (
3.2 km). - At or above $1,000\text{ km}$: Integer kilometers (
8967 km).
3.5 Certified Reference Test Vectors
Use these reference values to verify new implementations:
| Reader Position | Plus Code Target | Target Centroid | Distance | Bearing | Rendered Output |
|---|---|---|---|---|---|
| 37.4220°N, 122.0841°W (Mountain View) | 8FW4V75V+8R (Eiffel Tower) |
48.858312°N, 2.294563°E | 8,967,033 m | 33.39° | 8FW4V75V+8R (8967 km, bearing 033° NNE) |
| 51.5000°N, 0.1200°W (London) | 8FW4V75V+8R (Eiffel Tower) |
48.858312°N, 2.294563°E | 340,318 m | 148.72° | 8FW4V75V+8R (340.3 km, bearing 149° SSE) |
| -33.8568°S, 151.2153°E (Sydney) | 849VCWC8+R9 (Googleplex) |
37.422062°N, 122.084063°W | 11,952,709 m | 56.23° | 849VCWC8+R9 (11953 km, bearing 056° NE) |
Note the first row's compass name: 33.39° lies in the NNE sector, which spans 11.25° to 33.75°, one third of a degree below the NNE/NE boundary. Applying the formula in §3.4.4 to 33.39° gives index 1, NNE.
3.6 Backward Compatibility & Client Position
- Clients without the extension. Python
nomadnetconsumes the backtick and the marker character and renders the payload as ordinary text, so a page containingL8FW4V75V+8RL reaches an unmodified client as8FW4V75V+8R— the bare code, which is exactly what the reader needs. Degradation is therefore graceful and producers need no plain-text duplicate of the code. A malformed code or an unknown format token is not an extension at all, so it takes the same path. - A shortened code (
+before the eighth character) is rendered exactly as it was written: the default and%cshow the code,%dand%brender nothing rather than a placeholder, and%llis unavailable because it would need the reference point the code omits. A page that wants a resolvable location must write a full code. - Client position. The distance and bearing require the reader's position, which is a client-side setting and never travels in the page. In
gonomadnetit comes from an optional[location]section in the client's config file:
fix accepts any notation the geodesy engine understands (decimal degrees with or without hemisphere letters, degrees/minutes/seconds, a full Plus Code, or a Maidenhead grid locator). With no usable fix, the position-dependent forms degrade to the bare code and %ll still computes.
- Interaction. A rendered location is a clickable link. Activating it opens the client's location actions: a card showing the code, the coordinate, and — when a position is known — the distance and bearing, with buttons that copy the code or the coordinate. The link target carries the code (location:<code>), never the rendered sentence, so copying the code always yields a code another client can use.
3.7 Python nomadnet Reference Back-Port
In nomadnet/ui/textui/MicronParser.py:
import math
import re
from openlocationcode import openlocationcode
LOCATION_PATTERN = re.compile(r'`L([A-Z0-9+]{2,15})(?:\|(%[a-z]+))?`L')
FORMATS = ("%default", "%c", "%d", "%b", "%ll")
EARTH_RADIUS_M = 6371000.0
COMPASS_POINTS = [
"N", "NNE", "NE", "ENE", "E", "ESE", "SE", "SSE",
"S", "SSW", "SW", "WSW", "W", "WNW", "NW", "NNW"
]
def format_distance(meters):
if meters < 1000:
return f"{int(round(meters))} m"
km = meters / 1000.0
if km < 1000:
return f"{km:.1f} km"
return f"{int(round(km))} km"
def calculate_geodesy(lat1, lon1, lat2, lon2):
phi1, phi2 = math.radians(lat1), math.radians(lat2)
dphi = math.radians(lat2 - lat1)
dlam = math.radians(lon2 - lon1)
a = math.sin(dphi/2)**2 + math.cos(phi1)*math.cos(phi2)*math.sin(dlam/2)**2
c = 2 * math.atan2(math.sqrt(a), math.sqrt(1-a))
dist = EARTH_RADIUS_M * c
y = math.sin(dlam) * math.cos(phi2)
x = math.cos(phi1)*math.sin(phi2) - math.sin(phi1)*math.cos(phi2)*math.cos(dlam)
bearing = (math.degrees(math.atan2(y, x)) + 360.0) % 360.0
sector = int(math.floor((bearing + 11.25) / 22.5)) % 16
compass = COMPASS_POINTS[sector]
return dist, bearing, compass
def expand_locations(text, client_lat=None, client_lon=None):
def _replace(match):
code = match.group(1)
fmt = match.group(2) or "%default"
payload = code if match.group(2) is None else f"{code}|{match.group(2)}"
# An unusable construct is text, never an error: the markers are
# consumed and the payload reaches the reader exactly the way an
# unmodified client shows it.
if not openlocationcode.isValid(code) or fmt not in FORMATS:
return payload
if fmt == "%c":
return code
# A shortened code has no reference point, so it is rendered as
# written and the position-dependent forms add nothing.
if not openlocationcode.isFull(code):
return code if fmt in ("%default", "%ll") else ""
area = openlocationcode.decode(code)
if fmt == "%ll":
return f"{area.latitudeCenter:.6f}, {area.longitudeCenter:.6f}"
if client_lat is None or client_lon is None:
return code if fmt == "%default" else ""
dist, bearing, compass = calculate_geodesy(
client_lat, client_lon, area.latitudeCenter, area.longitudeCenter)
dist_str = format_distance(dist)
bearing_str = f"{int(round(bearing)):03d}° {compass}"
if fmt == "%d":
return dist_str
if fmt == "%b":
return bearing_str
# Default:
return f"{code} ({dist_str}, bearing {bearing_str})"
return LOCATION_PATTERN.sub(_replace, text)