MeshCore-EastMesh originates from the upstream MeshCore project:
Credits to Scott Powell / Ripple Radios and the MeshCore contributors for the original firmware and project foundation.
EastMesh is a community-driven mesh network across Eastern Australia. This repository provides tailored builds of MeshCore, including Observer firmware that integrates with our CoreScope telemetry platform.
CoreScope (https://core.eastmesh.au) offers visibility into the network, including repeater status, observers, and mapping data.
Observer builds feed EastMesh Core telemetry and are intended for Eastern Australia repeaters only; running them elsewhere can skew shared network data.
*_repeater_observerfirmware targets with:- native WiFi
- MQTT over WSS with JWT auth
- optional local HTTPS config panel on supported ESP32 targets
*_repeater_observer_espnowfirmware targets that add a local ESP-NOW mesh bridge*_repeater_bridge_espnowfirmware targets for a plain upstream-style repeater ESP-NOW bridge, without MQTT uplink or the EastMesh web panel*_repeater_observer_mqtt_bridgefirmware targets that add an MQTT mesh bridge through a broker you run*_room_server_mqtt_bridgefirmware targets: room servers with Wi-Fi, a web panel, an MQTT mesh bridge, and post sync between room servers- EastMesh-specific release workflows and versioning on top of upstream MeshCore releases
- docs and release guidance for EastMesh users instead of the full upstream MeshCore docs set
The community asked for MQTT bridges and room servers that share posts, so we've built both:
- Observer MQTT bridge (
observer-eastmesh-bridge-mqtt) links meshes that radio can't reach by relaying mesh packets through an MQTT broker. - Room Server MQTT bridge (
room-server-eastmesh-bridge-mqtt) is a room server whose posts sync with every other room server on the same broker and topic. It also bridges and repeats mesh packets.
Bridges aren't for everyone. Most repeaters should stay plain repeaters or observers, and a bridge should be a deliberate choice. Before you deploy one:
- Every bridged packet is retransmitted on the other side. Adverts, floods, and chat from one mesh are repeated over LoRa on the other, so both meshes carry more traffic and use more airtime. Bridging busy meshes can congest both.
- Talk to the people who run the meshes you're joining. A bridge links meshes that may have been kept separate on purpose, by region, radio config, or community. Don't bridge into a shared mesh without agreement.
- Treat the broker as part of your network. The bridge uses plain MQTT over TCP, not TLS. Use a broker with usernames and passwords, and don't run it open to the internet. Mesh messages stay MeshCore-encrypted end to end.
- Check your radio settings before you connect. A bridge transmits traffic from elsewhere, so set the correct regional radio preset first. New installs start on the upstream default, which is not the Australian band.
- Room sync shares everything posted to the room. Anyone with the same topic can read and post to every room on that topic. Posts made while a room server is offline are not delivered to it later.
Setup and commands are in Custom CLI and Room Server MQTT Bridge Commands.
Prebuilt firmware is published on GitHub Releases:
For flashing guidance, including when to use .bin vs -merged.bin, see:
The custom firmware flasher site is:
This repo uses uv for Python tooling and runs PlatformIO through uv run.
Official install docs:
Common install methods:
macOS and Linux:
curl -LsSf https://astral.sh/uv/install.sh | shHomebrew:
brew install uvWindows PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Install tooling:
uv syncList available build targets:
bash eastmesh-build.sh listBuild a single target:
uv run pio run -e heltec_v4_repeater_observerBuild with release-style version metadata:
export FIRMWARE_VERSION=v1.15.0
export EASTMESH_VERSION=v2026.5.1
bash eastmesh-build.sh build-firmware heltec_v4_repeater_observerFlash a target:
uv run pio run -e heltec_v4_repeater_observer -t upload --upload-port /dev/tty.usbmodemXXXXOpen a serial monitor:
uv run pio device monitor --port /dev/tty.usbmodemXXXX --baud 115200Build docs locally:
uv run --group docs zensical serve
uv run --group docs zensical buildeastmesh-build.sh- EastMesh local/release build wrapper
- injects
FIRMWARE_VERSION,CLIENT_VERSION, and EastMesh release metadata
build.sh- upstream MeshCore build wrapper retained to reduce future merge conflicts
pyproject.toml- Python tooling and docs dependencies
platformio.ini- root PlatformIO config and ESP32 helper scripts
variants/eastmesh/platformio.ini- shared EastMesh observer env definitions
examples/simple_repeater/MyMesh.cpp- repeater CLI wiring, MQTT command surface, and web allowlist integration
src/helpers/bridges/MQTTBridge.cpp- bidirectional MQTT mesh bridge (peer broker TCP, topic
meshcore/bridge/packets)
- bidirectional MQTT mesh bridge (peer broker TCP, topic
src/helpers/mqtt/MQTTUplink.cpp- MQTT uplink implementation, HTTPS web panel, WSS/JWT handling, and repeater WiFi control
RELEASE.md- tag formats and release workflow behavior
eastmesh-docs/- EastMesh-focused docs published to GitHub Pages
docs/- upstream MeshCore docs retained to reduce future merge conflicts
- curated broker support for:
eastmesh-aumeshmapperwaevletsmesh-eu(retired)letsmesh-us(retired)
- WSS transport at
/mqtt - JWT auth using the device identity
- CLI controls for:
- WiFi credentials
- WiFi powersaving
- board battery reporting on supported targets
- MQTT endpoint enablement
- MQTT packet and raw publishing
- owner public key and email
- local web panel enablement
The observer-eastmesh-bridge-mqtt release track (*_repeater_observer_mqtt_bridge) bridges raw mesh packets between repeaters through a peer MQTT broker you run (for example Mosquitto on a LAN PC). This is not the same as MQTT uplink to EastMesh/MeshMapper:
| MQTT uplink (observer) | MQTT mesh bridge | |
|---|---|---|
| Purpose | Publish JSON telemetry to curated brokers | Forward encrypted mesh packets between radios |
| Brokers | eastmesh-au, meshmapper, custom WSS |
Your peer broker (host:port, TCP) |
| Topic | meshcore/<iata>/... (per IATA) |
meshcore/bridge/packets (fixed) |
| Default on bridge builds | Off by default (enable in web panel / CLI) | On when bridge.enabled is on |
Targets: every observer board has a *_repeater_observer_mqtt_bridge build. List them with bash eastmesh-build.sh list | grep _repeater_observer_mqtt_bridge.
Room servers: the room-server-eastmesh-bridge-mqtt track (*_room_server_mqtt_bridge) uses the same bridge topic, so room servers join an observer MQTT bridge on the same broker and secret. Room servers on the same bridge.topic also sync their posts with each other. See Room Server MQTT Bridge Commands.
Related track: observer-eastmesh-bridge-espnow (*_repeater_observer_espnow) uses ESP-NOW instead of MQTT for local bridging.
Build example:
uv run pio run -e Xiao_S3_WIO_repeater_observer_mqtt_bridgeFlash (update):
uv run pio run -e Xiao_S3_WIO_repeater_observer_mqtt_bridge -t upload --upload-port COM10After a full flash erase, flash the merged image at 0x0 instead of only firmware.bin:
uv run pio run -e Xiao_S3_WIO_repeater_observer_mqtt_bridge -t mergebin
uv run pio pkg exec -p tool-esptoolpy -- esptool.py --chip esp32s3 --port COM10 write_flash 0x0 .pio/build/Xiao_S3_WIO_repeater_observer_mqtt_bridge/firmware-merged.binEach bridge node connects to the same peer broker with the same credentials and bridge.secret.
- Install Mosquitto on a machine reachable from both repeaters (for example
192.168.1.145). - Edit
mosquitto.conf(Windows service install:C:\Program Files\Mosquitto\mosquitto.conf) and add:
listener 1883 0.0.0.0
allow_anonymous false
password_file C:\Program Files\Mosquitto\passwdFor lab/testing only, allow_anonymous true works without a password file.
- Create a user (admin CMD):
cd "C:\Program Files\Mosquitto"
mosquitto_passwd -c passwd bridgeuser- Restart the service (do not run a second
mosquitto -vwhile the service owns port 1883):
Restart-Service mosquitto- Confirm LAN listen and open the firewall:
netstat -ano | findstr ":1883"Expect 0.0.0.0:1883, not only 127.0.0.1:1883.
- Test from another machine:
mosquitto_pub -h 192.168.1.145 -p 1883 -u bridgeuser -P your-password -t test -m hello
mosquitto_sub -h 192.168.1.145 -p 1883 -u bridgeuser -P your-password -t meshcore/bridge/packets -vBinary garbage on meshcore/bridge/packets is normal — payloads are XOR-encrypted mesh frames, not text.
Configure both bridge nodes identically for broker access; use the same bridge.secret on every node in the bridge group.
Serial or web panel CLI:
set wifi.ssid YourNetwork
set wifi.pwd YourWiFiPassword
set bridge.peer.host 192.168.1.145
set bridge.peer.port 1883
set bridge.peer.username bridgeuser
set bridge.peer.password your-password
set bridge.secret your-shared-bridge-secret
Web panel: MQTT Settings → Mesh bridge peer MQTT (host:port, username, password). The section appears when get bridge.type returns mqtt.
Useful checks:
get bridge.type
get bridge.peer.host
get bridge.enabled
Default admin password on dev builds is usually password unless you changed it.
Packets use magic 0xC03E, a Fletcher checksum, XOR encryption with bridge.secret, then publish/subscribe on meshcore/bridge/packets. Duplicate detection limits loops when both nodes see the same traffic.
More detail:
- Custom CLI — MQTT bridge settings
- Web panel — MQTT settings and bridge peer fields
- Releases — track comparison
On supported *_repeater_observer ESP32 targets, the repeater can expose a local HTTPS config panel over WiFi.
Features include:
- password-gated access using the existing repeater admin password
- allowlisted CLI execution
- grouped quick actions
- light and dark themes
- optional disable via
set web off
Recommended use is initial setup and occasional troubleshooting. On observer deployments, disable the panel again when finished if you want maximum MQTT heap headroom.
.github/workflows/eastmesh-build-observer-firmwares.yml.github/workflows/eastmesh-build-repeater-bridge-espnow-firmwares.yml.github/workflows/eastmesh-build-observer-espnow-firmwares.yml.github/workflows/eastmesh-build-observer-mqtt-bridge-firmwares.yml.github/workflows/eastmesh-build-room-server-mqtt-bridge-firmwares.yml.github/workflows/eastmesh-pr-build-check.yml.github/workflows/eastmesh-push-build-check.yml.github/workflows/eastmesh-github-pages.yml
The upstream MeshCore workflows are retained under their original filenames to reduce merge conflicts. They are not part of the EastMesh release flow and should stay disabled in GitHub Actions for this repository.
The current release workflows intentionally focus only on:
repeater-bridge-espnowobserver-eastmeshobserver-eastmesh-bridge-espnowobserver-eastmesh-bridge-mqttroom-server-eastmesh-bridge-mqtt
Current release tags are:
git tag repeater-bridge-espnow-v1.15.0
git tag observer-eastmesh-v2026.5.1
git tag observer-eastmesh-bridge-espnow-v2026.5.1
git tag observer-eastmesh-bridge-mqtt-v2026.7.0
git tag room-server-eastmesh-bridge-mqtt-v2026.10.1Repeater ESP-NOW bridge uses the upstream MeshCore version in the tag.
Observer and room server tracks use:
OFFICIAL_MESHCORE_VERSIONfrom GitHub Actions variables asFIRMWARE_VERSION- the EastMesh tag version as
EASTMESH_VERSION
See RELEASE.md for the full release flow.
Published docs site:
Current docs pages: