# 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_callsign` and
  `is_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 addresses
  `allcall` and `cqcqcq` are 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 in `FSQ_FAST_PUBLIC_SPEC.md`
  Part X–XI, and the bodies OpenJSQ's automatic replies put on the air
  (`snr=-3 db`, `Heard:` lines, `ack`, and the rest) in
  `JSQ_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 message back immediately (**OpenJSQ differs by design:** it repeats its own last transmission to the requester, not the supplied text — `JSQ_PUBLIC_PROTOCOL_SPEC.md` §79) |
| `~` | `w4ijg~ text` | Delayed repeat | Echoes back after 15 s (OpenJSQ: repeats its last transmission after a bounded delay, §79) |
| `#` | `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 |
| `-` | — | Unsupported | fldigi replies "not supported" |

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.

### 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).