Skip to content

MQTT Firmware (Direct Observer)

Flash observer firmware directly onto a supported board. The device connects to WiFi and publishes mesh traffic to MQTT brokers without a host computer.

Pre-configured firmware

The 2026-05-21 and newer images are pre-compiled by n30nex and come pre-configured with the MeshCore.ca broker pair (mqtt1.meshcore.ca and mqtt2.meshcore.ca) in slots 1 and 2, plus the USA/Canada radio defaults (910.525 MHz / 62.5 kHz / SF7 / CR5). After flashing, run the CLI setup block below to set WiFi, IATA, node name, path hash mode, and packet publishing.

Firmware attribution

These images are community builds based on the open source MeshCore firmware, released under the MIT License with copyright held by Scott Powell / Ripple Radios. The direct MQTT observer support is built from Adam Gessaman's mqtt-bridge-implementation-flex branch. The 2026-05-21 MeshCore.ca images were compiled and packaged by n30nex with MeshCore.ca broker defaults. MeshCore.ca is an independent community site and is not affiliated with, endorsed by, or officially connected to MeshCore or MeshOS.

Supported Boards

All boards support both Repeater and Room Server roles.

Board Notes
Heltec V3 Fully tested
Board Notes
Heltec V4 OLED Build verified, smoke test recommended
LILYGO T3S3 SX1262 Build verified, smoke test recommended
T-Beam Supreme SX1262 Build verified, smoke test recommended
T-Beam SX1262 Build verified, smoke test recommended
Seeed XIAO ESP32S3 + Wio-SX1262 Build verified, smoke test recommended
Board Notes
Heltec Wireless Tracker Needs dedicated firmware target and validation
Heltec Wireless Paper Needs dedicated firmware target and validation

New boards will appear in the firmware picker automatically as they are validated and released.

Firmware Downloads

Pick your board, role, and flash type to get the right firmware image.

Most users should choose First Flash (Merged), download the file, then flash it with the MeshCore Flasher. No esptool offsets are needed when using the picker download.

Loading firmware manifest... If this does not change, use the static download table below or download from GitHub Releases.

Static Download Index

If the firmware picker does not load, use this static table. First Flash (Merged) is the right choice for a new board, erased board, or recovery flash. Use Update only on a device already running MeshCore.

Board Role First Flash (Merged) Update
Heltec V3 Repeater Download Download
Heltec V3 Room Server Download Download
Heltec V4 OLED Repeater Download Download
Heltec V4 OLED Room Server Download Download
LILYGO T3S3 SX1262 Repeater Download Download
LILYGO T3S3 SX1262 Room Server Download Download
LILYGO T-Beam S3 Supreme SX1262 Repeater Download Download
LILYGO T-Beam S3 Supreme SX1262 Room Server Download Download
LILYGO T-Beam SX1262 Repeater Download Download
LILYGO T-Beam SX1262 Room Server Download Download
Seeed XIAO ESP32S3 + Wio-SX1262 Repeater Download Download
Seeed XIAO ESP32S3 + Wio-SX1262 Room Server Download Download

Prerequisites

Requirement Details
Board A supported LoRa board (see list above)
WiFi 2.4 GHz network credentials
IATA Code Your real 3-letter IATA airport code (e.g. YOW for Ottawa)
Radio preset Built into 2026-05-21+ firmware: USA/Canada recommended settings, 910.525 MHz / 62.5 kHz / SF7 / CR5
Path hash mode 3-byte path hashes: set path.hash.mode 2

Flashing

  1. Pick your board and role from the picker above
  2. Choose First Flash (Merged) unless you already know you need an app-only update image
  3. Download the firmware and flash it with the MeshCore Flasher

First time flashing?

Use First Flash (Merged). The published merged filenames end in -merged.bin, which lets MeshCore Flasher detect the full image and write it at the correct offset.

Flash type Use case Technical offset
First Flash (Merged) New board, erased board, recovery from a bad flash 0x00000
Update Device already running MeshCore with a valid bootloader and partition table 0x10000

Technical users can still flash with their preferred ESP tool. Most users should use the MeshCore Flasher and the First Flash (Merged) picker option.

CLI Setup

After flashing, connect to the device's admin CLI (serial or web) to set your WiFi, IATA code, and node name.

Guided Heltec V3 / V4 Setup

For Heltec V3 and Heltec V4 OLED boards running the MeshCore.ca direct MQTT firmware, the guided setup script prompts for your board, role, IATA code, WiFi network, WiFi password, node name, broker restore choice, and repeat/observe-only mode. It also applies the MeshCore Canada radio values, 3-byte path hash mode, and required MQTT packet publishing settings:

bash <(curl -fsSL https://meshcore.ca/analyzer/scripts/setup-mqtt-firmware.sh)

The script can send the commands over USB serial on Linux or macOS, or print a copy/paste command block for the web/admin CLI. If you already know the serial port, pass it directly:

bash <(curl -fsSL https://meshcore.ca/analyzer/scripts/setup-mqtt-firmware.sh) --port /dev/ttyUSB0

On Windows, use the PowerShell helper:

powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (iwr -UseBasicParsing https://meshcore.ca/analyzer/scripts/setup-mqtt-firmware.ps1).Content"

If you already know the COM port, pass it directly:

powershell -NoProfile -ExecutionPolicy Bypass -Command "& ([scriptblock]::Create((iwr -UseBasicParsing https://meshcore.ca/analyzer/scripts/setup-mqtt-firmware.ps1).Content)) -Port COM3"

To generate commands without touching a serial port:

bash <(curl -fsSL https://meshcore.ca/analyzer/scripts/setup-mqtt-firmware.sh) --print-only

Windows print-only mode:

powershell -NoProfile -ExecutionPolicy Bypass -Command "& ([scriptblock]::Create((iwr -UseBasicParsing https://meshcore.ca/analyzer/scripts/setup-mqtt-firmware.ps1).Content)) -PrintOnly"

Manual CLI Setup

If you prefer to configure the device manually, replace YOW with the real 3-letter airport code nearest to you and fill in your network credentials:

set name YOW-Repeater-01
set path.hash.mode 2
set mqtt.iata YOW
set wifi.ssid YourWiFiNetwork
set wifi.pwd YourWiFiPassword
set wifi.powersave none
set mqtt.status on
set mqtt.packets on
set bridge.enabled on
set mqtt.rx on
set mqtt.tx advert
reboot

Use a real IATA code

The firmware will let you type any value, but the public MeshCore.ca broker only accepts valid 3-letter IATA airport codes. If the code is not on the quick list, it can still work as long as it is a real airport code. Placeholder or made-up values such as XXX or HOME will not publish. Do not use CAN as shorthand for Canada; it is a real airport code for Guangzhou and will tag your observer to the wrong region.

Room Servers

For room server roles, change the name to match (e.g. YOW-Room-Server-01).

MeshCore Canada network settings

Fresh 2026-05-21 and newer direct MQTT firmware images already default to the USA/Canada (Recommended) radio preset used by MeshCore Canada communities. set path.hash.mode 2 is still required during onboarding because it selects 3-byte path hashes for repeater-backed MeshCore Canada networks. If you are updating an older image, reusing a device with retained preferences, or verifying a device before remote installation, run set radio 910.525,62.5,7,5 as well.

Packet Repeating

By default, the device will repeat packets for other nodes on the mesh in addition to observing. If that's what you want, no changes needed.

If you already have a repeater nearby (e.g. one on your roof) and this device should only observe without repeating traffic, disable it:

set repeat off

Broker Slots

These firmware images ship pre-configured with mqtt1.meshcore.ca and mqtt2.meshcore.ca in slots 1 and 2. No action needed unless your slots were cleared or overwritten.

Restore broker slots manually

If your broker slots were cleared or overwritten, restore them with:

set mqtt1.preset none
set mqtt2.preset none
set mqtt3.preset none
set mqtt4.preset none
set mqtt5.preset none
set mqtt6.preset none
set mqtt1.preset custom
set mqtt1.server wss://mqtt1.meshcore.ca:443
set mqtt1.port 443
set mqtt1.audience mqtt1.meshcore.ca
set mqtt2.preset custom
set mqtt2.server wss://mqtt2.meshcore.ca:443
set mqtt2.port 443
set mqtt2.audience mqtt2.meshcore.ca

Verify

Once your device is online, head to Check Your Observer to confirm it's reporting correctly.