Reticulum ESP-NOW Mesh

Overview

ESP-NOW based mesh networking firmware for ESP32 microcontrollers, providing Reticulum network connectivity through BLE and UART interfaces. Enables off-grid, encrypted mesh communication using Sideband, Columba, and other Reticulum-compatible applications.

Phone (Sideband)     ESP32 Client       ESP32 Retranslator     ESP32 Client      Phone
     |                   |                    |                    |              |
     |---BLE (KISS)----->|---ESP-NOW v2------->|---ESP-NOW v2------>|---BLE------->|
     |                   |    802.11 LR       |    802.11 LR      |              |
     |<--BLE (KISS)------|<--ESP-NOW v2--------|<--ESP-NOW v2------|<--BLE--------|

Three firmware types work together:

• Client -- BLE bridge between phone and ESP-NOW mesh
• Retranslator -- transport node that routes and relays packets
• RNode UART -- RNode-emulating serial bridge for PC (RNodeInterface, 921600 baud)
• Serial Bridge -- pure HDLC serial bridge for PC (SerialInterface, zero overhead, 921600 baud)

All nodes use ESP-NOW v2.0 with 1470-byte payloads and 802.11 Long Range mode for up to 500m line-of-sight range.

Supported Hardware

ESP32-S3 Retranslator PSRAM Variants

Firmware Types

BLE Client

Bridges a phone running Sideband/Columba (via BLE) to the ESP-NOW mesh. Emulates RNode over Nordic UART Service (NUS) with KISS framing. Phone runs the full Reticulum stack; the device is a transparent radio modem.

Retranslator

Runs the full microReticulum transport stack. Learns paths from announces, rebroadcasts announces, and forwards packets between nodes. Purely infrastructure -- no user-facing messaging capability. Invisible to Sideband/Columba users but extends mesh range.

RNode UART

Same as BLE client but communicates over USB serial at 921600 baud instead of BLE. For connecting a PC or laptop running Reticulum directly via USB cable. No BLE dependency, simpler and more reliable than wireless link.

Quick Start

Prerequisites

• PlatformIO CLI (v6.1+) or VS Code with PlatformIO extension
• USB cable for the target board
• For BLE client: Android phone with Sideband or Columba

Build and Flash

# Build for ESP32-C3 BLE client (default)
pio run -e client_c3

# Flash to connected board
pio run -e client_c3 -t upload

# Flash to specific port
pio run -e client_c3 -t upload --upload-port COM24

# Monitor serial output
pio device monitor

Configuration

All settings are in include/board_config.h:

User Controls

BLE Client

Retranslator

RNode UART

LED flashes on packet activity (TX/RX). Serial port runs KISS protocol at 921600 baud.

BLE Pairing

1. Flash BLE client firmware and power on the board
2. Device advertises as RNode XXXX (XXXX = last 2 bytes of MAC)
3. In Sideband: Settings > Connectivity > enable "Connect via RNode"
4. Hardware > RNode > check "Device requires BLE" > Scan
5. Select the device -- a 6-digit PIN appears on the display
6. Enter PIN on phone -- connection established

To pair with a different phone, hold BOOT for 2+ seconds. This clears existing bonds and restarts advertising.

Host Connection Setup

RNode UART (uart_* firmware)

Add to Reticulum config (~/.reticulum/config):

[[ESP-NOW RNode]]
  type = RNodeInterface
  port = /dev/ttyUSB0    # Linux
  # port = COM11         # Windows
  speed = 921600

Serial Bridge (serial_* firmware)

Add to Reticulum config (~/.reticulum/config):

[[ESP-NOW Bridge]]
  type = SerialInterface
  port = /dev/ttyUSB0    # Linux
  # port = COM11         # Windows
  speed = 921600

Serial Bridge has zero protocol overhead — maximum throughput, no handshake.

Display Screens

SSD1306 OLED (72x40, ESP32-C3)

ST7789 TFT (135x240, T-Display)

Factory Reset

Retranslator only. Hold BOOT button for 5 seconds:

1. NVS data cleared (display preferences, initialization flag)
2. Filesystem formatted (Reticulum identity and learned paths erased)
3. LED turns red during process
4. Device reboots and generates new transport identity

Build Environments

Client (BLE Bridge) -- 5 environments

Retranslator (Transport) -- 9 environments

RNode UART & Serial Bridge -- 6 environments

Performance

Event-Driven Architecture

All firmware types use event-driven main loops instead of busy polling. The CPU sleeps during idle periods and wakes instantly when mesh data arrives:

• BLE Client -- blocks on ESP-NOW RX queue (10ms timeout), 100Hz housekeeping
• RNode UART / Serial Bridge -- same pattern, 10ms timeout for 921600 baud serial
• Retranslator -- blocks on ESPNOWInterface semaphore (50ms timeout)

BLE Throughput Optimization

Real-world BLE throughput with WiFi+BLE coexistence: 30-60 KB/s. This exceeds typical Reticulum traffic requirements.

Known Limitations

• ESP32-C3 retranslator memory -- limited to small networks (up to 20 nodes) due to upstream microReticulum heap management issues under heavy announce traffic. Use ESP32-S3 with PSRAM for larger deployments.
• Transport node auto-reboot -- heap fragmentation from announce processing causes gradual memory loss (~670 bytes/cycle). Node auto-reboots at 40KB threshold (~15-20 days at 30min interval). Identity and paths persist on flash.
• ESP32-S2 -- retranslator and UART only (no BLE hardware).
• ESP32-S3 RGB LED -- the onboard NeoPixel LED on DevKitC boards ships with the solder bridge open by default. Close the pad labeled "RGB" near the LED to enable it. PSRAM works without any modification.

Troubleshooting