SPEEDBIRD SBP Mesh — on-air protocol specification#
Version 1 (SBM1). Published as required for data emissions by 47 CFR §97.309(a)(4).
The SBP mesh is an application-layer protocol carried inside ordinary SBP transfers (see ../SPEC.md).
It adds neighbour discovery, link-state routing, store-and-forward relaying and a mesh traceroute.
It changes nothing in the SBP PHY or link layer.
Regulatory notes.
- Nothing is encrypted or obscured (§97.113(a)(4)). Every field is printable ASCII or UTF-8 text. Binary user
data is base64-encoded (RFC 4648), and the
boption marks it. - Every SBP burst already carries the sending station's callsign in clear in its burst header (§97.119). Mesh frames also name the originating and destination callsigns in clear.
- A relaying station retransmits third-party traffic in its own SBP session, under its own callsign.
1. Carriage#
| Frame types | SBP carriage |
|---|---|
| HELLO, LSA, BULLETIN | One SBP UI burst addressed to QST: unconnected, no ARQ, at most 2000 bytes. Several frames may be bundled in one burst. |
| DATA, ACK, TRACE, TRACE-REPLY, RELAY-REFUSED | One ordinary SBP ARQ msg transfer to the next-hop station. The SBP ARQ acknowledgement is the per-hop ACK. |
A station that does not run the mesh software sees mesh payloads as text messages that begin with SBM1.
On the final hop to such a station, a mesh node delivers DATA as plain text instead: <src> via mesh: <text>.
2. Frame#
SBM1 <type> <src> <dst> <seq> <ttl> <path> <opts> <blen>\n<body>
The header is one ASCII line, with fields separated by single spaces and ended by LF (0x0A).
The body follows immediately and is exactly blen bytes long. Frames can be concatenated (a bundle).
A receiver parses frames in order and stops at the first malformed one.
| Field | Meaning |
|---|---|
SBM1 |
Magic plus protocol version 1. |
type |
H HELLO, L LSA, D DATA, A ACK (end-to-end receipt), T TRACE, R TRACE-REPLY, N RELAY-REFUSED, B BULLETIN. |
src |
Originator callsign: [A-Z0-9/-]{1,10}, with an optional -SSID. This is the radio's SBP callsign. |
dst |
Destination callsign, or * for broadcast (HELLO/LSA). A bare base call such as K4MFC addresses any radio of that station. |
seq |
Originator sequence number: decimal, u32. Each originating callsign keeps one counter for all frame types. It is never lower than (UTC seconds − 1 700 000 000), so a station that lost its state still outranks its old LSAs. |
ttl |
Hops left, decimal. Each relay decrements it. A frame that arrives with ttl ≤ 1 is not relayed. |
path |
Relays so far, as comma-separated hop entries, or - if there are none (see below). |
opts |
Comma-separated options, or -: r = end-to-end receipt requested; b = body is base64; x<unix> = expiry time (UTC seconds). |
blen |
Body length in bytes, decimal. |
Hop entry: CALL[:snr[:level]].
CALLis the callsign of the station that received the frame and passed it on.snris the SNR in dB (2500 Hz bandwidth) at which that station received the frame from the previous hop.levelis the SBP speed level index that SNR supports.~marks an unknown value.
These are the same fields as the hop lists returned by SbpLink.trace(): call, snr, level.
Duplicate key: (src, type, seq). For HELLO and LSA the key is (src, LS, seq), because they share
one counter.
3. HELLO and LSA body (link state)#
The body is a list of key=value fields separated by ;:
| Key | Value |
|---|---|
g |
Maidenhead locator of the station, 4–6 characters (optional). |
s |
Station base callsign, if it differs from the base of src. |
a |
This station's other radio callsigns, comma-separated (multi-radio stations, for example K4MFC-1 on HF and K4MFC-2 on VHF). Receivers join aliases with zero-airtime links. |
b |
Band tag: hf or vhf, optionally followed by :band (hf:40m). |
i |
Sender's HELLO interval on this channel, in seconds. Receivers expire the neighbour after 3.5 × this interval. |
n |
Neighbour list: comma-separated CALL:snr_in:snr_out:level:age[:p] entries (see below). |
pr |
1: this station is a public relay. It re-floods public bulletins (relay.mode is not off and public_broadcasts is on). |
ro |
Relay mode, present only when it is restrictive: allow (relays only traffic whose source or destination matches ra) or off (relays nothing for others). Absent means it relays everyone. |
ra |
Allow patterns, +-separated (with ro=allow). |
rd |
"norelay" deny patterns, +-separated. The station refuses to relay traffic whose source or destination matches one of them. |
Fields in each n entry:
snr_in: the SNR in dB at which the sender hearsCALL.snr_out: the SNR at whichCALLhears the sender, copied fromCALL's own HELLO or LSA.~if unknown.level: the SBP level the sender expects to receive fromCALL.age: seconds since the sender last heardCALL.p: present whenCALLis a plain SBP station that does not run the mesh. Such a station can only be a final destination, never a relay.
Example (one UI burst):
SBM1 H K4MFC-1 * 1763390012 1 - - 71
g=EM73pk;a=K4MFC-2;b=hf:40m;i=900;n=K4MFB:12:9.5:6:30,W1AW:-3:~:3:400:p
HELLO (H, ttl 1)#
HELLO is sent by each radio on its own channel:
- every
hello_s(HF 900 s, VHF 120 s), with ±20 % random jitter; - only when the channel is idle (see §6);
- carrying that radio's own 1-hop neighbour list.
HELLO is never relayed. A HELLO also installs the sender's link state in its neighbours' databases.
LSA (L, flooded)#
A station originates an LSA in these cases:
- when its link set changes: a neighbour appears, expires or goes down, or a link moves 2 or more SBP levels;
- at least every
lsa_refresh_s(HF 3600 s, VHF 900 s).
Change-triggered LSAs are rate-limited to one per lsa_min_gap_s (HF 300 s, VHF 30 s).
The initial TTL is lsa_ttl (6). A multi-radio station sends the LSAs of all its radio callsigns, bundled, on
each of its radios.
When a station receives an LSA it has not seen before and whose seq is newer than its stored copy, it
schedules a relay:
- It sets ttl − 1 and appends its own hop entry to
path. - It sends the relay on every radio, after a random delay of
relay_delay_s(HF 5–60 s, VHF 1–10 s). No station relays the same originator more often than once perrelay_min_gap_s. - If a newer LSA from the same originator arrives while the relay is pending, it replaces the pending copy.
- If the station hears
relay_suppress(3) copies of the same LSA before its own relay goes out, it drops the relay.
Pending relays are bundled into the station's next UI burst, up to max_bundle_bytes (366).
Link-state database entries expire 3 × lsa_refresh_s after they were installed.
4. Routing#
Each station keeps the following:
- a neighbour table built from every SBP burst it decodes. Listen-only discovery also learns from other stations' ordinary traffic.
- a link-state database (LSDB) built from HELLOs and LSAs.
From these it builds a directed graph. Vertices are radio callsigns; an edge a→b means "b hears a".
- SNR of an edge: a first-hand report is preferred. b's own
snr_infor a outranks a's relayedsnr_out. If only one direction of a link is known, the other is assumed to be 3 dB worse, and the edge cost is multiplied by 1.5. - Cost of a→b: the estimated seconds to move 1 kB:
hop_overhead_s(HF 10 s, VHF 3 s) + 8000 / throughput at the SBP level the a→b SNR supports;- × (1 + age / max_age);
- × (1 + 2 × recent session failures). Links are asymmetric.
- Usable links: a link needs at least −21 dB in both directions, because SBP ARQ needs a return path.
- Relays: only stations that run the mesh are expanded as relays. That means LSA originators, plus any
station a neighbour's LSA advertises without
p. - Path computation: Dijkstra from all of this station's radio callsigns. Each route records the next hop, the outgoing radio, the full path, the cost and an end-to-end store-and-forward throughput estimate (1 / Σ 1/bps).
5. Routed traffic (DATA / ACK / TRACE)#
The originator sends:
SBM1 D K4MFA K4MFE <seq> 8 - r,x<expiry> <blen>\n<text | base64>
The frame is sent as one SBP ARQ transfer to the next hop. Each relay does the following:
- Checks the duplicate key. A relay forwards a given frame at most once.
- Appends
CALL:snr:level(its own entry) topathand decrementsttl. - Queues the frame (store-and-forward) and sends it to its own next hop for
dst. The route avoidssrcand every station already inpath.
How queued frames are handled:
- No route: the frame stays queued and is retried every
msg_retry_s(HF 120 s, VHF 30 s), or immediately when routes change. - Expiry: queued frames are dropped at
x<expiry>, which defaults to 24 h after origination. - Failed hop: a failed SBP session is retried with exponential backoff.
link_fail_limit(2) consecutive failures mark the link down forlink_down_s(HF 1800 s, VHF 300 s). That triggers a new LSA and a reroute. - Dead end: if a relay has no route that avoids the path, it may hand the frame back towards a previous
relay. A station accepts a frame it handled before only if its own callsign is already in
path; it then routes around the dead end. TTL bounds every frame.
ACK (A): if r is set, the destination returns A with body = the decimal seq of the DATA frame,
routed back to src.
TRACE (T): the body is empty. The destination answers with R, whose body is
<seq of T> <hop entries>. The hop entries list the forward relays plus the destination itself, each with
the SNR and level at which it received the TRACE. The path of the R frame collects the return hops.
RELAY-REFUSED (N): a relay whose policy refuses a routed frame sends this frame to the station it got the
frame from (dst = previous hop, ttl 2). The body is <type> <src> <seq> <reason>, with spaces in the
reason replaced by _. Reasons are deny_list, not_on_allow_list, relay_off, rate and too_large.
The previous hop takes the frame again and reroutes it, avoiding the refusing station: for 1 h after a
rate refusal, for the frame's lifetime otherwise.
BULLETIN (B): a public broadcast. dst is QST, CQ or ALL, the initial ttl is 4, and the body is
text (or base64 with b). It is flooded like an LSA, within the airtime cap: each station delivers it once
(duplicate key), then re-broadcasts it with ttl − 1 and its own hop entry appended, after the relay delay,
if its relay policy allows. The relay_suppress rule applies. Plain SBP UI texts to QST from stations
that do not run the mesh are never re-broadcast.
6. Relay policy#
Each station decides what third-party traffic it carries. The default is mode all ("all public"):
relay everyone's routed traffic and public bulletins. The other modes are:
allowlist: relay only when the source or destination matches an allow rule.off: carry only the station's own traffic.
Deny rules always win, in every mode. A deny rule matches on source, destination or any hop in path.
Rules are callsign patterns:
K4MFC-6: exactly that callsign.W1ABC: that base call, with any SSID.W1*: shell-style wildcards (*,?).K4MFC-*also matches bareK4MFC.
Each rule can also be limited by field (src, dst, either, path, any) and by traffic kind
(msg, trace, lsa, bulletin). Denying lsa for a station stops re-flooding its LSAs, but the
station's LSAs are still learned.
There are also size and rate limits per source: max_size and rate_per_hour.
A station's own traffic is never refused. Rules never match the station's own callsigns.
Restrictive policies are advertised in HELLO/LSA (ro/ra/rd). Other stations' route computation
does not expand through a relay whose advertisement refuses that source and destination.
7. Airtime discipline#
Routing traffic means HELLO, LSA and relays. It is capped per radio at airtime_cap of a sliding
airtime_window_s: HF 2 %, VHF 5 % of 3600 s. A burst that would exceed the cap is deferred.
A station transmits routing traffic only when all of these hold:
- the SBP link reports no session, no transmission, no reception and nothing queued;
- nothing has been decoded for
idle_hold_s(HF 5 s, VHF 2 s); - no third-party ARQ session frame (anything except UI) has been heard for
session_hold_s(HF 30 s, VHF 10 s). A heard DISC releases this hold.
If the channel is busy, the station backs off for a random time of busy_backoff_s (HF 10–45 s), doubling
up to 4×.
beacon: false makes the station listen-only: it sends no HELLO, LSA or relays, but still learns the mesh
from other stations.
Typical HF load in steady state is about 0.5 % airtime per station: about 4 HELLOs, 1 LSA and a few bundled relays per hour, each a UI burst of about 2.3–3.4 s.
Source: speedbird-linux/speedbird-sbp-mesh-spec.md