Executive summary
URTB—USB-Radio Terminal Bridge—carries an interactive terminal through an authenticated encrypted session. Its main hardware path uses two USB-attached Heltec WiFi LoRa 32 V3 boards, preferring ESP-NOW and falling back to LoRa. The same host binary can be evaluated without hardware through Unix sockets, a child process, or an SSH jump host. Two endpoints share a passphrase-protected capsule; the intermediate transport does not receive the session secret. The repository includes firmware, host code, protocol documentation, threat modeling, decision records, and separate software and hardware test tiers.
Problem and context
Remote terminals usually assume an IP path and a trusted transport setup. URTB tests a narrower alternative for low-bandwidth or awkward links: keep the PTY protocol and cryptographic session on the endpoint computers, and treat the radio boards or jump host as untrusted byte transport.
What was built
- A host terminal program with listener and connector modes.
- Unix-socket, stdio, spawned-process, and Heltec USB transports.
- ESP-NOW firmware with automatic LoRa fallback and regional build settings.
- Passphrase-protected pre-shared-key capsules, optional one-time password, and
- Wire-format, security, porting, testing, and jump-host documentation.
- Sandbox profiles that integrate with the sibling
compartmentproject.
a burn mode for removing loaded key files.
How it works
Both endpoints load the same capsule, derive and authenticate the session, then frame terminal traffic with XChaCha20-Poly1305. Unique nonces protect each frame. On the hardware path the host talks to its local board over USB serial; boards carry frames over ESP-NOW and move to LoRa when that path fails.
The stdio and subprocess transports make the encrypted stream composable with SSH or another carrier. A jump host forwards ciphertext but does not receive the capsule passphrase or session key.
Evidence and validation
The software test tier covers the frame and host behavior without requiring radio devices. A separate hardware tier is documented for two Heltec V3 boards, and the jump-host guide records validated stdio and subprocess scenarios. CI runs the software checks; acceptance criteria map features to their test paths.
Boundaries
Endpoints must provision the same capsule out of band. Security does not hide that a radio or stream is active, and low-bandwidth radio behavior depends on range, region, interference, and board configuration. Signal-time cleanup is best effort for fatal process faults. Hardware use requires two specific boards and the region-appropriate frequency and power settings.
Repository map and first run
make doctor
make
make smoke
make checkThe no-hardware Unix-socket example is at the top of the source README. Use HOWTO.md for end-to-end scenarios, HOWTO_JUMPHOST.md for encrypted carrier setups, PROTOCOL.md for framing, and SECURITY.md for the threat model and key lifecycle.