A Zephyr module that implements a Reticulum client, LXMF messaging and a Reticulum transport node in C, for small devices such as the nRF9151 Feather.
Reticulum and
LXMF are created by Mark Qvist, as is the
RNode firmware whose LoRa framing the gateway
sample speaks. ret-client is an independent implementation of his protocols. The Python
reference implementation is the specification: byte formats are tested against vectors produced
by RNS's own functions, and every feature is tested end to end against a real rnsd. Without
Mark's design, reference code and documentation, none of this would exist. See the
Reticulum manual to learn about the network itself.
ret-client is not part of, or endorsed by, the Reticulum project.
Also built on:
- Zephyr and the nRF Connect SDK
- Monocypher by Loup Vaillant (X25519, Ed25519)
- MPack by Nicholas Fraser (MessagePack, for LXMF)
- Connects to an
rnsdTCPServerInterface(HDLC framing), optionally with an interface access code (IFAC). - Announces, path requests, encrypted packets to SINGLE destinations, delivery proofs and ratchets.
- Links, both sides (opening, with requests, and accepting), and Resources both ways.
- LXMF: opportunistic and DIRECT messages both ways, and sync from a propagation node.
- A transport node (
CONFIG_RET_TRANSPORT), behaving as RNS'sTransport.pywithenable_transport = yes: routing, announce rebroadcast and caps, path discovery, link and reverse tables, and tunnel synthesis.
The protocol as implemented, with the RNS functions each part follows, is in
docs/protocol.md.
| Sample | |
|---|---|
samples/ret_basic |
raw Reticulum packets and a link test |
samples/ret_lxmf |
an always-connected LXMF node |
samples/ret_lxmf_sleep |
a sleepy LXMF node: wake, sync, answer, suspend |
samples/ret_chat |
LXMF chat over the Zephyr shell |
samples/ret_lora_gateway |
a transport node bridging a LoRa radio (RNode framing) and an LTE/TCP uplink to a stock rnsd |
From a west workspace containing this repo (west init -m <repo> --mf west-vanilla.yml for
native_sim only, west-ncs.yml for the nRF91):
west build -b native_sim ret-client/samples/ret_basic -d build/ret_basic -p --no-sysbuild
./build/ret_basic/zephyr/zephyr.exe --seed-random--seed-random is required on native_sim: without it the test RNG repeats every run and rnsd
drops the repeated packets as duplicates. The sample connects to 127.0.0.1:4242.
For the nRF9151 Feather, see "Hardware" in AGENTS.md: build with sysbuild and
flash with scripts/flash.py. AGENTS.md also covers the unit tests, the Python test peers and
the end-to-end script (tools/run_e2e.sh).
- Zephyr 4.5 (vanilla,
west-vanilla.yml) or NCS 3.5 (through nfed,west-ncs.yml) - Monocypher 4.0.2 and MPack 1.1.1, fetched by west
- PSA Crypto API (mbedTLS / nrf_security) for SHA-256, HMAC and AES-256-CBC
- For the tests: Python with
rns1.5.7 andlxmf1.2.1 (tools/rns_peer, managed withuv)
ret-client follows the Reticulum and LXMF reference implementations closely, so it is
distributed under the same Reticulum License, with Mark Qvist's copyright notice
kept. Source files carry SPDX-License-Identifier: LicenseRef-Reticulum.
The license is MIT-style with two conditions: the software must not be used in systems meant to
harm people, and must not be used to create AI or machine-learning training datasets. Read
LICENSE for the exact terms.
Monocypher (BSD-2-Clause or CC0) and MPack (MIT) are fetched by west under their own licenses.