Meshtastic bridge CLI for reliable chunked transport.
npm install meshtastic-bridgeReliable chunking and reassembly for sending larger payloads over Meshtastic links.
This package focuses on the transport layer: binary envelopes, chunk splitting,
ACK/NACK reliability strategies, deduplication, and optional spooling.
- Binary envelopes (MessagePack + Zstandard) with compact headers
- Chunking/reassembly tuned for Meshtastic payload limits
- Reliability strategies (simple ACK, staged, windowed selective, parity window)
- Deduplication and semantic-key support to avoid replayed requests
- Optional on-disk spool for retrying outgoing messages
- In-memory radio for local simulation/testing
- Hardware harness for manual testing with real radios
- Interactive TUI with command palette for radio and mode selection
- Web browser UI for browsing websites over the mesh network
- Port accessibility detection to verify radio connections
- JSON-based mode configuration for transport parameters
This project ships a small Node wrapper so you can run the Python CLI via annpm-installed command.
``bashInstall from npm registry (recommended)
npm install -g meshtastic-bridge
Set
MESHTASTIC_BRIDGE_PYTHON if you need to point at a specific Python executable.
The UI uses the Meshtastic Python stack, so ensure requirements.txt is installed.Interactive TUI
The
meshbridge command launches an interactive terminal UI that provides:- Real-time monitoring: View radio connection status, gateway traffic, and message payloads
- Command palette (Ctrl+P): Access all commands and settings
- Radio port selection: Choose which serial port to connect to from detected and accessible ports
- Mode configuration: Switch between transport modes with different reliability strategies and parameters
- Gateway/client switching: Start gateway service or send client requests via the command palette
$3
-
Ctrl+P - Open command palette
- ↑/↓ or j/k - Navigate palette options
- Enter - Select palette option
- Esc - Close palette / Cancel
- Ctrl+C - Quit application$3
Transport modes are defined in JSON files in the
modes/ directory. Each mode can customize:
- Chunk size and header format
- ACK/NACK reliability strategy (simple, staged, windowed, parity)
- Timeout and retry parameters
- Compression settingsCreate custom modes by adding new JSON files to the
modes/ directory.Web Browser
When you select Open Client in the TUI, a web browser server automatically starts on
http://127.0.0.1:8080. This allows you to browse websites over your Meshtastic mesh network.$3
1. Run
meshbridge and select Open Client
2. Enter the Gateway Node ID in the TUI
3. Open http://127.0.0.1:8080 in your web browser
4. Enter any URL (e.g., example.com) in the search bar
5. The page is fetched through the gateway over the mesh and displayed$3
- Real-time progress tracking with chunk counts and ETA
- Automatic URL normalization (adds
https:// if missing)
- Relative link handling via tag injection
- Click-through navigation (links are fetched through the mesh)
- Works best with simple, text-based websites$3
You can also run the web browser directly without the TUI:
`bash
python ui_service/web_ui.py --gateway-node-id !abcd1234
`Or via the CLI:
`bash
python scripts/cli.py \
--mode client \
--gateway-node-id !abcd1234 \
--web-browser
`Quick start (simulated radios)
Terminal 1 - start a gateway:
`bash
python scripts/cli.py \
--mode gateway \
--gateway-node-id gw-1 \
--simulate-radio \
--node-id gw-1
`Terminal 2 - send a request:
`bash
python scripts/cli.py \
--mode client \
--gateway-node-id gw-1 \
--simulate-radio \
--node-id client-1 \
--command echo \
--data '{"message":"hello"}'
`Hardware harness
The manual harness lives in
tools/hardware_harness. It spins up a gateway and
client on two radios (or simulation), then provides an interactive menu for
echo and payload-digest tests.`bash
python tools/hardware_harness/dual_radio_harness.py
`CLI flags
| Flag | Description |
| --- | --- |
|
--mode {gateway,client} | Run as gateway or client (required). |
| --gateway-node-id | Meshtastic node ID of the gateway (required). |
| --simulate-radio | Use in-memory radio instead of hardware. |
| --radio-port | Serial port path (hardware mode). |
| --node-id | Override local node ID (default: gateway or client). |
| --command | Client command to run (client mode). |
| --data | JSON payload for the command (client mode). |
| --timeout | Client request timeout in seconds (default: 5). |
| --spool-path | Path for persistent outgoing message spool. |
| --log-level | Logging level (default: INFO). |
| --web-browser | Start web browser UI for browsing over mesh (client mode). |
| --web-host | Host for web browser UI (default: 127.0.0.1). |
| --web-port | Port for web browser UI (default: 8080). |Notes
- The binary protocol is described in
docs/SYSTEMS_DESIGN.md.
- The gateway exposes default handlers for echo, payload_digest, and health.
- For large payload testing, prefer the harness payload_digest` flow so the