Protocol compatibility #
Compatibility contract: the pinned fldigi implementation (v4.1.23, 61b97f41…) and the published FSQ documentation by ZL1BPU/ZL2AFP.
Key reference facts (from the Gate 0 audit):
- Internal sample rate 12000 Hz; symbol length 4096 samples at 3 baud; speeds 1.5/2/3/4.5/6 baud via symlen scaling; 33 tones, 3-bin spacing, ≈290 Hz bandwidth at 3 baud.
- Callsign CRC: CRC-8 poly 0x07, init 0x00, two lowercase hex digits.
- Callsign validity, as OpenJSQ's transport enforces it (
transports/fsq_legacy/src/fsq_legacy.cpp,is_valid_callsignandis_valid_station_callsign): a callsign is 1–15 characters drawn from letters, digits,-and/, with at least one letter or digit; a STATION callsign (a directed destination) must additionally contain at least one letter and at least one digit. A group destination is@followed by 1–30 letters, digits or/. The special addressesallcallandcqcqcqare reserved broadcast destinations. (An earlier revision of this note said "length 3–20"; that was never what the code checked.) - Directed-message triggers and
parse_*dispatch: see audit §8. The exact on-air frame — BOT, sender, CRC-8, destination, trigger, body, optional CRC-16 suffix, EOT — is specified inFSQ_FAST_PUBLIC_SPEC.mdPart X–XI, and the bodies OpenJSQ's automatic replies put on the air (snr=-3 db,Heard:lines,ack, and the rest) inJSQ_PUBLIC_PROTOCOL_SPEC.md§56.3.
Directed-command reference (from the pinned fldigi implementation) #
Semantics verified against the parse_* bodies in the vendored fsq.cxx. Wire form: DEST<trigger>[args], sent inside a directed frame.
| Trigger | Wire example | Meaning | Remote behavior (fldigi) |
|---|---|---|---|
| (space) | w4ijg hello | Chat text | Displays the message |
? | w4ijg? | Signal report | Replies snr=<estimate> |
$ | w4ijg$ | Heard-list query | Replies Heard: + its heard list (multi-line) |
@ | w4ijg@ | Location query | Replies with its QTH text |
& | w4ijg& | Station-message query | Replies with its QTC text |
^ | w4ijg^ | Version query | Replies fldigi <version> |
* | w4ijg* | Wake station | Enables its monitor (SELCAL) and acks; works even when "asleep" |
! | w4ijg! text | Repeat | Echoes the text to everyone immediately, undirected (call:XX text, two spaces). OpenJSQ 1.0.7 matches byte for byte when text follows ("repeat my message", JSQ_PUBLIC_PROTOCOL_SPEC.md §79.7), when the operator allows it; with no text it repeats its own last transmission to the requester (§79). fldigi reads the first word of the echoed text as an address (it strips the spaces), so text such as allcall#[f]x would be obeyed by every fldigi station: OpenJSQ refuses to echo it ("not repeating commands"); fldigi echoes it |
~ | w4ijg~ text | Delayed repeat | Echoes the text to everyone after 15 s. OpenJSQ 1.0.7 matches when text follows (§79.7); ~30 (a bare number) repeats its last transmission after that delay (§79.4). OpenJSQ's own ~{N}text delay form is sent only to stations whose capability record says they repeat for others, never to fldigi |
# | w4ijg#[name.txt]text | Store message/file | Writes text to name.txt (default <sender>.txt), acks |
+ | w4ijg+[name.txt] | Read message/file | Sends the stored file's contents back |
| | w4ijg|text | Alert | Pops an alert dialog with the text |
> | w4ijg> | Faster | Steps its FSQ speed up one notch, confirms new baud |
< | w4ijg< | Slower | Steps its FSQ speed down one notch, confirms |
; | via;dest text | Relay | via retransmits to dest, inserting [origin] |
[ | dest[origin] text | Relayed marker | Marks traffic relayed from origin; relayed queries answered via the relay path |
% | w4ijg%S | Image transfer | Starts image RX (mode letter selects size) — OpenJSQ parses the trigger and answers nothing; no image service is transmitted by this release |
= | w4ijg= hello, w4ijg=? | Local only, do not relay (OpenJSQ, JSQ_PUBLIC_PROTOCOL_SPEC.md §56.4) | fldigi has no dispatch for =: it does not reply and shows the text, including the displaced trigger as the body's first character. The frame stays DIRECTED because = is in OpenJSQ's trigger set (is_trigger, transports/fsq_legacy/src/fsq_legacy.cpp), so the header walk stops on it and the destination and sender CRC are intact |
- | — | Unsupported | Nothing: fldigi 4.1.23's case '-' is break;//parse_minus();, so the frame is dropped without a reply. OpenJSQ never sends - as a trigger; since 1.0.7 a -1..-15 after a plain callsign is part of the address (below) |
= is an OpenJSQ addition, not an fldigi mapping: nothing in the pinned implementation emits it and nothing there answers it. It is the one character in OpenJSQ's trigger set that was both free and safe — { is taken by the wide-mode structured envelopes, \ is not in the set at all (it would be absorbed into the destination and turn the frame undirected), and - is now part of call-n addresses (below). The real trigger is displaced one position into the body, and a receiver un-displaces it before applying any rule in this table.
allcall frames only honor space, *, #, %, [ (no query amplification storms). OpenJSQ mirrors this table in DirectedCommand and the session's compose logic; every mapping is unit-tested.
SSID-style names, call-n (OpenJSQ 1.0.7) #
OpenJSQ reads w4ijg-7 hi as chat to the one station W4IJG-7 when the text before the - is a plain callsign of 3 to 6 letters and digits, the number is 1 to 15 with no leading zero, and a trigger, a space or the end of the frame follows it. Everything else - a / call, allcall, cqcqcq, a group, -0, -01, -16, -1x - splits at the - exactly as fldigi splits it. A plain callsign or a /suffix behaves exactly as before. The rule and the CRC-16 tie-break are JSQ_TRANSPORT_SERVICE_SPEC.md §33.1.1.
What the pinned fldigi (4.1.23) does with these names, from fsq.cxx and from the round trips in third_party/fldigi-fsq/tests/test_fsq_roundtrip.cpp:
- Triggers (
fsq.cxx:405) include-. - A
call-nsender is heard whole.valid_callsign(:419-434) is a regex search, not an anchored match, sow4ijg-1passes; the sender walk (:466-483) lets-through and the CRC-8 covers all ofw4ijg-1. fldigi shows and lists the station asw4ijg-1. - fldigi answers it. Its automatic replies (
:631-637) go tostation_callingverbatim -w4ijg-1 snr=…- which OpenJSQ reads as addressed to W4IJG-1. - fldigi cannot be a
call-ndestination. The destination word (:521-559) ends at the first trigger, sokk4ib-1 hireaches fldigi KK4IB askk4ibplus-, andcase '-'(:594) does nothing: the frame is dropped, not shown, not answered. Harmless, and the reason an fldigi operator keeps a plain or/suffixcallsign. - fldigi relays it in its own form.
parse_relay(:682-697) inserts[origin]at the first trigger, sovia;w4ijg-7 higoes on asw4ijg[k1a]-7 hi. OpenJSQ puts the-7back on the destination. A plain fldigi W4IJG hearing that form takes it as relayed text for itself (-7 hifrom k1a), which is fldigi's own behaviour; an OpenJSQ via station writesw4ijg-7[k1a] hiinstead, which plain fldigi stations drop.
Unverified with FSQCall.
Forms (ICS-213 and similar) #
Forms are structured text riding the existing transports: transmitted as a directed message or stored at the remote station via #[formfile]. The serialized layout (field labels + values, flmsg-compatible where feasible) is a UX/application-layer concern — see DESKTOP_UX.md. No modem or protocol changes are required to carry forms.
This document grows into the full field-by-field compatibility spec as the fixture corpus expands. Fixture expectations are the ground truth; do not silently update them (see CONTRIBUTING.md).