microReticulum

Port of Reticulum Network Stack to C++ specifically but not exclusively targeting 32-bit and better MCUs.

Note that this is a library implementing the Reticulum Network Stack and not a useful application on its own. For an actual application, see microReticulum_Firmware which is a version of RNode firmware that implements a Reticulm Transport Node.

Dependencies

Build environment is configured for use in VSCode and PlatformIO.

This API is dependent on the following external libraries:

• rweather/Crypto
• ArduinoJson
• MsgPack

Build Options

• -DRNS_MEM_LOG Used to enable logging of low-level memory operations for debug purposes
• -DRNS_USE_FS Used to enable use of file system by RNS for persistence
• -DRNS_PERSIST_PATHS Used to enable persistence of RNS paths in file system (also requires -DRNS_USE_FS)

Memory Management Build Options

Two classes of memory allocator are defined; the container allocator (RNS_CONTAINER_ALLOCATOR) which is used for certain long-lived STL containers (e.g. path table), and the default allocator (RNS_DEFAULT_ALLOCATOR) which is used for all other C++ memory allocation (new/delete).

Each class of allocator can be configured to use a separate type of allocator. Available memory allocators are:

• RNS_HEAP_ALLOCATOR: Basic allocator that uses default system HEAP.
• RNS_HEAP_POOL_ALLOCATOR: Optimized TLSF managed HEAP buffer
• RNS_PSRAM_ALLOCATOR: Basic allocator that uses PSRAM memory (if PSRAM is available)
• RNS_PSRAM_POOL_ALLOCATOR: Optimized TLSF managed PSRAM buffer (if PSRAM is available)

Each class of allocator pool can have a separate buffer size:

• RNS_HEAP_POOL_BUFFER_SIZE=N Defines the HEAP TLSF memory pool buffer size (N bytes, default 0 which means dynamic)
• RNS_PSRAM_POOL_BUFFER_SIZE=N Defines the PSRAM TLSF memory pool buffer size (N bytes, default 0 which means dynamic)

"POOL" allocators use TLSF (Two-Level Segregate Fit) for efficient management of constrained MCU memory with minimal fragmentation.

The allocator for each class can be configured using build flags in `platformio.ini, for example:

[env]
build_flags = 
  -DRNS_DEFAULT_ALLOCATOR=RNS_HEAP_ALLOCATOR
  -DRNS_CONTAINER_ALLOCATOR=RNS_PSRAM_POOL_ALLOCATOR

NOTE: Currently -DRNS_DEFAULT_ALLOCATOR=RNS_HEAP_POOL_ALLOCATOR is only required on NRF52 boards since ESP32 already uses TLSF internally.

Building

Building and uploading to hardware is simple through the VSCode PlatformIO IDE

• Install VSCode and PlatformIO
• Clone this repo
• Lanch PlatformIO and load repo
• In PlatformIO, select the environment for intended board
• Build, Upload, and Monitor to observe application logging

Instructions for command line builds and building of individual example applications coming soon.

PlatformIO Command Line

Clean all environments (boards):

pio run -t clean

Full Clean (including libdeps) all environments (boards):

pio run -t fullclean

Run unit tests:

pio test
pio test -f test_msgpack
pio test -f test_msgpack -e native
pio test -f test_msgpack -e native17

Build a single environment (board):

pio run -e ttgo-t-beam
pio run -e wiscore_rak4631

Build and upload a single environment (board):

pio run -e ttgo-t-beam -t upload
pio run -e wiscore_rak4631 -t upload

Build and package a single environment (board):

pio run -e ttgo-t-beam -t package
pio run -e wiscore_rak4631 -t package

Build all environments (boards):

pio run

Known Issues

Use of the custom allocator (enabled by -DRNS_USE_ALLOCATOR=1) in conjunction with TLSF (enabled by -DRNS_USE_TLSF=1) is not currently working in ESP32 due to TLFS initialization failure at the time that allocator initialization takes place. This causes the allocator to fallback to using regular malloc/free instead of using TLFS as intended.

Roadmap

• Framework for simple C++ API that mimics Python reference implementation with implicit object sharing
• Utility class to efficiently handle byte buffers
• Implemenmtat basic Identity, Destination and Packet
• Successful testing of Announce mechanism
• Implement Ed2551 public-key signature and X25519 key exchange
• Implement encryption including AES, AES-CBC, HKDF, HMAC, PKCS7, and Fernet
• Successful testing of Packet encrypt/decrypt/sign/prof
• Implement dynamic Interfaces
• Implement UDP Interface for testing against Python reference Reticulum instances
• Implement basic Transport functionality
• Successful testing of end-to-end Path Finding
• Implement persistence for storage of runtime data structures (config, identities, routing tables, etc.)
• Support for Links and Resources in Transport
• Implement Packet proofs
• Successful testing of Transport of both Packets and Links
• Implement memory management appropriate for memory constricted MCUs
• Implement Link
• Implement AES256
• Implement Ratchets
• Implement Resource
• Implement Channel and Buffer
• Add example applications utilizing the C++ API
• Configure PlatformIO to easily build and upload test applications to board
• Add build tagets for all boards currently supported by RNode
• Implement new combination caching/storage manager for managing persistent data

Please open an Issue if you have trouble building ior using the API, and feel free to start a new Discussion for anything else.