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
|
<!-- AUTO-SYNC 2026-08-01 — vault: projects/hybbx/2026-07-13-master-documentation.md -->
<!-- Re-sync: /home/akb/Code/0-RESEARCHES/tools/vault-sync-slave-docs.sh -->
# HyBBX — Master operator guide
**Shipped guide** — canonical edits in research vault `projects/hybbx/2026-07-13-master-documentation.md`; run sync script after change.
## Summary
Single linear guide: what HyBBX is, how to install and configure it, attach RF via MAX25 prep, run clients and commands. Shipped product docs in `docs/` remain **frozen reference** — depth investigations live.
---
## 1. Role and architecture
HyBBX (**hyBBX** — hybrid Mailbox build System X) is a **plannable (hy)BBX network system**: closed and self-contained BBX networking; the Internet is used primarily for interconnection and logical work; Internet and external services are fully extensible via **plugins** ([§0.17](../../AGENT-INDEX.md#017-hybbx-product-positioning-static-rule)).
Technically: a **text-first BBX/mail/chat** daemon (`hybbxd`) with optional RF transports. Users connect via telnet (`:2323`), SSH (`:3232`), or WebSocket proxy. RF paths use transport plugins that bridge serial/KISS or kernel modems to **HBX** (Hybrid Bridge eXchange) on the circuit hub (`:7323`).
```
Users (telnet/SSH/WebSocket) ──► Main (storage, mail, HBX hub :7323)
▲
│ HBX/TCP
Secondary (packet_radio / baycom / crdop)
│
TNC / modem (after MAX25 prep)
```
| Role | `[networks]` | Hosts |
|------|--------------|-------|
| **Main** | `circuit=yes`, `ax25=no` (typical) | Users, HBX hub |
| **Secondary** | `circuit=no`, `ax25=yes` | RF near TNC; `circuit_host` → Main |
| **Standalone Main** | `ax25=yes` on same box | Lab / single-host (e.g. dual local TNC) |
**HBX/Circuit** — sole inter-node transport. Application core never sees raw KISS or on-air AX.25; only typed HBX frames on TCP.
Frozen reference: `docs/TOPOLOGY.md`, `docs/MANUAL.md`.
---
## 2. Install and build
| Step | Action |
|------|--------|
| Build | `hyBBX/scripts/build.sh` or CMake per `docs/BUILD.md` |
| Binary | `hybbxd` — start via `hybbx-start` or `hybbxd -c hybbx.ini` |
| Detached | `hybbx-start --screen` / `--tmux`; attach: `hybbxd --screen --attach` |
| INI templates | `hyBBX/share/hybbx-standalone.ini.example`, `hybbx-main.ini.example`, `hybbx-secondary.ini.example`, `hybbx-mesh.ini.example` |
First start creates Sysop in `users/users.ini` with a one-time random password on the console.
---
## 3. INI — operator essentials
Full key tables: frozen `docs/MANUAL.md`. Vault INI copy (reference station): `share/` INI examples.
### Core sections
| Section | Purpose |
|---------|---------|
| `[service]` | Name, session limit, prompt |
| `[storage]` | `flatfile` or `sqlite`; user shards under `users/` |
| `[networks]` | Enable plugins: `ax25`, `baycom`, `crdop`, `circuit`, `ssh`, `websocket` |
| `[transport.telnet]` | Bind, port `2323` |
| `[transport.circuit]` | HBX hub port `7323`, `max_links` (default 8, max 16) |
| `[transport.packet_radioN]` | TNC instance — device, `tnc=` profile, `protocol=kiss` |
| `[broadcast]` | `ax25_mycall`, `ax25_auto_message`, `ax25_dest` |
| `[max25]` | `check=yes` — probe max25d TCP `:7325` before local serial open |
### RF on Main vs Secondary
| Layout | TNC keys on Main `[transport.packet_radioN]` |
|--------|-----------------------------------------------|
| Remote Secondary | Bridge registry only (`link_id`, password) — no `device` |
| Local TNC (standalone) | Full keys: `device`, `tnc`, `baud`, `serial_line`, `rts_dtr` |
Bridge-registry rows without `device` are skipped at start (no serial open).
---
## 4. TNC attach (MAX25 contract) — v2.8.0
**Order:** MAX25 prep **before** HyBBX for local serial TNC. One process per `/dev/tty*`. HyBBX **attach-only** on KISS (`kiss_entry=none` after max25d prep).
| Layer | Owner | Action |
|-------|-------|--------|
| Boot-wait, DTR/RTS, MYCALL, `kiss on` | MAX25 | `max25-ctl start --hardware tncs` or `tnc2c-boot-wait.sh` |
| max25d reachability | HyBBX `[max25] check=yes` | TCP `:7325` — **required** for local TNC (start fails if down) |
| KISS attach | HyBBX `packet_radio` | `kiss_entry=none` (default with MAX25) |
| AX.25 UI build, HBX bridge, broadcast | HyBBX | `broadcast.c`, `packet_radio.c`, `tnc.c` |
| BayCom/based plugin | HyBBX | Built by default; `[networks] baycom=yes` when RF used — [operational status](../integration/2026-08-01-baycom-pccom-operational-status.md) |
HyBBX builds outbound UI frames from `[broadcast] ax25_mycall` — it does **not** send host `MYCALL` to the TNC (MAX25 does that at prep).
| INI key | Production value | Notes |
|---------|------------------|-------|
| `kiss_entry` | `none` | TNC already in KISS after MAX25 |
| `kiss_exit` | `none` | Shutdown does not send `kiss off` |
| `persist` | `255` on CB | CSMA — avoid random defer on busy channel |
| `protocol` | `kiss` | Required for Secondary RF |
| `[max25] check` | `yes` | Local serial edges only |
TNC profiles in `packet_radio`: `tnc2c`, `tnc2`, `pk232`, … — see shipped `docs/TNCS.md`. BayCom/based transport: **built by default**, **available and usable** — enable `[networks] baycom=yes`; KISS **`/tmp/max25-bcpr/kiss-bc0`**; standalone/co-host verified 2026-07-31 / 2026-08-01.
Release prep: [2026-07-14-v2.8.0-release-prep.md](2026-07-14-v2.8.0-release-prep.md).
Recovery without power cycle: internal research note) · MAX25 `stacks/tncs/docs/TNC-RECOVERY.md`.
---
## 5. RF, broadcast, and HBX
### Auto-beacon and manual broadcast
| Command | Scope | Sysop |
|---------|-------|-------|
| `/broadcast <msg>` | Local logged-in users (telnet/SSH/WebSocket) | yes |
| `/broadcast ax25` | Sequential RF beacon per link (`ax25_auto_message`; 60 s gap) | yes |
RF path: Main → HBX → Secondary link → KISS → TNC → on-air.
### Standalone Main production facts
Dual local TNC + optional BayCom on one host — shipped: [BAYCOM.md](BAYCOM.md) · [DUAL-TNC-OPERATOR-GUIDE.md](DUAL-TNC-OPERATOR-GUIDE.md). Vault depth: [co-host runbook](../integration/2026-07-31-standalone-cohost-runbook.md) · [BayCom operational status](../integration/2026-08-01-baycom-pccom-operational-status.md).
| Issue class | Vault SSoT fix |
|-------------|----------------|
| No PTT despite `RF TX` log | FCS strip, MYCALL before KISS, UNPROTO path, `persist=255` |
| Circuit queue dropped beacons | Bypass low-prio queue for AX.25 broadcast TX |
| `ax25_dest=*` invalid | Map to `QST` |
| TNC stuck after crash | KISS return frame `0xC0 0xFF 0xC0` before prep |
### BayCom and CRDOP plugins
| MAX25 hardware | HyBBX plugin | INI |
|----------------|--------------|-----|
| `hardware/modems` | `baycom` | `[networks] baycom=yes` — merge `share/hybbx/baycom-ser12-host.ini.example` |
| **BayCom/based** (max25-bcpr via MAX25) | available · default build | Standalone Main or co-host (TNC + PC-COM); KISS `/tmp/max25-bcpr/kiss-bc0` — [plugin](2026-07-18-baycom-based-plugin-via-max25.md) · [operational status](../integration/2026-08-01-baycom-pccom-operational-status.md) |
| `hardware/soft-modems` | `crdop` | `[networks] crdop=yes` — merge `share/hybbx/crdop-host.ini.example` |
Frozen: `docs/BAYCOM.md`, `docs/CRDOP.md` · MAX25 contract: `docs/HYBBX.md`. Public mark for SER12 class: **BayCom/based** (never Konverter/converter).
---
## 6. Clients
| Client | Transport | Default port |
|--------|-----------|--------------|
| `hybbx-telnet` | TCP | 2323 |
| `hybbx-ssh` | SSH (libssh) | 3232 |
| `hybbx-terminal` | HBX circuit | 7323 |
| Web browser | WebSocket via reverse proxy | per site |
Frozen: `docs/CLIENTS.md`, `docs/WEBSOCKET.md`.
---
## 7. Commands and access levels
Five levels: Sysop → Admin → Mod → User → Guest. `/help`, `/menu` filtered by level; `/index` lists all commands for every account.
| Sysop RF | `/broadcast`, `/broadcast ax25`, `/shutdown` |
|----------|-----------------------------------------------|
| Admin | `/usercreate`, `/activate`, `/promote`, `/demote` |
Frozen: `docs/COMMANDS.md`, `share/commands.yaml`, `share/areas.yaml`.
---
## 8. Operator start order (with MAX25)
Linear sequence for standalone Main + local TNC:
1. **MAX25 prep** — boot-wait or `max25d` per TNC port (or verify `ss -ltn | grep 7325`)
2. **HyBBX** — `hybbxd -c hybbx.ini` with `kiss_entry=none`, `[max25] check=yes`
3. **Verify** — log: `max25d reachable` → `KISS attach (MAX25 prep assumed)` → `RF TX` on `/broadcast ax25`
4. **RF check** — PTT and on-air decode at remote station
Integration detail: [DUAL-TNC-OPERATOR-GUIDE.md](DUAL-TNC-OPERATOR-GUIDE.md).
---
## 9. Future roadmap (deferred)
Aligned with MAX25 [V2.0.0-SCOPE](../../10-PROJECTS/docs/V2.0.0-SCOPE.md) **Later** row — **no product commits** until operator orders a separate track.
| Later | Status |
|-------|--------|
| **`/aichat`** — AI / assistant session command | **deferred** |
| AI / assistant integration (backends, APIs) | **deferred** |
| like-features | **deferred** |
Full map: [2026-07-14-hybbx-future-roadmap.md](2026-07-14-hybbx-future-roadmap.md).
**v2.8.0:** `/who` lists **interactive users only** (telnet/SSH/WebSocket) — plugin/RF connection sessions are not users.
---
## Related
| Topic | Path |
|-------|------|
| RF investigation SSoT | [2026-07-12-site-rf-broadcast-investigation.md](2026-07-12-site-rf-broadcast-investigation.md) |
| tnc.c recovery integration | [2026-07-13-tnc-recovery-integration.md](2026-07-13-tnc-recovery-integration.md) |
| INI operator notes | [2026-07-12-ini-operator-notes.md](2026-07-12-ini-operator-notes.md) |
| MAX25 boundary | [../integration/2026-07-12-max25-hybbx-boundary-final.md](../integration/2026-07-12-max25-hybbx-boundary-final.md) |
| Dual-TNC operator flow | [DUAL-TNC-OPERATOR-GUIDE.md](DUAL-TNC-OPERATOR-GUIDE.md) |
| Frozen product docs | `docs/` (read-only) |
| Production INI (vault) | `share/` INI examples |
| TNC hardware SSoT | [hardware/tnc2c/CONFIRMED.md](../../hardware/tnc2c/CONFIRMED.md) |
|
