Skip to content

Getting Started

Jump to bottom
Amir Nathoo edited this page Jul 13, 2025 · 4 revisions

Development Environment

Installing VSCode

Visual Studio Code is our recommended IDE for development:

  1. Download VSCode from the official website
  2. Install for your operating system (Windows, macOS, or Linux)
  3. Launch VSCode and proceed to installing the required extensions

Installing Extensions

The following extensions are essential for development:

PlatformIO

C++ Development

Optional Extensions

Quick Start Guide

Prerequisites

  • VSCode with PlatformIO installed
  • Two compatible LoRa boards (see Hardware section below)
  • USB cables for programming

Step 1: Setup a Hub Device

The hub device manages the mesh network and handles device inclusion.

cd examples/DeviceInclusion/MiniHub
cp device_info_example.h device_info.h
# Edit device_info.h to set your device ID and radio parameters
../../tools/builder.py build --target local_heltec_wifi_lora_32_V3 --clean --deploy

The hub provides a web admin panel for network management:

  • Connect to the hub's WiFi access point (SSID: "MiniHubAP", Password: "firefly2517")
  • Open http://192.168.20.1 in your browser
  • Use the admin panel to enable inclusion mode when ready to add devices

Step 2: Setup a Standard Device

Standard devices join the network through the hub's inclusion process.

cd examples/DeviceInclusion/Standard
cp device_info_example.h device_info.h
# Edit device_info.h to set unique device ID and matching radio parameters
../../tools/builder.py build --target local_seeed_xiao_esp32s3 --clean --deploy

The standard device will automatically join when it detects the hub's inclusion broadcast.

Step 3: Monitor the Network

Open serial monitors for both devices (115200 baud) to watch the automatic inclusion process and subsequent data exchange.

Automatic Inclusion Protocol

RadioMesh now features a fully automatic inclusion protocol built into the framework:

Key Features

  • Zero Application Code: Inclusion is handled entirely by the InclusionController
  • Automatic State Management: Protocol states and transitions are managed internally
  • Built-in Retry Logic: Exponential backoff (5s, 10s, 20s) with 3 retry attempts
  • Secure Key Exchange: ECDH-based key exchange for network security
  • State Persistence: Devices remember their inclusion status across reboots

How It Works

  1. Hub must be explicitly put into inclusion mode via:
    • Web admin panel (http://192.168.20.1 after connecting to MiniHubAP WiFi)
    • Programmatically using device->enableInclusionMode(duration)
  2. Hub broadcasts INCLUDE_OPEN messages periodically while in inclusion mode
  3. Non-included devices automatically respond with INCLUDE_REQUEST
  4. Hub and device perform secure key exchange
  5. Device confirms inclusion and joins the network
  6. All messages are handled automatically by the protocol layer

Application Integration

Applications only need to:

  • Enable inclusion mode on hubs when needed
  • Optionally monitor inclusion events for UI updates
  • No manual message handling or state management required

Building and Deploying RadioMesh

RadioMesh comes with a simple build tool written in python that provides a wrapper around platformIO CLI tool. The tool is located in the tools directory and is called builder.py. It can be used instead of the platformio cli for building both the library and the examples.

All you have to do is run the script from a folder containing a platformio.ini.

usage: builder.py [-h] {version,build,test,clean,list-targets} ...

builder - A PlatformIO CLI Wrapper to build RadioMesh library and examples.

positional arguments:
  {version,build,test,clean,list-targets}
                        Available commands
    version             Print cli version
    build               build the project for a specific target
    test                test the project for a specific target
    clean               clean the project for a specific target
    list-targets        list all available target environments

options:
  -h, --help            show this help message and exit

With builder, you can:

Show help for commands

./tools/builder.py build --help

List library build targets (from the project root)

% ./tools/builder.py list-targets

Build the library

Example:

% ./tools/builder.py build --target heltec_wifi_lora_32_V3 --clean - A clean library build for the Heltec WiFi LoRa v3 board.

Build and deploy examples

The DeviceInclusion example contains both Hub and Standard device configurations:

From examples/DeviceInclusion/MiniHub:

  • ../../tools/builder.py build --target local_heltec_wifi_lora_32_V3 --clean - Clean build for hub
  • ../../tools/builder.py build --target local_heltec_wifi_lora_32_V3 --clean --deploy - Build and deploy hub

From examples/DeviceInclusion/Standard:

  • ../../tools/builder.py build --target local_seeed_xiao_esp32s3 --clean - Clean build for standard device
  • ../../tools/builder.py build --target local_seeed_xiao_esp32s3 --clean --deploy - Build and deploy standard device

Run and deploy unit tests

Examples (from the project root):

  • % ./tools/builder.py test --target test_heltec_wifi_lora_32_V3 - Run all tests
  • % ./tools/builder.py test --target test_heltec_wifi_lora_32_V3 --suite test_DeviceBuilder - Run specific test suite

Note: tests are uploaded and run on the device, so you will need to connect your Arduino board using a USB cable for the command to work.

Hardware

Currently, RadioMesh supports the following Arduino boards:

ESP32-based Boards

Low-Power Boards

Radio Configuration

All devices in a mesh network must use compatible radio settings:

  • Same frequency band (868MHz for EU, 915MHz for US)
  • Same bandwidth, spreading factor, and coding rate
  • Configured in device_info.h for each device

Example: DeviceInclusion

The DeviceInclusion example demonstrates the complete automatic inclusion process:

MiniHub

  • Acts as the network hub managing device inclusion
  • Features OLED display showing network status
  • Automatically enables inclusion mode on startup
  • Tracks inclusion statistics (requests, successful joins)

Standard Device

  • Represents a typical sensor node
  • Automatically joins the network when hub is in inclusion mode
  • Sends periodic sensor data once included
  • Minimal code required - inclusion is fully automatic

Key Files

  • device_info.h - Device-specific configuration (ID, radio params)
  • MiniHub.ino - Hub implementation with display UI
  • StandardDevice.ino - Minimal standard device implementation

Troubleshooting

Common Issues

  1. Devices not communicating

    • Verify radio frequencies match between devices
    • Check antenna connections
    • Ensure devices are within range
    • Monitor serial output for error messages

  2. Inclusion failures

    • Hub inclusion mode times out after 60 seconds by default
    • Check for radio interference
    • Verify unique device IDs
    • Review protocol timeout settings

  3. Build errors

    • Ensure device_info.h exists (copy from device_info_example.h)
    • Verify PlatformIO environment matches your hardware
    • Check RadioMesh library installation

  4. Upload failures

    • Verify correct USB port selection
    • Check board is in programming mode
    • Try different USB cable or port

Next Steps

  1. Review the DeviceInclusion README for detailed protocol information
  2. Explore the API documentation
  3. Check the Wiki for advanced topics
  4. Join the community discussions for support

Project Documentation

RadioMesh source documentation can be found here

Clone this wiki locally