1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
|
<!-- AUTO-SYNC 2026-08-01 — vault: projects/max25-stack/2026-07-13-master-documentation.md -->
<!-- Re-sync: /home/akb/Code/0-RESEARCHES/tools/vault-sync-slave-docs.sh -->
# MAX25-Stack — Master operator guide
**Shipped guide** — canonical edits in research vault `projects/max25-stack/2026-07-13-master-documentation.md`; run sync script after change.
## Summary
Single linear guide: MAX25 layer model, `max25d`, devices (TNC, BayCom, CRDOP), M25/1 protocol, TNC recovery, FreeBSD split, HyBBX boundary. Shipped docs in `docs/` and `stacks/tncs/docs/` remain **frozen reference**.
---
## 1. What MAX25 is
**Main AX.25 Stack (MAX25)** — standalone packet-radio stack with HyBBX-compatible plugin boundaries. Owns RF prep (boot-wait, KISS entry, BayCom kernel lifecycle, CRDOP audio). HyBBX consumes prepared devices via transport plugins.
```
max25-terminal / max25-client (F10 menu, M25/1)
│
max25d — Main + Secondaries (:7325 M25/1)
│
HyBBX (external) — packet_radio | baycom | crdop
│
Hardware — tnc2c | baycom-ser12 | soft-crdop
```
Frozen: `docs/ARCHITECTURE.md`, `docs/README.md`.
---
## 2. Host layout — Main + Secondaries
| Role | Count | Function |
|------|-------|----------|
| **Main** | 1× | Stack hub, HyBBX attach point, M25/1 `:7325` |
| **Secondary** | 0–5+ | Additional `max25d` instances — one RF backend each |
**Linux rules (when netdev ships):**
| Item | Name |
|------|------|
| TUN interface | **`max25d0`** only |
| BayCom kernel netdev | **`bcsf0`** unchanged |
**Example split:** FreeBSD Main (CRDOP/TCP/IP hub) + Linux Secondary (TNC/BayCom). Not mandatory — single Linux host is the primary v1 layout.
Vault matrix: [2026-07-13-max25-freebsd-tnc-baycom-full-feature-matrix.md](2026-07-13-max25-freebsd-tnc-baycom-full-feature-matrix.md).
---
## 3. Install and site configuration
```bash
git clone <repo> MAX25-Stack && cd MAX25-Stack
./scripts/build.sh
sudo cmake --install build --prefix /usr/local # or user prefix
```
| File | Purpose |
|------|---------|
| `~/.config/max25/max25d.ini` | Devices, TCP, auth, serial watch |
| `share/max25/max25d.ini.example` | Template |
| `share/hybbx/*-host.ini.example` | HyBBX attach fragments |
```ini
[devices]
tnc2c = serial:/dev/ttyUSB0
; soft-crdop = crdop:default
```
Frozen runbook: `docs/MAX25-OPERATOR-RUNBOOK.md`, `docs/LINUX-HOST-SETUP.md`.
---
## 4. Start stack — by device type
### TNC (tnc2c, pktnc2)
```bash
max25-ctl start --hardware tncs --device tnc2c
# or: stacks/tncs/tnc2c-boot-wait.sh
```
Boot-wait: DTR+RTS high during power-on (Landolt TNC2C). Software recovery ladder before power cycle.
### BayCom/based (max25-bcpr userspace SER12)
**Available and usable** — default build ON (`MAX25_BUILD_MAX25_BCPR=ON`). Device **`max25e0`**. KISS release **`/tmp/max25-bcpr/kiss-bc0`**.
```bash
max25-ctl start --mode hybbx-cohost # or hybbx-host / standalone
# max25-bcpr-ctl when running daemon directly
```
HyBBX attach: `[networks] baycom=yes` · `[transport.baycom1] device=/tmp/max25-bcpr/kiss-bc0`.
SSoT: [2026-08-01-baycom-pccom-operational-status.md](../integration/2026-08-01-baycom-pccom-operational-status.md) · [cohost runbook](../integration/2026-07-31-standalone-cohost-runbook.md).
Legacy kernel path (`baycom-pr` / `baycom_ser_fdx`) — removed from product; freeze notes in shipped `docs/BAYCOM-FREEZES.md` only.
### CRDOP (soft modem)
```bash
max25-ctl start --hardware soft-modems --device soft-crdop
# TCP 8515 (control) / 8516 (data)
```
Vault dev master: [2026-07-13-crdop-development-master.md](2026-07-13-crdop-development-master.md).
Verify: `max25-ctl status` · `ss -ltn | grep 7325`.
---
## 5. M25/1 and operator terminal
| Item | Value |
|------|-------|
| Protocol | M25/1 text commands on TCP `:7325` |
| Client | `max25-terminal` — `SET DEVICE`, `CONNECT`, `SEND` |
| Codec | In-tree `ax25_codec.py` — no kernel AX.25 required |
Frozen: `docs/MAX25-TERMINAL.md`, `include/max25/protocol.md`.
---
## 6. TNC recovery (software-first)
Power cycle is **rescue fallback** only when DTR was low at cold boot or hardware hang.
| Situation | First action |
|-----------|--------------|
| Echo-only (`INFO` → `INFO`) | `tnc2c-host-reset.sh` or max25d serial watch |
| After prep `error-host` | Auto boot-wait escalate (if enabled) |
| Cold boot, no `cmd:` | `tnc2c-boot-wait.sh` with DTR before power-on |
**Software ladder** (TheFirmware TF 2.7): KISS return → JHOST 0 → ESC V → ESC QRES → ESC `@K` → MYCALL.
| Layer | Responsibility |
|-------|----------------|
| `max25d` / boot-wait | DTR, recovery, `kiss on`, serial watch |
| HyBBX `packet_radio` | Attach only — `kiss_entry=none` |
Vault SSoT: [2026-07-13-thefirmware-native-recovery-sequence.md](2026-07-13-thefirmware-native-recovery-sequence.md) · [hardware/tnc2c/2026-07-13-kiss-host-without-power-cycle.md](../../hardware/tnc2c/2026-07-13-kiss-host-without-power-cycle.md).
max25d INI defaults: `serial_watch=yes`, `stack_recover_only=yes`, `serial_bootwait_escalate=yes`.
Known failure mode (power-cycle still required): [2026-07-13-max25d-tnc-recovery-power-cycle-root-cause.md](2026-07-13-max25d-tnc-recovery-power-cycle-root-cause.md).
Frozen: `MAX25-Stack/stacks/tncs/docs/TNC-RECOVERY.md`.
---
## 7. BayCom/based ↔ max25d
```
Radio ← UART ← max25-bcprd (userspace SER12+HDLC) ← KISS PTY /tmp/max25-bcpr/kiss-bc0 ← HyBBX baycom / max25d
```
| Fact | Value |
|------|--------|
| Ship status | **Available · usable** — default build ON |
| Device id | **`max25e0`** (forks `max25e0:bcN`) |
| HyBBX cohost | `mode=hybbx-cohost` · verified standalone Main co-host 2026-07-31 / 2026-08-01 |
| RX before TX | Prove decode before live TX — [RX rule](../../operations/2026-07-19-rx-before-tx-rule.md) |
| Use BayCom/based when | Use TNC when |
|-----------------------|--------------|
| PC-COM / SER12 on real 8250 UART | TNC2C, PK-TNC2, USB serial KISS |
| max25-bcpr userspace path | Boot-wait + firmware KISS |
Alias compatibility: [2026-07-13-baycom-max25d-alias-compatibility.md](2026-07-13-baycom-max25d-alias-compatibility.md).
Shipped: `docs/BAYCOM.md` · vault SSoT: [2026-08-01-baycom-pccom-operational-status.md](../integration/2026-08-01-baycom-pccom-operational-status.md).
---
## 8. CRDOP
MAX25-SoftModem (`soft-crdop`) — acoustic AX.25 over soundcard. FreeBSD uses OSS; Linux uses ALSA.
| Host | CRDOP role |
|------|------------|
| Linux | RF backend in `max25d` |
| FreeBSD | Primary softmodem path (no kernel BayCom/TNC in stack defaults) |
**Upstream (operator · 2026-07-25):** modulation development on **T-Modem-384b** HW → **soft import** into this MAX25 soft path (**no** HW modem IC on MAX25). HyBBX boundary unchanged. SSoT: [384b identity § flow](../../operations/2026-07-25-t-modem-384b-identity.md#development-flow-operator--2026-07-25) · [CRDOP master](2026-07-13-crdop-development-master.md).
Frozen: `docs/CRDOP.md`, `stacks/crdop/docs/`.
---
## 9. FreeBSD and platform split
| Component | Linux | FreeBSD |
|-----------|-------|---------|
| `max25d` + RF (TNC/BayCom) | ✅ | ❌ (daemon Linux-first in v1) |
| `max25-terminal` | ✅ | ✅ (remote to Linux `:7325`) |
| CRDOP standalone / OSS | ALSA | OSS (DEV-Level 1 port) |
| Kernel BayCom `bcsf0` | ✅ | ❌ |
No native FreeBSD kernel AX.25 — userspace KISS/M25/1 only. Vault: [2026-07-13-max25-freebsd-tnc-baycom-full-feature-matrix.md](2026-07-13-max25-freebsd-tnc-baycom-full-feature-matrix.md).
Frozen: `docs/FREEBSD-AX25.md`, `docs/PLATFORMS.md`.
---
## 10. HyBBX boundary
**MAX25 before HyBBX.** One serial owner per port.
| MAX25 owns | HyBBX owns |
|------------|------------|
| Boot-wait, MYCALL, `kiss on`, max25-bcpr prep, CRDOPC | `[max25] check`, KISS attach, AX.25 UI, HBX, broadcast |
```bash
max25-ctl start --hardware tncs --device tnc2c # 1
ss -ltn | grep 7325 # 2
hybbxd -c hybbx.ini # 3 — kiss_entry=none
```
Vault: [../integration/2026-07-12-max25-hybbx-boundary-final.md](../integration/2026-07-12-max25-hybbx-boundary-final.md).
Frozen: `docs/HYBBX.md`, `docs/PACKET-RADIO.md`.
---
## 11. Virtual netdev (planned)
TUN **`max25d0`** — IPv4 `127.0.0.25/8`, IPv6 `::25/128`. DEV-Level 1 scaffold; `[netdev] enabled=no` default.
Vault analysis: [2026-07-13-max25-tcpip-virtual-netdev-hbx-analysis.md](2026-07-13-max25-tcpip-virtual-netdev-hbx-analysis.md).
Frozen: `docs/NETDEV.md`.
---
## 12. Troubleshooting
| Symptom | Check |
|---------|-------|
| Serial busy | One owner — stop minicom; max25d **or** HyBBX |
| TNC silent / echo-only | Recovery ladder; DTR at boot |
| max25d unreachable | HyBBX skips local TNC when `[max25] check=yes` |
| BayCom KISS open failed (io) | KISS path `/tmp/max25-bcpr/kiss-bc0`; max25d `mode=hybbx-cohost`; HyBBX in `dialout` — [root-cause](../integration/2026-07-31-baycom-kiss-open-io-root-cause.md) |
| CRDOP TCP fail | Ports 8515/8516; `crdopc` running |
Release audit: [2026-07-12-max25-v1.0.0-release-audit.md](2026-07-12-max25-v1.0.0-release-audit.md).
---
## Related
| Topic | Path |
|-------|------|
| FreeBSD + feature matrix SSoT | [2026-07-13-max25-freebsd-tnc-baycom-full-feature-matrix.md](2026-07-13-max25-freebsd-tnc-baycom-full-feature-matrix.md) |
| TF native recovery SSoT | [2026-07-13-thefirmware-native-recovery-sequence.md](2026-07-13-thefirmware-native-recovery-sequence.md) |
| max25d power-cycle root cause | [2026-07-13-max25d-tnc-recovery-power-cycle-root-cause.md](2026-07-13-max25d-tnc-recovery-power-cycle-root-cause.md) |
| CRDOP development | [2026-07-13-crdop-development-master.md](2026-07-13-crdop-development-master.md) |
| HyBBX integration guide | [../hybbx/2026-07-13-master-documentation.md](../hybbx/2026-07-13-master-documentation.md) |
| Dual-TNC operator flow | [DUAL-TNC-OPERATOR-GUIDE.md](DUAL-TNC-OPERATOR-GUIDE.md) |
| TNC2multi integration | [2026-07-14-tnc2multi-max25-integration.md](2026-07-14-tnc2multi-max25-integration.md) |
| Linux kernel AX.25 ecosystem gap | [reference/2026-07-13-linux-kernel-ax25-ecosystem-gap.md](../../reference/2026-07-13-linux-kernel-ax25-ecosystem-gap.md) |
| Frozen product docs | `docs/`, `stacks/tncs/docs/` |
|
