MeshRadio – Firmware Flash Guide (Without Development Environment)

MeshRadio – Webinterface & API Reference. <- Click here

This guide describes how to install the MeshRadio firmware on a supported device.

No programming knowledge is required.
Installation is performed using a ready-made firmware file.

Supported Hardware

MeshRadio currently supports four devices:

The correct firmware is available in the Downloads section <- Click

⚠️ Important
The firmware is board-specific.
Please use the correct firmware.

Required Software

Only one tool is required for flashing:

ESP Flash Download Tool

Download:

https://www.espressif.com/en/support/download/other-tools

After downloading, extract the ZIP file.

The tool does not require installation.

Step 1 – Connect the Board

Connect the LoRa board using a USB cable.

Examples:

Board	Connection
LILYGO_SX1276	USB-C
HELTEC_V3	USB-C
TBEAM_V11_SX1276	USB-C
TBEAM_V12_AXP2101	USB-C

Windows automatically detects the device as a USB Serial Port.

Example:

COM7

Remember the COM port.

Step 2 – Start the Flash Tool

Start the program:

flash_download_tool.exe

After that, a selection window appears.

Selection:

ChipType: ESP32    For LILYGO_SX1276, TBEAM_V11_SX1276, TBEAM_V12_AXP2101
ChipType: ESP32-S3 For HeltecV3
WorkMode: Develop
LoadMode: UART

Then:

OK

Step 3 – Select Firmware

Select the firmware in the Flash Tool.

Example:

MeshRadio_HeltecV3.bin

Set the address:

0x0

Enable the checkbox.

Step 4 – Set Flash Parameters

Set the following parameters:

Parameter	Value
SPI Speed	40 MHz
SPI Mode	DIO
Flash Size	4MB

These settings work with all supported boards.

Step 5 – Select COM Port

At the bottom of the Flash Tool:

COM Port: COM7
Baud Rate: 921600

(depending on the system, the COM port may differ)

Step 6 – Start Flashing

Click the button:

START

The tool now starts the flashing process.

Example output:

Writing at 0x00010000...
Hash of data verified.

The process takes approximately:

5 – 15 seconds

Step 7 – Flash Completed

After successful flashing, the following appears:

FINISH

The device will then restart automatically.

If not:

Press the RST button

ATTENTION!!!

Starting with version > 3.1, updates can be flashed via OTA WEB.
Version 3.1 itself, or the very first flash, must still be flashed using the tool!

http://<currentIP>/update

Flashing Under Linux (ESP32-S3 / LiLyGo)

1. Remove the old esptool version

sudo apt remove esptool

2. Create a Python environment

# If venv is not installed yet

sudo apt install python3-venv

python3 -m venv ~/esptool_env
source ~/esptool_env/bin/activate

3. Install the official esptool

pip install esptool

4. Flash the firmware

HeltecV3:

esptool.py --chip esp32s3 --port /dev/ttyACM0 --baud 921600 write_flash -z 0x00 AktuellesMeshRadioHeltec.bin

LiLyGo:

esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 write_flash -z 0x00 AktuellesMeshRadioLiLyGo.bin

Note

As long as the Python environment is active, the terminal shows:

(esptool_env)

First Start of the Device

Press reset once on the device!

After flashing, the node automatically creates a WiFi network.

SSID:

MeshRadio-Setup

MeshRadio-SetupX

Password:

Connection to the Webinterface

Connect to the WiFi network.

Then open in the browser:

http://192.168.4.1

The MeshRadio web interface with the configuration section will now appear.

Important Step – Factory Reset

After the first flash, a Factory Reset should always be performed.
During later flashing cycles, the NVS storage remains preserved.

Reason:

The internal memory (NVS) may contain old data.

Perform Factory Reset

In the web interface:

Factory Reset

The node then restarts automatically.

Then reconnect to:

MeshRadio-Setup

Typical Problems During Flashing

Device is not detected

Install the driver:

CP210x USB Driver

CH340 Driver

depending on the board.

Flash does not start

Hold the BOOT button while pressing START.

Then release it.

Wrong firmware

If the wrong firmware was used:

simply flash again.

The device cannot be permanently damaged by this.

Firmware Update

For a firmware update, simply flash again.

Procedure:

Start Flash Tool
↓
Select new firmware
↓
START

The configuration usually remains stored.

If problems occur:

Factory Reset

perform it.

ATTENTION!!!

Starting with version 3.1, updates can be flashed via OTA WEB.
Version 3.1 itself, or the first flash, must be flashed using the tool!

http://<currentIP>/update

Safety Notice

Only the firmware is replaced during flashing.

The following data may remain stored:

Node configuration
Frequency
Callsign
Routing settings

If a clean reinstallation is desired:

Perform Factory Reset.
After that, the device must be configured again!

Recommendation

After every firmware update:

Factory Reset
↓
Reload configuration
After that, the device must be configured again!

This ensures that old settings do not cause conflicts.

MeshRadio – Webinterface & API Reference

This documentation describes all functions of the MeshRadio web interface as well as the underlying API.

The web interface is used to configure a node without additional software.

Accessing the Webinterface

After startup, the node creates a WiFi network:

MeshRadio-Setup

Connect with:

Password:

Then open in the browser:

http://192.168.4.1

The local AP can now be configured:
Then APPLY FORM -> SAVE NVS -> RESET ESP

The target restarts, and if everything was correct it connects to the local AP.
In some cases, reset may need to be pressed on the target.

If something goes wrong, the address http://192.168.4.1 remains available.

Control can be performed via UART USB CLI. There you can also find the new address and the hostname.

Open the target COM port in PuTTY at 115200 baud.

After that, the device is available via the new IP address or the hostname:

http://<assignedIP or hostname>

Webinterface – Structure

The web interface consists of the following sections:

System Information
Node Configuration
RF Configuration
Routing Settings
Sensor Settings
Message Interface
Configuration Control
Command Trigger

If the device has a GPS module, the web interface is extended with this additional window.
Starting with version 3.3.0, every device with WiFi enabled can show a position on APRS as a router.

When clicking the APRS button, the following can be configured.

After filling everything in and saving it, the device sends the GPS data to the Relay Callsign. If everything is correct, it will be forwarded to APRS.fi.
If the position for the test gateway is entered, all APRS data is correct, and WiFi is connected, the position will be transmitted.

No GPS FIX on devices with GPS modules, no transmission!

1 System Information

Displays hardware and firmware information.

Field	Description
UI Indicator	Status of the interface (e.g. OK / OLD)
Status	Active operating state with parameters (Call, Mode, Display, WiFi, Relay, Crypto, Battery)
Target	Hardware board
LoRa Chip	Used LoRa chip
Firmware	Installed firmware version
Protocol	Used MeshRadio protocol version

2 Node Configuration

Basic configuration of the node.

Parameter	Description
Callsign	Own callsign
Relay Callsign	Destination node
Node Mode	Operating mode
Crypto	Encryption enabled
WiFi	Access point enabled

Callsign

Own callsign of the node.

Example:

DJ1ABCF

Maximum:

8 characters

Relay Callsign

Destination node for messages.
In Sensor mode with PowerSave on, the sensor sends an Awake message to this address.
If a BME280 or another sensor is activated, the data is sent as well.

Example:

DL7ABCF

Node Mode

Defines the role of the node.

Possible values:

0 = RELAY
1 = EDGE
2 = SENSOR

Description:

Mode	Function
RELAY	Router node
EDGE	Endpoint
SENSOR	Sensor node

Crypto

Enables AES-CCM encryption.

ON
OFF

If enabled, both nodes must use the same key. Crypto does not need to be enabled on both sender and receiver.
The device detects encrypted messages and decrypts them.

3 RF Configuration

Settings of the radio module.

Parameter	Description
Frequency	Radio frequency
TX Power	Transmit power

Frequency

Frequency in Hertz.

Example:

433050000

All nodes must use the same frequency.

TX Power

Transmit power in dBm.

Examples:

Typical values:

Value	Power
2	minimum
10	medium
14	standard
20	maximum power

4 Routing Settings

Mesh routing parameters.

Parameter	Description
Beacon Interval	Beacon interval
RouteAdv	Routing updates
RouteAdv TopN	Number of routing entries
RouteAdv Delta	ETX change
Holddown	Routing stabilization

Beacon Interval

Time between beacons.

Example:

Unit:

Milliseconds

5 Sensor Settings

Relevant only in Sensor mode.

Parameter	Description
PowerSave	Deep sleep enabled
Wake Period	Wake interval
RX Window	Receive window
BME280	Weather sensor enabled

PowerSave

Enables deep sleep.

ON
OFF

If enabled, the node sleeps between measurements.

Wake Period

Time between wake-up cycles.

Example:

300000
equals
5 minutes

RX Window

Time window in which the sensor can receive commands.

Example:

30000
equals
30 seconds

BME280

Enables the weather sensor.

ON
OFF

If enabled, the node sends:

SENSOR:AWAKE WX t=23.1C p=1013hPa rh=42% bat=3710mV bat=63%

ATTENTION! The BME280 sensors are hardwired.
Heltec: SDA GPIO 41 SCL GPIO 42 and LiLyGo: SDA GPIO 21 SCL GPIO 22

6 Message Interface

Direct sending of messages.

Fields:

Field	Description
Destination	Destination node
ACK	Delivery confirmation
Message	Message

Example

Destination: DL7ABCF
ACK: 1
Message: STATUS?

ACK

0 = no confirmation
1 = ACK required

7 Configuration Control

Control buttons in the web interface.

Apply Form

Applies changes immediately to runtime.
Changes are not yet saved.

Save NVS

Saves configuration permanently in flash memory.
Without Save, changes are lost after restart.
It is recommended to perform a reset after every change.

Load NVS

Loads saved configuration from flash memory.

Defaults

Restores default values.

Reload Config

Reloads the current configuration from the device.

Reset

Restarts the ESP.

Factory Reset

Deletes the entire configuration.

The following will be deleted:

Callsign
Frequency
Routing settings
WiFi settings

The device then restarts.

8. Command Trigger

Each device provides 2 GPIOs that can be assigned to a command.
These are different for LiLyGo and Heltec.
The GPIOs can be selected.
Command Destination describes the target node where the command should arrive.
In Command Text, the command to be sent is selected.
The GPIOs are programmed so that they only need to be pulled to GND to trigger the command.

What you can do with it now:

GPIO 48 – Usage (ESP32-S3)

The GPIO 48 pin can be used for various digital functions thanks to the flexible pin matrix of the ESP32-S3.

Communication & Sensors

GPS modules – e.g. as GPS_RX for NMEA data
One-wire sensors – e.g. DS18B20 temperature sensor
I²C / SPI – additional sensors or displays (e.g. BME280)
UART – additional serial communication port

Inputs and Outputs

Buttons / switches – with internal pull-up / pull-down resistors
Rotary encoder – for menu control
LEDs or buzzers – status indicators or signal tones
Relay modules – for switching external devices

Control (PWM)

Servo motors – position control
Fan control – speed control
LED dimming – brightness control of LEDs

Important Notes

No analog input: GPIO 48 has no ADC
3.3 V logic: 5 V must not be connected directly

API Reference

The web interface uses an HTTP API.
All commands can also be called directly via HTTP.

GET /api/cfg

Example: Also applies to all following commands.

http://<your_IP_or_domain>/api/cfg

Reads the complete configuration.

Response:

{
"callsign":"DJ1ABCF",
"relay_callsign":"DL7ABCF",
"net_id":66,
"crypto":1,
"node_mode":0,
"wifi":1,
"ssid":"MeshRadio",
"beacon":1,
"beacon_ms":30000,
"routeadv":1,
"rf_hz":433050000,
"tx_dbm":10,
"powersave":0
}

POST /api/cfg

Sets configuration.

Body example:

{
"callsign":"DJ1ABCF",
"node_mode":2,
"rf_hz":433050000
}

POST /api/reset

Restarts the device.

Response:

OK reset

POST /api/factory

Perform Factory Reset.

Response:

OK factory reset

POST /api/send

Sends a message.

Example:

{
"dst":"DL7ABCF",
"ack":1,
"text":"STATUS?"
}

CLI Commands (UART)

An additional serial CLI also exists.

help

Shows commands

help

status

Shows status

status?

wifi

wifi on
wifi off

role

role 0
role 1
role 2

crypto

crypto on
crypto off

relay

relay on
relay off
relay toggle

send

send DL7ABCF 1 HELLO

cmd

Remote commands.

cmd DL7ABCF 1 STATUS
cmd DL7ABCF 1 RELAY ON
cmd DL7ABCF 1 RELAY OFF
cmd DL7ABCF 1 RELAY TOGGLE
cmd DL7ABCF 1 CRYPTO ON
cmd DL7ABCF 1 CRYPTO OFF

Sensor Messages

ATTENTION! The BME280 sensors are hardwired. Heltec: SDA GPIO 41 SCL GPIO 42 and LiLyGo: SDA GPIO 21 SCL GPIO 22

Sensor nodes automatically send:

SENSOR:AWAKE

SENSOR:AWAKE WX t=23.1C p=1013hPa rh=42% bat=3710mV bat=63%

When BME280 and PowerSave are active.

There is a visualization with control for the sensor messages

Python file included in the release:

Description <- Click

Summary

Typical workflow:

Flash Firmware
↓
Factory Reset
↓
Configuration in the web interface
↓
Apply
↓
Save
↓
Reset