Leviculum

Leviculum is a Rust implementation of the Reticulum network stack. It is wire-compatible with the Python reference implementation and runs on Linux, macOS, and embedded devices.

What is Reticulum?

Reticulum is a networking stack for building resilient, encrypted mesh networks over any transport medium. It works over LoRa radios, TCP, UDP, serial links, or anything that can carry bytes. Every node gets a cryptographic identity. Every connection is end-to-end encrypted. No servers, no accounts, no infrastructure required.

What does leviculum do?

Leviculum provides the same functionality as Python Reticulum but compiled to native code. The lnsd daemon is a drop-in replacement for rnsd. The lncp file transfer tool replaces rncp. Python CLI tools like rnstatus, rnpath, and rnprobe work against a running lnsd without modification.

The protocol core (reticulum-core) compiles as no_std with only alloc, so it runs on microcontrollers. The same code powers the Linux daemon, a future Android app, and embedded firmware.

Who this manual is for

• Daemon users running lnsd alongside or instead of rnsd: start with the lnsd quickstart and the man pages.
• Developers embedding or extending the stack: read the Concepts part — the Architecture overview plus Interface Isolation, Python-RNS Compatibility, Identity and Forward Secrecy, and Storage and Embedding.
• Firmware flashers putting Leviculum on nRF52 boards: see the firmware section and the RNode protocol reference.

The Concepts part explains the non-obvious design ideas; the appendix carries the authoritative Reticulum and LXMF specifications.

Tools

Leviculum ships three binaries:

• lnsd – the Reticulum network daemon
• lns – multi-tool for network status, path lookup, probing, identity management, file transfer, and interactive sessions
• lncp – standalone file transfer utility (compatible with Python rncp)

Architecture Overview

This is the entry point to the Concepts part of the manual. It covers the sans-IO core, the crate split, the driver event loop, and the platform-abstraction traits — the mechanics that the four concept pages build on:

• Interface Isolation — why only the interface knows its medium’s quirks.
• Python-RNS Compatibility — wire/semantic compatibility and the drop-in daemon, vs. internal parity (not a goal).
• Identity and Forward Secrecy — dual keypairs, derived destinations, ratchets.
• Storage and Embedding — the Clock/Storage/Interface traits that let one core run on a host or a microcontroller.

The crate split

The protocol logic lives in one no_std crate; everything platform- specific wraps around it:

The application boundary is NodeCore: feed it bytes via handle_packet / handle_timeout and drain a TickOutput { actions, events }. The core decides what to send; the driver decides how and when to put it on the wire. See Storage and Embedding for the injected Clock/Storage/Interface traits that make this portable.

Sans-I/O Core

                     ┌─────────────────────────────────┐
                     │         reticulum-core           │
                     │                                  │
  handle_packet() ──►│  NodeCore<R, C, S>               │──► TickOutput {
  (iface_id, data)   │    ├── Transport (routing)       │      actions: Vec<Action>,
                     │    ├── Links + Channels           │      events: Vec<NodeEvent>,
  handle_timeout() ─►│    └── Destinations              │    }
                     │                                  │
  next_deadline() ──►│  Returns: Option<u64>            │
                     └─────────────────────────────────┘

  Action::SendPacket { iface, data }     — send to one interface
  Action::Broadcast { data, exclude }    — send to all interfaces (except one)

Driver Event Loop

The reticulum-std driver has 6 select! branches:

#![allow(unused)]
fn main() {
loop {
    select! {
        // 1. Packet from any interface
        (iface_id, data) = registry.recv_any() => {
            output = core.handle_packet(iface_id, &data);
            post_dispatch(output);
        }
        // 2. External action (connect, send, announce)
        output = action_dispatch_rx.recv() => { post_dispatch(output); }
        // 3. Timer fires
        _ = sleep_until(next_poll) => {
            output = core.handle_timeout();
            post_dispatch(output);
        }
        // 4. Shutdown
        _ = shutdown.changed() => break
        // 5. New interface (TCP accept, local client connect)
        handle = new_interface_rx.recv() => {
            registry.register(handle);
            output = core.handle_interface_up(iface_idx);
            post_dispatch(output);
        }
        // 6. Periodic storage flush (crash protection, hourly)
        _ = sleep_until(next_flush) => { core.storage_mut().flush(); }
    }
}
}

Post-dispatch (after every core call)

1. dispatch_actions(&mut ifaces, &output.actions) — routes Actions to interfaces (protocol logic in core)
2. React to errors — BufferFull: log. Disconnected: call handle_interface_down()
3. Forward output.events to the application
4. Schedule handle_timeout() from output.next_deadline_ms

Interface Trait

#![allow(unused)]
fn main() {
pub trait Interface {
    fn id(&self) -> InterfaceId;
    fn name(&self) -> &str;
    fn mtu(&self) -> usize;
    fn is_online(&self) -> bool;
    fn try_send(&mut self, data: &[u8]) -> Result<(), InterfaceError>;
}
}

Send-only. Receive is driver-specific (tokio: mpsc::poll_recv, Embassy: interrupt DMA, bare-metal: poll FIFO). try_send is fire-and-forget: Reticulum is best-effort, higher layers retransmit.

dispatch_actions() lives in core (not the driver) because action routing (broadcast exclusion, interface selection) is protocol knowledge.

In reticulum-std, InterfaceHandle wraps tokio::sync::mpsc::Sender behind the trait. An embedded driver implements it directly on a radio struct.

Core processes packets with zero delay. Collision avoidance (jitter, CSMA) is the interface’s responsibility — fast interfaces (TCP) transmit immediately, slow interfaces (LoRa) apply send-side jitter. This is the interface-isolation rule in code.

Writing a Driver

1. Create interface objects

Implement Interface on your outbound channel. Register with your own bookkeeping. Core references interfaces by InterfaceId only.

2. Run the event loop

Minimum 3 branches: receive, timer, shutdown. Feed everything through the post-dispatch sequence above.

3. Handle the receive path

Driver-specific. On complete packet: core.handle_packet(iface_id, &data) → post-dispatch. On disconnect: core.handle_interface_down(iface_id).

Packet Flow

Incoming

Interface → deframe → mpsc → recv_any() → handle_packet()
  → Transport::process_incoming() → TickOutput
  → dispatch_actions() → interfaces → wire
  → events → application

Outgoing

Application → connect/send/announce → TickOutput (via action_dispatch)
  → dispatch_actions() → interfaces → wire

Local Client (Shared Instance)

lns/lncp → Unix socket → LocalInterface (HDLC)
  → handle_packet() with is_local_client=true
  → local_client_known_dests updated (6h TTL)

RPC (rnstatus, rnpath, rnprobe)

Python CLI → Unix socket → RPC server (multiprocessing.connection, pickle)
  → handlers query NodeCore state or trigger probe
  → pickle response → CLI

The shared-instance socket and this RPC channel are what make lnsd a drop-in for rnsd; see Python-RNS Compatibility.

IPC platform support

The shared-instance data channel and the RPC control channel use abstract Unix sockets on Linux, filesystem Unix sockets on macOS/BSD, and TCP loopback on Windows (mirroring Python-RNS’s AF_INET fallback). Linux is the tested path and is the one exercised by our CI; macOS/Windows IPC is community-supported and not exercised by our CI.

Storage Trait

For the conceptual rationale (one core, host or embedded backend) see Storage and Embedding; for the per-method deep dive see Storage Trait Split Analysis.

Type-safe methods organized by collection:

Shared types in storage_types.rs: PathEntry, ReverseEntry, LinkEntry, AnnounceEntry, PacketReceipt.

Implementations: NoStorage (no-op), MemoryStorage (BTreeMap, host/tests), EmbeddedStorage (heapless FnvIndexMap, fixed capacity, used by reticulum-nrf), FileStorage (wraps MemoryStorage + disk).

FileStorage Persistence

Non-persistent collections (paths, reverses, links, announces, receipts) are RAM-only and rebuilt from network on restart.

Logging

Sentence-style messages with inline context. Good:

Destination <81b22f60> is now 4 hops away via <ecc35451> on iface 1
Answering path request for <4c0c6c7f> on iface 1, path is known

Bad:

path updated dest=81b22f60 hops=4

Use HexShort for hashes. Always explain drop reasons (“rate limited”, “duplicate packet”, “no path known”).

Interface Isolation

The single most important architectural rule in Leviculum:

Only the interface knows the quirks of its carrier medium. The core, the transport, and the daemon are media-agnostic.

A packet is a packet. At the boundary where the core hands bytes to an interface, there is no distinction between an announce, a link request, a data packet, or a resource chunk. They are all just bytes.

What “media-agnostic core” means

reticulum-core decides what to send and to which interface. It never decides when to put a frame on the wire, never spaces transmissions, and never reasons about contention. The core processes every packet with zero delay and emits an Action::SendPacket or Action::Broadcast immediately (see Architecture).

Because the core is the same code on a Linux daemon, an Android app, and an nRF52 firmware image, it cannot afford to know whether the medium underneath is a fibre-fast TCP socket or a half-duplex LoRa radio whose airtime budget is measured in minutes. Medium awareness lives entirely on the far side of the Interface trait.

What an interface is allowed to know

A LoRa interface knows it cannot transmit and receive at the same time. It knows its RadioSettings (bandwidth, spreading factor, coding rate) and therefore the airtime cost of any given frame. It holds packets back, applies its own randomised pre-TX jitter on top of the RNode firmware’s CSMA, and refuses new frames when its airtime budget is exhausted. Concretely:

• Send-side jitter — packets are queued, not sent immediately; the jitter window is sized from the radio parameters so two nodes do not re-collide (reticulum-std/src/interfaces/rnode.rs:130, the compute_jitter_max_ms doc comment, and the jitter queue at :448).
• CSMA — radio-level carrier sensing is handled by the RNode firmware; the interface defers collision avoidance to it rather than the core (reticulum-std/src/interfaces/rnode.rs:451).
• Airtime backpressure — a per-interface credit bucket charges every send by its airtime cost and signals BufferFull rather than flooding the serial queue (reticulum-std/src/interfaces/airtime.rs:1). This explicitly “never leaks into reticulum-core, so the no_std core stays free of host-side backpressure concerns” (same file).

A TCP interface has none of this. It just writes bytes (reticulum-std/src/interfaces/tcp.rs).

Why the rule is hard, not advisory

The rule binds anyone writing a fix. If a proposed fix for a collision, contention, or duplex problem introduces an awareness flag or counter in transport.rs, the node/ modules, or the daemon (“is a link in flight?”, “am I forwarding a link request?”), it is at the wrong layer. Such a fix must be redirected into the interface.

Interface implementations are therefore free to diverge from Python-Reticulum’s thin serial-writer style — that divergence is exactly where medium-specific intelligence belongs, and it satisfies the project’s deviation rule as long as wire and semantic compatibility are preserved.

Consequences

• The same routing logic runs unchanged over LoRa, TCP, UDP, serial, and the in-process local socket.
• New media are added by implementing one trait, not by threading medium-specific cases through the protocol core.
• Collision-avoidance bugs are debugged in one place — the interface — instead of being smeared across six stack layers.

See also: Storage and Embedding for the parallel isolation of persistence and time, and the RNode protocol page for the LoRa carrier details an interface must handle.

Python-RNS Compatibility

Leviculum is built to live in the same mesh as Python Reticulum (rnsd) and to be a drop-in replacement for the daemon and its tooling. Compatibility is pursued at two distinct levels, and one thing that is not pursued at all.

Level 1: wire and semantic compatibility

The protocol the two stacks speak must be identical on the air. The exact bytes of identities, destinations, announces, packets, and links are fixed by the Reticulum specification; the message format layered on top is fixed by the LXMF specification. Leviculum implements those formats so that a Python peer cannot tell a Leviculum neighbour from another Python node.

Semantic compatibility goes beyond byte layout: behaviours a Python peer expects from a neighbour — answering path requests, rebroadcast decisions, link lifecycle, ratchet handling — must still be delivered. Where the precise expected behaviour matters and is subtle, it is captured as a source-of-truth reference; the broadcast path is documented in Broadcast: Python-RNS parity reference, which records what Python does for every broadcast mechanism so the Rust core can match it.

Level 2: drop-in daemon and tooling

lnsd shares two interfaces with Python’s rnsd:

• The shared-instance IPC socket. A running daemon exposes a local control/data channel that client tools connect to. Leviculum speaks the same protocol, so Python’s rnstatus, rnpath, rnprobe, and rncp drive a running lnsd without modification, and the Leviculum tools lns and lncp drive a running rnsd just the same. The RPC control channel that backs rnstatus/rnpath/ rnprobe is implemented in reticulum-std/src/rpc/ (it speaks Python’s multiprocessing.connection framing with pickle payloads, see rpc/connection.rs and rpc/pickle.rs).
• The config-file format. lnsd parses the same INI-style config that rnsd uses (reticulum-std/src/config.rs, reticulum-std/src/ini_config.rs). Even keys Leviculum does not act on are parsed for compatibility — for example shared_instance_type and shared_instance_socket are read and honoured per RNS 1.3.x semantics so an existing rnsd config works unchanged (reticulum-std/src/config.rs:47-53).

This drop-in property is a deliberate design goal, not an accident. It is also what makes honest A/B testing possible: the test harness points the same client binary (e.g. lns selftest) at either daemon, never a parallel per-stack driver. A parallel driver would smuggle configuration differences into what claims to be a stack comparison.

What is explicitly not a goal: internal parity

Compatibility is not the same as parity.

• Compatibility — our stacks interoperate at the wire and semantic level.
• Parity — our internals mirror Python’s (same algorithms, same retry timings, same state-machine structure).

Leviculum needs the first, not the second. The historical parity documents under docs/src/architecture-*-python-parity.md are reference material for getting behaviour right, not commitments to maintain identical internals.

The deviation rule

A deviation from Python-RNS’s implementation is acceptable if and only if all three of the following hold:

1. Wire-format compatibility is preserved.
2. Semantic compatibility is preserved (behaviours Python peers expect from a neighbour are still delivered).
3. The deviation measurably improves robustness or mesh delivery.

“Because Python does it differently” is not, on its own, an objection; only “this breaks wire or semantic compatibility” is. The interface-isolation design — interfaces applying their own jitter, CSMA, and airtime budgeting — is a deliberate deviation that satisfies this rule.

Cryptographic Identity and Forward Secrecy

Every node and every endpoint in a Reticulum network is identified by cryptography, not by an address handed out by infrastructure. This page explains the conceptual model. For the exact byte layouts, defer to the Reticulum specification (its Identity, Destination, and Announce sections).

Identities are dual keypairs

A Reticulum identity holds two keypairs, used for two different jobs (reticulum-core/src/identity.rs:45):

• X25519 — for key agreement (ECDH). This is how two parties derive a shared secret to encrypt traffic to each other.
• Ed25519 — for digital signatures. This is how a node proves an announce or a packet genuinely came from the holder of the identity.

An identity may be full (it holds the private halves and can decrypt and sign) or public-only (it holds just the public keys, learned from someone else’s announce, and can only encrypt and verify). In the source this is the difference between the Option-wrapped private fields and the always-present public fields (reticulum-core/src/identity.rs:48).

Destinations are derived addresses

You do not pick a Reticulum address; you derive one. A Destination is an addressable endpoint whose 16-byte hash is computed from an application name, a set of aspects, and (for most types) an identity (reticulum-core/src/destination.rs:1). Because the address is a hash of stable inputs, it is reproducible and self-authenticating: anyone who knows the inputs computes the same address, and the identity bound into it proves ownership.

A destination also carries a type (SINGLE, GROUP, PLAIN, LINK) that selects its encryption behaviour, and a direction (IN, OUT) that selects whether it can receive or send (reticulum-core/src/destination.rs:6-7).

Announces carry the public keys

A node makes itself reachable by broadcasting an announce: a signed notification that carries the destination’s public keys out into the mesh. Peers that receive it learn the destination’s address and the keys needed to encrypt to it, and Transport learns a path back. The exact announce wire format is specified in the Reticulum spec.

Ratchets: forward secrecy without a link

End-to-end encryption protects traffic in flight, but if a long-lived identity key is ever compromised, an attacker who recorded past ciphertext could decrypt it. Ratchets close that window for packets sent to SINGLE destinations without first establishing a Link (reticulum-core/src/ratchet.rs:1).

The mechanism, conceptually:

1. A destination enables ratchets and generates an initial X25519 keypair.
2. It includes the current ratchet public key in its announces.
3. Senders encrypt to the ratchet public key, not the long-term identity key.
4. The destination rotates its ratchet keypair periodically (default ~30 minutes).
5. Old ratchets are retained for a while so late-arriving packets still decrypt (default 512 retained), then discarded.

Because the rotating key is short-lived and the private half is thrown away after rotation, compromising the long-term identity does not expose traffic encrypted to expired ratchets. That is forward secrecy.

Persisting ratchet keys across restarts is the job of the Storage trait (the ratchets/ and ratchetkeys/ collections, see Architecture). Links — the other path to forward secrecy, via an ephemeral session handshake — are a separate mechanism; see the Reticulum specification.

Where to read the exact bytes

This page stays conceptual on purpose. The authoritative definitions of identity serialisation, destination hashing, announce structure, and ratchet encoding are in the Reticulum specification. The Rust types above (identity.rs, destination.rs, ratchet.rs) implement that specification.

Storage and Embedding

reticulum-core is #![no_std] with only alloc (reticulum-core/src/lib.rs:59). It contains no I/O, no clock, no filesystem, and no async runtime. That is what lets the exact same protocol code run on a Linux daemon, a future Android app, and a bare-metal nRF52 firmware image. The bridge to the outside world is a small set of traits the core depends on but does not implement.

Three injected dependencies

The core declares its platform needs as traits in reticulum-core/src/traits.rs and takes implementations from the driver:

• Clock (traits.rs:162) — supplies now_ms(). The core never calls a system clock; time is handed in. On the host this is wall time; on the nRF52 it is the Embassy timer (reticulum-nrf/src/clock.rs:8).
• Storage (traits.rs:196) — supplies persistence and lookup for every collection the protocol maintains. flush() defaults to a no-op (traits.rs:466) so a RAM-only backend needs to implement nothing extra.
• Interface (traits.rs:97) — supplies framing and the wire (see Interface Isolation and the Interface trait).

Randomness is injected the same way, as an explicit rng: &mut impl CryptoRngCore parameter rather than a global (reticulum-core/src/lib.rs, “Platform Dependencies”).

The Storage trait

Rather than a generic key/value blob store, Storage exposes type-safe methods grouped by collection — packet-dedup hashes, the path table, the reverse table, link/announce tables, receipts, and ratchets — with typed entries from storage_types.rs. The full method inventory is tabulated in Architecture.

This shape was a deliberate decision. The deep analysis of every method — who calls it, how often, and whether it matters on an embedded target — is in Storage Trait Split Analysis. Read that page before changing the trait surface.

Three backends, one core

The same NodeCore is parameterised over its Storage implementation, so embedding is a matter of choosing a backend (reticulum-core/src/node/mod.rs:143, NodeCore<R: CryptoRngCore, C: Clock, S: Storage>):

FileStorage persists only what must survive a restart — known destinations, the packet dedup hashlist, and ratchet keys — and keeps the rest (paths, reverses, links, announces, receipts) in RAM, rebuilt from the network on restart. The file formats and flush strategy are in Architecture.

What the split buys you

• Host vs. embedded from one source tree. reticulum-std builds a tokio driver around the core; reticulum-nrf builds an Embassy driver around the same core (reticulum-nrf/src/bin/t114.rs, reticulum-nrf/src/bin/rak4631.rs, both #![no_std] and both constructing the core via NodeCoreBuilder).
• Testability. Because time and storage are injected, the core is driven deterministically in tests — feed bytes and a fixed clock, drain the TickOutput, assert. This is the basis of the minimal-reproducer tests under reticulum-std/tests/mvr/.
• No host concerns in the core. Backpressure, airtime budgeting, and serial queueing live host-side in reticulum-std and never leak into the no_std core (reticulum-std/src/interfaces/airtime.rs:1).

See Architecture for the sans-IO core diagram and the driver event loop that pumps these traits.

Installation

Requirements

• Rust stable toolchain
• Git

Optional, depending on what you want to test:

• Python 3 (for interop tests)
• Docker (for integration tests)
• 2-4 RNode modems via USB (for LoRa integration tests)

No system C libraries are required. All cryptography is compiled from Rust source.

Debian/Ubuntu setup

# Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Interop tests
sudo apt install python3

# Integration tests
sudo apt install docker.io
sudo usermod -aG docker $USER

# LoRa tests and embedded firmware (USB serial access)
sudo usermod -aG dialout $USER

Build from source

git clone https://codeberg.org/Lew_Palm/leviculum.git
cd leviculum
cargo build --release --bin lnsd --bin lns --bin lncp

The binaries are in target/release/.

Running the daemon

./target/release/lnsd -v

Reads its config from ~/.reticulum/config, the same location as Python Reticulum.

Development

Cargo aliases

Common workflows are available as cargo aliases (defined in .cargo/config.toml):

Test levels

Tests are organized by what they require:

Unit tests – just Rust, no extra dependencies:

cargo test-core
cargo test-std

Interop tests – require Python 3 and the vendored Reticulum:

git submodule update --init vendor/Reticulum
cargo test-interop

Integration tests – require Docker and pre-built release binaries:

cargo build --release --bin lnsd --bin lns --bin lncp
cargo test-integ

LoRa integration tests – require physical RNode modems connected via USB:

LoRa tests are #[ignore]d by default and must be run explicitly. They exercise real over-the-air transfers between RNode radios running Reticulum firmware. Tests are skipped automatically if the required devices are not connected.

Hardware setup:

• Connect RNodes via USB. They appear as /dev/ttyACM0, /dev/ttyACM1, etc.
• Your user must be in the dialout group: sudo usermod -aG dialout $USER
• Override device paths with environment variables if needed: LEVICULUM_RNODE_0=/dev/ttyUSB0 LEVICULUM_RNODE_1=/dev/ttyUSB1

Running LoRa tests:

# Single test
cargo test -p reticulum-integ -- --exact executor::tests::lora_link_rust --ignored --nocapture

# All 2-device tests
cargo test -p reticulum-integ -- lora_ --ignored --nocapture --test-threads=1

# Override radio parameters (bandwidth in Hz)
LORA_BANDWIDTH=125000 cargo test -p reticulum-integ -- --exact executor::tests::lora_lncp_push --ignored --nocapture

Each LoRa test must pass on all three bandwidth profiles (62.5 kHz, 125 kHz, 250 kHz). The TOML files define 62.5 kHz; use LORA_BANDWIDTH to switch.

Some tests use the lora-proxy binary for fault injection (dropping frames to test retransmit recovery). Build it before running proxy tests:

cargo build --release --bin lora-proxy

Embedded cross-compilation

Embedded targets are not downloaded automatically. Install them when needed:

rustup target add thumbv7em-none-eabihf   # nRF52840
rustup target add thumbv6m-none-eabi       # RP2040
cargo check-nrf52
cargo check-embedded

Before submitting changes

cargo fmt --all -- --check
cargo lint
cargo test-core
cargo test-interop

Configuration

lnsd reads the same INI-style configuration file as Python Reticulum (rnsd). The format is a drop-in: a config that rnsd accepts, lnsd accepts, and the two share the shared-instance IPC socket so client tools (rnstatus, rncp, lns diag, Sideband, Nomadnet) attach to either daemon without changes. Keys lnsd does not implement are tolerated, not rejected — an unknown key never makes lnsd refuse a config a current rnsd would load (ini_config.rs:193-198).

File location and lookup order

Pass an explicit config directory with --config DIR (lnsd.rs, -c/--config). With no flag, lnsd resolves the directory using the same order as Python Reticulum (config.rs:360-391):

1. /etc/reticulum — if /etc/reticulum/config exists
2. $HOME/.config/reticulum — if that directory’s config exists
3. $HOME/.reticulum — fallback, used even if absent

The config file is always named config inside that directory (config.rs:369-371). The storage directory defaults to <config_dir>/storage and can be overridden with --storage (lnsd.rs, -s/--storage).

This order is why the Debian package can install a system-wide config under /etc/reticulum and have Python clients connect to the live daemon with no extra flags (config.rs:354-359).

INI vs TOML detection

lnsd accepts both the Python INI format and native TOML. Detection is by content, not just extension (config.rs:315-338):

• An explicit .toml extension forces TOML.
• A file containing [[ (the ConfigObj subsection marker Python uses for interfaces) is parsed as INI.
• Otherwise TOML is tried first, then INI as a fallback.

In practice your config file uses the Python INI form shown throughout this page. Boolean values accept Yes, yes, True, true, 1, on (and their false counterparts); anything else is read as false (ini_config.rs:255-257).

The [reticulum] section

Core daemon settings. Every key below is parsed in ini_config.rs:153-199; defaults come from config.rs:137-155.

use_implicit_proof, storage_path, control_channel_capacity, and data_channel_capacity are read from TOML only; they have no INI key in apply_reticulum_key (ini_config.rs:155-199 parses just the nine keys above) and are best set in a TOML config or left at their defaults. storage_path is also settable from the command line via lnsd --storage.

flush_interval and keepalive_interval are Leviculum tuning extensions — Python Reticulum ignores them. Battery-powered or SD-card deployments may want a longer flush_interval; slow links benefit from a fixed keepalive_interval:

[reticulum]
  # Seconds between periodic storage flushes (crash protection only,
  # normal shutdown always flushes). Default: 3600.
  flush_interval = 3600

  # Link keepalive interval in seconds. When set, every link uses this
  # interval instead of the RTT-derived default. Default: unset.
  keepalive_interval = 360

The [interfaces] section

Interfaces are ConfigObj subsections under [interfaces], each named in double brackets [[Name]]. The name is free-form; the type key selects the interface implementation. Six types are supported (ini_config.rs:133-145):

TCPServerInterface, TCPClientInterface, UDPInterface, AutoInterface, RNodeInterface, SerialInterface.

An interface of any other type is skipped with a log line, not an error (ini_config.rs:136-143).

All interface keys are parsed in ini_config.rs:202-247; struct defaults are in config.rs:259-305.

Keys common to every interface

TCP server (TCPServerInterface)

[interfaces]
  [[Loopback TCP]]
    type = TCPServerInterface
    enabled = Yes
    listen_ip = 127.0.0.1
    listen_port = 45999

TCP client (TCPClientInterface)

[interfaces]
  [[RNS TCP Node Germany 002]]
    type = TCPClientInterface
    enabled = Yes
    target_host = 193.26.158.230
    target_port = 4965

UDP (UDPInterface)

AutoInterface (AutoInterface)

Discovers other Reticulum nodes on the same broadcast domain via multicast. No router or DHCP needed; the link must carry multicast.

RNode and Serial (RNodeInterface, SerialInterface)

RNodeInterface drives an RNode LoRa modem; SerialInterface is a raw serial KISS link. They share the serial-port and (for RNode) LoRa keys.

Serial keys:

LoRa keys (RNode), derived from source — the meanings below describe the RNode radio parameters the interface configures (config.rs:231-249):

IFAC (Interface Access Codes)

IFAC keys apply to any interface and authenticate / isolate a virtual network on the link. They are common to all interface types (ini_config.rs:243-245):

networkname and passphrase are secrets: lns diag redacts them before serialising a bundle (see the lns diag section).

Example configurations

Simple AutoInterface node

A node that talks to other Reticulum peers on the same LAN, no transport routing:

[reticulum]
  enable_transport = No
  share_instance = Yes

[interfaces]
  [[Default Interface]]
    type = AutoInterface
    enabled = Yes

TCP-server transport node

A routing entrypoint that accepts inbound TCP peers and bridges them with the local LAN:

[reticulum]
  enable_transport = Yes
  share_instance = Yes
  instance_name = entrypoint

[interfaces]
  [[Public TCP]]
    type = TCPServerInterface
    enabled = Yes
    listen_ip = 0.0.0.0
    listen_port = 4965

  [[Local LAN]]
    type = AutoInterface
    enabled = Yes

LoRa RNode node

A node on a LoRa RNode modem (radio values below are an EU 868 MHz example; set them for your region and hardware):

[reticulum]
  enable_transport = Yes
  share_instance = Yes

[interfaces]
  [[LoRa RNode]]
    type = RNodeInterface
    enabled = Yes
    port = /dev/ttyACM0
    frequency = 867200000
    bandwidth = 125000
    spreadingfactor = 8
    codingrate = 5
    txpower = 14

See the upstream Reticulum Manual for the protocol-level meaning of the radio and IFAC parameters.

lnsd Quickstart for Beta Testers

This page gets you from “I have the .deb file” to “my node is on the mesh and I know how to tell if it isn’t”, plus the one-liner you run when something is off so the bug report has everything we need.

For the protocol itself, the upstream Reticulum Manual is the reference. This page is about getting lnsd running on your machine.

Prerequisites

• Linux, x86_64 or aarch64. (macOS and embedded targets exist but are out of scope for the beta .deb path.)
• The nightly .deb for your architecture. Download links are on the releases page. The binaries inside are statically linked against musl, so the package installs on Debian ≥ 9 and Ubuntu ≥ 16.04 regardless of host glibc.
• A few free TCP/UDP ports on your machine for the configured interfaces (default ports below).

You do not need to install Rust, Python, or Docker for the beta flow.

Install

sudo apt install ./leviculum-nightly-amd64.deb       # or -arm64

The package:

• Installs lnsd, lns, and lncp under /usr/bin/.
• Creates a system user leviculum and a group of the same name.
• Drops a default config at /etc/reticulum/config (mode 2775, group-writable + setgid, so everything created inside it inherits the group).
• Enables and starts the lnsd.service systemd unit.

For the native tools (lns, lncp) and Python tools (rnstatus, rnpath, rnprobe, Sideband, Nomadnet, …) to talk to the running daemon, your user has to be in the leviculum group:

sudo usermod -aG leviculum "$USER"
# log out and back in, or `newgrp leviculum` for this shell only

Verify the installation:

lnsd --version          # e.g. 0.7.0-nightly.20260419-5a5df20
lns  --version
systemctl is-active lnsd

is-active should print active. If it prints failed, jump to Troubleshooting.

Minimum-viable config

The default /etc/reticulum/config is conservative: it brings up a single AutoInterface for local LAN peers, with transport routing disabled. That’s enough to talk to other Reticulum nodes on the same LAN, but it does not connect you to the wider mesh.

A reasonable beta-tester config has two interfaces: one for the LAN, one TCP uplink to a public entrypoint. Edit /etc/reticulum/config to:

[reticulum]
  # Pass announces and serve paths for other peers. Leave off if your
  # machine is mobile or sleeps a lot.
  enable_transport = Yes

  # Required for `lns diag`, `rnstatus`, Sideband etc. to attach to
  # this daemon. The default config already sets this.
  share_instance = Yes

[interfaces]

  # 1. Local mesh: discovers and talks to every other Reticulum node
  # on the same broadcast domain. No router/DHCP needed. Multicast
  # has to reach the link (most home LANs do; corporate Wi-Fi often
  # does not).
  [[Default Interface]]
    type = AutoInterface
    enabled = Yes

  # 2. TCP uplink to a public entrypoint. Pick a node from the
  # community directory: https://directory.rns.recipes/  (entrypoints
  # rotate; for redundancy add two or three, and see the Reticulum
  # manual's "Bootstrapping Connectivity" section for the
  # discover_interfaces auto-peering option). Example below: the
  # RNS TCP Node Germany 002 entry.
  [[RNS TCP Node Germany 002]]
    type = TCPClientInterface
    enabled = Yes
    target_host = 193.26.158.230
    target_port = 4965

Then restart the daemon so it picks up the new config:

sudo systemctl restart lnsd

lns diag (below) is the easiest way to confirm both interfaces came up.

Start the daemon

The systemd unit handles this for you on install. The relevant commands:

sudo systemctl start lnsd      # or restart
sudo systemctl stop lnsd
sudo systemctl status lnsd
journalctl -u lnsd -f          # live log tail
journalctl -u lnsd --since '10 min ago'

Logs go to the journal. Increase verbosity by editing the unit’s ExecStart to add -v (debug) or -vv (trace), then sudo systemctl daemon-reload && sudo systemctl restart lnsd. The RUST_LOG environment variable also works (see lnsd(1)).

To run lnsd by hand without systemd (useful for ad-hoc debugging):

sudo systemctl stop lnsd
sudo -u leviculum /usr/bin/lnsd -v --config /etc/reticulum

Check it’s working

Three commands. Run them as a user that is in the leviculum group.

1. lns diag

This is the main health-check. It connects to the running daemon over the shared-instance socket and renders a single-file diagnostic bundle:

lns diag --config /etc/reticulum

A healthy bundle looks roughly like this (your transport id, paths, and byte counters will differ):

===== Leviculum diagnostic bundle =====

----- Versions / build -----
lns version: 0.7.0
build profile: release
target: x86_64 / linux
daemon version: not exposed by the shared-instance RPC ...

----- Config -----
config dir:  /etc/reticulum
config file: /etc/reticulum/config
config file: present, parsed OK

Effective config (TOML, secrets redacted; the raw file is NOT included
because it may contain secrets):
[reticulum]
enable_transport = true
shared_instance = true
instance_name = "default"
...

----- Daemon view (shared-instance RPC) -----
instance name: default
RPC socket:    \0rns/default/rpc
authkey:       derived from /etc/reticulum/storage/transport_identity (not shown)

## interface_stats
transport id: 0123456789abcdef0123456789abcdef
daemon uptime: 12m 34s (754s)
interfaces (3):
  - Shared Instance[rns/default]  type=LocalServerInterface status=up rxb=0 txb=0 clients=1
  - AutoInterface[Default Interface/eth0/aabbccdd]  type=AutoInterface status=up rxb=482 txb=917 peers=2
  - TCPInterface[RNS TCP Node Germany 002/193.26.158.230:4965]  type=TCPClientInterface status=up rxb=14211 txb=8332

## path_table
known paths: 7
[ ... JSON array of {hash, via, hops, expires, ...} ... ]

## link_count
active links: 0

----- System -----
os: linux  kernel: 6.12.73+deb13-amd64
distro: Debian GNU/Linux 13 (trixie)
lnsd pid: 12345
lnsd VmRSS: 18432 kB
lnsd open fds: 27

----- Recent events -----
No structured event-log file specified ...

===== end of diagnostic bundle =====

What to look at first:

• status=up on every interface in the interface_stats section. An interface that came up but lost its medium reports status=down.
• Non-zero rxb / txb on the interfaces you expect traffic on (AutoInterface once any other Reticulum node is on the same LAN, TCPInterface as soon as it connects).
• peers=… on the AutoInterface line: how many other Reticulum nodes are visible on the LAN.
• known paths: N with N > 0 once announces have crossed the mesh. Brand-new daemons that haven’t heard any announces yet show known paths: 0 for the first few seconds — that’s normal.
• transport id is your node’s identity (the public half). It is safe to share; the private half lives in /etc/reticulum/storage/transport_identity and is never included in lns diag output.

2. lns selftest --help

Sanity-checks that lns itself is installed and runnable:

lns selftest --help

The actual lns selftest exercise needs one or two relay nodes you control. The full command and options live in lns(1).

3. rnstatus (optional — Python tools)

The .deb does not install Python Reticulum. If you want rnstatus / rnpath / rnprobe / Sideband:

sudo apt install python3 python3-pip
pip3 install --user rns
rnstatus

Python tools auto-detect /etc/reticulum/config and connect to the running lnsd through the same shared-instance socket. No extra flags are needed. (lns status exists as a placeholder but is not implemented yet — use rnstatus or lns diag until it lands.)

Connect to the wider mesh

With the config above, two things happen as soon as lnsd starts:

1. Announcing. Your node sends an announce for its probe destination on every enabled interface. Other transport-enabled nodes pass that announce on, so within seconds your node is visible to peers on the LAN and within a few minutes to peers reachable through the TCP uplink.
2. Learning paths. When other nodes announce, your daemon stores a path to each announced destination (hash, next hop, hop count, expiry). lns diag’s known paths: N is that table’s size.

When you want to talk to a specific destination (e.g. send a file with lncp), the daemon either has a path already (immediate) or requests one (a path-request packet, a few seconds, then immediate). You don’t have to do anything to make path discovery happen — it runs whenever the daemon is up.

For the protocol-level picture, read Bootstrapping Connectivity in the upstream Reticulum manual.

Troubleshooting

lnsd will not start

systemctl status lnsd
journalctl -u lnsd --since '10 min ago' | tail -50

Common causes:

• Config not parsed. Look for a “Failed to parse config” line in the journal. lns diag --no-rpc shows the parse status without needing the daemon up:

  config file: present but FAILED to parse: <details>
  

• Abstract socket already in use. Another lnsd or rnsd is running under the same instance_name. Stop it (sudo systemctl stop lnsd then pkill -f rnsd if applicable), or set a unique instance_name in your config.
• Permission on the storage directory. The leviculum user has to be able to write /etc/reticulum/storage/. The .deb sets the permissions correctly on install; a manual chown to root:root breaks the daemon. Fix:

  sudo chown -R leviculum:leviculum /etc/reticulum
  sudo chmod 2775 /etc/reticulum
  

No peers found / known paths: 0

Check lns diag’s interface_stats section:

• AutoInterface shows peers: 0 and rxb: 0 — multicast isn’t reaching the link. Likely causes: corporate Wi-Fi (multicast blocked); a Linux bridge or container network without multicast forwarding; no other Reticulum node on the segment.
• TCPClientInterface shows status=up but rxb: 0 — TCP connected but the remote isn’t sending anything, which usually means the remote is up but has no transport peers itself, or the entrypoint has been retired. Try a different entrypoint, or rely on AutoInterface + a TCP uplink to a known-good node you control.
• TCPClientInterface not listed at all — the daemon hasn’t connected yet (look for Establishing TCP connection lines in journalctl -u lnsd) or DNS for the target host doesn’t resolve.

Give it ~30 seconds after starting lnsd before concluding there’s a problem — the first round of announces and the initial TCP connect take a moment.

Native and Python tools cannot reach lnsd

Symptom: lns diag shows <unavailable: …> in the daemon-view section, or rnstatus errors with “Reticulum is not running”.

• Confirm your user is in the leviculum group:

  id | tr , '\n' | grep leviculum
  

  If not, sudo usermod -aG leviculum "$USER" and log out / back in.
• Confirm the daemon really is up and has share_instance = Yes:

  systemctl is-active lnsd
  grep -i share_instance /etc/reticulum/config
  

• Confirm both client and daemon are using the same config directory. The client defaults to /etc/reticulum if it exists, then ~/.config/reticulum, then ~/.reticulum. lns diag --config /etc/reticulum is explicit.

Submitting a bug report

Run lns diag and attach its output to your report:

lns diag --config /etc/reticulum --output /tmp/lns-diag.txt

The bundle is plain UTF-8 text, designed to be safe to attach: IFAC passphrase and networkname are redacted before serialisation; the node identity private key is never read into the bundle (only its SHA-256 is used, internally, to derive the shared-instance RPC authkey). The bundle does contain your node’s hostnames, configured TCP targets, byte counters, and known-destinations table — review it once before posting to a public tracker if your topology is sensitive.

If lnsd is in a structured event-log run (LEVICULUM_EVENT_LOG=/var/log/lnsd-events.log in the service unit’s Environment=), include the tail of that file too:

lns diag --event-log /var/log/lnsd-events.log \
         --output /tmp/lns-diag.txt

Otherwise the bundle already points the reviewer at journalctl -u lnsd, which is enough.

See also

• lnsd(1), lns(1), lncp(1) man pages.
• Configuration for the format reference.
• Installation for the source-build path.
• The upstream Reticulum Manual for the protocol itself.

lns

lns is the Reticulum command-line utility. It manages identities, copies files, runs an interactive session against a daemon, exercises the stack with a self-test, and collects diagnostic bundles.

Reticulum command-line utility

Usage: lns [OPTIONS] <COMMAND>

Commands:
  status      Show status of the Reticulum network
  path        Show or request paths to destinations
  identity    Identity management
  probe       Probe a destination
  interfaces  Show interface information
  selftest    Run integration self-test through relay node(s)
  cp          Copy files over Reticulum (compatible with rncp)
  connect     Interactive session: connect to rnsd and enter command loop
  diag        Collect a diagnostic bundle from a running lnsd (or rnsd) for bug reports
  help        Print this message or the help of the given subcommand(s)

Options:
  -c, --config <CONFIG>                Configuration file path
  -v, --verbose                        Enable verbose logging
      --corrupt-every <CORRUPT_EVERY>  Corrupt ~1 byte per N bytes on TCP write (fault injection)
  -h, --help                           Print help
  -V, --version                        Print version

-c/--config, -v/--verbose, and --corrupt-every are global flags available on every subcommand. --corrupt-every is a fault-injection tool for testing and should be left off in normal use.

identity

Manage Reticulum identities. An identity file holds the 64-byte private key (X25519 + Ed25519); the public half and the 16-byte hash are derived from it.

Usage: lns identity <COMMAND>

Commands:
  generate  Generate a new identity
  show      Show identity information

identity generate

Creates a fresh identity. With -o/--output FILE the private key is written to the file and the hash is printed; without it, the hash and public key are printed and nothing is saved (lns.rs:1126-1145).

lns identity generate -o my-identity.bin

Generated new identity
Hash: 0123456789abcdef0123456789abcdef
Saved to: my-identity.bin

Without -o, the public key is printed instead of being saved (lns.rs:1140-1144):

lns identity generate

Generated new identity
Hash: 0123456789abcdef0123456789abcdef
Public key: <64 hex bytes>

identity show

Loads a saved identity file and prints its path, hash, and public key (lns.rs:1147-1158):

lns identity show my-identity.bin

Identity: my-identity.bin
Hash: 0123456789abcdef0123456789abcdef
Public key: <64 hex bytes>

cp

Copy files over Reticulum, wire-compatible with Python’s rncp. This is the same engine as the standalone lncp tool, exposed as an lns subcommand.

Because -v/--verbose and -c/--config are global lns flags, cp uses -V/--cp-verbose and --cp-config for its own verbosity and config overrides (rncp itself uses -v and has no --config). Other options match lncp: -l/--listen, -w TIMEOUT, -s/--save, -O/--overwrite, -n/--no-auth, -b ANNOUNCE_INTERVAL. See the lncp page for the full option set and worked examples.

# Send a file
lns cp report.pdf 0123456789abcdef0123456789abcdef

# Listen for incoming transfers
lns cp -l

connect

Open an interactive session against a running daemon (lnsd or rnsd) and enter a command loop. The address is the daemon’s TCP interface (host:port); lns verifies TCP connectivity before building the node (lns.rs:554-560).

Usage: lns connect [OPTIONS] <ADDR>

Arguments:
  <ADDR>  Address of the rnsd to connect to (host:port)

Options:
  -c, --config <CONFIG>      Configuration file path
      --identity <IDENTITY>  Path to identity file (default: generate ephemeral)

With no --identity, an ephemeral identity is generated for the session (lns.rs:564-573). On connect, the session announces itself and prints its identity and destination hashes (lns.rs:616-619):

Identity: <hash>
Destination: <hash>
Announced as lns-cli
Type /help for commands.
>

Interactive commands

The command loop accepts these (lns.rs:534-546):

selftest

Run an end-to-end self-test through one or two relay nodes you control. The relay addresses are given as host:port.

Usage: lns selftest [OPTIONS] [TARGETS]...

Arguments:
  [TARGETS]...  Address(es) of relay node(s) (host:port). One or two addresses

Options:
  -c, --config <CONFIG>
          Configuration file path
      --duration <DURATION>
          Test duration in seconds [default: 180]
      --rate <RATE>
          Messages per second per direction [default: 1]
      --mode <MODE>
          Which test phases to run [default: all]
      --discovery-timeout <DISCOVERY_TIMEOUT>
          Discovery timeout in seconds (Phase 2: mutual path discovery) [default: 60]

The --mode flag selects which phases run; the values are all, link, packet, ratchet-basic, ratchet-enforced, bulk-transfer, and ratchet-rotation (default all). --duration defaults to 180 seconds, --rate to 1 message per second per direction, and --discovery-timeout to 60 seconds.

# Full self-test through one relay
lns selftest 192.0.2.10:4965

# Just the link phase, two relays, shorter run
lns selftest --mode link --duration 60 192.0.2.10:4965 192.0.2.11:4965

diag

Collect a self-contained diagnostic bundle from a running daemon for bug reports. diag queries the shared-instance RPC for the daemon’s live view (interface stats, path table, link count), bundles it with the secret-redacted config, version and build info, and system info, and prints to stdout (or to a file with --output).

Usage: lns diag [OPTIONS]

Options:
  -c, --config <CONFIG>
          Configuration file path
      --output <OUTPUT>
          Write the bundle to this path instead of stdout
      --instance-name <INSTANCE_NAME>
          Shared-instance name to query (default: from config, else "default")
      --event-log <EVENT_LOG>
          Tail this structured event-log file into the bundle
      --no-rpc
          Skip the daemon RPC queries; emit only config / versions / system

--no-rpc (lns.rs:491-493) skips the daemon queries — useful for checking config parse status when the daemon is down.

A bundle is assembled from these sections in order (diag.rs:63-190):

• Versions / build — lns version, build profile, target. (The daemon version is not exposed by the RPC; check the daemon’s startup log if needed.)
• Config — config dir and file, parse status, then the effective config rendered as TOML with secrets redacted. The raw file is never included.
• Interfaces (configured) — each configured interface from the parsed config.
• Daemon view (shared-instance RPC) — instance name, RPC socket path \0rns/<name>/rpc, and live interface_stats, path_table, and link_count queries.
• System — OS, kernel, distro, and the daemon’s pid / RSS / open fds.
• Recent events — tail of the structured event log if --event-log is given.

A trimmed bundle (your transport id, paths, and counters will differ):

===== Leviculum diagnostic bundle =====

----- Versions / build -----
lns version: 0.7.0
build profile: release
target: x86_64 / linux
daemon version: not exposed by the shared-instance RPC ...

----- Config -----
config dir:  /etc/reticulum
config file: /etc/reticulum/config
config file: present, parsed OK

Effective config (TOML, secrets redacted; the raw file is NOT included
because it may contain secrets):
[reticulum]
enable_transport = true
shared_instance = true
instance_name = "default"
...

----- Daemon view (shared-instance RPC) -----
instance name: default
RPC socket:    \0rns/default/rpc
authkey:       derived from /etc/reticulum/storage/transport_identity (not shown)

## interface_stats
transport id: 0123456789abcdef0123456789abcdef
daemon uptime: 12m 34s (754s)
interfaces (3):
  - Shared Instance[rns/default]  type=LocalServerInterface status=up rxb=0 txb=0 clients=1
  - AutoInterface[Default Interface/eth0/aabbccdd]  type=AutoInterface status=up rxb=482 txb=917 peers=2
  - TCPInterface[RNS TCP Node Germany 002/193.26.158.230:4965]  type=TCPClientInterface status=up rxb=14211 txb=8332

## path_table
known paths: 7
[ ... JSON array of {hash, via, hops, expires, ...} ... ]

## link_count
active links: 0

----- System -----
os: linux  kernel: 6.12.73+deb13-amd64
distro: Debian GNU/Linux 13 (trixie)
lnsd pid: 12345
lnsd VmRSS: 18432 kB
lnsd open fds: 27

----- Recent events -----
No structured event-log file specified ...

===== end of diagnostic bundle =====

Secret redaction

The bundle is designed to be safe to attach to a public tracker. IFAC passphrase and networkname are redacted before the config is serialised, and the node’s private key is never read into the bundle — only its hash is used internally to derive the RPC authkey (diag.rs:119-128, 162-168). The bundle still contains your hostnames, configured TCP targets, byte counters, and known-paths table, so review it once before posting if your topology is sensitive.

lns diag --config /etc/reticulum --output /tmp/lns-diag.txt

See the lnsd Quickstart for how to read the bundle as a health check.

Planned commands

status, path, probe, and interfaces are present as placeholders but are not implemented yet — they print a “Not implemented yet” notice and exit 0 (lns.rs:1104-1174). They are tracked as Codeberg issue #22. Until they land:

• For status, use lns diag or the Python rnstatus.
• For paths and interfaces, use the interface_stats and path_table sections of lns diag, or rnpath / rnstatus.
• For probing a destination, use the Python rnprobe.

lns status

Reticulum Status
================

Status: Not implemented yet

lncp

lncp is the Reticulum file-transfer tool. It sends a file to a destination or listens for incoming transfers, and is wire-compatible with Python’s rncp — an lncp listener accepts an rncp sender and vice versa. The same engine is also reachable as lns cp.

Reticulum File Transfer Utility

Usage: lncp [OPTIONS] [FILE] [DESTINATION]

Arguments:
  [FILE]         File to send (send mode)
  [DESTINATION]  Destination hash, 32 hex characters (send mode)

Options:
      --config <CONFIG>   Path to alternative Reticulum config directory
  -v, --verbose...        Increase verbosity
  -q, --quiet...          Decrease verbosity
  -l, --listen            Listen for incoming transfer requests
  -w <TIMEOUT>            Fetch / transfer phase timeout in seconds
  -s, --save <SAVE>       Save received files in specified path
  -O, --overwrite         Allow overwriting received files
  -n, --no-auth           Accept requests from anyone
  -b <ANNOUNCE_INTERVAL>  Announce interval (-1=none, 0=once at startup, N=every N sec) [default: 0]
  -p, --print-identity    Print identity and destination info and exit
  -i <IDENTITY>           Path to identity file to use
  -S, --silent            Fully silent: no progress output and no log output at all (equivalent to -qq)
  -C, --no-compress       Disable automatic compression
  -f, --fetch             Fetch file from remote listener
  -F, --allow-fetch       Allow authenticated clients to fetch files
  -j, --jail <JAIL>       Restrict fetch requests to specified path
  -P, --phy-rates         Display physical layer transfer rates
  -a <ALLOWED>            Allow identity hash (can be specified multiple times)
  -h, --help              Print help
  -V, --version           Print version

Modes

Send

Give a FILE and a 32-hex-character DESTINATION hash. lncp establishes a link to the destination and transfers the file:

lncp report.pdf 0123456789abcdef0123456789abcdef

The file is compressed automatically unless you pass -C/--no-compress.

Listen

-l/--listen waits for incoming transfer requests. The listener prints its own destination hash so the sender knows where to aim:

lncp -l -s ~/incoming

Fetch

-f/--fetch pulls a file from a remote listener instead of pushing to it (the listener must allow this with -F/--allow-fetch).

Options

A few options only make sense in listen mode and warn otherwise: -F/--allow-fetch warns when no -l is given, and -j/--jail warns without -F (lncp.rs:199-204). -n/--no-auth overrides any -a allow-list (lncp.rs:213-214).

Identity and authorisation

-p/--print-identity loads (or generates) the identity and prints the rncp receive destination hash followed by the identity hash, then exits (lncp.rs:334-352):

lncp -p

0123456789abcdef0123456789abcdef
Identity  : fedcba9876543210fedcba9876543210

By default a listener only accepts senders whose identity hash you have allowed with -a (repeatable). -n/--no-auth drops that check and accepts anyone. An -a hash must be 32 hex characters / 16 bytes (lncp.rs:314-332).

Examples

Send a file

On the receiver, start a listener and note its destination hash:

lncp -l -s ~/incoming -O

On the sender, transfer the file to that hash:

lncp ./report.pdf 0123456789abcdef0123456789abcdef

Listen and receive with authorisation

Allow only one known sender, saving into ~/incoming and showing physical-layer rates:

lncp -l -s ~/incoming -a fedcba9876543210fedcba9876543210 -P

The sender finds its own identity hash with lncp -p.

lncp needs a running daemon (lnsd or rnsd) on the same shared instance to reach the mesh — see the lnsd Quickstart.

lnsd(1)

NAME

lnsd – Reticulum network daemon

SYNOPSIS

lnsd [-c dir] [-s dir] [-v…] [-q…]

DESCRIPTION

lnsd runs the Reticulum network stack as a long-lived daemon process. It is a drop-in replacement for Python’s rnsd. Other programs connect to it via shared instance IPC (Unix abstract socket).

On startup, lnsd reads config from the configuration directory, opens all configured interfaces, and begins routing packets. It keeps running until it receives SIGINT or SIGTERM.

Sending SIGUSR1 prints a diagnostic dump of internal state to stderr.

OPTIONS

-c, –config dir

Path to the Reticulum configuration directory. Defaults to ~/.reticulum. The config file is <dir>/config.

-s, –storage dir

Storage directory path. Defaults to <config_dir>/storage.

-v, –verbose

Increase log verbosity. Once for debug, twice for trace.

-q, –quiet

Decrease log verbosity. Once for warnings only, twice for errors only.

ENVIRONMENT

RUST_LOG

Overrides the verbosity flags. See the tracing-subscriber documentation for filter syntax.

FILES

~/.reticulum/config

Default configuration file (INI format, same as Python Reticulum).

~/.reticulum/storage/

Default storage directory for identities, known destinations, and cached path state.

SIGNALS

SIGINT, SIGTERM

Graceful shutdown.

SIGUSR1

Dump diagnostic state to stderr.

EXAMPLES

Start with default config and verbose logging:

lnsd -v

Start with a custom config directory:

lnsd --config /etc/reticulum

SEE ALSO

lns(1), lncp(1)

lns(1)

NAME

lns – Reticulum network utility

SYNOPSIS

lns [-c dir] [-v] command [args…]

DESCRIPTION

lns is a multi-tool for interacting with a running Reticulum network. It combines the functionality of Python’s rnstatus, rnpath, rnprobe, and more into a single binary.

GLOBAL OPTIONS

-c, –config dir

Path to the Reticulum configuration directory.

-v, –verbose

Enable verbose logging.

COMMANDS

lns status

Not yet implemented (stub, prints “Not implemented yet” — tracked as Codeberg #22). Will show status of the Reticulum network by connecting to the running daemon via shared instance, equivalent to Python’s rnstatus.

lns path [destination]

Not yet implemented (stub — tracked as Codeberg #22). Will show or request paths to destinations: without an argument, list all known paths; with a destination hash (hex), request a path to that destination. Equivalent to Python’s rnpath.

lns probe destination

Not yet implemented (stub — tracked as Codeberg #22). Will probe a destination by sending a probe packet and measuring round-trip time, equivalent to Python’s rnprobe.

lns interfaces

Not yet implemented (stub — tracked as Codeberg #22). Will show information about configured network interfaces.

lns identity generate [-o file]

Generate a new Reticulum identity and write it to file.

lns identity show file

Show the hash and public keys of the identity in file.

lns cp [options] [file] [destination]

Copy files over Reticulum, compatible with Python’s rncp. See lncp(1) for the full option reference.

lns connect addr

Open an interactive session to a Reticulum daemon at addr (host:port). Supports link establishment, message exchange, and announce discovery. Type /help in the session for available commands.

lns selftest target [target]

Run integration self-tests through one or two relay nodes. Tests link establishment, channel data, ratchet operation, and bulk transfer.

Options:

–duration seconds

Test duration (default: 180).

–rate n

Messages per second per direction (default: 1).

–mode mode

Which phases to run: all, link, packet, ratchet-basic, ratchet-enforced, bulk-transfer, ratchet-rotation (default: all).

lns diag

Collect a self-contained diagnostic bundle from a running lnsd (or rnsd) for attaching to bug reports: versions/build, the secret-redacted config and configured interfaces, the daemon’s live view via the shared-instance RPC (interface stats, path table, link count), best-effort system info, and an event-log pointer. Printed to stdout by default. Use the global -c/–config to point at the daemon’s config directory.

Secrets are redacted — IFAC passphrase and networkname never appear, and the node identity private key (storage/transport_identity) is never read into the bundle (it is used only to derive the RPC authkey). Queries the daemon doesn’t support (e.g. when run against Python rnsd) are reported as unavailable rather than failing.

Options:

–output path

Write the bundle to path instead of stdout (a one-line confirmation is printed to stderr).

–instance-name name

Shared-instance name to query (default: from the config, else default).

–event-log path

Tail this structured event-log file into the bundle (when lnsd was started with LEVICULUM_EVENT_LOG set).

–no-rpc

Skip the daemon RPC queries; emit only the config, versions, and system sections.

EXAMPLES

Show network status:

lns status

Request a path:

lns path a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Probe a destination:

lns probe a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Generate a new identity:

lns identity generate -o my_identity

SEE ALSO

lnsd(1), lncp(1)

lncp(1)

NAME

lncp – Reticulum file transfer utility

SYNOPSIS

lncp [options] file destination lncp [options] -l [-s dir]

DESCRIPTION

lncp transfers files over the Reticulum network. It is compatible with Python’s rncp. It connects to a running daemon (lnsd or rnsd) via shared instance IPC.

In send mode, lncp sends file to the node identified by destination (a 32-character hex hash). In listen mode (-l), it waits for incoming file transfer requests.

OPTIONS

file

File to send (send mode).

destination

Destination hash, 32 hex characters (send mode).

–config dir

Path to alternative Reticulum configuration directory.

-v, –verbose

Increase verbosity. Repeat for more detail.

-q, –quiet

Decrease verbosity.

-l, –listen

Listen for incoming transfer requests.

-w seconds

Sender timeout before giving up (default: 15).

-s, –save dir

Save received files in the specified directory.

-O, –overwrite

Allow overwriting existing files when receiving.

-n, –no-auth

Accept requests from anyone (no authentication).

-b interval

Announce interval in seconds. -1 = never, 0 = once at startup, N = every N seconds (default: 0).

-p, –print-identity

Print identity and destination info and exit.

-i file

Path to identity file to use.

-S, –silent

Disable transfer progress output.

-C, –no-compress

Disable automatic compression.

-f, –fetch

Fetch file from remote listener instead of pushing.

-F, –allow-fetch

Allow authenticated clients to fetch files.

-j path

Restrict fetch requests to the specified path.

EXAMPLES

Send a file:

lncp myfile.tar.gz a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Listen for incoming files and save to a directory:

lncp -l -s ~/received/

Listen with verbose logging, accepting from anyone:

lncp -l -n -v

SEE ALSO

lnsd(1), lns(1)

LNode Firmware: Supported Boards

The LNode firmware turns an nRF52840-based board into a standalone Reticulum transport node. It runs the same reticulum-core transport engine that powers the Linux daemon, cross-compiled for Cortex-M4F, and routes packets between three interfaces: USB serial (HDLC framing to a host), the SX1262 LoRa radio, and BLE. There is no PC in the data path; the device is a router in its own right.

The transport engine is the same reticulum-core library that powers the Linux daemon, compiled for Cortex-M4F. (reticulum-nrf/README.md:4)

On the wire the firmware speaks the RNode LoRa framing protocol, so an LNode and an RNode interoperate on the same LoRa network. On the host side it connects to lnsd or rnsd over USB serial with HDLC framing. On the BLE side it implements the Columba v2.2 protocol for the Columba Android app. (reticulum-nrf/README.md:6, reticulum-nrf/src/bin/t114.rs:3-8)

What the firmware does

Each firmware binary registers exactly three Reticulum interfaces and runs an event-driven main loop that dispatches packets between them:

(Interface registration and MTUs: reticulum-nrf/src/bin/t114.rs:157-162 and reticulum-nrf/src/bin/rak4631.rs:195-200. The main loop selecting over the three RX sources plus a timer deadline: reticulum-nrf/src/bin/t114.rs:256-307.)

Transport routing is enabled in the node builder (.enable_transport(true)), so an LNode forwards packets and serves paths for other peers, exactly like a transport-enabled lnsd. (reticulum-nrf/src/bin/t114.rs:123-128)

Supported boards

Both boards are nRF52840 + SX1262 and both run BLE through the Nordic S140 SoftDevice. (reticulum-nrf/README.md:1-6, reticulum-nrf/Cargo.toml:65-77)

Note on BLE: Both firmware entry points register a BLE interface and call reticulum_nrf::ble::init (reticulum-nrf/src/bin/t114.rs:206-232, reticulum-nrf/src/bin/rak4631.rs:243-270). The Cargo softdevice feature — and therefore the BLE stack — is pulled in by both BSP features (bsp-t114 = ["softdevice"], bsp-rak4631 = ["softdevice"], reticulum-nrf/Cargo.toml:102-116).

The optional baseboard peripherals (display, GNSS, battery telemetry) exist only on the RAK19026 baseboard of the WisMesh Pocket V2 and are each gated behind their own Cargo feature, so the bare-module build stays unchanged. (reticulum-nrf/Cargo.toml:52-63, reticulum-nrf/src/bin/rak4631.rs:274-298)

Cargo features and binaries

Two firmware binaries are defined, one per board family:

[[bin]]
name = "t114"
path = "src/bin/t114.rs"

[[bin]]
name = "rak4631"
path = "src/bin/rak4631.rs"

(reticulum-nrf/Cargo.toml:135-142)

The board-support-package (BSP) features select the runtime for a given board. Exactly one BSP feature must be enabled per build; a compile_error! in lib.rs enforces the mutual exclusion. (reticulum-nrf/Cargo.toml:94-116)

The mapping from board to binary + features used by the flash recipes:

(Feature sets as invoked in the just flash, just flash-rak4631, and just flash-rak4631-pocket recipes: Justfile:278, Justfile:292, Justfile:304.)

Build target

All firmware builds target the hard-float Cortex-M4 triple:

thumbv7em-none-eabihf

(reticulum-nrf/README.md:15. Add it with rustup target add thumbv7em-none-eabihf.)

Default radio profile

The radio parameters are compiled into the firmware and must match the RNode configuration on the same LoRa network.

(reticulum-nrf/README.md:8. The eu_medium profile the firmware loads at boot: reticulum-nrf/src/lora.rs:124-138, applied at reticulum-nrf/src/bin/t114.rs:200 and reticulum-nrf/src/bin/rak4631.rs:239.)

See Flashing for how to build and write these binaries to a board, and Recovery for the bootloader-entry details.

LNode Firmware: Building and Flashing

This page covers the prerequisites, the build, and every just flash* recipe — what each one does and when to reach for it.

Physical-device steps. The author of this page cannot flash a board, so any step that writes to or resets real hardware is marked derived from source — requires the physical device. The commands themselves are quoted verbatim from the Justfile and reticulum-nrf/README.md; only the outcome on hardware is un-verified here.

Prerequisites

Install the Rust embedded toolchain, the ARM cross-compiler (needed by nrf-sdc for C-header bindgen), and add your user to the dialout group for serial-port access. Log out and back in after the usermod so the new group membership takes effect.

rustup target add thumbv7em-none-eabihf
rustup component add llvm-tools
sudo apt install gcc-arm-none-eabi
sudo usermod -aG dialout $USER

(reticulum-nrf/README.md:12-19)

--release is mandatory

Always build and flash with --release. The debug profile does not fit the nRF52840 flash — the image overflows FLASH by several hundred KB at link time.

The debug profile does not fit the nRF52840 flash (the image overflows FLASH by several hundred KB at link time) — always build and flash with --release; all just flash-* recipes already do. (reticulum-nrf/README.md:64-67)

Every just flash* recipe already passes --release, so following the recipes below keeps you safe. The release profile is size-optimized (opt-level = "z", lto = true, codegen-units = 1); DWARF debug info is kept in the .elf (strip = "none", debug = true) for HardFault post-mortem analysis, but the UF2 only carries loadable sections, so the debug info does not bloat what lands on the device. (reticulum-nrf/Cargo.toml:123-133)

The build/flash workflow

The firmware crate reticulum-nrf is its own Cargo workspace, separate from the repo-root workspace, and is cross-compiled. The flash recipes therefore cd reticulum-nrf before invoking cargo. (Justfile:274-278)

A plain build (no flash) is:

cargo build --release

(reticulum-nrf/README.md:23)

Flashing wraps cargo run: the runner builds the release binary, then copies the resulting UF2 onto each board’s UF2 bootloader drive. The UF2 conversion and copy happen inside the cargo run step — a bare cargo build produces only the ELF.

Build the firmware with cargo build --release. Flash with just flash (from the repo root), which wraps cargo run --release --bin t114. (reticulum-nrf/README.md:23)

Touch-free vs. manual double-tap

For the T114, flashing is touch-free in the common case: the host opens the board’s transport CDC port at 1200 baud, the firmware intercepts the line-coding change, writes a retained-register magic, and soft-resets into the Adafruit UF2 bootloader. No button press. (reticulum-nrf/README.md:27)

A physical double-tap of RESET is still needed when the firmware on a specific T114 has crashed or never reached USB init (panic before the handler is installed, stack overflow, hardware fault). The runner detects this per device via a UF2-drive-polling timeout and prompts for that specific board only; the rest of the batch keeps flashing touch-free. (reticulum-nrf/README.md:38)

The WisMesh Pocket V2 (RAK4631) running stock Meshtastic has no 1200-baud-touch handler and no externally accessible RESET pin, so its first flash needs either just dfu-rak4631 (a Meshtastic admin command, below) or the manual needle double-tap in the hidden pinhole. Once our firmware is on the board, subsequent flashes use the touch path automatically. (Justfile:287-289, Justfile:306-311. See Recovery for the pinhole detail.)

The flash recipes

Each recipe below is quoted from the Justfile. The cargo invocation is derived from source — requires the physical device to actually write firmware (it builds the same on any host, but only does something useful with a board attached).

just flash — every T114

Flashes every attached T114 sequentially. Flashing all of them is deliberate: if only one were flashed, a later multi-node test could run against mixed firmware versions. Use this as your default for T114s.

cd reticulum-nrf && cargo run --release --bin t114 --features bsp-t114

(Justfile:277-278; rationale reticulum-nrf/README.md:25)

just flash-one PORT — a single T114

Flashes one T114 by port path or udev symlink. Use it for A/B firmware testing (one board on a new build, one on the old).

just flash-one /dev/leviculum-transport
just flash-one /dev/ttyACM3

Expands to:

cd reticulum-nrf && LEVICULUM_FLASH_ONLY=<PORT> cargo run --release --bin t114 --features bsp-t114

(Justfile:280-285; usage forms reticulum-nrf/README.md:31-36)

just flash-rak4631 — every RAK4631 (bare module)

Flashes every attached RAK4631 / WisMesh Pocket V2 with the bare-module build (no baseboard peripherals).

cd reticulum-nrf && LEVICULUM_USB_PID=0002 LEVICULUM_BOARD_NAME=RAK4631 \
  LEVICULUM_UF2_BOARD_ID=WisBlock-RAK4631-Board \
  cargo run --release --bin rak4631 --features bsp-rak4631

(Justfile:291-292)

just flash-rak4631-one PORT — a single RAK4631

Flashes one RAK4631 by port path or udev symlink.

just flash-rak4631-one /dev/ttyACM0
just flash-rak4631-one /dev/leviculum-rak-transport

Expands to:

cd reticulum-nrf && LEVICULUM_FLASH_ONLY=<PORT> LEVICULUM_USB_PID=0002 \
  LEVICULUM_BOARD_NAME=RAK4631 LEVICULUM_UF2_BOARD_ID=WisBlock-RAK4631-Board \
  cargo run --release --bin rak4631 --features bsp-rak4631

(Justfile:294-298)

just flash-rak4631-pocket — WisMesh Pocket V2, full baseboard

Flashes with all RAK19026 baseboard peripherals enabled (display, GNSS, battery). --features rak-baseboard aggregates the three baseboard features. Use this for a complete WisMesh Pocket V2.

cd reticulum-nrf && LEVICULUM_USB_PID=0002 LEVICULUM_BOARD_NAME=RAK4631 \
  LEVICULUM_UF2_BOARD_ID=WisBlock-RAK4631-Board \
  cargo run --release --bin rak4631 --features bsp-rak4631,rak-baseboard

(Justfile:303-304; rak-baseboard aggregate reticulum-nrf/Cargo.toml:121)

just dfu-rak4631 PORT — DFU entry for stock Meshtastic

Triggers the Adafruit UF2 bootloader on a stock-Meshtastic WisMesh Pocket V2 in software. Stock Meshtastic has no 1200-bps-touch handler and the device has no externally accessible RESET pin, so this firmware-side admin command is the only software-only DFU entry. Needed only for the first flash from Meshtastic; after our firmware lands, just flash-rak4631 uses the touch path and this recipe is no longer needed. Requires the meshtastic CLI on PATH (pip install meshtastic).

just dfu-rak4631 /dev/ttyACM0

Runs:

meshtastic --port /dev/ttyACM0 --enter-dfu

(Justfile:306-314)

A note on disconnecting consumers

Flashing a board takes over its transport serial port. Any running consumer of that port (for example an active lnsd pointed at it) loses its connection when the board is flashed. The flash action is explicit and active; no persistence is promised across it. (reticulum-nrf/README.md:40)

The device keeps its Reticulum identity in internal flash and preserves it across firmware updates, so re-flashing does not change the node’s address. (reticulum-nrf/README.md:42. More in Recovery.)

Verifying the build before you flash

cargo build --release (above) confirms the image links and fits flash. If you want to lint the firmware as CI does:

just lint-nrf

(Builds both BSP feature sets under clippy with -D warnings: Justfile:38-40.)

Next: Serial ports for wiring the flashed board into lnsd.

LNode Firmware: USB Serial Ports

A flashed LNode presents two USB CDC-ACM serial ports to the host. Knowing which is which is the difference between reading a debug log and talking the Reticulum transport protocol.

The two ports

The firmware exposes two CDC-ACM serial ports. The lower-numbered port is the debug log output; the higher-numbered port is the Reticulum transport interface that carries HDLC frames. The actual /dev/ttyACM* numbers depend on what else is plugged into USB.

The firmware exposes two USB CDC-ACM serial ports. The lower-numbered port is the debug log output. The higher-numbered port is the Reticulum transport interface that carries HDLC frames. The actual /dev/ttyACM* numbers depend on other connected USB devices. (reticulum-nrf/README.md:44-46)

Each CDC-ACM class occupies two USB interfaces (a Communication interface plus a Data interface), so the two ports map onto four USB interface numbers:

(reticulum-nrf/udev/99-leviculum.rules, header comment.)

Stable device paths via udev

Because the /dev/ttyACM* enumeration order is not stable, install the shipped udev rules to get fixed symlinks:

sudo cp udev/99-leviculum.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules

(reticulum-nrf/README.md:50-53)

After the next plug-in, the symlinks point at the correct ports regardless of enumeration order. The names are board-family specific, keyed off the per-board USB PID:

(Symlink names and PIDs: reticulum-nrf/udev/99-leviculum.rules. The firmware-side USB VID/PID constants: reticulum-nrf/src/boards/t114.rs:139-140 for 1209:0001, reticulum-nrf/src/boards/rak4631.rs:126-127 for 1209:0002.)

Multiple boards of the same kind. The short symlinks (/dev/leviculum-transport) land on whichever device udev sees first. The rules also emit per-serial-number symlinks (/dev/leviculum-transport-<SERIAL>); use those when more than one board of the same family is attached. (reticulum-nrf/udev/99-leviculum.rules, header comment and SYMLINK+="leviculum-transport-%s{serial}" lines.)

Reading the debug port

The debug port is plain text at 115200 baud:

picocom /dev/leviculum-debug -b 115200

(reticulum-nrf/README.md:59-60)

On the debug port you will see the boot banner, the firmware git SHA, the node identity, and the periodic diagnostics the firmware emits — for example the LNode started -- identity: … line and the [FW_BUILD] banner re-emitted every few seconds. (reticulum-nrf/src/bin/t114.rs:164-168, :323-333.) Do not point lnsd at the debug port; it carries log text, not HDLC frames.

Pointing lnsd at the transport port

The transport port speaks the RNode LoRa framing protocol over HDLC, the same wire protocol lnsd/rnsd use for an RNode. Configure it as an RNodeInterface (the dedicated single-radio RNode driver) with its port set to the transport symlink.

The radio parameters in the config must match the firmware’s compiled-in defaults (the EU medium profile), otherwise the two sides talk past each other on the air. (reticulum-nrf/README.md:8; reticulum-nrf/src/lora.rs:124-138.)

[interfaces]

  [[LNode T114]]
    type = RNodeInterface
    enabled = yes
    port = /dev/leviculum-transport
    frequency = 869525000
    bandwidth = 125000
    txpower = 17
    spreadingfactor = 7
    codingrate = 5

The key names and types come from the [[RNode Interface]] config schema (port, frequency, bandwidth, txpower, spreadingfactor, codingrate; docs/src/rnode-protocol.md:674-684). The values above are the firmware’s compiled defaults: 869.525 MHz, BW 125 kHz, 17 dBm, SF7, CR4/5 (reticulum-nrf/src/lora.rs:124-138).

For a RAK4631 / WisMesh Pocket V2 the only change is the port:

  [[LNode Pocket V2]]
    type = RNodeInterface
    enabled = yes
    port = /dev/leviculum-rak-transport
    frequency = 869525000
    bandwidth = 125000
    txpower = 17
    spreadingfactor = 7
    codingrate = 5

After editing /etc/reticulum/config, restart the daemon so it picks up the new interface:

sudo systemctl restart lnsd

(Same restart flow as any config change; see the lnsd Quickstart.)

Confirming the link came up

Run the standard health-check and look for the new interface in the interface_stats section with status=up and non-zero counters once LoRa traffic flows:

lns diag --config /etc/reticulum

(lns diag usage and the interface_stats reading are described in the lnsd Quickstart.)

For the full key-by-key reference of the [[RNode Interface]] section and the meaning of the optional keys (flow_control, airtime_limit_*, callsign beaconing), see the Configuration chapter and docs/src/rnode-protocol.md.

LNode Firmware: Bootloader Entry and Recovery

The nRF52840 boards use the Adafruit UF2 bootloader: it appears as a mass-storage drive, and writing a .uf2 file to that drive flashes the device. This page covers how to enter that bootloader (touch-free and manual), the board-specific caveats, what survives a re-flash, and what to do when USB stays dark.

Physical-device steps. The author of this page cannot operate a board. Every step that presses a button, taps a pinhole, or observes a drive appearing is derived from source — requires the physical device. The commands and mechanisms are quoted from reticulum-nrf/README.md and the Justfile; only the hardware outcome is un-verified here.

Entering the UF2 bootloader

Touch-free (1200-baud), the common case for T114

When the LNode firmware is already running, the host can drop it into the bootloader without any physical interaction: it opens the board’s transport CDC port at 1200 baud, the firmware intercepts the line-coding change, writes a retained-register magic value, and soft-resets into the Adafruit UF2 bootloader.

The host opens each T114’s transport CDC port at 1200 baud, the firmware intercepts the line-coding change, writes a retained-register magic, and soft-resets into the Adafruit UF2 bootloader. No physical button press required. (reticulum-nrf/README.md:27)

All just flash* recipes use this path automatically when the device is running our firmware. (derived from source — requires the physical device.)

Manual RESET double-tap, the fallback

A physical double-tap of the RESET button forces the UF2 bootloader regardless of firmware state. You need it when the firmware on a specific board has crashed or never reached USB init — a panic before the 1200-baud handler is installed, a stack overflow, or a hardware fault. In a just flash batch the runner detects this per device via the UF2-drive-polling timeout and prompts for that specific board only; the rest of the batch keeps flashing touch-free.

the firmware on a specific T114 has crashed or never reached USB init (panic before the handler is installed, stack overflow, hardware fault). The runner detects this per device via the UF2-drive-polling timeout and prompts for that specific T114 only. (reticulum-nrf/README.md:38)

(derived from source — requires the physical device.)

WisMesh Pocket V2 (RAK4631): the hidden-pinhole caveat

The RAK WisMesh Pocket V2 has no externally accessible RESET pin, so the ordinary double-tap-the-button trick does not apply. On this board:

• First flash from stock Meshtastic. Stock Meshtastic has no 1200-baud-touch handler, so the touch-free path does not work yet. Use the software DFU command instead:

  just dfu-rak4631 /dev/ttyACM0
  

  which runs meshtastic --port /dev/ttyACM0 --enter-dfu. This firmware-side admin command is the only software-only DFU entry on a board with no accessible RESET pin. Requires the meshtastic CLI (pip install meshtastic). (Justfile:306-314)

• Manual fallback. Where the software command is unavailable, the bootloader is reached by a needle double-tap in the hidden pinhole — there is no visible reset button; the reset contact is reachable only through a small pinhole, double-tapped with a needle. (This pinhole detail comes from project field notes, not from the firmware source; the source confirms only that the device “has no externally accessible RESET pin”, Justfile:307-308.)

• After our firmware lands, subsequent flashes use the touch handler in src/usb.rs and the DFU recipe is no longer needed. (Justfile:309-310)

Do not flash foreign nRF52 firmware onto the Pocket V2 without a recovery plan. Project field experience is that prebuilt third-party nRF52 firmware may not boot on this RAK board (USB stays dark). Because the only software DFU entry is firmware-side, a board that boots into a non-responsive image and exposes no RESET pin can be hard to recover. (This caveat is project knowledge; it is not stated in the firmware source, which documents only the missing RESET pin and the firmware-side DFU command.)

All steps in this section are derived from source / project notes — requires the physical device.

Identity persistence across updates

A re-flash does not change the node’s Reticulum address. The device stores its Reticulum identity in internal flash and preserves it across firmware updates.

The device stores its Reticulum identity in internal flash and preserves it across firmware updates. (reticulum-nrf/README.md:42)

Mechanically, the firmware loads the identity from a dedicated flash page at boot and only generates (and saves) a new one when none is present:

if id_store.load() => Some(identity)   -> "Identity loaded from flash"
else                                   -> generate new, then save

(reticulum-nrf/src/bin/t114.rs:118-154, reticulum-nrf/src/bin/rak4631.rs:155-192. The identity lives on the board’s identity_flash_page, e.g. 0xEC000 on the T114, reticulum-nrf/src/boards/t114.rs:144.) Flashing new firmware rewrites the program region but leaves that page intact, so the node keeps its address. You can confirm the loaded identity on the debug port: the boot log prints Identity loaded from flash and an [IDENTITY] line with the full hash (reticulum-nrf/src/bin/t114.rs:170-174).

When USB stays dark

If the board enumerates nothing on USB after a flash or a bad image:

1. Force the bootloader manually. On a T114, double-tap RESET to get the UF2 drive regardless of the running image (reticulum-nrf/README.md:38). On a Pocket V2, use the hidden-pinhole needle double-tap (see above) — the board has no accessible RESET pin (Justfile:307-308).

2. Re-flash the known-good LNode firmware once the UF2 drive appears: just flash (T114) or just flash-rak4631 / just flash-rak4631-pocket (RAK4631). See Flashing.

3. Read the debug port at 115200 baud to see why it crashed — the firmware replays the previous boot’s HardFault/panic post-mortem and the persistent log on the next boot:

   picocom /dev/leviculum-debug -b 115200
   

   Look for [HARDFAULT_PMRT], [PANIC_PMRT], and [PERSISTENT_LOG] lines (reticulum-nrf/src/bin/t114.rs:77-110; reticulum-nrf/README.md:59-60).

(All hardware steps: derived from source / project notes — requires the physical device.)

ESP32 RNodes vs. nRF52 LNodes. The bricking risk above is specific to the nRF52 LNodes. The ESP32-based RNodes (LilyGO T-Beam) have a mask-ROM download bootloader and cannot be bricked: a failed flash is always recoverable by re-running the flash recipe. The nRF52 LNodes (T114, RAK4631) are different — a bad external image can leave the device USB-dark, which is why a recovery plan matters here. (Justfile:316-320)

Building on Leviculum in Rust: Choosing a Layer

Leviculum is a Rust workspace, not a single crate. The Reticulum stack is split into layers so that the same protocol engine can run on a tokio server, a bare-metal nRF52 radio, or behind a C ABI. As an application developer your first decision is which layer you build against. This chapter explains the four crates, the dependency direction between them, and gives a decision table.

The companion chapters are the Rust API tutorial (a hands-on reticulum-std walkthrough), the Rust API reference (verified signatures of the key types), and Embedded development (building on reticulum-core directly). If you are writing C rather than Rust, the C API overview and How-To are your counterparts to those chapters.

The four layers

        reticulum-ffi  (C ABI)        reticulum-nrf  (nRF52 firmware)
              │                              │
              ▼                              │
        reticulum-std  (std, tokio)         │
              │                              │
              ▼                              ▼
                    reticulum-core  (no_std, sans-IO)

The dependency direction is strict and one-way. reticulum-std builds on reticulum-core; reticulum-ffi wraps reticulum-std; reticulum-nrf wraps reticulum-core directly (it never pulls in std or tokio). Nothing depends on a layer above it.

reticulum-core — the no_std, sans-IO engine

reticulum-core is the protocol. It is no_std (it pulls in alloc, but not the standard library), performs no I/O of its own, and owns no runtime. It is sans-IO: you feed it received bytes, it returns a TickOutput describing the packets to send and the events that occurred, and you dispatch those yourself. Time, persistence, and the network are abstracted behind three traits — Clock, Storage, and Interface — that you implement for your platform.

Build against reticulum-core when you have your own runtime or event loop and do not want tokio: embedded firmware, an integration into a different async executor, a simulator, or a host program that wants byte-level control. See Embedded development.

reticulum-std — the full std/tokio application layer

reticulum-std is what most Rust applications use. It supplies the platform pieces reticulum-core abstracts: a SystemClock, file-backed storage with Python-compatible on-disk formats, and concrete interfaces (TCP client and server, UDP, AutoInterface for LAN discovery, RNode/LoRa, raw serial). On top of those it runs the sans-IO core inside a tokio event loop and exposes an async, handle-based API: build a node with ReticulumNodeBuilder, start() it, take an EventReceiver, and use LinkHandle / PacketSender to send.

Build against reticulum-std when you are writing a normal Rust program on Linux/macOS that talks to a Reticulum mesh. This is the path the tutorial and the examples under reticulum-std/examples/ take.

reticulum-ffi — the C ABI wrapper

reticulum-ffi exposes reticulum-std through a C-compatible ABI: opaque handles, integer error codes, a pollable event fd. It is the layer behind leviculum.h and libleviculum.so. If you are writing Rust you do not use it — you use reticulum-std directly, which is what reticulum-ffi itself does internally. It exists so that non-Rust programs (C, and anything that can call a C library) get the same engine.

If your application is in C, stop here and read the C API overview and How-To instead; they are the C counterpart to this Rust documentation.

reticulum-nrf — the reference firmware

reticulum-nrf is standalone firmware for nRF52 boards (the T114 and RAK4631 LoRa nodes), built with the Embassy async embedded framework. It is version 0.4.0, targets thumbv7em-none-eabihf, and depends on reticulum-core directly with default-features = false — no std, no tokio. It is both a usable firmware and the worked reference for how to drive the sans-IO core on bare metal; the embedded chapter walks through its main loop.

You do not “build on” reticulum-nrf the way you build on a library; you fork it or read it as the canonical example of a reticulum-core integration on a real device.

Decision table

Adding the dependency

None of these crates are published on crates.io. Depend on them by path (in a workspace checkout) or by git. For a reticulum-std application:

# Path, when your crate lives next to the libreticulum checkout
[dependencies]
reticulum-std = { path = "../libreticulum/reticulum-std" }
tokio = { version = "1", features = ["full"] }

# Or by git
# reticulum-std = { git = "https://codeberg.org/…/libreticulum" }

For embedded work depend on reticulum-core instead, with default features off:

[dependencies]
reticulum-core = { path = "../libreticulum/reticulum-core", default-features = false }

The workspace is edition 2021, version 0.7.0 (the reticulum-nrf firmware tracks its own 0.4.0), and licensed AGPL-3.0-or-later.

Rust API Tutorial: Building on reticulum-std

This chapter builds a small application on reticulum-std, the std/tokio layer. By the end you will have created a node, attached an interface, registered a destination, sent both a single packet and link data, and consumed NodeEvents. Every snippet is adapted from a real example under reticulum-std/examples/; each step names the file it comes from so you can read the full program. For exact signatures of everything used here, see the Rust API reference.

If you have not yet decided that reticulum-std is the right layer, read Choosing a layer first.

Setup

Add the dependency and tokio. The crates are not on crates.io, so use a path (workspace checkout) or git:

[dependencies]
reticulum-std = { path = "../libreticulum/reticulum-std" }
tokio = { version = "1", features = ["full"] }
tracing-subscriber = "0.3"

The examples all assume a running Reticulum daemon to attach to. Start a Python rnsd (or a Leviculum lnsd) listening on 127.0.0.1:4242, then run an example with, for instance, cargo run --example simple_send.

Step 1: build and start a node

The entry point is ReticulumNodeBuilder. You add interfaces on the builder, call build().await, then start().await. This is the opening of every example; here it is from simple_send.rs:

use reticulum_std::driver::ReticulumNodeBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt::init();

    // Build a node with a TCP interface to a local daemon.
    let mut node = ReticulumNodeBuilder::new()
        .add_tcp_client("127.0.0.1:4242".parse()?)
        .build()
        .await?;

    node.start().await?;
    // ... use the node ...
    node.stop().await?;
    Ok(())
}

build() loads or generates the node’s transport identity (persisted under the storage path) and prepares interfaces, but does not run anything. start() spawns the tokio event loop and brings the interfaces online. stop() flushes state and tears the loop down. If you are constructing a node outside an async context, build_sync() is the non-async equivalent of build().

Other interfaces are added the same way: add_tcp_server(addr), add_udp_interface(listen, forward), add_auto_interface() (IPv6 multicast LAN discovery), and add_rnode_interface(...) for LoRa. A relay node adds enable_transport(true), as in relay_daemon.rs:

#![allow(unused)]
fn main() {
// Adapted from relay_daemon.rs
let mut node = ReticulumNodeBuilder::new()
    .enable_transport(true)
    .add_tcp_client(peer)
    .build()
    .await?;
}

Step 2: take the event receiver and consume events

Everything inbound — announces, paths, link lifecycle, link data — reaches you as NodeEvent values on an EventReceiver. Take it once with take_event_receiver() and call recv().await in a loop. From simple_send.rs:

#![allow(unused)]
fn main() {
let mut events = node
    .take_event_receiver()
    .ok_or("Failed to get event receiver")?;

while let Some(event) = events.recv().await {
    println!("Received event: {:?}", event);
}
}

recv() behaves like a tokio::sync::mpsc::Receiver::recv (it is cancel-safe in tokio::select!) and returns None only once the node has shut down. The echo_server.rs example shows the real shape: match on the variants you care about and ignore the rest.

#![allow(unused)]
fn main() {
use reticulum_std::NodeEvent;

// Adapted from echo_server.rs
loop {
    tokio::select! {
        Some(event) = events.recv() => match event {
            NodeEvent::LinkEstablished { link_id, is_initiator } => {
                println!("link up: {:02x?} (we initiated: {})",
                    &link_id.as_bytes()[..4], is_initiator);
            }
            NodeEvent::LinkDataReceived { link_id, data } => {
                println!("{} bytes on {:02x?}: {:?}",
                    data.len(), &link_id.as_bytes()[..4],
                    String::from_utf8_lossy(&data));
            }
            NodeEvent::MessageReceived { link_id, msgtype, sequence, data } => {
                println!("msg type 0x{:04x} seq {} on {:02x?}",
                    msgtype, sequence, &link_id.as_bytes()[..4]);
            }
            NodeEvent::AnnounceReceived { announce, interface_index } => {
                println!("announce from {:02x?} on iface {}",
                    &announce.destination_hash().as_bytes()[..4], interface_index);
            }
            other => println!("other: {:?}", other),
        },
        _ = tokio::signal::ctrl_c() => break,
    }
}
}

Note the two receive variants. MessageReceived is the channel-multiplexed path (sequenced, retransmitted) most link applications use; LinkDataReceived is the lower-level raw-link-packet path (for example a Python peer calling RNS.Packet(link, data).send()). The chat.rs example handles both.

Step 3: register and announce a destination

To be reachable you register a local destination and announce it. A destination is built from your identity, a direction, a type, an app name, and aspect strings. This is from the api module’s own test, which is the most compact worked registration in the tree:

#![allow(unused)]
fn main() {
use reticulum_std::{Destination, Direction, DestinationType, generate_identity};

let id = generate_identity();

let dest = Destination::new(
    Some(id),
    Direction::In,
    DestinationType::Single,
    "leviculum-test",
    &["api"],
)?;
let dh = *dest.hash();              // 16-byte DestinationHash, read before moving dest

node.register_destination(dest);   // consumes dest

// Announce it; the optional payload rides along in the announce.
node.announce_destination(&dh, Some(b"hi")).await?;
}

Read dest.hash() before calling register_destination, which takes the Destination by value. Incoming (Direction::In) destinations are auto-accepted for links by the core (Python-RNS parity): when a peer opens a link to one, the stack accepts and proves it automatically and you see a LinkEstablished event — there is no separate accept call.

Step 4: send a single packet

For fire-and-forget delivery use a PacketSender, the single-packet handle. A path to the destination must already be known (learn it from an announce, or call request_path). Adapted from the PacketSender doctest in driver/sender.rs:

#![allow(unused)]
fn main() {
let endpoint = node.packet_sender(&dest_hash);
let _packet_hash = endpoint.send(b"Hello!").await?;
}

send returns the truncated packet hash, which you can match against a later PacketDeliveryConfirmed event if the destination proves delivery.

Step 5: open a link and send on it

A link is an encrypted session. Open one with connect, passing the destination hash and its 32-byte Ed25519 signing key (the signing half of the peer’s identity, learned from its announce). You get back a LinkHandle. Adapted from the LinkHandle doctest in driver/stream.rs:

#![allow(unused)]
fn main() {
let handle = node.connect(&dest_hash, &signing_key).await?;

// The handle is usable immediately, but the link is not yet established.
// Watch for NodeEvent::LinkEstablished on the event receiver before relying
// on delivery, then send:
handle.send(b"Hello!").await?;
}

connect returns as soon as the link request is dispatched; the link is pending until a LinkEstablished event fires for its link_id. send absorbs pacing and busy conditions by retrying internally; try_send is the non-blocking variant that surfaces backpressure instead. Responses arrive as MessageReceived / LinkDataReceived events on the receiver you took in step 2. Close with handle.close().await when done.

On the responder side you do not call connect. Once a LinkEstablished event fires for a link you did not initiate (is_initiator == false), the link is already live; mint a writable handle for it with node.link_handle(&link_id) and send on that.

Where to go next

• simple_send.rs and echo_server.rs — the minimal node + event loop.
• chat.rs — both receive variants, node status (active_link_count, pending_link_count).
• relay_daemon.rs — a transport node and transport_stats().
• link_test.rs / link_integration_test.rs — these drop down to reticulum-core’s Link directly against a Python rnsd, useful if you want to see the wire-level handshake rather than the high-level handle API.

The full method list of every type is in the generated rustdoc. Build it with:

cargo doc --no-deps --open -p reticulum-std

For verified signatures of the types used above, continue to the Rust API reference.

Rust API Reference

This chapter is a reference for the key entry points and core value types of the Leviculum Rust API, organized by type. Each signature carries a file:line citation to the source as of this writing. It is deliberately not exhaustive: the complete per-type method list is generated rustdoc (see Full rustdoc at the end). Use this chapter to orient, then rustdoc for the long tail.

The hands-on introduction is the tutorial; the layer overview is Choosing a layer.

All reticulum-std types are re-exported from the crate root (reticulum-std/src/lib.rs:35-57), so use reticulum_std::{NodeEvent, LinkHandle, …} works without naming submodules.

reticulum-std (std / tokio)

Reticulum

The configuration-driven entry point, wrapping a ReticulumNode. Defined at reticulum-std/src/reticulum.rs:13. Use this when your node is described by a Config (an INI file or a programmatic Config); use ReticulumNodeBuilder when you assemble interfaces in code.

ReticulumNodeBuilder

The programmatic builder. Defined at reticulum-std/src/driver/builder.rs:34; re-exported as reticulum_std::ReticulumNodeBuilder. Each setter consumes and returns self.

ReticulumNode

The running node. Defined at reticulum-std/src/driver/mod.rs:412; re-exported as reticulum_std::ReticulumNode. Selected methods:

The stable, curated facade reticulum_std::api (reticulum-std/src/api/mod.rs:55 NodeBuilder / :206 Node) re-projects this surface with core internals hidden; it is what reticulum-ffi wraps. Notable facade-only helpers: api::generate_identity() (api/mod.rs:30), api::version() (api/mod.rs:37), api::version_string() (api/mod.rs:46), and Node::connect_with_key (api/mod.rs:329) / Node::accept_link (api/mod.rs:345).

LinkHandle

Send-only async handle for a link. Defined at reticulum-std/src/driver/stream.rs:45; re-exported as reticulum_std::LinkHandle. Incoming data is delivered via NodeEvent, not on the handle.

PacketSender

Send-only async handle for single packets, the single-packet analog of LinkHandle. Defined at reticulum-std/src/driver/sender.rs:42; re-exported as reticulum_std::PacketSender.

EventReceiver and NodeEvent

EventReceiver is the merged event stream, defined at reticulum-std/src/driver/mod.rs:259. It internally fronts a lossless control plane and a droppable data plane (Codeberg #71), draining control first.

NodeEvent is the event enum, defined in core at reticulum-core/src/node/event.rs:21 and re-exported as reticulum_std::NodeEvent. It is #[non_exhaustive], so always include a catch-all arm. The variants most applications match (field names verbatim from source):

MessageReceived is the channel-multiplexed (sequenced) receive path; LinkDataReceived is the raw-link-packet path. The full variant list (resources, requests/responses, identify, stale/recovered, control-plane overflow) is in event.rs and in rustdoc.

Config

Configuration, defined at reticulum-std/src/config.rs:11; re-exported as reticulum_std::Config. pub reticulum: ReticulumConfig (config.rs:14) and pub interfaces: HashMap<String, InterfaceConfig> (config.rs:17).

reticulum-core (no_std, sans-IO)

The core is the no_std engine the std layer drives. You use these types directly only when building on reticulum-core — see Embedded development. All are re-exported from reticulum-core/src/lib.rs:123-143.

NodeCore<R, C, S>

The sans-IO protocol engine, generic over an RNG R: CryptoRngCore, a clock C: Clock, and storage S: Storage. Defined at reticulum-core/src/node/mod.rs:143. It never performs I/O; every method that can produce output returns a TickOutput the caller must dispatch.

A node is more often built with NodeCoreBuilder (node/builder.rs:38), whose fn build<R, Clk, S>(self, rng: R, clock: Clk, storage: S) -> NodeCore<R, Clk, S> (node/builder.rs:168) supplies the platform triple. Setters include identity, proof_strategy, and enable_transport.

Core TickOutput and Action

TickOutput is what every core method returns. Defined at reticulum-core/src/transport.rs:138. It is #[must_use] — dropping it silently loses outbound packets and events.

Action is the I/O the driver performs, defined at reticulum-core/src/transport.rs:113:

The helper dispatch_actions(interfaces: &mut [&mut dyn Interface], actions: Vec<Action>, ifac_configs: &BTreeMap<usize, IfacConfig>) -> DispatchResult (transport.rs:211) routes Actions to interfaces with broadcast-exclusion and IFAC wrapping handled in core, so every driver gets it for free.

Value types

Identity — a key pair or public-only identity. Defined at reticulum-core/src/identity.rs. Re-exported as reticulum_std::Identity.

Destination — a local or remote destination. Defined at reticulum-core/src/destination.rs. Re-exported as reticulum_std::Destination.

DestinationHash — a 16-byte address (newtype, destination.rs:158): fn new(bytes: [u8; TRUNCATED_HASHBYTES]) -> Self (destination.rs:162), fn as_bytes(&self) -> &[u8; TRUNCATED_HASHBYTES] (destination.rs:167), fn into_bytes(self) -> [u8; TRUNCATED_HASHBYTES] (destination.rs:172). Direction (destination.rs:130) and DestinationType (destination.rs:102) are the small enums passed to Destination::new. Packets are constructed internally (reticulum_core::packet::Packet); applications work with destinations and links, not raw packets.

Platform traits

The three abstractions you implement to run the core on a platform. Defined in reticulum-core/src/traits.rs and re-exported from lib.rs:141.

Provided Storage implementations: NoStorage (traits.rs:506, zero-sized no-op for stubs and stateless devices), MemoryStorage (reticulum-core/src/memory_storage.rs, BTreeMap-backed with caps), and EmbeddedStorage (reticulum-core/src/embedded_storage.rs:37, heapless-backed for flash-constrained targets; fn new() -> Self at embedded_storage.rs:344). reticulum-std adds a file-backed Storage with Python-compatible on-disk formats.

Full rustdoc

This chapter covers the load-bearing surface; the exhaustive method list is the generated rustdoc. Build and open it with:

cargo doc --no-deps --open -p reticulum-std    # std/tokio layer
cargo doc --no-deps --open -p reticulum-core   # no_std core

Embedded Development: Building on reticulum-core

This chapter is for building on reticulum-core directly: embedded firmware, a custom async runtime, a simulator, or any host program that wants byte-level control without tokio. The core is no_std (it uses alloc, but not the standard library) and sans-IO — it performs no I/O and owns no runtime. You feed it bytes, it hands back a TickOutput, and you do the I/O. The worked reference is the nRF52 firmware in reticulum-nrf, cited throughout.

If you can use std and tokio, prefer reticulum-std and read the tutorial instead — reticulum-std is itself a driver for this same core. See Choosing a layer for the trade-off.

The dependency

Depend on reticulum-core with default features off. It is not on crates.io, so use a path or git:

[dependencies]
reticulum-core = { path = "../libreticulum/reticulum-core", default-features = false }

No std, no tokio. You bring your own executor (Embassy, RTIC, a bare loop) and your own allocator. The reference firmware reticulum-nrf is version 0.4.0, targets thumbv7em-none-eabihf, and uses Embassy.

The sans-IO contract

The core is a state machine with exactly three ways in, and one way out. The way out is always a TickOutput (reticulum-core/src/transport.rs:138), carrying actions to perform, events that occurred, and next_deadline_ms, the time at which you must next tick the timer. It is #[must_use]: dropping it loses outbound packets and events.

received bytes ─► handle_packet(iface, data) ─┐
timer expired  ─► handle_timeout()            ├─► TickOutput { actions, events, next_deadline_ms }
                                              │
                                              └─► you: dispatch actions, react to events,
                                                       schedule the next timeout

The three entry points (signatures in the reference):

• handle_packet(iface, data) — reticulum-core/src/node/mod.rs:1006. Feed one received frame, tagged with the InterfaceId it arrived on.
• handle_timeout() — reticulum-core/src/node/mod.rs:1098. Run periodic maintenance (path expiry, announce rebroadcasts, keepalives, retransmissions). Call it at or before next_deadline.
• next_deadline() — reticulum-core/src/node/mod.rs:1129. The earliest timer deadline in milliseconds, or None if no timer is pending. Sleep until this, or until a packet arrives, whichever comes first.

App-initiated operations (register_destination, announce_destination, connect, send_on_link, send_single_packet) likewise return a TickOutput you must dispatch.

The driver loop

The shape is: compute the next deadline, wait for whichever of “a packet on any interface” or “the deadline” happens first, call the matching entry point, dispatch the resulting actions. This is exactly the reticulum-nrf T114 main loop (reticulum-nrf/src/bin/t114.rs:256-307), here with three interfaces (serial, LoRa, BLE) selected over with Embassy’s select4:

#![allow(unused)]
fn main() {
// Adapted from reticulum-nrf/src/bin/t114.rs:256
loop {
    let deadline = node
        .next_deadline()
        .map(Instant::from_millis)
        .unwrap_or(Instant::MAX);

    match select4(
        serial.incoming_rx.receive(),
        lora_channels.incoming_rx.receive(),
        ble_channels.incoming_rx.receive(),
        Timer::at(deadline),
    )
    .await
    {
        Either4::First(data) => {
            let output = node.handle_packet(InterfaceId(0), &data);
            let mut ifaces: [&mut dyn Interface; 3] =
                [&mut serial_iface, &mut lora_iface, &mut ble_iface];
            dispatch_actions(&mut ifaces, output.actions, &ifac_configs);
        }
        Either4::Second(data) => {
            let output = node.handle_packet(InterfaceId(1), &data);
            let mut ifaces: [&mut dyn Interface; 3] =
                [&mut serial_iface, &mut lora_iface, &mut ble_iface];
            dispatch_actions(&mut ifaces, output.actions, &ifac_configs);
        }
        Either4::Third(data) => {
            let output = node.handle_packet(InterfaceId(2), &data);
            let mut ifaces: [&mut dyn Interface; 3] =
                [&mut serial_iface, &mut lora_iface, &mut ble_iface];
            dispatch_actions(&mut ifaces, output.actions, &ifac_configs);
        }
        Either4::Fourth(()) => {
            let output = node.handle_timeout();
            let mut ifaces: [&mut dyn Interface; 3] =
                [&mut serial_iface, &mut lora_iface, &mut ble_iface];
            dispatch_actions(&mut ifaces, output.actions, &ifac_configs);
        }
    }
}
}

Three things to notice:

1. next_deadline() drives the timer. Map None to “wait forever” (Instant::MAX) so you wake only when something actually needs doing — there is no fixed tick rate.
2. InterfaceId(n) tags the source. The index you pass to handle_packet must match the interface’s own id(), so the core’s routing tables and broadcast-exclusion stay consistent.
3. dispatch_actions does the routing. Rather than matching on each Action yourself, hand the whole actions vec plus your &mut dyn Interface slice to dispatch_actions (reticulum-core/src/transport.rs:211). Broadcast exclusion, interface selection, and IFAC wrapping live in core, so every driver gets them for free.

This loop ignores output.events because a leaf firmware node has no application logic to react to them; a richer firmware would drain output.events here the way the std event loop drains the EventReceiver.

Building the node

NodeCoreBuilder (reticulum-core/src/node/builder.rs:38) takes the platform triple — RNG, Clock, and Storage — in its build call. From the T114 firmware (reticulum-nrf/src/bin/t114.rs:123-142):

#![allow(unused)]
fn main() {
// Adapted from reticulum-nrf/src/bin/t114.rs:123
let mut builder = NodeCoreBuilder::new()
    .enable_transport(true)
    .max_incoming_resource_size(8 * 1024)
    .respond_to_probes(true);

if let Ok(Some(identity)) = id_store.load() {
    builder = builder.identity(identity);
}

let mut node = Box::new(builder.build(rng, EmbassyClock, EmbeddedStorage::new()));
}

build consumes the builder and the platform triple and returns the NodeCore<R, C, S>.

Implementing the platform traits

Three traits decouple the core from your hardware. Their signatures are in the reference; here is what to supply.

Clock

A monotonic millisecond clock. The whole trait is one required method. The nRF52 implementation wraps Embassy’s timer (reticulum-nrf/src/clock.rs):

#![allow(unused)]
fn main() {
use reticulum_core::traits::Clock;

pub struct EmbassyClock;

impl Clock for EmbassyClock {
    fn now_ms(&self) -> u64 {
        embassy_time::Instant::now().as_millis()
    }
}
}

now_secs, has_elapsed, and deadline have default implementations (reticulum-core/src/traits.rs:167-179); you only provide now_ms. It must be monotonic.

Interface

The send side of an interface — id, name, mtu, is_online, and the non-blocking try_send (reticulum-core/src/traits.rs:97). The receive side is deliberately not in the trait: receiving is platform-specific (an interrupt, a DMA buffer, an Embassy channel), and you feed received bytes into the core via handle_packet yourself. try_send returns InterfaceError::BufferFull (non-fatal, packet dropped — Reticulum is best-effort) or InterfaceError::Disconnected. A minimal always-ready interface looks like the test impl in traits.rs:

#![allow(unused)]
fn main() {
use reticulum_core::traits::{Interface, InterfaceError};
use reticulum_core::transport::InterfaceId;

struct MyRadio { /* hardware handle */ }

impl Interface for MyRadio {
    fn id(&self) -> InterfaceId { InterfaceId(1) }
    fn name(&self) -> &str { "my-radio" }
    fn mtu(&self) -> usize { 500 }
    fn is_online(&self) -> bool { true }
    fn try_send(&mut self, data: &[u8]) -> Result<(), InterfaceError> {
        // hand `data` to the radio's TX queue, non-blocking
        Ok(())
    }
}
}

A constrained medium (LoRa) overrides next_slot_ms (reticulum-core/src/traits.rs:150) to report the next airtime-fit time, so the core schedules retries against capacity without knowing any radio physics — the interface-isolation rule. For a fast link the default (“always ready”) is correct.

Storage

Key-value persistence for the path table, link table, announce caches, identities, ratchets, and dedup hashes (reticulum-core/src/traits.rs:196). It is a large trait; you do not write it from scratch:

• NoStorage (reticulum-core/src/traits.rs:506) — zero-sized, every lookup returns nothing. Use it for a stateless node or a smoke test.
• EmbeddedStorage (reticulum-core/src/embedded_storage.rs:37, EmbeddedStorage::new() at :344) — heapless-backed, fixed-capacity, the production choice for flash-constrained devices. This is what the nRF52 firmware uses.
• MemoryStorage (reticulum-core/src/memory_storage.rs) — BTreeMap-backed with configurable caps, for hosts with more memory.

Implement Storage yourself only to add real persistence (e.g. to flash); the file-backed implementation in reticulum-std is the worked example of wrapping MemoryStorage with disk writes.

Summary

• Depend on reticulum-core with default-features = false. No std, no tokio, alloc required.
• Drive the loop: next_deadline() → wait for a packet or the deadline → handle_packet / handle_timeout → dispatch_actions(output.actions).
• Implement Clock (trivial), Interface (send side only — you feed RX in via handle_packet), and pick a Storage (NoStorage / EmbeddedStorage / MemoryStorage, or your own).
• The full worked driver is reticulum-nrf/src/bin/t114.rs; the full method list is cargo doc --no-deps -p reticulum-core (see the reference).

C API: Overview and Concepts

Leviculum ships a C API so an application can use the Reticulum network stack the way it uses any normal Unix C library: a clean header, opaque handle types, integer error codes, and composition with the application’s own event loop. This chapter explains the model that the How-To and the API Reference build on. For the design rationale behind these choices, see the design-of-record at docs/leviculum-api-design.md.

Every symbol is prefixed lev_ (functions) or LEV_ (constants). The header is leviculum.h, the library is libleviculum.so.

Installing and linking

Once the development package is installed, building against Leviculum is the usual two lines:

#include <leviculum.h>

cc app.c $(pkg-config --cflags --libs leviculum)

The pkg-config call expands to -lleviculum plus the include and library paths. To build from source and install the header, the shared object (with its SONAME and dev symlinks), the static archive, and the pkg-config file:

make -C reticulum-ffi install PREFIX=/usr/local   # builds, then installs

To link Leviculum statically while glibc stays dynamic, pass --static so pkg-config adds the archive’s system dependencies, and force the archive:

cc app.c $(pkg-config --cflags leviculum) \
    -l:libleviculum.a $(pkg-config --static --libs-only-l leviculum | sed 's/-lleviculum//')

See Installation for the full toolchain setup. The install is verified end to end (dynamic and static, x86_64 and aarch64) by scripts/verify-packaging.sh.

Opaque handles

Every complex object is an opaque pointer. The application never sees a struct layout, so the ABI stays stable across versions. Each handle has a constructor and a matching free function; _free(NULL) is always a no-op.

Two builders are single-use: lev_builder_build and lev_register_destination take the contents of their handle and leave an empty shell that the caller still frees.

Addresses are not handles. A destination hash, a link id, and an identity hash are each a fixed 16-byte value (LEV_ADDR_LEN); a resource hash is 32 bytes (LEV_RESOURCE_HASH_LEN). They cross the boundary as plain uint8_t arrays.

Error handling

Functions that can fail return int: 0 (LEV_OK) on success, a negative LEV_ERR_* code on failure. Constructors that return a handle return NULL on failure. Two helpers turn a code into text:

• lev_strerror(code) returns a static, never-freed string for the code.
• lev_last_error() returns a thread-local string with the specific detail of the most recent failing call on the calling thread (which argument, which address). It is owned by the library and must not be freed.

int rc = lev_start(node);
if (rc != LEV_OK) {
    fprintf(stderr, "start failed: %s (%s)\n", lev_strerror(rc), lev_last_error());
}

The full code list is in the reference.

Buffers: the read(2) convention

Every function that returns bytes into a caller buffer uses the same shape, modelled on read(2):

int lev_identity_hash(const lev_identity_t *id,
                      uint8_t *buf, uintptr_t cap, uintptr_t *out_len);

• The caller owns buf and passes its capacity cap plus an out_len.
• On success the library writes the bytes and sets *out_len to the count.
• If cap is too small (or buf is NULL), nothing is written, *out_len is set to the required size, and the call returns LEV_ERR_BUFFER_TOO_SMALL. Passing buf == NULL is therefore a valid size query.

uint8_t hash[LEV_ADDR_LEN];
uintptr_t len = sizeof(hash);
if (lev_identity_hash(id, hash, sizeof(hash), &len) == LEV_OK) {
    /* `hash` holds `len` bytes */
}

The library never hands C a raw pointer to free: all freeing goes through a typed lev_*_free, which removes C-free-versus-Rust-dealloc mistakes.

Out-parameters for returned values

Status and value are never multiplexed into one return. A call that both can fail and produces a value returns the int status and writes the value through an out-parameter:

uint8_t packet_hash[LEV_ADDR_LEN];
int rc = lev_send_datagram(node, dest, data, len, packet_hash, 3000);

lev_link_t *link = NULL;
int rc2 = lev_connect(node, dest, 5000, &link);   /* link in *out */

Strings and bytes

• Opaque byte payloads (keys, hashes, datagram data, link data, resource data) are always a pointer plus a length, never NUL-terminated, and may contain zero bytes.
• Human-readable strings the library consumes (storage path, destination app_name, request path) are NUL-terminated UTF-8 C strings.
• A destination’s aspects are passed as a const char *const * array plus a count.
• Library-returned static strings (lev_strerror, lev_last_error, lev_version_string) are NUL-terminated and must not be freed.

The event model: a pollable fd

Everything inbound (received announces, link data, request and response arrivals, resource progress and completion) reaches the application as events. A node exposes a single readable file descriptor that the application adds to its own poll/epoll/select loop:

struct pollfd p = { .fd = lev_event_fd(node), .events = POLLIN };
poll(&p, 1, -1);

lev_event_t *ev;
while (lev_next_event(node, &ev) == LEV_OK && ev) {
    switch (lev_event_type(ev)) {
        case LEV_EVENT_ANNOUNCE_RECEIVED: /* ... */ break;
        case LEV_EVENT_LINK_DATA:         /* ... */ break;
    }
    lev_event_free(ev);
}

The fd is level-triggered: it is readable exactly while the queue is non-empty. After each wake, drain with lev_next_event until it yields NULL. lev_wait_event(node, &ev, timeout_ms) is a convenience that blocks for the next event without your own loop. The event side is single-consumer: do not call the two drain functions concurrently for the same node.

The fd is owned by the library and closed by lev_free. The shutdown order is mandatory: stop reacting to the fd, remove it from your loop, then call lev_free. Polling the fd after lev_free is a use-after-close.

Event handles are fully self-owned (payloads are copied out at dequeue), so an event stays valid until lev_event_free regardless of later calls. Read its fields with the typed accessors (lev_event_link_id, lev_event_data, lev_event_request_id, lev_event_resource_hash, and so on); an accessor that does not apply to the event type returns LEV_ERR_INVALID_ARG.

Threading and blocking

The tokio runtime is created and owned inside the node and never exposed.

• A leviculum_t is thread-safe: its methods may be called concurrently from multiple threads.
• The event side is single-consumer (above).
• Every potentially-blocking call takes a timeout_ms (negative means wait forever); on expiry it returns LEV_ERR_TIMEOUT. The link data path is try_send-first: lev_link_try_send never blocks and returns LEV_ERR_AGAIN under backpressure, while lev_link_send retries up to its deadline.
• lev_free, lev_stop, and the other blocking calls must run on a plain OS thread, never on a worker thread of another runtime (for example a host async runtime); doing so would panic the embedded block_on.
• The log callback may fire on any internal worker thread and must not call back into any lev_* function.

No panic crosses the boundary

Every exported function wraps its body so that an internal Rust panic is caught and converted to LEV_ERR_PANIC (or NULL for a constructor) instead of unwinding into C, which would be undefined behaviour. After a caught panic the affected node should be freed and not reused.

One-time setup and logging

lev_init() performs idempotent process setup (logging subscriber and panic hook). It is optional, since other entry points run it lazily, but call it explicitly to configure logging before the first node. Logging is silent by default; raise it with lev_log_set_level(LEV_LOG_INFO) and route records with lev_log_set_callback, or leave the default which writes to stderr.

With these conventions in hand, the Tutorial builds a complete, useful program (levcat, a pipe over the mesh) step by step, the How-To is the recipe book for every flow, and the API Reference documents every function.

Tutorial: Build levcat, a Pipe over Reticulum

This tutorial builds one small, complete, genuinely useful program from scratch: levcat, a bidirectional pipe over the mesh, the netcat of Reticulum. Run it in two terminals and it is a chat. Feed it a file and it is a file transfer (levcat connect ... < file). Drop it in a shell pipeline and it carries bytes between machines, over TCP, over LoRa, over anything Reticulum reaches.

Along the way you learn the patterns every Leviculum C program needs: bring up a node, announce and discover a destination, open a link, and — the heart of it — run the node’s event loop inside your own poll(2) loop, alongside your own file descriptors. After this you can write your own Leviculum program.

This builds on the Overview (opaque handles, the read(2) buffer convention, the pollable event fd); skim it first. The How-To is the recipe companion, and the API Reference has every signature. The finished program is reticulum-ffi/examples/c/levcat.c, compiled and tested in the repo, so the code here is real, not pseudo-code.

What we build

Two roles share one transport and one steady-state loop:

levcat listen  <storage> <bind host:port>           # the listening end
levcat connect <storage> <peer host:port> <dest-hex> # the dialing end

The listener registers a destination, announces it, and prints its address. The connector is handed that address, finds a path to it, and opens a link. Once linked, both ends pump stdin to the link and link data to stdout.

1. Skeleton

Start with argument parsing, one-time init, and a signal flag so Ctrl-C exits cleanly. lev_init() is optional (other calls run it lazily) but it is the place to set up logging before anything else.

#include <errno.h>
#include <poll.h>
#include <signal.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

#include "leviculum.h"

static volatile sig_atomic_t stop = 0;
static void on_signal(int s) { (void)s; stop = 1; }

int main(int argc, char **argv) {
    signal(SIGINT, on_signal);
    signal(SIGTERM, on_signal);
    lev_init();

    if (argc == 4 && strcmp(argv[1], "listen") == 0)
        return run_listen(argv[2], argv[3]);
    if (argc == 5 && strcmp(argv[1], "connect") == 0)
        return run_connect(argv[2], argv[3], argv[4]);

    fprintf(stderr, "usage:\n  %s listen  <storage> <bind host:port>\n"
                    "  %s connect <storage> <peer host:port> <dest-hex>\n",
            argv[0], argv[0]);
    return 2;
}

2. Bring up a node

A node is built, then started. The builder is an opaque handle you configure and then consume; see reference: node lifecycle and builder. Both roles share this helper, differing only in the interface they add — a TCP server for the listener, a TCP client for the connector.

static leviculum_t *build_start(const char *storage,
                                void (*configure)(lev_builder_t *, const char *),
                                const char *arg, lev_identity_t *id) {
    lev_builder_t *b = lev_builder_new();
    if (!b) return NULL;
    if (lev_builder_storage_path(b, storage) != LEV_OK) { lev_builder_free(b); return NULL; }
    if (id) lev_builder_identity(b, id);
    configure(b, arg);                 /* add the interface */
    leviculum_t *node = lev_builder_build(b);
    lev_builder_free(b);               /* build empties the builder; still free it */
    if (!node) return NULL;
    if (lev_start(node) != LEV_OK) { lev_free(node); return NULL; }
    return node;
}

static void cfg_server(lev_builder_t *b, const char *addr) { lev_builder_add_tcp_server(b, addr); }
static void cfg_client(lev_builder_t *b, const char *addr) { lev_builder_add_tcp_client(b, addr); }

3. The listening end

The listener owns a destination: an address other nodes can reach. We generate an identity, register an incoming single destination under the app name levcat with the aspect pipe, and read back its 16-byte hash. Then we announce it so the network learns a path, and print the address — to stderr, because stdout is the data pipe and must stay clean.

lev_identity_t *id = lev_identity_generate();
leviculum_t *node = build_start(storage, cfg_server, bind_addr, id);

const char *aspects[] = {"pipe"};
lev_destination_t *dest =
    lev_destination_new(id, LEV_DIRECTION_IN, LEV_DEST_SINGLE, "levcat", aspects, 1);
uint8_t dh[LEV_ADDR_LEN];
size_t dhl = sizeof(dh);
lev_destination_hash(dest, dh, sizeof(dh), &dhl);
lev_register_destination(node, dest);
lev_destination_free(dest);

char hexhash[2 * LEV_ADDR_LEN + 1];
hex(dh, LEV_ADDR_LEN, hexhash);                 /* lev_hex_encode wrapper */
fprintf(stderr, "destination: %s\n", hexhash);

Now wait for someone to dial in. We re-announce in a loop (so a peer that starts later still discovers us) and watch for a LEV_EVENT_LINK_REQUEST. When it arrives we read the link id from the event and accept it. See How-To: announcing and discovering.

lev_link_t *link = NULL;
while (!stop && !link) {
    lev_announce(node, dh, NULL, 0, 2000);
    for (int i = 0; i < 3 && !link; i++) {
        lev_event_t *ev = NULL;
        if (lev_wait_event(node, &ev, 200) != LEV_OK || !ev) continue;
        if (lev_event_type(ev) == LEV_EVENT_LINK_REQUEST) {
            uint8_t lid[LEV_ADDR_LEN];
            size_t l = sizeof(lid);
            lev_event_link_id(ev, lid, sizeof(lid), &l);
            lev_accept_link(node, lid, 5000, &link);
        }
        lev_event_free(ev);
    }
}

One subtlety: accepting a link does not make it immediately usable for sending. The responder’s link becomes active only after the initiator’s RTT exchange, signalled by the responder’s own LEV_EVENT_LINK_ESTABLISHED. Sending before that returns LEV_ERR_SEND (“link not active”). So we wait for it before pumping, writing through any data that arrives meanwhile so none is lost:

int active = 0;
while (link && !stop && !active) {
    lev_event_t *ev = NULL;
    if (lev_wait_event(node, &ev, 200) != LEV_OK || !ev) continue;
    int t = lev_event_type(ev);
    if (t == LEV_EVENT_LINK_ESTABLISHED) active = 1;
    else if (t == LEV_EVENT_LINK_MESSAGE) emit_message(ev);   /* don't drop early data */
    else if (t == LEV_EVENT_LINK_CLOSED)  stop = 1;
    lev_event_free(ev);
}
if (active) pump(node, link);

lev_wait_event is the blocking drain we use during setup; the steady-state loop (pump, below) uses the pollable fd instead. Every event must be freed with lev_event_free.

4. The dialing end

The connector is given the listener’s address as hex. Decode it to 16 bytes, bring up a node with a TCP client interface, and wait for a path: the listener’s announce arrives over the link and installs one. lev_request_path nudges it along; lev_has_path reports when it is ready. See reference: paths, connect, and links.

uint8_t dest[LEV_ADDR_LEN];
size_t dlen = sizeof(dest);
lev_hex_decode((const uint8_t *)dest_hex, strlen(dest_hex), dest, sizeof(dest), &dlen);

leviculum_t *node = build_start(storage, cfg_client, peer_addr, NULL);

lev_request_path(node, dest, 2000);
for (int i = 0; i < 300 && lev_has_path(node, dest) != 1; i++) {
    lev_event_t *ev = NULL;
    if (lev_wait_event(node, &ev, 200) == LEV_OK && ev) lev_event_free(ev);
}

With a path in hand, open the link. lev_connect returns as soon as the request is sent — the link is usable only after the handshake, which the engine signals with LEV_EVENT_LINK_ESTABLISHED. Wait for it, then start pumping.

lev_link_t *link = NULL;
lev_connect(node, dest, 8000, &link);

int established = 0;
for (int i = 0; i < 100 && !established; i++) {
    lev_event_t *ev = NULL;
    if (lev_wait_event(node, &ev, 200) == LEV_OK && ev) {
        if (lev_event_type(ev) == LEV_EVENT_LINK_ESTABLISHED) established = 1;
        lev_event_free(ev);
    }
}
if (established) pump(node, link);

5. The pump loop — the heart of it

Both ends now have a link and run the same loop. This is the pattern that makes Leviculum composable: the node exposes a single readable file descriptor (lev_event_fd), so you put it in your own poll(2) set right next to your own fds. Here that is stdin. One poll waits for either: local input to send, or a network event to receive. See the event model.

static void pump(leviculum_t *node, lev_link_t *link) {
    struct pollfd fds[2];
    fds[0].fd = STDIN_FILENO;        fds[0].events = POLLIN;
    fds[1].fd = lev_event_fd(node);  fds[1].events = POLLIN;

    while (!stop) {
        int r = poll(fds, 2, 1000);
        if (r < 0) { if (errno == EINTR) continue; break; }

        if (fds[0].revents & POLLIN) {          /* local input -> link */
            uint8_t buf[CHUNK];
            ssize_t n = read(STDIN_FILENO, buf, sizeof(buf));
            if (n <= 0) { /* EOF: flush, then close — see below */ return; }
            if (lev_link_send(link, buf, (size_t)n, 5000) != LEV_OK) return;
        }

        if ((fds[1].revents & POLLIN) && drain_to_stdout(node)) return; /* link -> stdout */
    }
}

Two details:

• Chunking. A link’s reliable channel has a maximum message size, so we read stdin in #define CHUNK 256-byte pieces that fit on any interface. lev_link_send is the reliable, sequenced send; it blocks up to its deadline, retrying backpressure internally. (The non-blocking sibling is lev_link_try_send, which returns LEV_ERR_AGAIN instead of waiting — see How-To: links and exchanging data.)
• Receiving. lev_link_send on one side surfaces as a LEV_EVENT_LINK_MESSAGE on the other. We drain every pending event and copy each message’s bytes to stdout, using the read(2)-style accessor (size query, then fill):

static void emit_message(lev_event_t *ev) {
    size_t need = 0;
    lev_event_data(ev, NULL, 0, &need);              /* size query */
    uint8_t *d = malloc(need ? need : 1);
    size_t got = need;
    lev_event_data(ev, d, need, &got);               /* fill */
    fwrite(d, 1, got, stdout);
    fflush(stdout);
    free(d);
}

static int drain_to_stdout(leviculum_t *node) {
    int closed = 0;
    lev_event_t *ev = NULL;
    while (lev_next_event(node, &ev) == LEV_OK && ev) {
        int t = lev_event_type(ev);
        if (t == LEV_EVENT_LINK_MESSAGE) {
            emit_message(ev);
        } else if (t == LEV_EVENT_LINK_CLOSED) {
            closed = 1;
        }
        lev_event_free(ev);
    }
    return closed;
}

The fd is level-triggered: it stays readable while the queue is non-empty, so after each wake we drain with lev_next_event until it yields NULL. The event side is single-consumer — never drain the same node from two threads.

6. Closing cleanly

When local input ends (Ctrl-D, or the end of a piped file), we are done sending. Give the reliable channel a moment to deliver the last bytes — draining any final inbound meanwhile — then close our end. The peer sees LEV_EVENT_LINK_CLOSED and exits too, so a cat file | levcat connect ... terminates instead of hanging. This is the if (n <= 0) branch of the pump:

for (int g = 0; g < 10 && !stop; g++) {
    struct pollfd ef = {fds[1].fd, POLLIN, 0};
    if (poll(&ef, 1, 100) > 0 && drain_to_stdout(node)) break;
}
lev_close_link(link, 2000);
return;

(A production tool would do a real half-close so the reverse direction can keep flowing; we keep it minimal.) Then tear the node down in order — the link first, then the node:

lev_link_free(link);   /* NULL-safe; closes the link if still open */
lev_stop(node);        /* persists state, stops the loop */
lev_free(node);        /* releases the runtime and the event fd */
lev_identity_free(id); /* listener only */

The shutdown order is mandatory: stop reacting to the event fd before lev_free, which closes it.

7. Build and run it

Compile against the installed library with pkg-config (installing and linking):

cc levcat.c $(pkg-config --cflags --libs leviculum) -o levcat

Open two terminals. In the first, listen:

$ ./levcat listen /tmp/levcat-a 127.0.0.1:4242
destination: a1b2c3d4e5f6...        # printed on stderr

In the second, connect with that address, then type on either side:

$ ./levcat connect /tmp/levcat-b 127.0.0.1:4242 a1b2c3d4e5f6...
hello from the other terminal

That is a chat. It is also a pipe — send a file and end with Ctrl-D, or:

# receiver
./levcat listen  /tmp/levcat-a 127.0.0.1:4242 > received.tar
# sender
tar c somedir | ./levcat connect /tmp/levcat-b 127.0.0.1:4242 <dest-hex>

Nothing here is TCP-specific. Swap lev_builder_add_tcp_* for lev_builder_add_rnode (or load a config file) and the same program pipes bytes across a LoRa mesh.

Where to go next

You have used the core of the API: node setup, announce and discovery, links, and the event loop. From here:

• Bulk data with progress, compression, and metadata: How-To: resource transfer (and the full reticulum-ffi/examples/c/lncp.c file-copy tool).
• Lightweight RPC: How-To: request and response.
• Best-effort single packets: How-To: datagrams.
• Inspecting the stack: How-To: diagnostics.
• Every signature and constant: the API Reference.

Full program: reticulum-ffi/examples/c/levcat.c.

C API: How-To, Building Applications

This chapter shows how the functions combine into working programs. It assumes the model from the Overview: opaque handles, integer error codes, read(2) buffers, and the pollable event fd. Each recipe gives the functions involved and a focused snippet; the complete, compiling programs are the acceptance tests under reticulum-ffi/examples/c/, named per recipe. For a single program built end to end from these pieces, see the Tutorial.

Error checks are abbreviated in the snippets for readability. In real code, check every int return against LEV_OK and report lev_last_error() (see Errors and logging).

A minimal node

Build a node, attach an interface, start it, and shut it down. The builder is single-use: lev_builder_build consumes its configuration and you still free the empty handle.

#include <leviculum.h>
#include <stdio.h>

int main(void) {
    lev_init();
    printf("leviculum %s\n", lev_version_string());

    lev_builder_t *b = lev_builder_new();
    lev_builder_storage_path(b, "/var/lib/myapp/reticulum");
    lev_builder_add_tcp_client(b, "127.0.0.1:4242");   /* a Reticulum hub */

    leviculum_t *node = lev_builder_build(b);
    lev_builder_free(b);                               /* build emptied it */
    if (!node) {
        fprintf(stderr, "build failed: %s\n", lev_last_error());
        return 1;
    }

    if (lev_start(node) != LEV_OK) {
        fprintf(stderr, "start failed: %s\n", lev_last_error());
        lev_free(node);
        return 1;
    }

    /* ... run the application ... */

    lev_stop(node);
    lev_free(node);     /* lev_free also stops a still-running node */
    return 0;
}

Interfaces are added on the builder: lev_builder_add_tcp_client, lev_builder_add_tcp_server, lev_builder_add_udp, lev_builder_add_auto_interface. Use lev_builder_identity to pin a specific identity (otherwise one is generated), and lev_builder_enable_transport(b, 1) to act as a relay.

Full program: reticulum-ffi/examples/c/phase_a.c.

Running the event loop

Everything inbound arrives as events. Add lev_event_fd(node) to your loop, and on each wake drain with lev_next_event until it yields NULL.

#include <poll.h>

int fd = lev_event_fd(node);
for (;;) {
    struct pollfd p = { .fd = fd, .events = POLLIN };
    poll(&p, 1, -1);

    lev_event_t *ev;
    while (lev_next_event(node, &ev) == LEV_OK && ev) {
        switch (lev_event_type(ev)) {
            case LEV_EVENT_ANNOUNCE_RECEIVED: on_announce(ev); break;
            case LEV_EVENT_LINK_REQUEST:      on_link_request(ev); break;
            case LEV_EVENT_LINK_MESSAGE:      on_link_message(ev); break;
            /* ... */
        }
        lev_event_free(ev);
    }
}

If you do not want to own a loop, block for one event at a time:

lev_event_t *ev = NULL;
if (lev_wait_event(node, &ev, 1000) == LEV_OK && ev) {   /* up to 1s */
    /* handle ev */
    lev_event_free(ev);
}

Rules: the fd is level-triggered (readable while the queue is non-empty); the two drain functions are single-consumer (one thread at a time); and the shutdown order is stop reacting to the fd, then lev_free. Reading an event’s fields uses the typed accessors shown in the recipes below.

Running as or with a daemon

A node need not bring up its own interfaces in code. Three builder calls cover the daemon use cases.

Load an RNS-style config (the same INI rnsd/lnsd read), so interfaces, transport, and the shared instance come from a file an operator edits. This is also how a C node reaches LoRa without programmatic radio setup, the config names an RNodeInterface or SerialInterface and the stack brings it up.

lev_builder_t *b = lev_builder_new();
lev_builder_config_file(b, "/etc/leviculum/config");
leviculum_t *node = lev_builder_build(b);
lev_builder_free(b);
lev_start(node);   /* now a daemon: run the event loop until signalled */

Offer a shared instance, so other local programs and the Reticulum tools (rnstatus, rnpath, rnprobe) attach to this one stack instead of each opening the radio:

lev_builder_share_instance(b, "leviculum");   /* opens the IPC + RPC endpoint */

Or attach to a running daemon as a client, the way rncp/rnx do, instead of bringing up interfaces of your own:

lev_builder_connect_shared_instance(b, "leviculum");

A NULL path or name returns LEV_ERR_INVALID_ARG. The daemon.c example is a worked acceptance program for all three calls. The lncp.c file-copy tool has both styles: its recv/send modes bring up their own interface, while its recv-shared/send-shared modes attach to a running lnsd by instance name, so several tools share one daemon’s radio.

Radio interfaces (LoRa and serial)

For off-grid mesh, add an RNode (LoRa) or a raw serial interface programmatically, no config file needed:

lev_builder_t *b = lev_builder_new();
/* RNode: device, frequency Hz, bandwidth Hz, spreading factor, coding rate,
 * tx power dBm. */
lev_builder_add_rnode(b, "/dev/ttyUSB0", 867200000, 125000, 8, 5, 0);
/* Serial: device, speed, data bits, parity ("N"/"E"/"O"), stop bits. */
lev_builder_add_serial(b, "/dev/ttyACM0", 115200, 8, "N", 1);

The device is opened at lev_start, so a wrong path surfaces there, not at the setter (which only rejects a NULL path with LEV_ERR_INVALID_ARG). A serial port is raw KISS with no handshake; an RNode performs the RNode detect and config handshake on start. For the optional RNode knobs (airtime limits, flow control, buffer size), load a config file instead. The radio.c example brings a node up over a serial interface.

Identities

An identity is a key pair. Generate one, persist it, and reload it next run. The on-disk format is the raw 64-byte private key, compatible with Python Reticulum.

lev_identity_t *id;
id = lev_identity_load_file("/var/lib/myapp/identity");
if (!id) {                                   /* first run: make one */
    id = lev_identity_generate();
    lev_identity_save_file(id, "/var/lib/myapp/identity");
}

uint8_t hash[LEV_ADDR_LEN];
uintptr_t len = sizeof(hash);
lev_identity_hash(id, hash, sizeof(hash), &len);   /* the 16-byte address */

A combined key is 64 bytes (LEV_IDENTITY_KEY_LEN): the X25519 encryption key in bytes 0..32 and the Ed25519 signing key in bytes 32..64. Applications rarely split it by hand, because lev_connect resolves the signing key for you (see below). Use lev_builder_identity(b, id) to give a node a fixed identity, and lev_identity_free(id) when done.

An identity also signs, verifies, encrypts, and decrypts directly, for crypto tooling and signed application data, interoperable with Python peers (Ed25519 for signatures, X25519+AES for encryption):

uint8_t sig[64];
uintptr_t n = sizeof(sig);
lev_identity_sign(id, msg, msg_len, sig, sizeof(sig), &n);
int ok = lev_identity_verify(id, msg, msg_len, sig, n);   /* 1 valid, 0 not */

/* Encrypt to a peer's public-only identity; only its private key recovers it. */
uint8_t ct[512];
uintptr_t ctl = sizeof(ct);
lev_identity_encrypt(peer, msg, msg_len, ct, sizeof(ct), &ctl);

Sign, encrypt, and decrypt write read(2) style (a NULL buffer queries the length); signing and decryption need the private key and return LEV_ERR_CRYPTO on a public-only identity, while verify needs only the public key.

Full programs: reticulum-ffi/examples/c/phase_a.c and crypto.c.

Announcing and discovering

To be reachable, a node registers an incoming destination and announces it. Other nodes learn the destination (its address, identity, and a path) from the announce, which arrives as LEV_EVENT_ANNOUNCE_RECEIVED.

Announcing side:

const char *aspects[] = { "inbox" };
lev_destination_t *dest = lev_destination_new(
    id, LEV_DIRECTION_IN, LEV_DEST_SINGLE, "myapp", aspects, 1);

uint8_t dh[LEV_ADDR_LEN];
uintptr_t dhl = sizeof(dh);
lev_destination_hash(dest, dh, sizeof(dh), &dhl);   /* read before registering */

lev_register_destination(node, dest);   /* consumes dest */
lev_destination_free(dest);             /* free the empty shell */

lev_announce(node, dh, NULL, 0, 2000);  /* optional app_data, here none */

For forward secrecy, call lev_destination_enable_ratchets(dest, now_ms) on an inbound destination before registering it (now_ms is the current time in milliseconds); peers, including Python ones, then encrypt to a rotating ratchet key. lev_destination_ratchet_public(node, dh, ...) reads the current key. See reticulum-ffi/examples/c/ratchet.c.

For delivery proofs, call lev_destination_set_proof_strategy(dest, strategy) before registering. LEV_PROOF_ALL auto-proves every received packet (Python’s PROVE_ALL). LEV_PROOF_APP raises a LEV_EVENT_PACKET_PROOF_REQUESTED event whose data is the 32-byte packet hash; the app decides and calls lev_send_proof(node, dest_hash, packet_hash, timeout_ms). See reticulum-ffi/examples/c/proof.c.

Receiving side, in the event loop:

case LEV_EVENT_ANNOUNCE_RECEIVED: {
    uint8_t peer[LEV_ADDR_LEN];
    uintptr_t n = sizeof(peer);
    lev_event_dest_hash(ev, peer, sizeof(peer), &n);   /* who announced */
    /* optional payload via lev_event_data(ev, ...) */
    break;
}

After processing the announce, the receiver has a path and the announcer’s cached identity, so lev_has_path(node, peer) returns 1 and lev_connect will work.

Full program: reticulum-ffi/examples/c/phase_b.c.

Links and exchanging data

A link is an encrypted session to a destination. lev_connect resolves the peer’s signing key from the identity cached by an announce, so you pass only the destination hash:

lev_link_t *link = NULL;
int rc = lev_connect(node, peer, 5000, &link);
if (rc == LEV_ERR_UNKNOWN_DEST) { /* no announce seen yet */ }
else if (rc == LEV_ERR_NO_PATH) { lev_request_path(node, peer, 3000); }
else if (rc == LEV_OK) { /* link is pending; wait for established */ }

The connecting node watches for LEV_EVENT_LINK_ESTABLISHED; the destination node watches for LEV_EVENT_LINK_REQUEST and accepts it:

case LEV_EVENT_LINK_REQUEST: {
    uint8_t lid[LEV_ADDR_LEN];
    uintptr_t n = sizeof(lid);
    lev_event_link_id(ev, lid, sizeof(lid), &n);
    lev_link_t *accepted = NULL;
    lev_accept_link(node, lid, 5000, &accepted);
    /* keep `accepted` to send on this link */
    break;
}

Send and receive link data. lev_link_send blocks up to its deadline, retrying backpressure; lev_link_try_send returns LEV_ERR_AGAIN instead of blocking. It sends over the link’s reliable channel (sequenced and retransmitted, the same RawBytesMessage Python peers use), so the peer sees a LEV_EVENT_LINK_MESSAGE, with a message type and a sequence number:

lev_link_send(link, (const uint8_t *)"hello", 5, 5000);

case LEV_EVENT_LINK_MESSAGE: {
    uint8_t buf[512];
    uintptr_t n = sizeof(buf);
    uint16_t msgtype = 0, sequence = 0;
    if (lev_event_data(ev, buf, sizeof(buf), &n) == LEV_OK) {
        lev_event_msgtype(ev, &msgtype);   /* 0 for raw bytes */
        lev_event_sequence(ev, &sequence); /* per-channel send order */
        /* `n` bytes received */
    }
    break;
}

A peer that sends a raw, unsequenced link packet instead of using the channel (for example Python’s RNS.Packet(link, data).send()) arrives as the lower-level LEV_EVENT_LINK_DATA, which carries only link_id and data.

Close with lev_close_link(link, 2000) and release with lev_link_free(link) (which also closes an open link). A LEV_EVENT_LINK_CLOSED event reports a link that drops for any reason.

Full program: reticulum-ffi/examples/c/phase_c.c.

Proving identity on a link

By default a link is anonymous. Either side can prove an identity to the peer; the peer is notified with LEV_EVENT_LINK_IDENTIFIED and can read it back.

/* prover */
lev_link_identify(node, my_link_id, my_identity, 3000);

/* peer, in the event loop */
case LEV_EVENT_LINK_IDENTIFIED: {
    lev_identity_t *who = lev_link_remote_identity(node, my_link_id);
    if (who) {
        uint8_t h[LEV_ADDR_LEN];
        uintptr_t n = sizeof(h);
        lev_identity_hash(who, h, sizeof(h), &n);   /* the peer's address */
        lev_identity_free(who);
    }
    break;
}

The 16-byte identity hash is also the payload of the LEV_EVENT_LINK_IDENTIFIED event (lev_event_data).

Full program: reticulum-ffi/examples/c/phase_c.c.

Request and response

For a request/response service, the responder registers a handler for a path on its destination; the requester sends a request over a link. Request and response payloads are msgpack-encoded values.

Responder:

lev_register_request_handler(node, dh, "/echo",
                             LEV_REQUEST_POLICY_ALLOW_ALL, NULL, 0);

case LEV_EVENT_REQUEST_RECEIVED: {
    uint8_t link_id[LEV_ADDR_LEN], req_id[LEV_ADDR_LEN], data[512];
    uintptr_t a = sizeof(link_id), b = sizeof(req_id), c = sizeof(data);
    lev_event_link_id(ev, link_id, sizeof(link_id), &a);
    lev_event_request_id(ev, req_id, sizeof(req_id), &b);
    lev_event_data(ev, data, sizeof(data), &c);          /* the request body */
    /* path is available via lev_event_path(ev, ...) */
    lev_send_response(node, link_id, req_id, data, c, 3000);  /* echo it */
    break;
}

Requester (over an established link, whose id comes from lev_link_id):

uint8_t req[] = { 0xA4, 'p','i','n','g' };   /* msgpack "ping" */
uint8_t request_id[LEV_ADDR_LEN];
lev_send_request(node, link_id, "/echo", req, sizeof(req), 5000, request_id);

case LEV_EVENT_RESPONSE_RECEIVED: {
    uint8_t rid[LEV_ADDR_LEN], body[512];
    uintptr_t a = sizeof(rid), b = sizeof(body);
    lev_event_request_id(ev, rid, sizeof(rid), &a);   /* match request_id */
    lev_event_data(ev, body, sizeof(body), &b);
    break;
}

A request that gets no reply within its deadline surfaces as LEV_EVENT_REQUEST_TIMEOUT. To restrict callers, use LEV_REQUEST_POLICY_ALLOW_LIST with an array of n_ids 16-byte identity hashes.

Full program: reticulum-ffi/examples/c/phase_d.c.

Datagrams

A datagram is a single, unreliable packet to a destination. A path must already be known. Delivery is best-effort: a LEV_EVENT_PACKET_RECEIVED on the other side, and a delivery confirmation only if the destination returns a proof.

uint8_t packet_hash[LEV_ADDR_LEN];
int rc = lev_send_datagram(node, dest_hash, (const uint8_t *)"hi", 2,
                           packet_hash, 3000);
if (rc == LEV_ERR_NO_PATH) { lev_request_path(node, dest_hash, 3000); }

/* receiver */
case LEV_EVENT_PACKET_RECEIVED: {
    uint8_t buf[256];
    uintptr_t n = sizeof(buf);
    lev_event_data(ev, buf, sizeof(buf), &n);
    break;
}

Full program: reticulum-ffi/examples/c/phase_d.c.

Resource transfer

A resource carries bulk data (a file) over a link, in segments, with optional compression and msgpack metadata. The receiver chooses a strategy: accept all, reject all, or be asked per transfer.

Receiver sets a strategy on the link, then accepts when advertised:

lev_set_resource_strategy(node, link_id, LEV_RESOURCE_ACCEPT_APP);

case LEV_EVENT_RESOURCE_ADVERTISED:
    lev_accept_resource(node, link_id, 3000);   /* or lev_reject_resource */
    break;

case LEV_EVENT_RESOURCE_COMPLETED: {
    uint8_t buf[65536];
    uintptr_t n = sizeof(buf);
    lev_event_data(ev, buf, sizeof(buf), &n);    /* the assembled data */
    /* metadata via lev_event_metadata(ev, ...) if present */
    break;
}

Sender initiates the transfer and tracks progress:

uint8_t resource_hash[LEV_RESOURCE_HASH_LEN];
lev_send_resource(node, link_id, file_data, file_len,
                  NULL, 0,        /* optional msgpack metadata */
                  1,              /* auto-compress */
                  resource_hash, 5000);

case LEV_EVENT_RESOURCE_PROGRESS: {
    double frac;
    lev_event_progress(ev, &frac);   /* 0.0 .. 1.0 */
    break;
}

LEV_EVENT_RESOURCE_COMPLETED carries the data only on the receiver; LEV_EVENT_RESOURCE_FAILED reports a transfer that did not finish.

lev_send_resource returns once the transfer is initiated: the receiver then pulls the parts part by part. A sending program must keep its node alive and running the event loop until the transfer is done, the receiver must keep the link it accepted open (freeing a link closes it), and the receiver applies its resource strategy on the link before the resource arrives. Exiting the sender right after the call returns aborts an in-flight transfer.

Full programs: reticulum-ffi/examples/c/phase_e.c, and reticulum-ffi/examples/c/lncp.c, a complete two-process file-copy tool (lncp send / lncp recv) that exercises the whole stack end to end.

Errors and logging

Every fallible call returns int. Pair the code with the thread-local detail:

int rc = lev_connect(node, peer, 5000, &link);
if (rc != LEV_OK) {
    fprintf(stderr, "connect: %s (%s)\n", lev_strerror(rc), lev_last_error());
}

LEV_ERR_AGAIN (from lev_link_try_send) and LEV_ERR_TIMEOUT are normal, retryable conditions, not hard failures. Logging from the stack itself is off by default; turn it on and route it to your own sink:

static void log_sink(int level, const char *msg, void *user) {
    (void)user;
    fprintf(stderr, "[lev %d] %s\n", level, msg);
}

lev_init();
lev_log_set_callback(log_sink, NULL);
lev_log_set_level(LEV_LOG_INFO);

The callback may run on an internal thread and must not call back into any lev_* function. For hex display of an address, use lev_hex_encode and lev_hex_decode.

Diagnostics

For an rnstatus-style view, lev_transport_stats reads the transport counters and the path-table size:

uint64_t sent, received, dropped, paths;
lev_transport_stats(node, &sent, &received, NULL, NULL, &dropped, &paths);

Any out-pointer may be NULL to skip it.

For an rnpath-style listing, take a frozen snapshot of the path table, read its entries by index, and free it:

lev_path_table_t *table = lev_path_table_snapshot(node);
for (int i = 0; i < lev_path_table_count(table); i++) {
    uint8_t dest[LEV_ADDR_LEN];
    uint8_t hops;
    lev_path_table_entry(table, i, dest, &hops, NULL, NULL, NULL, NULL);
    /* `dest` reachable in `hops` hops */
}
lev_path_table_free(table);

The snapshot is a point-in-time copy, so reads never race a changing table.

Interface stats work the same way (lev_interface_stats_snapshot / _count / _name / _entry / _free), giving each interface’s name, online status, and byte counters for an rnstatus-style interface listing. See reticulum-ffi/examples/c/stats.c.

Putting it together

A typical application wires these into one loop: it loads or generates an identity, builds and starts a node with an interface, registers and announces a destination, then runs the event loop, reacting to announces by connecting, to link requests by accepting, and to data, request, and resource events by serving the application. The phase_b.c through phase_e.c programs are complete two-node demonstrations of exactly these flows, runnable via cargo test-ffi.

C API: Reference

Every public function and constant of leviculum.h, grouped by area. The header reticulum-ffi/leviculum.h is generated from the Rust source and is the canonical statement of the exact prototypes; this reference is kept in sync with it and adds semantics. For the model behind these signatures (handles, the read(2) buffer convention, out-parameters, the event fd, threading), read the Overview first.

Conventions used below:

• Functions return int: LEV_OK (0) on success, a negative LEV_ERR_* on failure; constructors return NULL on failure. After any failure, lev_last_error() holds a detail string.
• A (uint8_t *buf, uintptr_t cap, uintptr_t *out_len) triple is read(2) style: buf == NULL or too-small cap returns LEV_ERR_BUFFER_TOO_SMALL with *out_len set to the required size.
• timeout_ms is a deadline in milliseconds; negative means wait forever; on expiry the call returns LEV_ERR_TIMEOUT.

Opaque types

Initialisation and logging

int lev_init(void);
int lev_log_set_level(int level);
int lev_log_set_callback(lev_log_callback cb, void *user);
typedef void (*lev_log_callback)(int level, const char *message, void *user);

• lev_init runs one-time process setup (logging subscriber, panic hook) once, through an internal Once. Idempotent and thread-safe. Optional: other entry points run it lazily.
• lev_log_set_level sets the global verbosity to one of the LEV_LOG_* constants. Returns LEV_ERR_INVALID_ARG for an out-of-range level.
• lev_log_set_callback routes log records to cb (with user passed back unchanged), or restores the stderr default when cb is NULL. The callback may run on any internal worker thread, receives a NUL-terminated message valid only for the call, and must not call back into any lev_* function.

Versioning

const char *lev_version_string(void);
uint32_t    lev_version_number(void);

• lev_version_string returns the version (for example "0.7.0") as a static, never-freed string.
• lev_version_number packs it as (major << 16) | (minor << 8) | patch, a host-byte-order integer for in-process comparison only.

Errors

const char *lev_strerror(int code);
const char *lev_last_error(void);

• lev_strerror returns a static message for a LEV_ERR_* code; safe any time, never freed.
• lev_last_error returns the thread-local detail string for the most recent failing call on the calling thread, or NULL if there is none. Owned by the library, valid until the next failing call on the same thread, never freed.

Error codes

Identity

struct lev_identity_t *lev_identity_generate(void);
struct lev_identity_t *lev_identity_from_private_key(const uint8_t *key, uintptr_t len);
struct lev_identity_t *lev_identity_from_public_key(const uint8_t *key, uintptr_t len);
struct lev_identity_t *lev_identity_load_file(const char *path);
int  lev_identity_save_file(const struct lev_identity_t *id, const char *path);
void lev_identity_free(struct lev_identity_t *id);
int  lev_identity_hash(const struct lev_identity_t *id, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_identity_public_key(const struct lev_identity_t *id, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_identity_private_key(const struct lev_identity_t *id, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_identity_has_private_keys(const struct lev_identity_t *id);
int  lev_identity_sign(const struct lev_identity_t *id, const uint8_t *msg, uintptr_t msg_len, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_identity_verify(const struct lev_identity_t *id, const uint8_t *msg, uintptr_t msg_len, const uint8_t *sig, uintptr_t sig_len);
int  lev_identity_encrypt(const struct lev_identity_t *id, const uint8_t *plaintext, uintptr_t plaintext_len, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_identity_decrypt(const struct lev_identity_t *id, const uint8_t *ciphertext, uintptr_t ciphertext_len, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);

• lev_identity_generate makes a new random full identity; NULL on failure.
• lev_identity_from_private_key / lev_identity_from_public_key build an identity from a 64-byte combined key (len must equal LEV_IDENTITY_KEY_LEN); the public-key variant yields a public-only identity. NULL on failure.
• lev_identity_load_file reads the raw 64-byte private key file (the Python-Reticulum format); NULL if missing, wrong size, or invalid.
• lev_identity_save_file writes the private key to path atomically; LEV_ERR_CRYPTO if the identity is public-only.
• lev_identity_hash writes the 16-byte identity hash; _public_key and _private_key write the 64-byte combined keys (_private_key returns LEV_ERR_CRYPTO for a public-only identity). All read(2) style.
• lev_identity_has_private_keys returns 1 for a full identity, 0 otherwise (and 0 on NULL).
• lev_identity_sign writes the 64-byte Ed25519 signature of msg read(2) style; LEV_ERR_CRYPTO if the identity is public-only. lev_identity_verify returns 1 if the signature is valid, 0 if not (including a wrong-length signature), and a negative LEV_ERR_* on a NULL argument; it needs only the public key.
• lev_identity_encrypt encrypts plaintext to the identity’s public key (the Reticulum X25519+AES scheme) and writes the ciphertext read(2) style; encryption is randomised, so a length query and the real call differ in bytes but not length. lev_identity_decrypt reverses it with the private key and returns LEV_ERR_CRYPTO for a public-only identity or a ciphertext that fails to authenticate.

Every returned lev_identity_t is owned by the caller and freed with lev_identity_free.

Node lifecycle and builder

struct lev_builder_t *lev_builder_new(void);
void lev_builder_free(struct lev_builder_t *b);
int  lev_builder_identity(struct lev_builder_t *b, const struct lev_identity_t *id);
int  lev_builder_storage_path(struct lev_builder_t *b, const char *path);
int  lev_builder_add_tcp_client(struct lev_builder_t *b, const char *addr);
int  lev_builder_add_tcp_server(struct lev_builder_t *b, const char *addr);
int  lev_builder_add_udp(struct lev_builder_t *b, const char *listen_addr, const char *forward_addr);
int  lev_builder_add_auto_interface(struct lev_builder_t *b);
int  lev_builder_add_rnode(struct lev_builder_t *b, const char *port, uint64_t frequency, uint32_t bandwidth, uint8_t spreading_factor, uint8_t coding_rate, int8_t tx_power);
int  lev_builder_add_serial(struct lev_builder_t *b, const char *port, uint32_t speed, uint8_t databits, const char *parity, uint8_t stopbits);
int  lev_builder_enable_transport(struct lev_builder_t *b, int enabled);
int  lev_builder_event_capacity(struct lev_builder_t *b, uintptr_t control_cap, uintptr_t data_cap);
int  lev_builder_link_keepalive(struct lev_builder_t *b, uint64_t secs);
int  lev_builder_config_file(struct lev_builder_t *b, const char *path);
int  lev_builder_share_instance(struct lev_builder_t *b, const char *name);
int  lev_builder_connect_shared_instance(struct lev_builder_t *b, const char *name);
struct leviculum_t *lev_builder_build(struct lev_builder_t *b);

int  lev_start(struct leviculum_t *node);
int  lev_stop(struct leviculum_t *node);
int  lev_is_running(const struct leviculum_t *node);
int  lev_identity_hash_self(const struct leviculum_t *node, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
void lev_free(struct leviculum_t *node);

• lev_builder_new allocates a builder; lev_builder_free releases it (lev_builder_free(NULL) is a no-op).
• The setters configure the node: _identity pins a (cloned) identity, _storage_path sets the state directory, the _add_* calls add interfaces (TCP addresses are host:port), _enable_transport toggles relay mode, and _event_capacity sets the event-queue sizes (control and data planes; a 0 keeps the current default). Each setter returns LEV_ERR_INVALID_ARG if the builder was already consumed.
• lev_builder_link_keepalive overrides the link keepalive interval, in seconds, for every link the node creates; the stale-link timeout scales with it (a link goes stale after twice the keepalive). The value is clamped to the protocol minimum. The default (no call) derives the interval from the link RTT. Useful for slow links, and for making LEV_EVENT_LINK_STALE observable quickly. The same knob is the keepalive_interval key in a config file.
• lev_builder_add_rnode adds a LoRa interface over an RNode: port is the serial device, then the required radio settings (frequency and bandwidth in Hz, spreading_factor, coding_rate denominator, tx_power in dBm). lev_builder_add_serial adds a raw KISS serial interface: port, speed, databits, parity ("N", "E", or "O"), stopbits. Both return LEV_ERR_INVALID_ARG on a NULL device path (or NULL parity). For the optional RNode tuning (airtime limits, flow control, buffer size) use a config file. The device is opened at lev_start, not when the setter runs.
• lev_builder_config_file loads an RNS-style INI config (the same format rnsd/lnsd read) from path; its [reticulum] and [interfaces] sections add to whatever the builder set programmatically. Loading a config brings up every interface type it names, including RNode and Serial, so a C node reaches LoRa through a config file.
• lev_builder_share_instance makes the node offer a shared instance under name: it opens a local IPC endpoint and the rnstatus/rnpath/rnprobe RPC server, so other local programs (and tools) attach to this one stack.
• lev_builder_connect_shared_instance makes the node a client of a shared instance named name instead of bringing up its own interfaces, the way rncp/rnx attach to a running daemon. A NULL path or name returns LEV_ERR_INVALID_ARG.
• lev_builder_build produces a leviculum_t and empties the builder; you still call lev_builder_free on the empty handle. NULL on failure.
• lev_start spawns the event loop and brings up interfaces; lev_stop persists state and tears it down; a stopped node can be started again. lev_start on a running node returns LEV_ERR_CONFIG.
• lev_is_running returns 1 while the loop runs (0 on NULL).
• lev_identity_hash_self writes the node’s own 16-byte identity hash.
• lev_free stops a running node and releases it (lev_free(NULL) is a no-op). Call it, and the other blocking calls, from a plain OS thread.

The event-side functions on a node (lev_event_fd, lev_next_event, lev_wait_event) are documented under Events.

Destinations and announce

struct lev_destination_t *lev_destination_new(const struct lev_identity_t *identity,
                                              int direction, int dest_type,
                                              const char *app_name,
                                              const char *const *aspects, uintptr_t n_aspects);
void lev_destination_free(struct lev_destination_t *dest);
int  lev_destination_hash(const struct lev_destination_t *dest, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_destination_enable_ratchets(struct lev_destination_t *dest, uint64_t now_ms);
int  lev_destination_ratchet_public(const struct leviculum_t *node, const uint8_t *dest_hash, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_destination_set_proof_strategy(struct lev_destination_t *dest, int strategy);
int  lev_send_proof(const struct leviculum_t *node, const uint8_t *dest_hash, const uint8_t *packet_hash, int timeout_ms);
int  lev_register_destination(const struct leviculum_t *node, struct lev_destination_t *dest);
int  lev_announce(const struct leviculum_t *node, const uint8_t *dest_hash,
                  const uint8_t *app_data, uintptr_t app_data_len, int timeout_ms);
int  lev_send_datagram(const struct leviculum_t *node, const uint8_t *dest_hash,
                       const uint8_t *data, uintptr_t data_len, uint8_t *out_hash, int timeout_ms);

• lev_destination_new builds a destination from an identity (may be NULL; required for some types, forbidden for LEV_DEST_PLAIN), a direction, a type, an app_name, and an array of n_aspects NUL-terminated aspect strings. NULL on failure.
• lev_destination_hash writes the 16-byte hash; read it before registering. Returns LEV_ERR_INVALID_ARG once the destination has been consumed.
• lev_destination_enable_ratchets turns on forward secrecy for an inbound destination before it is registered; now_ms is the current time in milliseconds, seeding ratchet rotation. LEV_ERR_INVALID_ARG for an outbound destination or one already registered. lev_destination_ratchet_public reads the current 32-byte ratchet public key of a registered destination (read(2) style), or LEV_ERR_INVALID_ARG if it has no ratchets. Ratcheted destinations interoperate with Python peers.
• lev_destination_set_proof_strategy sets, before registration, how a destination proves delivery of received packets: LEV_PROOF_NONE (default, never), LEV_PROOF_APP (emit LEV_EVENT_PACKET_PROOF_REQUESTED so the app decides, then calls lev_send_proof), or LEV_PROOF_ALL (auto-prove every packet, Python’s PROVE_ALL). lev_send_proof sends a delivery proof for the packet_hash from a proof-requested event; LEV_ERR_SEND if no return path exists.
• lev_register_destination registers the destination on the node so it can be announced and accept links and packets. It consumes the destination (the handle is emptied; still free it). LEV_ERR_INVALID_ARG if already registered.
• lev_announce broadcasts a registered destination (by 16-byte hash) on all interfaces, with optional app_data.
• lev_send_datagram sends one unreliable packet to a destination and writes the 16-byte packet hash into out_hash. A path must be known (LEV_ERR_NO_PATH otherwise).

Paths, connect, and links

int lev_has_path(const struct leviculum_t *node, const uint8_t *dest_hash);
int lev_hops_to(const struct leviculum_t *node, const uint8_t *dest_hash, uint8_t *out);
int lev_request_path(const struct leviculum_t *node, const uint8_t *dest_hash, int timeout_ms);

int lev_connect(const struct leviculum_t *node, const uint8_t *dest_hash,
                int timeout_ms, struct lev_link_t **out);
int lev_connect_with_key(const struct leviculum_t *node, const uint8_t *dest_hash,
                         const uint8_t *signing_key, int timeout_ms, struct lev_link_t **out);
int lev_accept_link(const struct leviculum_t *node, const uint8_t *link_id,
                    int timeout_ms, struct lev_link_t **out);

int  lev_link_send(const struct lev_link_t *link, const uint8_t *data, uintptr_t len, int timeout_ms);
int  lev_link_try_send(const struct lev_link_t *link, const uint8_t *data, uintptr_t len);
int  lev_link_id(const struct lev_link_t *link, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_link_is_closed(const struct lev_link_t *link);
int  lev_link_identify(const struct leviculum_t *node, const uint8_t *link_id,
                       const struct lev_identity_t *identity, int timeout_ms);
struct lev_identity_t *lev_link_remote_identity(const struct leviculum_t *node, const uint8_t *link_id);
int  lev_close_link(struct lev_link_t *link, int timeout_ms);
void lev_link_free(struct lev_link_t *link);

• lev_has_path returns 1 if a path to the destination is known, else 0 (negative on a NULL argument). lev_hops_to writes the hop count into *out or returns LEV_ERR_NO_PATH. lev_request_path asks the network for a path; the result arrives as an event and lev_has_path then returns 1.
• lev_connect opens a link by destination hash, resolving the peer’s signing key from the identity cached by an announce; *out receives the link. Returns LEV_ERR_UNKNOWN_DEST if no identity is cached and LEV_ERR_NO_PATH if no path is known (it does not auto-request one).
• lev_connect_with_key is the same with an explicit 32-byte Ed25519 signing key, for out-of-band peers.
• lev_accept_link accepts an incoming link request (16-byte link id from a LEV_EVENT_LINK_REQUEST event); *out receives the link.
• lev_link_send sends data, retrying backpressure up to the deadline (then LEV_ERR_TIMEOUT); lev_link_try_send never blocks and returns LEV_ERR_AGAIN under backpressure. Inbound data arrives as LEV_EVENT_LINK_DATA.
• lev_link_id writes the 16-byte link id. lev_link_is_closed returns 1 if closed (0 on NULL).
• lev_link_identify proves an identity to the peer (who sees LEV_EVENT_LINK_IDENTIFIED); lev_link_remote_identity returns the peer’s identity as a new handle the caller frees, or NULL if the peer has not identified.
• lev_close_link closes gracefully (idempotent); lev_link_free releases the handle, closing an open link first.

Request and response

int lev_register_request_handler(const struct leviculum_t *node, const uint8_t *dest_hash,
                                 const char *path, int policy,
                                 const uint8_t *allow_identity_hashes, uintptr_t n_ids);
int lev_send_request(const struct leviculum_t *node, const uint8_t *link_id, const char *path,
                     const uint8_t *data, uintptr_t data_len,
                     int response_timeout_ms, uint8_t *out_request_id);
int lev_send_response(const struct leviculum_t *node, const uint8_t *link_id,
                      const uint8_t *request_id, const uint8_t *data, uintptr_t data_len, int timeout_ms);

• lev_register_request_handler registers a handler for path on a local destination. For LEV_REQUEST_POLICY_ALLOW_LIST, allow_identity_hashes is n_ids * 16 bytes of identity hashes; otherwise pass NULL, 0. Registering overwrites a previous handler for the same destination and path; there is no unregister.
• lev_send_request sends a request on an established link to path and writes the 16-byte request id into out_request_id. data is the msgpack-encoded payload (NULL, 0 for none); response_timeout_ms is the request-response deadline. The response (LEV_EVENT_RESPONSE_RECEIVED) or a timeout (LEV_EVENT_REQUEST_TIMEOUT) arrives as an event.
• lev_send_response replies to a received request (link id and request id from the LEV_EVENT_REQUEST_RECEIVED event); data must be one valid msgpack-encoded value.

Resource transfer

int lev_send_resource(const struct leviculum_t *node, const uint8_t *link_id,
                      const uint8_t *data, uintptr_t data_len,
                      const uint8_t *metadata, uintptr_t metadata_len,
                      int auto_compress, uint8_t *out_hash, int timeout_ms);
int lev_set_resource_strategy(const struct leviculum_t *node, const uint8_t *link_id, int strategy);
int lev_accept_resource(const struct leviculum_t *node, const uint8_t *link_id, int timeout_ms);
int lev_reject_resource(const struct leviculum_t *node, const uint8_t *link_id, int timeout_ms);

• lev_send_resource sends bulk data over a link and writes the 32-byte resource hash into out_hash. metadata, if present, must be msgpack-encoded; auto_compress is 0 or 1. The call blocks only for the initial dispatch; progress and completion arrive as events.
• lev_set_resource_strategy sets how incoming resources on a link are handled (one of the LEV_RESOURCE_* constants).
• lev_accept_resource / lev_reject_resource answer a LEV_EVENT_RESOURCE_ADVERTISED event under the AcceptApp strategy.

Events

int  lev_event_fd(const struct leviculum_t *node);
int  lev_next_event(struct leviculum_t *node, struct lev_event_t **out);
int  lev_wait_event(struct leviculum_t *node, struct lev_event_t **out, int timeout_ms);
void lev_event_free(struct lev_event_t *ev);

int  lev_event_type(const struct lev_event_t *ev);
int  lev_event_link_id(const struct lev_event_t *ev, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_event_dest_hash(const struct lev_event_t *ev, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_event_request_id(const struct lev_event_t *ev, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_event_resource_hash(const struct lev_event_t *ev, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_event_path(const struct lev_event_t *ev, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_event_data(const struct lev_event_t *ev, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_event_metadata(const struct lev_event_t *ev, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_event_progress(const struct lev_event_t *ev, double *out);
int  lev_event_dropped_count(const struct lev_event_t *ev, uint64_t *out);
int  lev_event_msgtype(const struct lev_event_t *ev, uint16_t *out);
int  lev_event_sequence(const struct lev_event_t *ev, uint16_t *out);
int  lev_event_is_sender(const struct lev_event_t *ev);

• lev_event_fd returns the readable fd to add to a poll/epoll/select loop. The library owns it and closes it in lev_free; never close it.
• lev_next_event dequeues without blocking: on success *out is an event handle, or NULL when the queue is empty. lev_wait_event blocks up to timeout_ms (negative forever); *out is NULL if the timeout elapses. It wakes promptly when an event arrives (the event fd is the real wake source) and otherwise rechecks at most every 250 ms, so an infinite wait still returns soon after an event lands. Both are single-consumer for a node. Free each event with lev_event_free.
• lev_event_type returns the event’s LEV_EVENT_* type (0 on NULL).
• The accessors read a field of the event, read(2) style for the byte fields: _link_id, _dest_hash, _request_id (16 bytes each), _resource_hash (32 bytes), _path (UTF-8 bytes, not NUL-terminated), _data (the primary payload, possibly empty), _metadata (msgpack bytes). _progress writes a double in 0.0..1.0 for resource-progress events; _dropped_count writes the count of a LEV_EVENT_CONTROL_OVERFLOW event; _msgtype and _sequence write the message type and sequence of a LEV_EVENT_LINK_MESSAGE event. An accessor that does not apply to the event type returns LEV_ERR_INVALID_ARG.
• lev_event_is_sender returns 1 on the sender side of a resource event (_PROGRESS/_COMPLETED/_FAILED), 0 on the receiver side (or for other events). A sender’s LEV_EVENT_RESOURCE_COMPLETED (empty data) signals that an outgoing transfer finished; a receiver’s carries the data. A node that both sends and receives resources uses this to tell the two apart.

Event types

Diagnostics

int lev_transport_stats(const struct leviculum_t *node,
                        uint64_t *out_packets_sent, uint64_t *out_packets_received,
                        uint64_t *out_packets_forwarded, uint64_t *out_announces_processed,
                        uint64_t *out_packets_dropped, uint64_t *out_path_count);

struct lev_path_table_t *lev_path_table_snapshot(const struct leviculum_t *node);
int  lev_path_table_count(const struct lev_path_table_t *table);
int  lev_path_table_entry(const struct lev_path_table_t *table, uintptr_t index,
                          uint8_t *dest_hash, uint8_t *hops, uint8_t *next_hop,
                          int *has_next_hop, uint64_t *interface_index, uint64_t *expires_ms);
void lev_path_table_free(struct lev_path_table_t *table);

struct lev_interface_stats_t *lev_interface_stats_snapshot(const struct leviculum_t *node);
int  lev_interface_stats_count(const struct lev_interface_stats_t *table);
int  lev_interface_stats_name(const struct lev_interface_stats_t *table, uintptr_t index,
                              uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int  lev_interface_stats_entry(const struct lev_interface_stats_t *table, uintptr_t index,
                               int *online, int *is_local_client,
                               uint64_t *rx_bytes, uint64_t *tx_bytes);
void lev_interface_stats_free(struct lev_interface_stats_t *table);

• lev_transport_stats reads the node’s transport counters and the current path-table size into the out-parameters, the basis for an rnstatus-style view. Any out-pointer may be NULL to skip that counter; a NULL node returns LEV_ERR_NULL_PTR. The values are a point-in-time snapshot.
• lev_path_table_snapshot returns an owned, frozen copy of the path table for an rnpath-style view, or NULL on a NULL node; free it with lev_path_table_free (NULL is a no-op). Because it is frozen, reads never race a changing table. lev_path_table_count gives the number of entries. lev_path_table_entry reads one entry by index into the out-parameters: dest_hash and next_hop (each at least LEV_ADDR_LEN bytes when non-NULL), hops, has_next_hop (1 for a relayed path, 0 for a direct one), interface_index, and expires_ms. Any out-pointer may be NULL; LEV_ERR_INVALID_ARG if index is out of range.
• lev_interface_stats_snapshot returns an owned, frozen copy of the interface list for an rnstatus-style interface view, freed with lev_interface_stats_free. lev_interface_stats_count gives the number of interfaces. lev_interface_stats_name reads the interface name read(2) style (variable length), and lev_interface_stats_entry reads the scalar fields (online, is_local_client, rx_bytes, tx_bytes) into out-parameters. Both return LEV_ERR_INVALID_ARG for an out-of-range index.

Helpers

int lev_hex_encode(const uint8_t *data, uintptr_t len, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);
int lev_hex_decode(const uint8_t *hex, uintptr_t hex_len, uint8_t *buf, uintptr_t cap, uintptr_t *out_len);

• lev_hex_encode writes 2 * len lowercase hex bytes (not NUL-terminated), read(2) style.
• lev_hex_decode writes hex_len / 2 bytes; LEV_ERR_INVALID_ARG on an odd length or a non-hex digit.

RNode Interface Protocol Research

Research based on Python RNS v1.1.3, source files:

• RNS/Interfaces/RNodeInterface.py (1558 lines)
• RNS/Interfaces/RNodeMultiInterface.py (1149 lines)
• RNS/Interfaces/Interface.py (302 lines, base class)
• RNS/Interfaces/KISSInterface.py (standard KISS, for comparison)

1. Serial Protocol

1.1 Framing

The RNode serial protocol uses KISS framing, not HDLC. This is a critical distinction from the TCP/Serial framing used elsewhere in Reticulum.

Frame format:

[FEND 0xC0] [CMD byte] [escaped payload...] [FEND 0xC0]

Escaping (KISS standard):

When the payload contains 0xC0 (FEND) or 0xDB (FESC), they are replaced:

• 0xDB -> 0xDB 0xDD (FESC TFESC) – escape is applied FIRST
• 0xC0 -> 0xDB 0xDC (FESC TFEND)

Note the escape ordering: FESC bytes are escaped first, then FEND bytes. This matches Python’s data.replace(bytes([0xdb]), bytes([0xdb, 0xdd])).replace(bytes([0xc0]), bytes([0xdb, 0xdc])).

Comparison with HDLC framing (used for TCP):

Key difference: KISS frames carry a command byte after the opening FEND. Standard HDLC frames do not. The RNode protocol is a KISS superset with RNode-specific command extensions.

1.2 Command Set (complete table)

Configuration Commands (Host -> Device, Device -> Host as confirmation)

Statistics Commands (Device -> Host, unsolicited)

System Commands

Multi-Interface Commands (RNodeMultiInterface only)

Note: CMD_INT8_DATA (0xC0) collides with FEND. This appears to be an oversight or intentional oddity in the multi-interface protocol. It means interface 8 data cannot actually be distinguished from a frame delimiter. In practice, multi-interface devices may not populate all 12 slots.

Error Codes (in CMD_ERROR payload)

Platform Constants

Radio Chip Types (Multi-Interface only)

1.3 Initialization Sequence

The host performs this exact sequence after opening the serial port:

Step 1: Open serial port

Baud: 115200
Data bits: 8
Stop bits: 1
Parity: None
Flow control: None (xonxoff=False, rtscts=False, dsrdtr=False)
Timeout: 0 (non-blocking reads)

Step 2: Wait 2.0 seconds

This is a hard-coded sleep to let the device settle after USB enumeration or power-on. Critical for reliability.

Step 3: Start read loop thread

A background thread begins reading bytes from the serial port and parsing KISS frames.

Step 4: Send detect + query commands (single frame sequence)

C0 08 73 C0 50 00 C0 48 00 C0 49 00 C0

This decodes as four back-to-back KISS frames:

1. FEND CMD_DETECT DETECT_REQ(0x73) FEND – “Are you an RNode?”
2. CMD_FW_VERSION 0x00 FEND – “What firmware version?”
3. CMD_PLATFORM 0x00 FEND – “What platform?”
4. CMD_MCU 0x00 FEND – “What MCU?”

Note: Frames 2-4 rely on FEND at end of previous frame serving as start of next frame (KISS allows this).

For RNodeMultiInterface, an additional query is appended: 5. CMD_INTERFACES 0x00 FEND – “List your radio interfaces”

Step 5: Wait for detect response (200ms for serial, 5s for TCP/BLE)

The read loop parses incoming bytes. When it sees CMD_DETECT with payload 0x46 (DETECT_RESP), it sets self.detected = True. The FW_VERSION, PLATFORM, and MCU responses are also parsed and stored.

Step 6: Validate firmware version

Required minimum: major >= 1, minor >= 52 (for single-interface). Required minimum: major >= 1, minor >= 74 (for multi-interface).

Step 7: Configure radio parameters

Sends these commands in sequence:

1. CMD_FREQUENCY with 4-byte big-endian frequency in Hz
2. CMD_BANDWIDTH with 4-byte big-endian bandwidth in Hz
3. CMD_TXPOWER with 1-byte TX power in dBm
4. CMD_SF with 1-byte spreading factor (5-12)
5. CMD_CR with 1-byte coding rate (5-8)
6. CMD_ST_ALOCK with 2-byte short-term airtime limit (if configured)
7. CMD_LT_ALOCK with 2-byte long-term airtime limit (if configured)
8. CMD_RADIO_STATE with 0x01 (RADIO_STATE_ON)

For multi-interface: each command is preceded by CMD_SEL_INT with the subinterface index, and configurations are sent per-subinterface.

Step 8: Validate radio state

Wait 250ms (serial) / 1.0s (BLE) / 1.5s (TCP), then compare the device-reported values (r_frequency, r_bandwidth, etc.) against the configured values. Frequency must match within 100 Hz.

Step 9: Mark interface online

Wait 300ms, then set self.online = True.

1.4 Data Transfer

Outgoing (Host -> Device)

A Reticulum packet is wrapped as:

[FEND 0xC0] [CMD_DATA 0x00] [KISS-escaped packet bytes] [FEND 0xC0]

For multi-interface, data is sent as:

[FEND] [CMD_SEL_INT 0x1F] [interface_index] [FEND] [FEND] [CMD_DATA 0x00] [KISS-escaped packet bytes] [FEND]

The packet bytes are the raw Reticulum packet (header + payload), with NO additional metadata. RSSI/SNR are not included in outgoing packets.

Incoming (Device -> Host)

The device sends received packets as:

[FEND 0xC0] [CMD_DATA 0x00] [KISS-escaped packet bytes] [FEND 0xC0]

For multi-interface, the device uses interface-specific data commands:

[FEND 0xC0] [CMD_INTn_DATA] [KISS-escaped packet bytes] [FEND 0xC0]

where CMD_INTn_DATA indicates which radio interface received the packet.

Accompanying metadata (separate KISS frames, sent before the data frame):

The device sends RSSI and SNR as separate KISS frames before or after the data frame:

• CMD_STAT_RSSI (0x23): 1 byte, unsigned. Actual RSSI = value - 157 dBm
• CMD_STAT_SNR (0x24): 1 byte, signed. Actual SNR = value * 0.25 dB

These are stored on the interface object and cleared after process_incoming delivers the packet:

self.r_stat_rssi = None
self.r_stat_snr = None

Periodically reported statistics (unsolicited, from device)

The device periodically sends these frames without host request:

CMD_STAT_CHTM (0x25) – Channel Time, 11 bytes:

Bytes 0-1:  airtime_short (BE u16, /100 = percent)
Bytes 2-3:  airtime_long (BE u16, /100 = percent)
Bytes 4-5:  channel_load_short (BE u16, /100 = percent)
Bytes 6-7:  channel_load_long (BE u16, /100 = percent)
Byte  8:    current_rssi (unsigned, -157 offset)
Byte  9:    noise_floor (unsigned, -157 offset)
Byte  10:   interference (unsigned, -157 offset; 0xFF = no interference)

Note: For multi-interface (RNodeMultiInterface), CMD_STAT_CHTM is only 8 bytes (no RSSI/noise_floor/interference fields):

Bytes 0-1:  airtime_short (BE u16, /100 = percent)
Bytes 2-3:  airtime_long (BE u16, /100 = percent)
Bytes 4-5:  channel_load_short (BE u16, /100 = percent)
Bytes 6-7:  channel_load_long (BE u16, /100 = percent)

CMD_STAT_PHYPRM (0x26) – Physical Parameters, 12 bytes (single) / 10 bytes (multi):

Bytes 0-1:   symbol_time (BE u16, /1000 = milliseconds)
Bytes 2-3:   symbol_rate (BE u16, baud)
Bytes 4-5:   preamble_symbols (BE u16)
Bytes 6-7:   preamble_time (BE u16, milliseconds)
Bytes 8-9:   csma_slot_time (BE u16, milliseconds)
Bytes 10-11: difs_time (BE u16, milliseconds)  -- ONLY in single-interface

CMD_STAT_CSMA (0x28) – CSMA Parameters, 3 bytes (single-interface only):

Byte 0: contention_window_band
Byte 1: contention_window_min
Byte 2: contention_window_max

CMD_STAT_BAT (0x27) – Battery Status, 2 bytes:

Byte 0: battery_state (0x00=unknown, 0x01=discharging, 0x02=charging, 0x03=charged)
Byte 1: battery_percent (0-100, clamped)

CMD_STAT_TEMP (0x29) – CPU Temperature, 1 byte:

Byte 0: temperature + 120 (actual temp = value - 120 Celsius)
Valid range: -30 to +90 Celsius

1.5 Flow Control

The RNode protocol implements software flow control via the CMD_READY mechanism:

1. When flow_control=True is configured, the host sets interface_ready = False after sending each packet.
2. The device sends a CMD_READY frame when it has finished transmitting and is ready for the next packet.
3. Upon receiving CMD_READY, the host calls process_queue():
   • If packets are queued, pops the first one and sends it.
   • If no packets are queued, sets interface_ready = True.
4. If interface_ready is False when process_outgoing() is called, the packet is appended to packet_queue instead of being sent immediately.

When flow_control=False (the default), interface_ready starts True and is never set to False by the host. The CMD_READY frames from the device still trigger process_queue(), which is a no-op if the queue is empty.

The packet queue is a simple FIFO list with no maximum size and no priority. Overflow is not explicitly handled.

2. Radio Configuration

2.1 Parameters and Encoding

Frequency (CMD_FREQUENCY, 0x01)

• 4 bytes, big-endian unsigned integer
• Unit: Hertz
• Example: 868.0 MHz = 0x33B13B40
• Encoding: [freq >> 24, (freq >> 16) & 0xFF, (freq >> 8) & 0xFF, freq & 0xFF]
• KISS-escaped after encoding

Bandwidth (CMD_BANDWIDTH, 0x02)

• 4 bytes, big-endian unsigned integer
• Unit: Hertz
• Encoding identical to frequency
• Valid range: 7,800 Hz to 1,625,000 Hz

TX Power (CMD_TXPOWER, 0x03)

• 1 byte, unsigned for single-interface (0-37 dBm)
• 1 byte, signed for multi-interface (-9 to +37 dBm). Encoded as txpower.to_bytes(1, signed=True) on send; decoded as byte - 256 if byte > 127 else byte on receive.
• Unit: dBm

Spreading Factor (CMD_SF, 0x04)

• 1 byte, unsigned
• Valid range: 5-12

Coding Rate (CMD_CR, 0x05)

• 1 byte, unsigned
• Valid range: 5-8
• Represents 4/5 through 4/8

Short-term Airtime Limit (CMD_ST_ALOCK, 0x0B)

• 2 bytes, big-endian unsigned integer
• Encoding: int(percent * 100) – so 50.0% becomes 5000
• KISS-escaped after encoding

Long-term Airtime Limit (CMD_LT_ALOCK, 0x0C)

• Same encoding as ST_ALOCK

Radio State (CMD_RADIO_STATE, 0x06)

• 1 byte
• 0x00 = OFF, 0x01 = ON, 0xFF = ASK (query current state)

2.2 Hardware Variants

The Python code identifies devices by platform and MCU:

Platforms:

Radio chips (Multi-Interface only):

Frequency validation:

• Single-interface: 137 MHz to 3 GHz (broad range, device validates further)
• Multi-interface SX127X/SX126X: 137 MHz to 1 GHz
• Multi-interface SX128X: 2.2 GHz to 2.6 GHz

Hardware MTU: Fixed at 508 bytes for all RNode variants.

2.3 Firmware Detection

The host queries firmware version as part of the detect sequence:

FEND CMD_FW_VERSION 0x00 FEND

Response is 2 KISS-escaped bytes: [major, minor].

Required minimum versions:

• RNodeInterface (single radio): 1.52
• RNodeMultiInterface (multi radio): 1.74

If firmware is below minimum, Python calls RNS.panic() with instructions to update via rnodeconf.

Validation logic:

if maj_version > REQUIRED_MAJ:
    firmware_ok = True
elif maj_version >= REQUIRED_MAJ and min_version >= REQUIRED_MIN:
    firmware_ok = True

2.4 Transport Variants: USB, TCP, BLE

The RNode can be accessed over three transport types. The serial protocol is identical over all three; only the physical transport differs.

USB Serial (default)

• Baud: 115200, 8N1
• Uses pyserial Serial object directly
• Read timeout: 100ms
• Detect wait: 200ms

TCP (port specified as tcp://hostname)

• Port: 7633 (TCPConnection.TARGET_PORT)
• Uses raw TCP socket with TCP_NODELAY
• Has keepalive mechanism: sends detect command every 3.5s (ACTIVITY_KEEPALIVE = ACTIVITY_TIMEOUT - 2.5 = 3.5s)
• Read timeout: 1500ms
• Detect wait: 5.0s
• TCP keepalive probes: every 2s, after 5s idle, 12 probes, 24s user timeout

BLE (port specified as ble:// or ble://name or ble://AA:BB:CC:DD:EE:FF)

• Uses Nordic UART Service (NUS) over BLE GATT:
  • Service: 6E400001-B5A3-F393-E0A9-E50E24DCCA9E
  • RX Char: 6E400002-B5A3-F393-E0A9-E50E24DCCA9E (host writes to device)
  • TX Char: 6E400003-B5A3-F393-E0A9-E50E24DCCA9E (device notifies host)
• Requires device to be bonded (paired)
• Read timeout: 1250ms
• Detect wait: 5.0s
• Uses bleak Python library for BLE access
• Write chunk size limited to max_write_without_response_size

3. Medium Access

3.1 CSMA/CA

CSMA is handled entirely by the RNode firmware, not the host.

The host has no CSMA logic. It simply sends packets to the device. The device reports its CSMA parameters back to the host for informational/ monitoring purposes via:

• CMD_STAT_PHYPRM (0x26): symbol time, symbol rate, preamble symbols, preamble time, CSMA slot time, DIFS time
• CMD_STAT_CSMA (0x28): contention window band, min, max

The host stores these values but does not use them for transmission decisions. All carrier sensing, backoff, and collision avoidance is performed by the RNode firmware.

3.2 Airtime Calculation

On-air bitrate calculation (host-side, for capacity planning):

bitrate = sf * (4.0 / cr) / (2**sf / (bandwidth/1000)) * 1000

Where:

• sf = spreading factor (5-12)
• cr = coding rate (5-8, representing 4/5 through 4/8)
• bandwidth = channel bandwidth in Hz

This gives the effective data rate in bits per second.

Channel utilization (device-reported):

The device periodically sends CMD_STAT_CHTM with:

• r_airtime_short: Short-term airtime percentage (own TX)
• r_airtime_long: Long-term airtime percentage (own TX)
• r_channel_load_short: Short-term channel load (all observed activity)
• r_channel_load_long: Long-term channel load (all observed activity)

The host does NOT compute channel utilization itself. It relies entirely on the device’s reporting.

Airtime limiting:

If configured, the host sends airtime limits to the device:

• CMD_ST_ALOCK: Short-term airtime limit percentage
• CMD_LT_ALOCK: Long-term airtime limit percentage

The device enforces these limits in firmware.

3.3 Timing and Jitter

The RNode interface applies NO send-side jitter or timing delays.

Unlike Transport’s PATHFINDER_RW (0.5s random window for announce rebroadcasts), the RNode interface has no equivalent jitter mechanism. All timing is either:

1. Device-side CSMA (carrier sensing in firmware)
2. Transport-layer announce scheduling (handled by Transport, not the interface)
3. Announce rate cap (in base Interface class, based on bitrate):

   tx_time = (len(packet) * 8) / self.bitrate
   wait_time = tx_time / announce_cap
   

   Default announce_cap = 2% of interface bandwidth.

The 80ms sleep in the read loop idle path is purely to prevent busy-waiting when no data is available, not a timing mechanism.

Callsign beaconing:

If id_interval and id_callsign are configured, the interface periodically transmits the callsign as raw packet data (not a Reticulum packet). The timer resets on each TX. The first_tx timestamp records when the first actual (non-callsign) packet was transmitted.

4. Queue Management

4.1 TX Pipeline

process_outgoing(data)
    |
    |-- Is interface online?
    |   No -> drop silently
    |
    |-- Is interface_ready?
    |   No -> queue(data) -> append to self.packet_queue
    |   Yes:
    |       |-- If flow_control: set interface_ready = False
    |       |-- KISS-escape the data
    |       |-- Build frame: FEND + CMD_DATA(0x00) + escaped_data + FEND
    |       |-- serial.write(frame)
    |       |-- Increment txb counter

Key observations:

• packet_queue is an unbounded Python list (no max size)
• FIFO ordering, no priority
• interface_ready starts as False, set to True only after successful device configuration (in configure_device)
• With flow_control=False (default), interface_ready is always True once online, so the queue is never used
• With flow_control=True, the queue drains one packet at a time via CMD_READY callbacks

4.2 RX Pipeline

readLoop() [background thread]
    |
    |-- Read 1 byte from serial
    |-- Parse KISS frame state machine:
    |   |-- FEND: start new frame, reset command
    |   |-- First byte after FEND: set as command byte
    |   |-- CMD_DATA (0x00): accumulate into data_buffer with KISS unescaping
    |   |-- CMD_* (config): accumulate into command_buffer, parse when complete
    |   |-- FEND while in CMD_DATA frame: frame complete
    |
    |-- On complete CMD_DATA frame:
    |   process_incoming(data_buffer)
    |       |-- Increment rxb counter
    |       |-- self.owner.inbound(data, self)  [delivers to Transport]
    |       |-- Clear r_stat_rssi and r_stat_snr
    |
    |-- On complete CMD_* frame:
    |   Parse and store in corresponding r_* fields
    |
    |-- Timeout handling:
    |   If partial frame and no data for > self.timeout ms:
    |       Clear buffer, reset state machine

Buffer size limit: self.HW_MTU (508 bytes). If data_buffer reaches this size, additional bytes are silently dropped until the next FEND.

4.3 Threading Model

Single-interface (RNodeInterface):

Main thread:                Read loop thread:
    |                           |
    configure_device() -->  readLoop() [daemon]
    |                           |
    process_outgoing() ----     | <-- serial.read(1)
    setFrequency()    ----     | --> parse KISS frames
    setBandwidth()    ----     | --> update r_* fields
    ...               ----     | --> process_incoming() -> owner.inbound()
                               | --> process_queue() [on CMD_READY]
                               |
                               | [80ms sleep when no data]

Both threads access self.serial (the pyserial object). There is NO explicit locking between the write path (main thread) and the read path (readLoop thread). pyserial’s internal buffering provides some safety, but this is technically a race condition in the Python implementation.

For BLE and TCP transports, separate TX/RX queues with locks are used:

• ble_rx_lock / ble_tx_lock
• tcp_rx_lock / tcp_tx_lock

Multi-interface (RNodeMultiInterface):

Same model, but the read loop dispatches to the correct sub-interface based on CMD_INTn_DATA command bytes. The CMD_SEL_INT command in the read loop updates self.selected_index, which determines which sub-interface receives configuration confirmations.

5. Interface Lifecycle

5.1 INI Configuration

The [[RNode Interface]] section accepts these config keys:

RNodeMultiInterface adds:

Each sub-interface is defined as a nested section with:

5.2 Connection Management

Startup:

1. Validate configuration parameters
2. Open serial port
3. If open succeeds: configure_device (detect, init radio, validate)
4. If open fails: start reconnect_port thread

Reconnection:

• reconnect_port() runs in a loop:
  • Sleep 5 seconds (RECONNECT_WAIT)
  • Try to open port and configure device
  • Repeat until online or detached
• The readLoop also triggers reconnection when it catches an exception (serial port error, device reset, etc.)
• ESP32 devices send CMD_RESET 0xF8 when they reset while online, which the host treats as an error triggering reconnection.

Shutdown (detach):

1. Set self.detached = True
2. Disable external framebuffer
3. Set radio state to OFF
4. Send CMD_LEAVE
5. Close BLE/TCP connections if applicable

Ingress limiting:

RNodeInterface overrides should_ingress_limit() to always return False. This means RNode interfaces never throttle incoming announces at the interface level (Transport still applies its own limiting).

5.3 Statistics

The interface tracks and exposes:

Counters (host-maintained):

• rxb: Total bytes received (incremented in process_incoming)
• txb: Total bytes transmitted (incremented in process_outgoing)

Device-reported:

• r_stat_rx: Total device RX packet count (4-byte)
• r_stat_tx: Total device TX packet count (4-byte)
• r_stat_rssi: Last packet RSSI in dBm (byte - 157)
• r_stat_snr: Last packet SNR in dB (signed_byte * 0.25)
• r_stat_q: Signal quality percentage (computed from SNR and SF)
• r_airtime_short / r_airtime_long: TX airtime percentages
• r_channel_load_short / r_channel_load_long: Channel load percentages
• r_battery_state / r_battery_percent: Battery info
• r_temperature / cpu_temp: CPU temperature in Celsius

Signal quality calculation:

q_snr_min = Q_SNR_MIN_BASE - (sf - 7) * Q_SNR_STEP  # where BASE=-9, STEP=2
q_snr_max = Q_SNR_MAX  # 6
q_snr_span = q_snr_max - q_snr_min
quality = clamp(((snr - q_snr_min) / q_snr_span) * 100, 0, 100)

RSSI decoding: All RSSI values use the same offset: actual_dBm = raw_byte - 157.

6. Physical Device Info

Connected Device

Device:     /dev/ttyACM0
USB Vendor: 1a86 (QinHeng Electronics)
USB Model:  USB Single Serial (55d4)
USB Serial: 5896004228
Driver:     cdc_acm
Symlinks:   /dev/serial/by-id/usb-1a86_USB_Single_Serial_5896004228-if00

Probe Results

Detection:       Successful (DETECT_RESP = 0x46)
Firmware:        1.85
Platform:        ESP32 (0x80)
MCU:             0x81
Battery report:  Received (CMD_STAT_BAT 0x27, state=0x00 unknown, percent=0%)

The device also sent an unsolicited CMD_STAT_BAT frame during the detect sequence, which is expected – the device reports battery status periodically.

The QinHeng Electronics CH340/CH9102 USB-serial chip (VID 1a86, PID 55d4) is commonly used on ESP32 development boards, specifically the Heltec and LilyGO T-Beam variants commonly used for RNode.

7. Implementation Notes for Rust

7.1 What Maps to Our Interface Trait (Send Side)

The outgoing path is straightforward: process_outgoing(data) takes a raw Reticulum packet and wraps it in a KISS frame. This maps to our Interface trait’s send method. The KISS framing (FEND + CMD_DATA + escape + FEND) is a simple transformation.

The flow control queue (interface_ready / packet_queue) is host-side state that should live on the interface struct. When flow_control is enabled, the interface buffers packets until the device signals CMD_READY.

7.2 What Needs Its Own Async Task (Receive Side, Serial I/O)

The Python implementation uses a daemon thread for readLoop(). In our async Rust architecture, this maps to an async task that:

1. Reads bytes from the serial port (async serial I/O)
2. Parses the KISS frame state machine
3. Dispatches complete frames:
   • CMD_DATA -> feed to NodeCore via handle_packet()
   • CMD_STAT_* -> update interface metadata
   • CMD_READY -> trigger queue drain
   • CMD_ERROR -> handle errors

The serial port read should use tokio-serial or similar async serial crate. The KISS deframer runs in the same task (no separate thread needed).

The read loop is the only path that needs to be truly async. All writes (config commands, data packets) can be synchronous or fire-and-forget since there’s no write-side acknowledgment protocol.

7.3 Where Send-Side Jitter Fits

There is no send-side jitter in the RNode interface itself. All timing is handled by:

1. RNode firmware: CSMA/CA with carrier sensing
2. Transport layer: Announce rebroadcast random window (PATHFINDER_RW = 0.5s)
3. Interface base class: Announce rate cap (announce_cap = 2%)

The announce rate cap and queue management from the base Interface class should be implemented in the transport/driver layer, not in the RNode interface itself. The interface is a dumb pipe – it takes packets from the send queue and KISS-frames them to the serial port.

7.4 State the Interface Needs to Maintain

Configuration (set once):

• frequency, bandwidth, txpower, sf, cr
• st_alock, lt_alock
• flow_control flag
• id_callsign, id_interval
• port path, transport type (USB/TCP/BLE)

Device-reported (updated from read loop):

• r_frequency, r_bandwidth, r_txpower, r_sf, r_cr, r_state, r_lock
• r_stat_rssi, r_stat_snr (per-packet, cleared after delivery)
• r_airtime_short, r_airtime_long, r_channel_load_short, r_channel_load_long
• r_symbol_time_ms, r_symbol_rate, r_preamble_symbols, r_preamble_time_ms
• r_csma_slot_time_ms, r_csma_difs_ms
• r_csma_cw_band, r_csma_cw_min, r_csma_cw_max
• r_battery_state, r_battery_percent, r_temperature
• detected, firmware_ok, maj_version, min_version
• platform, mcu, display

Runtime (host-managed):

• online flag
• interface_ready flag (for flow control)
• packet_queue (if flow_control enabled)
• rxb, txb counters
• first_tx timestamp (for callsign beaconing)

7.5 Relationship to Existing KISS Framing in reticulum-core

The existing framing code in reticulum-core/src/framing/hdlc.rs is HDLC framing, NOT KISS framing. They are different protocols.

Key differences:

We need a new framing/kiss.rs module alongside the existing hdlc.rs. The module structure should be:

framing/
    mod.rs       -- re-exports both
    hdlc.rs      -- existing, for TCP
    kiss.rs      -- new, for RNode serial

The KISS module needs:

• Constants: FEND, FESC, TFEND, TFESC
• fn kiss_escape(data: &[u8]) -> Vec<u8>
• fn kiss_frame(cmd: u8, data: &[u8]) -> Vec<u8>
• struct KissDeframer with state machine for parsing incoming bytes (tracking command byte, escape state, buffer)

The KissDeframer should yield (command: u8, data: Vec<u8>) tuples, not raw byte buffers like the HDLC Deframer.

7.6 Is This Standard KISS or a Superset?

It is a KISS superset. Standard KISS TNC protocol (as used in amateur radio) defines:

The framing layer (FEND/FESC/TFEND/TFESC) is identical to standard KISS. The command bytes 0x01-0x06 overlap with standard KISS but have completely different semantics (frequency vs. txdelay, etc.).

This means our KISS framing module should implement the framing layer generically, and the RNode command interpretation should be in a separate module (e.g., interfaces/rnode.rs in reticulum-std).

7.7 Architecture Mapping

reticulum-core/src/framing/kiss.rs    -- KISS framing (FEND/FESC escaping)
                                         Layer 0, no_std compatible
                                         Pure data transformation, no I/O

reticulum-std/src/interfaces/rnode.rs  -- RNode interface implementation
                                         Owns serial port (async I/O)
                                         KISS command interpretation
                                         Radio configuration state machine
                                         Flow control queue management

reticulum-std/src/driver/              -- Existing driver integrates RNode
                                         interface alongside TCP

The KISS framing module belongs in reticulum-core because it’s a pure data transformation (like HDLC). The RNode interface logic belongs in reticulum-std because it performs I/O (serial port access).

7.8 Implementation Priority

For a minimal working RNode interface:

1. KISS framing module (framing/kiss.rs) – escape/unescape, frame/deframe
2. RNode command parser – interpret command bytes and payloads
3. Initialization sequence – detect, query, configure, validate
4. Data path – TX: KISS-frame packets; RX: deframe and deliver
5. Statistics – parse RSSI/SNR/channel stats from device
6. Flow control – CMD_READY queue management
7. Reconnection – handle disconnect/reconnect
8. Multi-interface support – CMD_SEL_INT, CMD_INTn_DATA

BLE and TCP transport support for RNode can be deferred; USB serial is the primary use case.

SX1261/2 Datasheet Reference (Driver Development Extract)

Source: Semtech SX1261/2 Data Sheet, Rev 2.2, DS.SX1261-2.W.APP, December 2024.

This document extracts the sections relevant for SX1262 LoRa driver development. For the complete datasheet, see semtech.com.

8. Digital Interface and Control

The SX1261/2 is controlled via a serial SPI interface and a set of general purpose input/output (DIOs). At least one DIO must be used for IRQ and the BUSY line is mandatory. BUSY indicates that the chip is ready for new command only if this signal is low.

8.1 Reset

A complete “factory reset” can be issued by toggling pin NRESET. It is automatically followed by the standard calibration procedure and any previous context is lost. The pin should be held low for typically 100us for the Reset to happen.

8.2 SPI Interface

The SPI interface uses a synchronous full-duplex protocol: CPOL = 0, CPHA = 0 (Mode 0). Only the slave side is implemented.

• MOSI is generated by the master on the falling edge of SCK and is sampled by the slave on the rising edge of SCK.
• MISO is generated by the slave on the falling edge of SCK.
• A transfer is always started by the NSS pin going low. MISO is high impedance when NSS is high.
• SPI runs on the external SCK clock to allow high speed up to 16 MHz.

SPI Timing Requirements (Table 8-1)

8.2.2 SPI Timing When Leaving Sleep Mode

One way for the chip to leave Sleep mode is to wait for a falling edge of NSS. The delay between the falling edge of NSS and the first rising edge of SCK must take into account the wake-up sequence and the chip initialization. During Sleep mode and the initialization phase, BUSY is set high. Once the chip is in STDBY_RC mode, BUSY goes low and the host can start sending a command. This is also true for startup at battery insertion or after a hard reset.

8.3.1 BUSY Control Line

The BUSY control line indicates the status of the internal state machine. When BUSY is held low, the internal state machine is in idle mode and the radio is ready for a command.

For all “write” commands, BUSY is asserted high after time T_SW. T_SW from NSS rising edge to BUSY rising edge is max 600 ns in all cases.

“Read” commands are handled directly without the internal state machine and BUSY remains low after a read command.

Switching Times (Table 8-2)

8.4 Digital Interface Status versus Chip Modes (Table 8-3)