78 lines
3.7 KiB
Markdown
78 lines
3.7 KiB
Markdown
|
# host-bridge (Phase 0)
|
||
|
|
|
||
|
|
A host-side Python bridge that connects to one radio per network —
|
||
|
|
Meshtastic, MeshCore, and Reticulum (via an RNode-flashed board) — over
|
||
|
|
each project's **official** client protocol, and relays text messages
|
||
|
|
between all three. See `../docs/ARCHITECTURE.md` for why this is Phase 0
|
||
|
|
(prove the cross-network translation logic on 3 separate boards, no
|
||
|
|
custom firmware) rather than Phase 1 (one time-multiplexed radio on a
|
||
|
|
single Heltec V3).
|
||
|
|
|
||
|
|
## Status
|
||
|
|
|
||
|
|
**Written, not yet hardware-tested.** Every library call has been checked
|
||
|
|
against the upstream project's actual source/docs (see comments in each
|
||
|
|
`adapters/*.py` file for what was verified and how), and all four
|
||
|
|
dependencies (`meshtastic`, `meshcore`, `rns`, `lxmf`) install and import
|
||
|
|
cleanly. What's unverified is the actual on-air behavior once real radios
|
||
|
|
are attached — that requires the three boards described below.
|
||
|
|
|
||
|
|
## What you need to test this for real
|
||
|
|
|
||
|
|
- A Meshtastic-flashed board (e.g. Heltec V3) connected via USB serial or reachable over TCP (ESP32 WiFi build)
|
||
|
|
- A MeshCore companion-radio-flashed board, serial or TCP
|
||
|
|
- An RNode-flashed board (any RNode-compatible LoRa board) reachable via RNS's serial interface — configure this the same way archy's own `core/archipelago/src/mesh/reticulum.rs` KISS interface does, since this bridge uses the standard `rns`/`lxmf` Python packages, not a custom implementation
|
||
|
|
- All three radios need actual antennas/RF range to each other's respective real-world networks to see any traffic worth relaying — this is not simulatable without a radio in the loop
|
||
|
|
|
||
|
|
## Install
|
||
|
|
|
||
|
|
```bash
|
||
|
|
python3 -m venv venv
|
||
|
|
source venv/bin/activate
|
||
|
|
pip install -r requirements.txt
|
||
|
|
```
|
||
|
|
|
||
|
|
## Run
|
||
|
|
|
||
|
|
```bash
|
||
|
|
python3 main.py \
|
||
|
|
--meshtastic-port /dev/ttyUSB0 \
|
||
|
|
--meshcore-port /dev/ttyUSB1 \
|
||
|
|
--reticulum-storage ./rns-storage
|
||
|
|
```
|
||
|
|
|
||
|
|
Use `--meshtastic-host`/`--meshcore-host` instead of the `-port` flags if a
|
||
|
|
board is reachable over TCP (e.g. an ESP32 WiFi build) instead of USB
|
||
|
|
serial. Run `python3 main.py --help` for the full flag list.
|
||
|
|
|
||
|
|
## How relaying works
|
||
|
|
|
||
|
|
Each adapter pushes received text onto a shared, thread-safe queue
|
||
|
|
(`bridge_core.MessageBus`). A single dispatcher loop in `main.py` pulls
|
||
|
|
each message off, tags it with its origin network + sender, and re-sends
|
||
|
|
it on the other two networks — never back onto the network it came from.
|
||
|
|
|
||
|
|
Content-hash dedup (`MessageBus.is_duplicate`, 5-minute TTL by default)
|
||
|
|
stops the obvious relay loop (the bridge re-hearing its own relayed
|
||
|
|
copy). This is a known-simple v0 approach — it can't distinguish two
|
||
|
|
different messages that happen to have identical text within the TTL
|
||
|
|
window, and it doesn't help if there are *multiple* archy-messh bridges
|
||
|
|
active near each other. Good enough to prove the concept; revisit once
|
||
|
|
Phase 1 needs something more robust.
|
||
|
|
|
||
|
|
## Known gaps (by design, for v0)
|
||
|
|
|
||
|
|
- **Reticulum has no broadcast-channel primitive.** Meshtastic has channel
|
||
|
|
PSKs, MeshCore has public channel indices — Reticulum/LXMF messaging is
|
||
|
|
point-to-point between Destinations. `ReticulumAdapter` fakes broadcast
|
||
|
|
by tracking a roster of peer delivery-destinations learned from their
|
||
|
|
LXMF announces and fanning out to all of them individually. A shared
|
||
|
|
symmetric-key Reticulum `GROUP` destination would be a closer analog to
|
||
|
|
a real channel — noted as a follow-up, not implemented here.
|
||
|
|
- **MeshCore channel messages carry no sender identity at the protocol
|
||
|
|
level** (verified against `meshcore/reader.py` — `CHANNEL_MSG_RECV` has
|
||
|
|
no pubkey/name field). MeshCore apps convey sender identity by
|
||
|
|
convention inside the message text itself; this bridge doesn't attempt
|
||
|
|
to parse that out, so messages relayed *from* MeshCore show `?` as the
|
||
|
|
sender.
|