Initial push

4 files changed, 271 insertions, 0 deletions

diff --git a/stacks/tncs/docs/HYBBX-TNC2C.md b/stacks/tncs/docs/HYBBX-TNC2C.md
new file mode 100644
index 0000000..8d2207f
--- /dev/null
+++ b/stacks/tncs/docs/HYBBX-TNC2C.md
@@ -0,0 +1,54 @@
+# HyBBX + TNC2C
+
+MAX25 prepares the TNC (recovery + KISS entry); HyBBX attaches with **`kiss_entry = none`**.
+
+## Flow
+
+```
+max25d auto_start / max25-ctl start --hardware tncs --device tnc2c
+        ↓  (software recovery + kiss on)
+HyBBX Secondary starts packet_radio plugin (attach-only)
+        ↓
+KISS on serial → AX.25 sessions
+```
+
+Software recovery without power cycle: [TNC-RECOVERY.md](TNC-RECOVERY.md).
+
+## Preparation (MAX25)
+
+```bash
+./scripts/max25-ctl start --hardware tncs --device tnc2c
+# Production: max25d with [stack] auto_start = yes
+```
+
+One process per serial port — stop other userspace serial owners before HyBBX starts.
+
+## HyBBX INI
+
+Merge `share/hybbx/tnc2c-host.ini.example` or `stacks/tncs/hybbx-tnc2c.ini` into Secondary `hybbx.ini`:
+
+```ini
+[transport.packet_radio1]
+tnc = tnc2c
+device = /dev/ttyUSB0
+baud = 19200
+serial_line = 8n1
+rts_dtr = yes
+kiss_entry = none
+persist = 255
+
+[max25]
+check = yes
+```
+
+Set `device`, callsign, and frequency for your station.
+
+For HyBBX **without** max25d (standalone), use `kiss_entry = kiss_on` or `auto` instead — HyBBX runs its own recovery before KISS entry.
+
+## Checks
+
+- MAX25 prep returned host/KISS ready (boot-wait OK or max25d `ready`)
+- `fuser` on device is empty before HyBBX start (max25d holds port in production)
+- Log shows KISS active on the expected port
+
+Full contract: [docs/HYBBX.md](../../docs/HYBBX.md)
diff --git a/stacks/tncs/docs/TNC-RECOVERY.md b/stacks/tncs/docs/TNC-RECOVERY.md
new file mode 100644
index 0000000..2e36357
--- /dev/null
+++ b/stacks/tncs/docs/TNC-RECOVERY.md
@@ -0,0 +1,108 @@
+# TNC recovery (software-first)
+
+TheFirmware / TNC-2 class devices (Landolt TNC2C, PK-TNC2, TAPR TNC-2) can usually return to **host command mode** and **KISS** without a power cycle. Power-cycle with DTR held high is a **rescue fallback** only.
+
+Shared implementation: `stacks/tncs/tnc_serial_recovery.py` (used by `tnc2c-host-reset`, `tnc2c-boot-wait`, and `max25d` `kiss_bridge`).
+
+## When to use what
+
+| Situation | First action | Rescue (if software fails) |
+|-----------|--------------|----------------------------|
+| Echo-only (`INFO` → `INFO`, no banner) | `max25d` serial watch / `./tnc2c-host-reset.sh` | `./tnc2c-boot-wait.sh` only if cold-boot without DTR |
+| After `max25d` prep `error-host` | Auto boot-wait escalate (power OFF 10s → ON) | `./tnc2c-boot-wait.sh` if escalate disabled |
+| PK-TNC2 (9600 8N1) | `./pktnc2-boot-wait.sh --recover-only` | `./pktnc2-boot-wait.sh` + power cycle |
+| Cold boot, never saw `cmd:` | `./tnc2c-boot-wait.sh` (DTR before power-on) | Fix wiring (DTR/RTS, CTS bridge) |
+
+## Software recovery ladder (TheFirmware TF 2.7 native)
+
+Run with **DTR+RTS high** and the port open:
+
+1. Passive listen (~1.5 s) + **DTR settle 2 s** after open (max25d)
+2. KISS return `0xC0 0xFF 0xC0` (firmware reset → banner)
+3. Buffer flush `^Q^X` + JHOST 0 (leave host mode)
+4. **ESC V** — version / terminal probe
+5. **ESC QRES** — software cold boot (no mains power cycle; DTR must stay high)
+6. ESC E 0 + second ESC QRES
+7. Legacy TAPR `kiss off` + `INFO` (last resort only)
+
+Success markers: `TheFirmware`, `NORD`, `Version 2.7`, `Checksum`, `cmd:`.
+
+Then enter KISS: **ESC `@K`** (`0x1B 40 4B`). MYCALL: **ESC I** `<call>`.
+
+Native TF sequence: see [Software recovery ladder](#software-recovery-ladder-thefirmware-tf-27-native) above.
+
+## Operator commands
+
+```bash
+cd stacks/tncs
+
+# Software recovery (no power cycle)
+./tnc2c-host-reset.sh              # terminal mode
+./tnc2c-host-reset.sh --kiss       # terminal + KISS
+./tnc2c-boot-wait.sh --recover-only
+
+# PK-TNC2
+./pktnc2-boot-wait.sh --recover-only
+
+# Rescue: power cycle with DTR held (Landolt TNC2C cold-boot requirement)
+./tnc2c-boot-wait.sh               # power OFF → ON while script runs
+```
+
+## MAX25 + HyBBX contract
+
+| Layer | Responsibility |
+|-------|----------------|
+| `max25d` / boot-wait | DTR sequencing, software recovery, `kiss on` / `auto` |
+| HyBBX `packet_radio` | Attach only — `kiss_entry = none` |
+| Power cycle | Rescue when DTR was low at cold boot or hardware hang |
+
+HyBBX INI (production): `kiss_entry = none`, `persist = 255` (CB CSMA), optional `[max25] check = yes`.
+
+max25d runs `recover_terminal()` in `kiss_bridge.stabilize_session()` before `MYCALL` and KISS entry. The KISS RX thread starts **only after** successful stabilization (avoids a race where RX consumes recovery replies).
+
+### max25d serial watch (automatic)
+
+When `[stack] serial_watch = yes` and `stack_recover_only = yes` (default), max25d **opens the TNC serial port itself** — no `boot-wait` subprocess (avoids port conflict). Recovery runs inline via `stabilize_session`.
+
+| INI key | Default | Role |
+|---------|---------|------|
+| `serial_watch` | yes | Enable periodic probe + auto-repair |
+| `serial_watch_interval` | 60 | Seconds between health probes |
+| `serial_repair_cooldown` | 20 | Minimum gap between repair attempts |
+| `stack_recover_only` | yes | Daemon start uses `--recover-only` (no power cycle) |
+| `stack_retry_interval` | 120 | Retry failed stack prep with recover-only |
+| `serial_bootwait_escalate` | yes | Escalate to boot-wait after repeated inline failures |
+| `serial_bootwait_escalate_after` | 3 | Inline `error-host` failures before boot-wait |
+| `serial_bootwait_escalate_cooldown` | 300 | Minimum seconds between boot-wait escalations |
+
+Triggers: initial prep `error-host` (immediate boot-wait escalate), `error-host` / `error-kiss` / `error-tx` / `error-io`, failed TX (one auto-retry). Serial watch still escalates after `serial_bootwait_escalate_after` consecutive inline failures if prep did not already escalate.
+
+**Healthy KISS:** when the backend is `ready`, serial watch does **not** tear down KISS on the periodic interval — repair runs only when status is in the error set above (not a periodic `kiss off` / probe on a working session).
+
+## Firmware RX diagnostics (max25d / boot-wait)
+
+On each recovery step, logs include byte count, matched firmware markers (`TheFirmware`, `cmd:`, …), and a printable preview. On failure:
+
+- `recovery: firmware assessment — …` — classified state (silent, echo-only, binary/KISS, non-banner text)
+- `recovery: RX capture — …` — full accumulated RX summary with hex snippet
+
+Use these lines to distinguish **DTR/cold-boot** (echo-only, 0 B passive) from **wrong baud/line** (garbage/binary) from **stuck KISS** (binary frames, no `cmd:`).
+
+Use when:
+
+- Software ladder ends in echo-only or silence
+- TNC was powered on **without** DTR high (Landolt TNC2C terminal detection)
+- Suspected hardware hang
+
+```bash
+./tnc2c-boot-wait.sh
+# While script listens: power OFF 10 s, power ON — keep script running (DTR stays high)
+```
+
+Do **not** close the serial port between boot-wait and HyBBX/max25d attach — DTR drop can return the TNC to echo mode.
+
+## See also
+
+- [TNC2C-OPERATIONS.md](TNC2C-OPERATIONS.md) — daily ops
+- [HYBBX-TNC2C.md](HYBBX-TNC2C.md) — HyBBX attach
+- [../../docs/PACKET-RADIO.md](../../docs/PACKET-RADIO.md) — serial profiles, CSMA
diff --git a/stacks/tncs/docs/TNC2C-OPERATIONS.md b/stacks/tncs/docs/TNC2C-OPERATIONS.md
new file mode 100644
index 0000000..aa9b8ef
--- /dev/null
+++ b/stacks/tncs/docs/TNC2C-OPERATIONS.md
@@ -0,0 +1,66 @@
+# TNC2C operations
+
+Landolt TNC2C on a serial port — software recovery, boot-wait rescue, verify, HyBBX attach.
+
+## Prerequisites
+
+- Port free: no HyBBX or other userspace serial owner on the TNC serial device
+- `tnc2c-serial.env` matches your wiring (device, baud, line format)
+- DTR+RTS asserted while talking to the TNC (boot-wait and host-reset do this)
+
+## Normal prep (max25d / HyBBX)
+
+Production path: `max25d` with `auto_start` runs boot-wait and software recovery before KISS attach.
+
+```bash
+./scripts/max25-ctl start --hardware tncs --device tnc2c
+# or: sudo max25d -c /etc/max25/max25d.ini
+```
+
+Manual recovery without power cycle:
+
+```bash
+cd stacks/tncs
+./tnc2c-host-reset.sh --kiss
+# or: ./tnc2c-boot-wait.sh --recover-only
+```
+
+Full ladder and rescue rules: [TNC-RECOVERY.md](TNC-RECOVERY.md).
+
+## Boot-wait (rescue — power cycle)
+
+Use when software recovery fails or the TNC was cold-started without DTR high:
+
+```bash
+cd stacks/tncs
+./tnc2c-boot-wait.sh
+```
+
+Power cycle the TNC while the script holds DTR+RTS. Expect `OK: HOST` when successful.
+
+## Verify
+
+```bash
+./tnc2c-integration-test.sh
+./tnc2c-health.sh
+```
+
+Integration test runs boot-wait + verify in one process so DTR does not drop between steps.
+
+## HyBBX
+
+1. MAX25 prep complete (boot-wait or `max25d` auto_start with recovery).
+2. Merge `share/hybbx/tnc2c-host.ini.example` into Secondary `hybbx.ini` — **`kiss_entry = none`** (MAX25 owns KISS entry).
+3. Do not run another userspace serial client on the same device while HyBBX is active.
+
+See [HYBBX-TNC2C.md](HYBBX-TNC2C.md) and [../../docs/HYBBX.md](../../docs/HYBBX.md).
+
+## Recovery
+
+| Symptom | Action |
+|---------|--------|
+| Echo only, no `cmd:` | `./tnc2c-host-reset.sh` then `./tnc2c-boot-wait.sh --recover-only` |
+| Still echo-only / silent | **Rescue:** `./tnc2c-boot-wait.sh` + power cycle (DTR high) |
+| `max25d` reports `error-host` | Stop other serial owners; run `--recover-only`; restart max25d |
+| Port busy | Stop HyBBX or other serial owner; check `fuser` on device |
+| Wrong baud | Fix `tnc2c-serial.env` and retry |
diff --git a/stacks/tncs/docs/TNC2C-REFERENCE.md b/stacks/tncs/docs/TNC2C-REFERENCE.md
new file mode 100644
index 0000000..774248c
--- /dev/null
+++ b/stacks/tncs/docs/TNC2C-REFERENCE.md
@@ -0,0 +1,43 @@
+# TNC2C reference (example profile)
+
+Example profile for a Landolt TNC2C with **19200 8N1** host link and **2400** radio AFSK. Adjust for your hardware.
+
+## Serial (host)
+
+| Parameter | Example |
+|-----------|---------|
+| Device | `/dev/ttyUSB0` |
+| Baud | 19200 |
+| Format | 8N1 |
+| RTS/DTR | Required for boot-wait |
+
+## Radio (typical CB packet)
+
+| Parameter | Example |
+|-----------|---------|
+| Modem | TCM3105 |
+| Radio baud | 2400 |
+| Band | CB |
+| Duplex | Half |
+
+## Config file
+
+`stacks/tncs/tnc2c-serial.env` — copy and edit device/baud for your station.
+
+## Tool matrix
+
+| Tool | Use |
+|------|-----|
+| `tnc2c-boot-wait.sh` | Host mode after power-on (rescue) |
+| `tnc2c-host-reset.sh` | Software recovery without power cycle |
+| `tnc2c-autotest.sh` | Quick 19200-8N1 probe |
+| `tnc2c-health.sh` | Full check, no TX |
+| `tnc2c-integration-test.sh` | Post boot-wait HyBBX gate |
+| `tnc2c-listen.sh` | Passive monitor |
+| `tnc2c-probe` | Port scan utility |
+
+## HyBBX INI snippet
+
+Use `share/hybbx/tnc2c-host.ini.example` — set `device`, `mycall`, and RF fields for your station.
+
+HyBBX TNC profiles: [hyBBX docs/TNCS.md](https://github.com/ngteq/hyBBX/blob/main/docs/TNCS.md)