Initial push

1 files changed, 127 insertions, 0 deletions

diff --git a/stacks/crdop/docs/SOFTMODEM.md b/stacks/crdop/docs/SOFTMODEM.md
new file mode 100644
index 0000000..fef0a0e
--- /dev/null
+++ b/stacks/crdop/docs/SOFTMODEM.md
@@ -0,0 +1,127 @@
+# MAX25-SoftModem — product definition
+
+> **Authoritative rule:** [docs/CRDOP.md](../../../docs/CRDOP.md) · **Doc index:** [INDEX.md](INDEX.md)
+
+## Name and role
+
+- **Product:** MAX25-SoftModem (stack acronym **CRDOP**; plugin id `soft-crdop`)
+- **Stack version:** MAX25-Stack **v1.0.0** · **Dev track:** `CUR999` in `$SRC/stacks/crdop/VERSION`
+- **Stack:** MainAX25-Stack — **standard** component (built/installed unless `MAX25_BUILD_CRDOP=OFF`)
+- **Nature:** Pure MAX25 in-house development — in **development and test phase**, openly documented
+
+## Use like a hardware modem
+
+CRDOP uses the host **sound card IN and OUT** plus a **suitable radio** (or acoustic coupling to existing RF hardware). In `max25d` it registers like any other device backend — operators use the same M25/1 flow (`SET DEVICE`, `CONNECT`, `SEND`).
+
+```
+┌──────────┐   line or acoustic    ┌─────────────┐   TCP    ┌─────────┐
+│  Radio   │ ◄──────────────────► │ CRDOP/ALSA  │ ◄──────► │ max25d  │
+└──────────┘                      └─────────────┘          └─────────┘
+                                        │
+                                  1200–19200 baud
+                                  half or full duplex
+```
+
+### Acoustic AX.25 compatibility
+
+On the **acoustic / RF layer**, CRDOP targets **AX.25 Packet Radio** interoperability at the PHY level:
+
+- **1200 baud Bell 202 AFSK** (1200/2200 Hz) — standard VHF/UHF and CB packet class
+- **Half- and full-duplex** per radio and audio capability
+- **Acoustic or line-level** coupling — valid test and field configuration
+
+CRDOP is an **alternative modem** when the sound card is the RF interface. It does not replace an existing UART/KISS path when that path is already in use.
+
+Interface specification for builders: [HARDWARE-INTERFACE.md](HARDWARE-INTERFACE.md). MAX25-Stack usage: [MAX25-USAGE.md](MAX25-USAGE.md).
+
+## Protocol stack
+
+| Layer | Policy |
+|-------|--------|
+| On-air / acoustic | AX.25-compatible AFSK tones (1200 baud primary) |
+| Host to max25d | MAX25-native TCP control + data (see [PROTOCOL.md](PROTOCOL.md)) |
+
+We study legacy stacks; we implement our own modem and document it for **reproducible hardware builds**.
+
+## Sound path — kernel ALSA only
+
+CRDOP does **not** use PulseAudio, PipeWire-as-default, or any desktop sound server.
+
+| Layer | Function |
+|-------|----------|
+| **MAX25 sound-proxy** | Sole shim between modem DSP and ALSA — buffers, timing, duplex, xrun recovery |
+| **libasound** | Direct `hw:` / `plughw:` opens |
+| **Kernel ALSA** | Driver + `/dev/snd/*` |
+| **Hardware** | Sound card → radio interface |
+
+Configure explicit devices in `crdop.ini` `[audio]` (`capture`, `playback`). See [AUDIO-ARCHITECTURE.md](AUDIO-ARCHITECTURE.md).
+
+## Baud scope
+
+| Priority | Range | Status |
+|----------|-------|--------|
+| **P0** | **1200 baud** Bell 202 AFSK | Primary — CB + VHF on-air |
+| **P1** | **9600–19200** G3RUH direct FSK | Planned after 1200 stable (VHF backbone) |
+| **P2** | **300** HF AFSK | Optional |
+| — | **>19200 baud** | **Not implemented** — do not configure or expect |
+
+Full modulation matrix, RF paths, band context, delivery milestones: **[ROADMAP.md](../ROADMAP.md)**.
+
+Higher baud rates demand **proportionally better** audio hardware (sample rate, jitter, SNR, isolation). G3RUH requires a **direct FSK radio path** — not the CB FM mic/speaker route.
+
+## Duplex
+
+| Mode | Status |
+|------|--------|
+| **Half-duplex** | Standard CB / packet-radio (PTT or VOX-style timing) |
+| **Full-duplex** | Supported when radio and audio hardware allow simultaneous TX/RX paths |
+
+Configure in `crdop.ini`: `[modem] duplex = half|full`.
+
+## Sound card — required (not optional)
+
+CRDOP must:
+
+1. **Generate** precise mark/space frequencies on **playback**.
+2. **Decode** those tones reliably on **capture**.
+
+Requirements **scale with baud**:
+
+| Baud class | Audio expectation |
+|------------|-------------------|
+| 1200 | Stable full-duplex or half-duplex USB codec or PCI interface; galvanic isolation to radio |
+| 9600–19200 | Low-jitter interface, adequate bandwidth, verified loopback before on-air |
+
+**Unsuitable:** onboard laptop mic/speaker shortcuts, anonymous USB “sound sticks”, Bluetooth bridges, unisolated consumer line inputs.
+
+Document your ALSA device in INI (`[audio] capture` / `playback`) and verify with loopback or sidetone before traffic.
+
+## Open hardware
+
+Documentation targets builders who want to **manufacture radio ↔ sound-card interfaces**:
+
+- Level matching (radio mic/speaker ↔ line level)
+- Galvanic isolation (transformers / opto)
+- PTT integration (GPIO, serial — VOX not recommended for packet)
+- Acoustic coupler fixtures for bench validation
+
+Generic interface specification: [HARDWARE-INTERFACE.md](HARDWARE-INTERFACE.md). Delivery milestones: [ROADMAP.md](../ROADMAP.md).
+
+## Build / release (MAX25-Stack-v1.0.0)
+
+**CRDOP dev track:** `CUR999` in `$SRC/stacks/crdop/VERSION` (ships with MAX25-Stack v1.0.0).
+
+| Item | Shipped |
+|------|---------|
+| CRDOP scaffold (INI, launcher, install) | **Yes** — default CMake |
+| `max25d` `crdop-tcp` backend | **Yes** — offline-tested |
+| Native `crdopc` DSP binary | **In development** — in-house modem DSP |
+| ARDOP / ardopcf vendor tree | **Never** in release tarball |
+
+## HyBBX
+
+When CRDOP is active, HyBBX Secondary attaches via `share/hybbx/crdop-host.ini.example`. HyBBX remains an external project.
+
+## Testing phase
+
+Current work: loopback audio, acoustic bench validation, field on-air trials, acceptable sound-card criteria. Report results via project issues — RF acceptance remains manual until automated gates exist. Developer tests: [DEVELOPER.md](DEVELOPER.md).