microReticulum

The repository provides several sample programs to demonstrate microReticulum usage, categorized by build system and transport type.

Native Examples (CMake)

• udp_transport: UDP-based transport node.
• udp_announce: UDP announce example.
• link_native: Link establishment over a native interface.
• nomadnet: NomadNet-style application example.

Note: The CMake build also produces a shared helper library udp_interface located in examples/common/udp_interface/ used by UDP examples and interop senders.

LoRa Examples (PlatformIO)

• lora_transport/: LoRa radio transport node.
• lora_announce/: LoRa announce example.
• lora_transport_internalfs_override/: LoRa transport with InternalFS persistence override.

When building a client for the microReticulum Provisioning subsystem, keep the following transport constraints in mind:

• MsgPack Framing: Every request and response is a single, complete MsgPack-encoded Bytes blob. The library does not support chunking or streaming; you must receive the full response before proceeding.
• Synchronous Execution: The firmware-side implementation is synchronous and reentrant-unsafe. Clients must serialize requests; do not attempt to have multiple parallel in-flight operations to the same device.
• Endianness: The protocol is little-endian-agnostic because MsgPack handles multi-byte encoding.
• Security: There is no built-in authentication or encryption at this layer. Security must be implemented in the transport layer (e.g., TLS, encrypted BLE, etc.) that wraps these MsgPack frames.

The GET_INFO operation returns a SchemaVersion key. Clients should check this version to determine how to parse the GET_SCHEMA response layout.

Current Version: 2

Compatibility Tip: A v1-compatible client can still process v2 responses by reading only the first three elements of the namespace array (id, name, and fields), effectively treating the schema as a flat list.

When RNS_USE_FS is enabled, namespaces are persisted as MsgPack files.

Persistence Details

• File Path: Namespaces use a dotted path based on their hierarchy (e.g., Interfaces.LoRa.msgpack). Flat namespaces are backward compatible.
• Format: A MsgPack map where keys are field IDs (uint) and values are the typed data.
• Atomicity: Writes are atomic. Data is written to a .tmp file first, then rename()'d over the live file to prevent corruption during power loss.
• Forward Compatibility: Unknown field IDs in a file are silently ignored during loading.
• Exclusions: FF_READ_ONLY and FF_WRITE_ONLY fields are not persisted.
• Security: FF_SECRET fields are persisted to disk. The Provisioning subsystem does not provide encryption-at-rest; users must implement an outer encryption layer if storing sensitive material.

The C++ implementation uses wire-format cross-validation to ensure compatibility with Python Reticulum (e.g., version 1.2.9).

1. Byte-level validation: The C++ unit test test/test_resource_advertisement uses a PYTHON_GOLDEN_HEX byte sequence captured from Python's RNS.Resource.ResourceAdvertisement.pack(). It asserts that ResourceAdvertisement::unpack in C++ correctly parses these bytes and that ResourceAdvertisement::pack in C++ produces the exact same byte sequence.
2. Regenerating golden bytes: If the Python reference's wire format changes, use encode_advertisement.py to regenerate the golden bytes so the C++ test constants can be updated.

All communication follows a strict MsgPack array format consisting of exactly 3 elements:

[ op_id, seq, payload ]

Error Handling Note: In a successful response, the op_id matches the request. If an error occurs, the op_id in the response will be 101 (ERROR). You can recover the original operation ID by checking the seq field in the error response.

// Example Request: [op_id, seq, payload]
[1, 12345, null]

// Example Response: [op_id, seq, payload]
[1, 12345, {"schema": ...}]

To reduce bandwidth, clients can implement a short-circuit cache using the Hash field returned in GET_STATE responses. The hash is a CRC32 of the response body (excluding the hash itself).

How to use it:

1. On a GET_STATE request, include the previously received hash in the PriorHash field of the request envelope.
2. The hash must use the same scope (the same NamespaceFilter and Draft setting).
3. If the server's current state matches the hash, it returns { Unchanged: true } instead of the full payload.

Cache Key Requirements: A cache key must be a combination of (NamespaceFilter, Draft). A hash for Draft: false is not valid for Draft: true.

Invalidation: Discard cached hashes after any SET_STATE, COMMIT, DISCARD, FACTORY_RESET, or REBOOT operations.

# Example logic for cache key
cache_key = (namespace_filter, is_draft)

Native examples (UDP transport, UDP announce, native link establishment, and NomadNet-style applications) can be built using CMake on Linux, macOS, or Raspberry Pi. The CMake target names correspond to the directory names.

To build all native examples at once, use the --target flag with the specific target names. You can also skip building examples entirely during the configuration step if you are building the parent project.

# Configure the build directory
cmake -S . -B build

# Build all native examples
cmake --build build -j --target udp_transport udp_announce link_native nomadnet

# Build a single example
cmake --build build -j --target udp_transport

# Skip building examples during configuration
cmake -S . -B build -DRNS_BUILD_EXAMPLES=OFF