Skip to content

Societus/myriadmesh-node

BranchesTags

Repository files navigation

MyriadMesh Node

Lightweight application for edge deployment with multi-adapter support

The node component enables MyriadMesh connectivity on edge devices, embedded systems, and resource-constrained hardware. It provides flexible deployment modes from pure relay nodes to fully-featured mesh routers.

Overview

MyriadMesh Node is a minimal, efficient application designed for deployment on:

  • Raspberry Pi and single-board computers
  • Embedded Linux devices
  • Low-power microcontroller platforms
  • Edge IoT gateways
  • Remote/offline communication nodes

The node provides:

  • Multiple deployment modes (relay, minimal, full)
  • 13 network adapters (Bluetooth, LoRa, WiFi HaLoW, Cellular, Radio, etc.)
  • Intelligent routing with automatic failover
  • Store-and-forward messaging for offline resilience
  • Lightweight footprint (as small as 8 MB in relay mode)

Deployment Modes

1. Relay Mode (Pure Traffic Forwarding)

Perfect for: IoT edge devices, bandwidth-constrained nodes

Characteristics:

  • Pure packet relay (no routing decisions)
  • Minimal memory footprint (~32 MB RAM)
  • Smallest binary (~8 MB)
  • No local state management
  • Just forwards packets between adapters

Use cases:

  • WiFi repeater for mesh network
  • LoRa relay between distant nodes
  • Bridge between different network types
  • Very low-power devices

Build:

cargo build --bin myriadnode --release --no-default-features --features relay-mode

2. Minimal Mode (Lightweight Node)

Perfect for: Embedded nodes, devices with limited resources, nodes that reach a server

Characteristics:

  • Limited adapter set (Bluetooth LE, LoRa, WiFi)
  • Local message routing
  • Can reach and communicate with full servers
  • ~128 MB RAM typical
  • ~32 MB binary
  • Operates standalone or integrated with servers

Use cases:

  • Mesh network node on IoT devices
  • Mobile device background service
  • Embedded Linux gateway
  • Field deployment with server reach-back

Build:

cargo build --bin myriadnode --release --features minimal-mode

3. Full Mode (Complete Node)

Perfect for: Primary nodes, high-powered devices, server integration

Characteristics:

  • All adapters enabled (Ethernet, Cellular, Radio, etc.)
  • Full routing capabilities
  • Can act as relay hub
  • ~512 MB RAM typical
  • ~64 MB binary
  • Complete feature set

Use cases:

  • Primary mesh hub
  • Server-grade node
  • Powerful hardware deployment
  • Carrier-class infrastructure

Build:

cargo build --bin myriadnode --release --features node-mode

Repository Structure

myriadmesh-node/
├── Cargo.toml                 Workspace root
├── README.md                  This file
├── DEPLOYMENT.md              Deployment guide
├── GETTING_STARTED.md         Quick start guide
├── crates/
│   ├── myriadmesh-network/    Network adapter layer
│   │   ├── Cargo.toml
│   │   ├── src/
│   │   │   ├── lib.rs
│   │   │   ├── adapter.rs     NetworkAdapter trait
│   │   │   ├── manager.rs     Adapter discovery/management
│   │   │   ├── types.rs       Common types
│   │   │   ├── metrics.rs     Performance metrics
│   │   │   └── adapters/      13 network adapters
│   │   │       ├── bluetooth.rs
│   │   │       ├── bluetooth_le.rs
│   │   │       ├── lora.rs
│   │   │       ├── cellular.rs
│   │   │       ├── wifi_halow.rs
│   │   │       ├── ethernet.rs
│   │   │       ├── hf_radio.rs
│   │   │       ├── frsgmrs.rs
│   │   │       ├── aprs.rs
│   │   │       ├── dialup.rs
│   │   │       └── ... (more adapters)
│   │   └── tests/
│   │
│   └── myriadmesh-i2p/        Privacy layer
│       ├── Cargo.toml
│       ├── src/
│       │   ├── lib.rs
│       │   ├── adapter.rs     i2p network adapter
│       │   ├── dual_identity.rs
│       │   ├── capability_token.rs
│       │   └── ...
│       └── tests/
│
├── myriadnode-minimal/        Minimal node binary
│   ├── Cargo.toml
│   ├── src/
│   │   ├── main.rs            Entry point with CLI
│   │   ├── config.rs          Configuration management
│   │   ├── deployment.rs      Deployment mode handling
│   │   └── relay.rs           Pure relay functionality
│   ├── examples/
│   │   ├── relay-mode.rs      Relay mode example
│   │   ├── minimal-mode.rs    Minimal mode example
│   │   └── node-mode.rs       Full node mode example
│   └── tests/
│       ├── integration_relay.rs
│       ├── integration_node.rs
│       └── ...
│
├── docs/
│   ├── ARCHITECTURE.md        Node architecture
│   ├── ADAPTERS.md           Adapter implementation guide
│   ├── CONFIGURATION.md      Config file reference
│   ├── DEPLOYMENT.md         Production deployment
│   └── TROUBLESHOOTING.md    Common issues and solutions
│
├── examples/
│   ├── raspberry-pi/         Raspberry Pi setup
│   ├── docker/               Docker deployment
│   └── embedded/             Embedded device setup
│
└── tests/
    ├── e2e_relay.rs          End-to-end relay tests
    ├── e2e_routing.rs        End-to-end routing tests
    └── adapter_tests.rs      Adapter integration tests

Network Adapters

The node supports 13 diverse network types:

Short-Range Personal Area Networks

  • Bluetooth Classic (bluetooth.rs) - BR/EDR, RFCOMM, ~100m range
  • Bluetooth Low Energy (bluetooth_le.rs) - Power-efficient, mesh-capable
  • Dial-up (dialup.rs) - Legacy modem support (Hayes AT, PPP)

Wireless Local Area Networks

  • Ethernet (ethernet.rs) - Wired TCP/IP connectivity
  • WiFi HaLoW (wifi_halow.rs) - 802.11ah, long-range, low-power
  • System Socket (system_socket.rs) - Generic socket transport

Cellular Networks

  • Cellular (cellular.rs) - 4G/LTE/5G mobile networks

Low-Power Wide Area Networks

  • LoRa (lora.rs) - LoRaWAN, Meshtastic relay, 15km+ range, low power
  • i2p (via myriadmesh-i2p) - Privacy-preserving overlay network

Radio Frequency

  • HF Radio (hf_radio.rs) - Shortwave, long-distance communication
  • FRS/GMRS (frsgmrs.rs) - Family/General Mobile Radio Service
  • APRS (aprs.rs) - Amateur Packet Radio System (ham radio)

Windows Platform

  • Windows (windows.rs) - Windows-specific networking (IOCP)

Feature Flags

Adapter Features

Control which adapters are included in the binary:

[features]
# Individual adapters
bluetooth = []
bluetooth-le = []
lora = []
cellular = []
wifi-halow = []
ethernet = []
hf-radio = []
frsgmrs = []
aprs = []
dialup = []
i2p = ["myriadmesh-i2p"]

# Feature groups
embedded = ["bluetooth-le", "lora"]           # Minimal for embedded
full = ["ethernet", "bluetooth", "cellular", "wifi-halow", "i2p"]  # All adapters

Build Examples

# Minimal relay
cargo build --release --no-default-features --features relay-mode

# Embedded with Bluetooth and LoRa
cargo build --release --features "minimal-mode,bluetooth-le,lora"

# Full node with all adapters
cargo build --release --features "node-mode,full"

# LoRa-only node
cargo build --release --features "lora"

Installation

Prerequisites

# Ubuntu/Debian
sudo apt-get install libsodium-dev libssl-dev pkg-config

# macOS
brew install libsodium openssl

# Fedora
sudo dnf install libsodium-devel openssl-devel

# Alpine
apk add libsodium-dev openssl-dev pkgconfig

From Source

git clone https://github.com/myriadmesh/node.git
cd myriadmesh-node

# Build minimal relay
cargo install --path myriadnode-minimal --release --no-default-features --features relay-mode

# Or build full node
cargo install --path myriadnode-minimal --release

Quick Start

# Start relay node
myriadnode --mode=relay

# Start minimal node
myriadnode --mode=minimal --config config.toml

# Start full node
myriadnode --mode=node --config config.toml

Configuration

Create config.toml:

[node]
node_id = "auto"  # Auto-generate or specify
data_dir = "./data"

[network]
listen_address = "0.0.0.0"
listen_port = 8900

# Enable specific adapters
adapters = [
    "bluetooth-le",
    "lora",
    "ethernet"
]

[logging]
level = "info"
format = "json"

[security]
# Enable i2p for privacy
i2p_enabled = true
i2p_tunnel_length = 3

[performance]
# Routing cache size
route_cache_size = 1000

# Message queue depth
message_queue_depth = 10000

# Maximum fragment size per adapter
max_fragment_size = 1024

Deployment Guide

Raspberry Pi 3/4

# Install OS
# (Use Raspberry Pi Imager or manual installation)

# Install dependencies
sudo apt-get update
sudo apt-get install libsodium-dev libssl-dev pkg-config

# Build for ARM
cargo build --release --target armv7-unknown-linux-gnueabihf

# Copy binary
scp target/armv7-unknown-linux-gnueabihf/release/myriadnode pi@raspberrypi:/home/pi/

# Run with systemd
sudo cp myriadnode.service /etc/systemd/system/
sudo systemctl enable myriadnode
sudo systemctl start myriadnode

Docker

# Build image
docker build -f Dockerfile -t myriadmesh/node:latest .

# Run container
docker run -d \
  --name myriad-node \
  -p 8900:8900 \
  -v /data/myriad:/root/.myriad \
  myriadmesh/node:latest \
  --mode=minimal

Embedded Linux

# Cross-compile for embedded target
cargo build --release --target aarch64-unknown-linux-musl

# Static binary with minimal dependencies
RUSTFLAGS="-C link-arg=-static" cargo build --release

Development

Building

# Build all crates
cargo build --release

# Build specific deployment mode
cargo build --release --features minimal-mode

# Cross-compile
cross build --release --target armv7-unknown-linux-gnueabihf

Testing

# Run unit tests
cargo test --release

# Run integration tests
cargo test --release -- --test-threads=1

# Test specific adapter
cargo test --test adapter_tests --features lora

# Test with logging
RUST_LOG=debug cargo test --release -- --nocapture

Debugging

# Enable debug logging
RUST_LOG=myriad_node=debug ./target/debug/myriadnode --mode=relay

# Run with gdb
rust-gdb ./target/debug/myriadnode

# Memory profiling
valgrind --tool=massif ./target/release/myriadnode --mode=relay

Performance Targets

Metric Relay Mode Minimal Mode Full Mode
Memory (RSS) 32 MB 128 MB 512 MB
Binary size 8 MB 32 MB 64 MB
Message throughput 1000+ msg/s 500+ msg/s 200+ msg/s
Latency (p99) <10ms 50ms 100ms
CPU usage <5% (idle) 10-20% 20-30%

Adapter Implementation Guide

To add a new adapter:

  1. Implement NetworkAdapter trait (adapters/your_adapter.rs):
pub struct YourAdapter { /* ... */ }

#[async_trait]
impl NetworkAdapter for YourAdapter {
    async fn send(&mut self, dest: &NodeId, data: &[u8]) -> Result<()> { /* ... */ }
    async fn receive(&mut self) -> Result<Frame> { /* ... */ }
    // ... other trait methods
}
  1. Register in AdapterManager (manager.rs):
fn create_adapter(&self, adapter_type: &str) -> Result<Box<dyn NetworkAdapter>> {
    match adapter_type {
        "your-adapter" => Ok(Box::new(YourAdapter::new()?)),
        // ...
    }
}

  1. Add tests (adapters/tests/your_adapter_tests.rs)

  2. Document in docs/ADAPTERS.md

  3. Add feature flag to Cargo.toml

Troubleshooting

High Memory Usage

  • Reduce message_queue_depth in config
  • Disable unused adapters
  • Use relay mode instead of full node

Slow Routing

  • Check DHT network connectivity
  • Review adapter metrics
  • Increase route_cache_size

Adapter Not Working

  • Check adapter logs with RUST_LOG=debug
  • Verify adapter hardware is connected
  • Test adapter directly with examples/test_adapter.rs

See TROUBLESHOOTING.md for more.

Monitoring

Health Checks

# Check node status
curl http://localhost:8900/api/status

# Get adapter metrics
curl http://localhost:8900/api/adapters

# View message queue depth
curl http://localhost:8900/api/metrics

Logging

# View logs
journalctl -u myriadnode -f

# Export logs
journalctl -u myriadnode --output=json > logs.json

Roadmap

Short-term (1-2 months)

  • Optimize LoRa adapter for low power
  • Add NB-IoT cellular adapter
  • Improve Bluetooth mesh support

Medium-term (2-4 months)

  • Hardware acceleration for crypto
  • Satellite connectivity adapter
  • Mesh network auto-provisioning

Long-term (6+ months)

  • Quantum-resistant encryption option
  • Multi-core parallel routing
  • 5G SA support

Contributing

See CONTRIBUTING.md in the main repository.

License

Licensed under GPL-3.0-only.

Support

  • Documentation: See docs/ directory
  • Issues: GitHub Issues
  • Getting Started: GETTING_STARTED.md
  • Community: Discord/Matrix

Development Roadmap

See ROADMAP.md for detailed timeline and work items.

Current Phase: Adapter Implementation (6-9 weeks)

Critical Path:

  1. [NOW] UDP adapter (1 week) - BLOCKS basic networking
  2. I2P adapter SAM integration (2-3 weeks) - Privacy layer
  3. Node.start() implementation (1 week) - Depends on adapters
  4. Physical radio adapters (4-6 weeks) - LoRa, Cellular, APRS
  5. Deployment modes & optimization (2-3 weeks) - Embedded support

Key Deliverables:

  • UDP adapter with NAT traversal (Week 1)
  • I2P adapter with SAM protocol (Weeks 2-3)
  • Adapter manager integration (Week 3)
  • Node bootstrap and message routing (Week 4)
  • LoRa, Cellular, APRS adapters (Weeks 5-8)
  • Deployment modes: relay, minimal, full (Week 8)
  • Raspberry Pi optimization (Week 9)

Blocked by:

  • Core team: DHT queries, Router integration needed for node.start()

Blocks:

  • Server team: Cannot transmit messages without adapters

Repository: https://github.com/myriadmesh/node Crates.io: https://crates.io/crates/myriadmesh-network, myriadmesh-i2p

About

No description, website, or topics provided.

Resources

Readme

License

View license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages