SPEEDBIRD

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.

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]].

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.

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:

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:

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:

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:

  1. It sets ttl − 1 and appends its own hop entry to path.
  2. 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 per relay_min_gap_s.
  3. If a newer LSA from the same originator arrives while the relay is pending, it replaces the pending copy.
  4. 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:

From these it builds a directed graph. Vertices are radio callsigns; an edge a→b means "b hears a".

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:

  1. Checks the duplicate key. A relay forwards a given frame at most once.
  2. Appends CALL:snr:level (its own entry) to path and decrements ttl.
  3. Queues the frame (store-and-forward) and sends it to its own next hop for dst. The route avoids src and every station already in path.

How queued frames are handled:

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:

Deny rules always win, in every mode. A deny rule matches on source, destination or any hop in path.

Rules are callsign patterns:

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:

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