Initial push

1 files changed, 108 insertions, 0 deletions

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