vasilito
9f2de2a0b1
Docs:
- Baseline was stated as 0.3.1 across the canonical set while the branch,
Cat 0/1 crates and every Cat 2 fork are 0.3.2. AGENTS.md also cited a
sources/redbear-0.3.1/ archive that does not exist; the only archive
present is sources/redbear-0.1.0/. Versioning examples now match the
forks as they actually stand (redoxfs/syscall 0.9.1, libredox 0.1.19).
- Repaired 18 instances of 'immutable archived' across 8 documents, where
a global find/replace had turned sync/synced/archived into that phrase
and produced ungrammatical text ('never auto-immutable archived',
'### Source immutable archived').
- Settled the apply-patches.sh contradiction empirically. Both sides were
wrong: the GROSS WARNING blocks (x5) described it as routine
patch-linking, and SCRIPT-BEHAVIOR-MATRIX.md said build-redbear.sh
'never invokes' it. It is invoked at build-redbear.sh:487, but only to
auto-repair a failed verify-overlay-integrity.sh check.
- Dropped the dangling reference to a local/AGENTS.md section
'NO OVERLAY-STYLE PATCHES — SCOPED POLICY' that does not exist.
Build system:
- mk/prefix.mk hardcoded 13.2.0 in the limits.h removal, which silently
no-ops after a toolchain upgrade and leaves the conflicting header.
Version-globbed.
- Parameterized GCC_RECIPE so the from-source toolchain path is not
pinned to gcc13.
- The three cstdlib strtold seds were not idempotent -- the shipped GCC
13 toolchain carried that comment block 17 times from repeated
'make prefix' runs. Each is now guarded.
54 lines
3.9 KiB
Markdown
54 lines
3.9 KiB
Markdown
# redbear-btctl — Operator Runbook
|
|
|
|
**Daemon:** redbear-btctl
|
|
**Init service:** `/usr/lib/init.d/21_btctl.service`
|
|
**Status check:** `redbear-btctl --status [adapter]`
|
|
**Restart:** `init-svc restart btctl`
|
|
|
|
## Logs
|
|
- Destination: `stderr` (visible via `journalctl -u btctl`)
|
|
- Debug: `REDBEAR_BTCTL_LOG=debug redbear-btctl [command]`
|
|
- Trace: `REDBEAR_BTCTL_LOG=trace redbear-btctl [command]`
|
|
|
|
## Modes
|
|
- CLI commands (one-shot): `--probe`, `--status`, `--scan`, `--bond-list`, `--bond-add-stub`, `--bond-remove`, `--connect`, `--disconnect`, `--read-char`
|
|
- Daemon mode (no args, Redox only): Long-running `scheme:btctl` daemon. Handles connect/disconnect/read-char via scheme write paths. On Redox host, CLI commands (`--connect`, `--disconnect`, `--read-char`) forward requests to the live daemon via `scheme:btctl` paths.
|
|
|
|
## CLI Commands
|
|
| Command | Usage | Description |
|
|
|---------|-------|-------------|
|
|
| `--probe` | `redbear-btctl --probe` | Adapter list + capabilities |
|
|
| `--status` | `redbear-btctl --status [hciN]` | Adapter status, bond count, scan result count |
|
|
| `--scan` | `redbear-btctl --scan [hciN]` | Trigger stub scan (returns `demo-beacon,demo-sensor`) |
|
|
| `--bond-list` | `redbear-btctl --bond-list [hciN]` | List persisted bond records |
|
|
| `--bond-add-stub` | `redbear-btctl --bond-add-stub hci0 AA:BB:CC:DD:EE:FF [alias]` | Add stub bond record |
|
|
| `--bond-remove` | `redbear-btctl --bond-remove hci0 AA:BB:CC:DD:EE:FF` | Remove bond record |
|
|
| `--connect` | `redbear-btctl --connect hci0 AA:BB:CC:DD:EE:FF` | Connect to bonded device |
|
|
| `--disconnect` | `redbear-btctl --disconnect hci0 AA:BB:CC:DD:EE:FF` | Disconnect bonded device |
|
|
| `--read-char` | `redbear-btctl --read-char hci0 AA:BB:CC:DD:EE:FF <svc-uuid> <char-uuid>` | Read GATT characteristic |
|
|
|
|
## Backend Selection
|
|
- `REDBEAR_BTCTL_BACKEND=stub` (default) — Stub backend with hardcoded adapter `hci0`
|
|
- `REDBEAR_BTCTL_BACKEND=hci` — Live HCI backend (reads from /scheme/btusb)
|
|
|
|
## Scheme Paths (Daemon Mode, Redox Only)
|
|
- `/scheme/btctl/adapters/<adapter>/status` — Connection status
|
|
- `/scheme/btctl/adapters/<adapter>/transport-status` — Transport health
|
|
- `/scheme/btctl/adapters/<adapter>/connection-state` — Connected bond IDs
|
|
- `/scheme/btctl/adapters/<adapter>/connect` — Write bond ID to connect
|
|
- `/scheme/btctl/adapters/<adapter>/disconnect` — Write bond ID to disconnect
|
|
- `/scheme/btctl/adapters/<adapter>/read-char` — Write bond/service/char UUIDs to read
|
|
- `/scheme/btctl/adapters/<adapter>/connect-result` — Last connect result
|
|
- `/scheme/btctl/adapters/<adapter>/disconnect-result` — Last disconnect result
|
|
- `/scheme/btctl/adapters/<adapter>/read-char-result` — Last read-char result
|
|
|
|
## Signals / SIGTERM Behavior
|
|
- No SIGTERM handler; killed by init system. Daemon uses `INIT_NOTIFY` fd for scheme-ready notification.
|
|
|
|
## Common Issues
|
|
1. **`redbear-btctl daemon is not serving scheme:btctl`** — CLI command attempted a scheme write on a host without the daemon running. Start the daemon first (`redbear-btctl` with no args on Redox), or use the stub CLI path on the host (connect/disconnect/read-char output is marked `runtime_scope=process-local-host-cli`).
|
|
2. **`bond record not found`** — Bond must be created via `--bond-add-stub` before `--connect`/`--disconnect`/`--read-char`. Bonds persist to `bond_store_root` on disk.
|
|
3. **`explicit-startup-required` in status** — Transport runtime (`redbear-btusb --daemon`) is not running or its status file is missing/stale. The control daemon requires the USB transport layer to be active.
|
|
4. **`only the experimental` error on `--read-char`** — The stub backend only supports reading the Battery Service (0x180F) Battery Level (0x2A19) characteristic. Other UUIDs are rejected with this message.
|
|
5. **Stub backend limitation** — All commands produce bounded stub responses suitable for development/testing. Real hardware requires `REDBEAR_BTCTL_BACKEND=hci` with a live `redbear-btusb` daemon serving the USB transport.
|