QRPBBB Protocol v0 Draft 20210918

[Chris Baird]

file: Documentation/QRPBBB_Protocol_v0
revision: 20210918 - DRAFt draft DrAfT dRaFt

A primary feature of QRPBBB is being distributable over the APRS Digipeater
mesh network when the need arises. To provide that, it is compatible with the
experimental use formats available in the APRS Protocol Standard.

To prepare yourself, QRPBBB packets resemble the following:

VK2CJB-6>APZQRP:{{QS:462688b8,9:Subject: Re: qrpbbb testing
VK2CJB-6>APZQRP,WIDE1-1,WIDE2-1:{{QI:
VK2CJB-6>APZQRP,NOGATE:{{QW:9feecb71,1-17:462688b8,1-15

Of course this is using the TNC2MON representation of an AX.25 frame, and what
actually goes to air is not ASCII character strings.


> The packet preamble

"APZQRP" is an destination address field that APRS uses for software
identification. The APRS Working Group assigns these, however those starting
with "APZ" are for temporary use for products in development. Eventually the
day will come when QRPBBB is presented with it very own destination address and
there will need to be a flag-day for all sites on the network to change over.

As per APRS, additional path items may be included to control the acceptance by
digipeaters and iGates. "NOGATE" should also be included here to prevent
needless traffic to APRS-IS.

"{{Q" indicates an APRS User-defined packet type "2"-- again something
non-assigned. The potential for a future change to an assigned type "1"
user-defined packet exists as well.


> QRPBBB commands

The transmissions follow the format:

<aprs preamble><qrpbbb command>:<payload>


>> Command "I"

Example: VK2CJB-6>APZQRP,NOGATE:{{QI:

This requests all sites receiving it to enqueue an Identification beacon packet
which consists of a free-form message. The payload section could be a future
command parameter.


>> Command "i"

Example: VK2CJB-6>APZQRP,WIDE1-1,WIDE2-1:{{Qi:VK2CJB-6 is a site operated by..

The response packet to the "I" command. Unlike how the rest of the system might
operate, this packet is intentionally using a "spread far and wide" path and
lets itself be uploaded to APRS-IS. A log is kept locally of the information.


>> Command "A"

Format: A:<msgid>,<length>[:<msgid>,<length>]*

Example: VK2CJB-7>APZQRP:{{QA:af6498dd,15:b65973a1,11:4cfc179c,35:325ad5b9,17

This broadcasts to the network the existence of messages on a site.

Every message has a Adler-32 checksum calculated from the content (excluding
the mutable header lines like "Path:") and the 8-character string of the
hexadecimal value becomes a <msgid> identifier.

While it is possible to determine when an entire message has been received by
extending the incoming message length and requesting lines until the correct
checksum appears, providing the total number of lines at the start is a lot
less hassle.

To reduce the amount of packets required, a colon-separated list is used. The
optimal length of the payload is still to be determined, but Experimental APRS
packets can be up to 253 bytes, but on the other hand, larger packets at 1200
baud have a lot more potential to clobber another station's packets.

In practice, a site could announce its list of incomplete messages every hour,
its latest complete articles somewhat regularly (messages < 4 days old, every 4
hours), and provide a complete dump only occasionally (messages < 30 days,
every Saturday morning).


>> Command "S"

Format: S:<msgid>,<linespec>:<payload>

Example: VK2CJB-6>APZQRP:{{QS:4e5d6e8a,10:I'm making good progress...
VK2CJB-6>APZQRP:{{QS:28d973fa,10,13:
VK2CJB-6>APZQRP:{{QS:deadbeef,20-23:!!!! ACTUNG !!!!

The "sending" command is how the line-by-line process of message transmission happens.

<linespec> is a comma-separated list of line numbers, with continuous sequences
compressed to <start><minus-sign><end>. When more than one line number is
specified, there is identical content on each of those lines. The second
example above is from a message where line 10 and 13 were blank lines.

Sites will notice <msgids> they do not know about and create a new incoming
message. (Prior to the "A" command, announcing the existence of a message was
done by sending the last line from it.)


>> Command "W"

Format: W:<msgid>,<linespec>[:<msgid>,<linespec>]*

Example: VK2CJB-6>APZQRP:{{QW:462688b8,1-15
VK2CJB-6>APZQRP:{{QW:9feecb71,1-17:462688b8,1-15
VK2CJB-6>APZQRP:{{QW:462688b8,1-2,10,12,14

This requests unknown message lines from other sites.

Requesting lines that don't exist ("1-9999") is permissable, as the linespec
used here is not an announcement of the real length of a message, either is the
knowledge of <msgid> looked into.

A site with only an incomplete copy of a message does service what requests it can.

While it might be a way to reduce traffic, sites are not expected to drop a
request when they notice another site handling it before them, due to the
chance of the first transmission not being received for whatever reason.

>> Command "C"

Format: C:<uhave|uwant|uheard|ident> <args>

Provides remote control. While the usual routine is to process incoming packets
on a regularly scheduled basis, a site (possibly in portable operation) may
require immediate attention from other systems. The RADIOMODE's packet
transmission period still applies, although the output packets from these
commands are given a higher priority.

A payload can be included for those qrpbb_*.py scripts that can take arguments.

Supported remote commands are:

- uhave [<daysold> "newsspool" "incomplete"]
Immediately executes qrpbbb_ihave.py on all sites within path range and
generates their msgid announcements.

- uwant [<priority>]
Immediately executes qrpbbb_iwant.py on all sites.

- uheard
Stations broadcast their received station lists.

- ident
Identical to the I command above.


>> Command "h"

Format: h:<unix timestamp> <station>[,<timestamp> <station>]*

Provides a listing of the latest several stations heard. Used for network mapping.


>> Command "F" [proposed]

Format: F:<msgid>:<callsign>:<reason>
? F:<msgid>:<callsign>:<digital-signature>:<reason>
? F:<msgid>:<digital-signature>:<reason>

Example: VK2CJB-6>APZQRP:{{QF:462688b8:VK2CJB:Oops, jpeg posted with Distribution:qrpbbb
VK2CJB-6>APZQRP,NOGATE,WIDE1-1,WIDE2-1:{{QF:0d15ea5e:VK2CJB:\
Deleting sales advertisement of a car from VK2FJDA

Stops distribution of a message in the network, and removes any completed
transfers from a newsserver.

Being an Amateur Radio network, we don't go around impersonating other users,
but the idea is there to include a digital signature, should it be required
(..because someone gave the QRPBBB software to a twit with brainworms..) The 64
character base64-encoded ECDSA/NIST192p looks suitable for this use.

A site may additionally create an RFC1036 Control Cancel message to be
distributed via the qrpbbb.control newsgroup, although it shouldn't be required normally.