// Reticulum's hardware abstraction layer and interface types. Use when working with RNode, AutoInterface, TCP, UDP, I2P, Serial, KISS, BLE interfaces, interface modes, IFAC, bandwidth allocation, or MTU.
| name | interfaces |
| description | Reticulum's hardware abstraction layer and interface types. Use when working with RNode, AutoInterface, TCP, UDP, I2P, Serial, KISS, BLE interfaces, interface modes, IFAC, bandwidth allocation, or MTU. |
This skill provides knowledge about Reticulum's hardware abstraction layer and interface types. Invoke when the user mentions interface types, RNode, AutoInterface, TCP interface, UDP interface, I2P, Serial, KISS, Pipe, Local, Weave, Backbone, interface modes, IFAC (Interface Access Code), announce propagation, bandwidth allocation, or MTU.
Reticulum implements a flexible hardware abstraction layer that allows communication over virtually any medium. The interface system handles physical layer details while presenting a uniform API to the transport layer.
Key principle: Interfaces are the only part of Reticulum that need to know about physical medium characteristics. Everything above the interface layer is hardware-agnostic.
Reticulum includes 15+ built-in interface types:
RNodeInterface: Hardware interface for RNode LoRa devices - open-source, general-purpose data radios.
Properties:
Use cases: Off-grid mesh networking, long-range point-to-point links, disaster communications
RNodeMultiInterface: Manages multiple RNode sub-interfaces for frequency diversity and channel bonding.
AutoInterface: Zero-configuration local network discovery and communication over Ethernet/WiFi.
Properties:
Use cases: LAN mesh networking, automatic peer discovery, zero-config local communication
TCPClientInterface: Connects to remote TCP server, establishing persistent connection.
TCPServerInterface: Listens for incoming TCP connections, spawning interface per client.
Properties:
Use cases: Internet backbone connectivity, connecting to public nodes, WAN bridges
UDPInterface: Connectionless UDP-based interface for specific remote endpoints.
Properties:
Use cases: Low-latency links, controlled network segments, testing
I2PInterface: Anonymous networking via the Invisible Internet Project.
Properties:
Use cases: Censorship resistance, privacy-critical applications, anonymous mesh networking
SerialInterface: Direct serial port communication (RS-232, USB serial, etc.).
Properties:
Use cases: Direct device connections, legacy hardware integration, physical point-to-point links
KISSInterface: Serial interface using KISS protocol framing for radio modems.
AX25KISSInterface: KISS interface with AX.25 (amateur packet radio) support.
Properties:
Use cases: Amateur radio packet networks, hardware TNC integration, legacy radio modems
PipeInterface: Bidirectional communication through Unix pipes or external programs.
Properties:
Use cases: Custom transport scripts, integration with external tools, testing and development
LocalInterface: Unix socket-based inter-process communication on same machine.
Properties:
Use cases: Multi-process applications, local service integration, development/testing
WeaveInterface: Advanced interface type for creating resilient multi-path networks.
Properties:
Use cases: High-availability links, multi-homed connectivity, resilient backbone connections
BackboneInterface: High-speed backbone networking over IP networks (designed for Yggdrasil and similar).
Properties:
Use cases: Yggdrasil backbone links, high-speed overlay networks, regional/global connectivity
All interfaces support optional mode setting that affects announce propagation, path discovery, and path expiration:
Behavior: All discovery, meshing, and transport functionality active.
Announce propagation: Accepts announces from all modes, propagates to Full, Boundary, and Roaming interfaces.
Path expiration: Standard (7 days / PATHFINDER_E)
Use case: Default for most interfaces, general mesh participation
Behavior: Dedicated point-to-point link between two nodes.
Announce propagation: Same as Full mode.
Use case: Direct connections between two specific nodes, dedicated radio links, serial links
Behavior: Same as Full, plus actively discovers unknown paths on behalf of clients.
Announce propagation: Same as Full mode.
Path discovery: When receiving path request for unknown destination from gateway interface, attempts discovery via all other interfaces and forwards discovered path back to requestor.
Use case: Interface facing clients that need wide path resolution (e.g., client-facing WiFi interface while uplink is on another interface)
Important: Gateway mode goes on the client-facing interface, not the uplink.
Behavior: Network access point for transient clients.
Announce propagation: Does NOT accept announces from other APs or Roaming interfaces. Propagates to Full, Boundary, and Roaming interfaces only.
Path expiration: Short (1 day / AP_PATH_TIME)
Characteristics:
Use case: Public LoRa hotspots, wide-area radio access points with transient users
Behavior: Physically mobile interface from network's perspective.
Announce propagation: Accepts announces from Full and Boundary only. Does NOT propagate announces to any other interfaces (leaf mode).
Path expiration: Very short (6 hours / ROAMING_PATH_TIME)
Use case: Mobile vehicle external interface, while internal interfaces serve devices moving WITH the vehicle
Example: Vehicle with external LoRa (roaming mode) and internal WiFi (full mode). Internal devices reach each other and LoRa-side devices when in range; LoRa-side reaches internal devices when vehicle is in range.
Behavior: Connects significantly different network segments.
Announce propagation: Accepts announces from Full, AP, Boundary, and Roaming. Propagates to Full and Boundary only.
Path expiration: Standard (7 days)
Use case: Interface connecting different network types (e.g., local LoRa mesh + high-speed Internet backbone)
Example: LoRa mesh node with Internet connection - set Internet-facing interface to Boundary mode.
The following rules govern automatic announce forwarding between interface modes:
From Full interface → Propagates to: Full, Boundary, Roaming (not AP)
From Gateway interface → Same as Full mode
From Access Point interface → Propagates to: Full, Boundary, Roaming (not other APs)
From Roaming interface → Propagates to: Full, Boundary (not AP, not other Roaming)
From Boundary interface → Propagates to: Full, Boundary (not AP, not Roaming)
Receiving side:
This creates a hierarchical propagation graph that prevents announce flooding while ensuring reachability.
IFAC enables named virtual networks and passphrase-protected interfaces. Packets without valid IFAC are silently dropped.
IFAC generation:
ifac_netname (network name) and/or ifac_netkey (passphrase)Full_Hash(network_name) + Full_Hash(passphrase)HKDF(SHA-256(ifac_origin), salt=IFAC_SALT, length=64)Identity.from_bytes(ifac_key)ifac_size (1-64 bytes)IFAC verification:
IFAC size: Configurable from 8 to 512 bits in config (1 to 64 bytes). Default varies by interface type:
Smaller IFAC = lower overhead but higher collision probability. Larger IFAC = stronger authentication but more bandwidth.
Constants:
IFAC_MIN_SIZE = 1 # Minimum IFAC size in bytes
IFAC_SALT = bytes.fromhex("adf54d882c9a9b80...") # Fixed salt for IFAC derivation
[[Private LoRa Network]]
type = RNodeInterface
port = /dev/ttyUSB0
# Create isolated virtual network
ifac_netname = private_mesh
ifac_netkey = correct_horse_battery_staple
ifac_size = 64 # 64 bits = 8 bytes
Only interfaces with matching netname+netkey can communicate. Others see encrypted garbage or invalid signatures.
The announce_cap option controls maximum bandwidth allocated to announce propagation and network maintenance at any given time.
Default: 2% (ANNOUNCE_CAP = 2)
Range: 1-100 (percentage of interface bandwidth)
Behavior:
Per-interface configuration:
[[High Speed Backbone]]
type = TCPClientInterface
announce_cap = 5 # Allow 5% bandwidth for announces
Calculation:
tx_time = (packet_length_bytes * 8) / interface_bitrate_bps
wait_time = tx_time / (announce_cap / 100.0)
announce_allowed_at = current_time + wait_time
Fine-grained control over announce re-broadcast rate on fast interfaces:
announce_rate_target: Minimum seconds between re-broadcasts of announces for same destination.
3600 = max once per hour per destinationannounce_rate_grace: Number of times destination can announce before rate limiting applied.
announce_rate_penalty: Additional delay after rate limit triggered.
These moderate the rate at which received announces are re-broadcast to other interfaces, independent of announce_cap.
MTU is the maximum packet size an interface can transmit, configurable per-interface.
Default: 500 bytes (Reticulum.MTU = 500)
Calculation chain:
MTU = 500 # Wire MTU (configurable per-interface)
HEADER_MAXSIZE = 2 + 1 + 32 = 35 bytes # Flags + hops + 2x truncated hash
IFAC_MIN_SIZE = 1 byte # Minimum IFAC overhead
MDU (Maximum Data Unit) = MTU - HEADER_MAXSIZE - IFAC_MIN_SIZE
MDU = 500 - 35 - 1 = 464 bytes # Available for payload
# For links (with encryption overhead):
Link.MDU = floor((MTU - IFAC_MIN_SIZE - HEADER_MINSIZE - TOKEN_OVERHEAD) / AES128_BLOCKSIZE) * AES128_BLOCKSIZE - 1
Auto-configuration: Some interfaces (like AutoInterface, TCPClientInterface) support automatic MTU optimization based on detected bitrate:
if bitrate >= 1 Gbps: HW_MTU = 524288
elif bitrate > 750 Mbps: HW_MTU = 262144
elif bitrate > 400 Mbps: HW_MTU = 131072
elif bitrate > 200 Mbps: HW_MTU = 65536
# ... down to ...
elif bitrate <= 62.5 kbps: HW_MTU = None (use default)
Larger MTU = higher throughput but requires all intermediary hops to support it. Link MTU discovery negotiates optimal MTU across multi-hop paths.
Configuration:
[[High Speed Link]]
type = TCPClientInterface
target_host = 10.0.0.1
target_port = 4242
mtu = 16384 # Increase MTU for high-speed link
All interfaces support these common configuration options:
enabled: yes or no - Whether interface is active
mode: Interface mode (full, gateway/gw, access_point/ap, roaming, boundary)
ifac_netname: Virtual network name (string)
ifac_netkey: Virtual network passphrase (string)
ifac_size: IFAC signature size in bits (minimum 8, i.e., 1 byte)
announce_cap: Bandwidth percentage for announces (1-100, default 2)
announce_rate_target: Minimum seconds between re-broadcasts per destination
announce_rate_grace: Number of announces before rate limiting
announce_rate_penalty: Penalty delay after rate limit
mtu: Maximum transmission unit in bytes (default 500)
ingress_control: Enable/disable ingress limiting (default enabled on most interfaces)
All interfaces track basic statistics:
rxb: Bytes received
txb: Bytes transmitted
bitrate: Configured/detected bitrate in bits per second
online: Boolean - interface operational status
HW_MTU: Hardware MTU (may differ from configured MTU)
Statistics accessible via rnstatus utility or programmatically via interface properties.
This skill should activate when users mention:
Reticulum is fully extensible with custom interfaces. Custom interface classes inherit from RNS.Interfaces.Interface and implement:
Required methods:
__init__(): Initialize interfaceprocess_outgoing(data): Send data to physical mediumprocess_incoming(data): Receive data from physical mediumRequired properties:
IN: Boolean - can receiveOUT: Boolean - can transmitbitrate: Interface speed in bpsOptional:
mode: Interface mode constantannounce_cap: Bandwidth allocation overrideSee RNS/Interfaces/Interface.py for base class and implementation details.
Some interface types (AutoInterface, TCPServerInterface, I2PInterface, WeaveInterface, BackboneInterface) spawn child interfaces dynamically:
Example: TCPServerInterface spawns TCPClientInterface for each incoming connection. Each client connection is a separate interface in the transport layer.
See implementation files:
https://github.com/markqvist/Reticulum/RNS/Interfaces/Interface.py - Base interface classhttps://github.com/markqvist/Reticulum/RNS/Interfaces/RNodeInterface.py - RNode implementationhttps://github.com/markqvist/Reticulum/RNS/Interfaces/AutoInterface.py - AutoInterface implementationhttps://github.com/markqvist/Reticulum/RNS/Interfaces/TCPInterface.py - TCP client/serverhttps://github.com/markqvist/Reticulum/RNS/Interfaces/I2PInterface.py - I2P implementationhttps://github.com/markqvist/Reticulum/RNS/Transport.py - IFAC calculation and verification (lines 795-830)https://github.com/markqvist/Reticulum/docs/source/interfaces.rst - Interface configuration documentationhttps://github.com/markqvist/Reticulum/docs/source/understanding.rst - Lines 677-694 (IFAC), 834-867 (announce propagation)Reticulum's cryptographic primitives, identity structure, encryption tokens, and key derivation. Use when working with Ed25519, X25519, identity hashes, HKDF, token format, encryption, signatures, ratchets, or key derivation.
Reticulum's addressing system and destination types. Use when working with destination types (SINGLE, GROUP, PLAIN, LINK), destination hashes, aspect naming, or addressing.
Reticulum's link system — encrypted channels with forward secrecy. Use when working with link establishment, link requests, ECDH, ephemeral keys, forward secrecy, channels, keep-alive, or link timeouts.
Reticulum's packet structure and wire format. Use when working with packet headers, MTU/MDU, packet types, header types (HEADER_1/HEADER_2), packet context flags, IFAC, or binary packet encoding.
Detailed knowledge of Reticulum's announce mechanism for automatic path discovery. Use when working with announce propagation, path discovery, announce bandwidth, announce forwarding, path requests, or announce structure.
Reticulum's resource transfer system for large data over links. Use when working with resource transfers, windowing, hashmaps, segments, compression, file transfers, or resource states.