shade/MeshCore-Posadmesh
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #61 from xJARiD/develop

Browse Source 
docs: improve EastMesh getting started guides
This commit is contained in:
xJARiD
2026-05-08 12:07:16 +10:00
committed by GitHub
parent 7b23753ac7 2f09626c49
commit d245151a3d
8 changed files with 330 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files
eastmesh-docs/api.md
+22 -2
View File
@@ -10,6 +10,26 @@ It is intended for:
This is not a cloud API and not a separate backend service. The repeater firmware serves it directly.
## Start Here
You do not need this page for normal EastMesh use. Use the [Repeater Web Panel](./web-panel.md) if you just want to configure or check a repeater in a browser.
Use this page when you want a local script, dashboard, or home-lab tool to talk directly to the repeater.
The simplest useful API flow is:
1. log in with the repeater admin password
2. save the returned token
3. send a CLI command through `/api/command`
```bash
TOKEN=$(curl -sk -X POST https://<repeater-ip>/login --data '<admin-password>')
curl -sk https://<repeater-ip>/api/command \
-H "X-Auth-Token: $TOKEN" \
--data 'get mqtt.status'
```
## Scope And Availability
The API is available only when:
@@ -235,7 +255,7 @@ This is useful for:
- remote diagnostics from a laptop or phone
- simple scripts that collect operational state
- admin tools that want to reuse existing CLI behavior instead of adding new firmware endpoints
- admin tools that want to reuse existing CLI behaviour instead of adding new firmware endpoints
Example:
@@ -363,4 +383,4 @@ If stats requests fail:
- prefer `/api/command` when you need exact CLI parity
- prefer `/api/stats` for dashboards and trend views
- keep polling conservative, especially on repeaters with two active MQTT connections
- if you are finished with troubleshooting, consider disabling the web panel with `set web off` to maximize heap headroom on constrained boards
- if you are finished with troubleshooting, consider disabling the web panel with `set web off` to maximise heap headroom on constrained boards
eastmesh-docs/boards.md
+39 -12
View File
@@ -2,12 +2,41 @@
This page is meant to help you choose a board, not just list every technical detail.
If you only want a quick answer:
## Start Here
- for a roof-mounted or set-and-forget MQTT repeater, start with `heltec_v4`, `heltec_v4_tft`, `Station_G2`, or `T_Beam_S3_Supreme_SX1262`
- for an app-first Wi-Fi companion, headless boards are fine and often simpler
- if you want an onboard screen people will actually use, prefer TFT boards
If you are new to MeshCore hardware and just want a sensible starting point, first decide whether the device is a companion or a repeater.
For companions, think Wi-Fi-connected automation endpoint:
- use companion Wi-Fi builds when another system, such as Home Assistant, RemoteTerm, or your own tooling, needs to connect to MeshCore over Wi-Fi
- these are usually not hands-on daily devices, so a screen is optional rather than a must-have
- headless or simple boards are often fine when the companion will sit near power and be managed from another app or automation system
- check the companion tables below when you do want a display, GPS, or a more complete board package
For MQTT/web repeaters, think Wi-Fi, broker visibility, and enough headroom for the local web panel:
- common starting points are `Heltec_v3` and `heltec_v4`
- `heltec_v4_repeater_mqtt` is a strong all-round MQTT repeater choice with GPS, PSRAM, and 16 MB flash
- choose boards with more flash and PSRAM when you want MQTT plus the local web panel, stats, or more room for future features
- screens are not a major requirement because MQTT repeaters have the local web panel for setup and troubleshooting
- headless repeaters are often the cleanest choice when the device will live in a roof, box, or fixed install and you will configure it from the web panel, serial console, or app
For bridge repeaters, think local radio linking between nearby repeaters:
- use bridge firmware when two local repeaters need to exchange traffic across different MeshCore radio configs, such as `Australia (Narrow)` and `Australia (Mid)`
- pure ESP-NOW bridge repeaters do not need MQTT, the EastMesh web panel, or a screen
- prioritise stable power, suitable antennas, and placement over display features
- use `repeater-mqtt-bridge` only when the same repeater also needs MQTT uplink; otherwise `repeater-bridge-espnow` keeps the role simpler
Other notes:
- screens matter more for companions or bench/field devices than fixed repeaters
- if you do want an onboard screen people will actually use, prefer TFT boards
- if you want a low-power status screen, prefer e-paper boards
- if location-aware or mobile use matters, prefer GPS-capable boards such as the T-Beam family, `heltec_tracker_v2`, `Heltec_v3`, `heltec_v4`, or `ThinkNode_M5`
- if you want the most conservative, older radio family choices, the `SX1276` boards are `LilyGo_TLora_V2_1_1_6`, `Tbeam_SX1276`, and `Heltec_v2`
## About The Tables
The tables below are built from the repo's PlatformIO board metadata and variant build flags.
@@ -18,15 +47,13 @@ The tables below are built from the repo's PlatformIO board metadata and variant
- `GPS` uses `✅` when present and is blank when absent.
- `SD` uses `✅` when the board is currently known to support the SD-backed archive path in EastMesh, `🧪` when the hardware likely supports TF/microSD but the board-specific integration still needs validation, and is blank when there is no current SD/archive support note.
## Start Here
## Track Notes
- Pick an `ESP32-S3` board with `16MB` flash and PSRAM if you want strong overall headroom for MQTT plus UI: `heltec_v4_tft`, `heltec_v4`, `Station_G2`, `LilyGo_TBeam_1W`.
- Pick a TFT board if this will be used as a human-facing companion or field node: `heltec_v4_tft`, `heltec_tracker_v2`, `LilyGo_TDeck`, `Heltec_T190`.
- Pick e-paper if you want a status screen with lower idle draw and less frequent refresh: `Heltec_E213`, `Heltec_E290`, `Heltec_Wireless_Paper`, `ThinkNode_M5`.
- Pick a headless board if this is mainly a fixed MQTT gateway and screen space is not useful: `RAK_3112`, `Generic_E22`, `Meshimi`, `Xiao_C6`.
- Pick a headless Wi-Fi companion if the phone app will be the primary UI anyway: `RAK_3112_companion_radio_wifi`, `Xiao_S3_WIO_companion_radio_wifi`, `Station_G2_companion_radio_wifi`.
- Pick a GPS-capable board if location-aware/mobile use matters: the T-Beam family, `heltec_tracker_v2`, `Heltec_v3`, `heltec_v4`, `Station_G2`, `ThinkNode_M5`.
- If you want the most conservative, older radio family choices, the `SX1276` boards are `LilyGo_TLora_V2_1_1_6`, `Tbeam_SX1276`, and `Heltec_v2`.
- `companion-wifi` boards are for app-connected companion devices.
- `repeater-mqtt` boards are for Wi-Fi repeaters that publish to MQTT.
- `repeater-bridge-espnow` and `repeater-mqtt-bridge` boards are for local ESP-NOW bridge use between nearby repeaters on different MeshCore radio configs.
Bridge firmware is not MQTT-over-WAN or VPN bridging. Use it when two local repeaters need to exchange traffic across radio configs such as `Australia (Narrow)` and `Australia (Mid)`.
## Additional Signals
eastmesh-docs/custom-cli.md
+44 -20
View File
@@ -4,6 +4,28 @@ This page covers the EastMesh-specific CLI commands added in this repository.
It does not try to repeat the full upstream MeshCore CLI surface.
## Start Here
If you are doing first-time setup, these are the commands most users need before anything else:
```text
set wifi.ssid <your-ssid>
set wifi.pwd <your-password>
get wifi.status
set mqtt.iata <code>
get mqtt.status
```
For MQTT repeaters with the local web panel, these are also useful:
```text
set web on
get web.status
set web off
```
Use `set web on` while setting up or troubleshooting, then use `set web off` when a fixed MQTT repeater needs maximum memory headroom.
## Repeater MQTT Commands
These commands are available on `*_repeater_mqtt` firmware targets.
@@ -12,7 +34,7 @@ No-argument `get` commands must be entered exactly as shown.
### MQTT Status And Routing
- `get mqtt.status`: shows WiFi, NTP, IATA, endpoint status, status publishing state, and TX state.
- `get mqtt.status`: shows Wi-Fi, NTP, IATA, endpoint status, status publishing state, and TX state.
- `get mqtt.statuscfg`: shows whether periodic status messages are enabled as a simple `on` or `off` value. Most users can just use `get mqtt.status`.
- `get mqtt.client_version`: shows the MQTT `client_version` string published by the repeater.
- `get mqtt.iata`: shows the IATA/location code used in MQTT topics.
@@ -61,19 +83,21 @@ Legacy dotted aliases are also accepted:
- `mqtt.letsmesh.eu`
- `mqtt.letsmesh.us`
### WiFi Settings For MQTT Repeaters
### Wi-Fi Settings For MQTT Repeaters
- `get wifi.status`: shows SSID, connection state, raw WiFi status code, IP, channel, and signal when connected.
- `get wifi.ssid`: shows the configured WiFi SSID.
- `set wifi.ssid <ssid>`: sets the WiFi SSID.
- `set wifi.pwd <password>`: sets the WiFi password.
- `get wifi.powersaving`: shows the current WiFi power save mode.
- `set wifi.powersaving none|min|max`: sets WiFi power saving mode.
- `get wifi.status`: shows SSID, connection state, raw Wi-Fi status code, IP, channel, and signal when connected.
- `get wifi.ssid`: shows the configured Wi-Fi SSID.
- `set wifi.ssid <ssid>`: sets the Wi-Fi SSID.
- `set wifi.pwd <password>`: sets the Wi-Fi password.
- `get wifi.powersaving`: shows the current Wi-Fi power save mode.
- `set wifi.powersaving none|min|max`: sets Wi-Fi power saving mode.
### ESP-NOW Bridge Settings For MQTT Bridge Repeaters
These commands are available on `*_repeater_mqtt_bridge` firmware targets.
Bridge commands are for local ESP-NOW bridge use between nearby repeaters, such as linking repeaters on `Australia (Narrow)` and `Australia (Mid)`. They are not MQTT-over-WAN, VPN, or internet bridge controls.
- `get bridge.channel`: shows the configured ESP-NOW bridge channel.
- `set bridge.channel <channel>`: sets the ESP-NOW bridge channel and restarts the bridge. Use a value from `1` to `14`.
- `get bridge.secret`: shows the configured ESP-NOW bridge secret.
@@ -81,12 +105,12 @@ These commands are available on `*_repeater_mqtt_bridge` firmware targets.
After running `set bridge.channel`, expect the bridge and web panel connection to drop briefly while the radio restarts. On current MQTT bridge test builds, this can look like the board rebooted.
For `*_repeater_mqtt_bridge` builds that are connected to WiFi, the ESP-NOW bridge channel must match the active 2.4 GHz WiFi channel:
For `*_repeater_mqtt_bridge` builds that are connected to Wi-Fi, the ESP-NOW bridge channel must match the active 2.4 GHz Wi-Fi channel:
1. Run `get wifi.status`.
2. Read the `channel:<n>` value from the connected WiFi status.
2. Read the `channel:<n>` value from the connected Wi-Fi status.
3. Run `get bridge.channel`.
4. If the values differ, run `set bridge.channel <n>` using the WiFi channel value.
4. If the values differ, run `set bridge.channel <n>` using the Wi-Fi channel value.
5. Use the same `bridge.channel` and `bridge.secret` on every ESP-NOW bridge node that should talk together.
Example:
@@ -133,7 +157,7 @@ These commands are only available on `LilyGo_TBeam_1W_*` repeater builds.
- `set fan off`: forces the fan off and persists that mode across reboot.
- `set fan timeout <Ns>`: changes the automatic post-TX hold window in seconds and persists it across reboot, for example `set fan timeout 45s`.
Auto mode behavior:
Auto mode behaviour:
- forces the fan on during TX and keeps it on for the configured timeout afterward
- otherwise turns the fan on at `48C`
@@ -160,7 +184,7 @@ Notes:
- `start ota` releases the local HTTP redirect listener on port `80` so the OTA HTTP listener can take over without stopping the rest of the repeater services, regardless of whether the command is run from the web panel, serial CLI, or a remote companion/app CLI session
- the `/app` Regions shortcut runs the existing MeshCore region commands in sequence: `region put au`, `region put au-STATE`, `region allowf au`, `region allowf au-STATE`, then `region save`
## Companion WiFi Rescue Commands
## Companion Wi-Fi Rescue Commands
These commands are available in the serial rescue CLI for `*_companion_radio_wifi` builds.
@@ -171,14 +195,14 @@ To enter `CLI Rescue`:
- long-press the user button within the first 8 seconds after boot
- wait for `========= CLI Rescue =========`
- `get wifi.status`: shows configured SSID, connection status, raw WiFi status code, IP, channel, and signal when connected.
- `get wifi.ssid`: shows the configured WiFi SSID.
- `get wifi.powersaving`: shows the current WiFi power saving mode.
- `set wifi.ssid <ssid>`: saves a WiFi SSID and immediately retries connection.
- `set wifi.pwd <password>`: saves a WiFi password and immediately retries connection.
- `set wifi.powersaving none|min|max`: changes the WiFi power save mode.
- `get wifi.status`: shows configured SSID, connection status, raw Wi-Fi status code, IP, channel, and signal when connected.
- `get wifi.ssid`: shows the configured Wi-Fi SSID.
- `get wifi.powersaving`: shows the current Wi-Fi power saving mode.
- `set wifi.ssid <ssid>`: saves a Wi-Fi SSID and immediately retries connection.
- `set wifi.pwd <password>`: saves a Wi-Fi password and immediately retries connection.
- `set wifi.powersaving none|min|max`: changes the Wi-Fi power save mode.
Companion WiFi builds also still support the existing rescue commands such as:
Companion Wi-Fi builds also still support the existing rescue commands such as:
- `set pin <6-digit-pin>`
- `rebuild`
eastmesh-docs/index.md
+16 -3
View File
@@ -13,11 +13,24 @@ MeshCore-EastMesh keeps the upstream MeshCore firmware intact and publishes four
They are not MQTT-over-WAN, VPN, or internet bridge releases. MQTT is still the uplink/visibility path for MQTT firmware; it is not used to tunnel mesh traffic between distant sites.
If you are just trying to pick a board or download firmware, start with:
If you want guidance first, start with:
- [Compare Boards](./boards.md)
- [Download and Flash Releases](./releases.md)
- [Flash NOW!](https://flasher.eastmesh.au)
If you already know your board and just want the quickest path, skip the docs and open the flasher:
- [Open the EastMesh Flasher](https://flasher.eastmesh.au)
## I Want To
- choose a board: start with [Compare Boards](./boards.md)
- flash firmware with guidance: start with [Download and Flash Releases](./releases.md)
- flash firmware now: open the [EastMesh Flasher](https://flasher.eastmesh.au)
- set up a repeater after flashing: use [Download and Flash Releases](./releases.md) and [Use the Repeater Web Panel](./web-panel.md)
- understand EastMesh CLI commands: use [Custom CLI Commands](./custom-cli.md)
- automate or script against a repeater: use [Use the Repeater Web API](./api.md)
- build firmware locally: use [Build Locally With uv](./local-builds.md)
## End User Guides
@@ -36,7 +49,7 @@ If you are just trying to pick a board or download firmware, start with:
This docs site only covers the EastMesh-specific pieces in this repository.
For general MeshCore behavior, radio operation, and upstream firmware concepts, refer to the upstream project:
For general MeshCore behaviour, radio operation, and upstream firmware concepts, refer to the upstream project:
- [meshcore-dev/MeshCore](https://github.com/meshcore-dev/MeshCore)
eastmesh-docs/local-builds.md
+50 -4
View File
@@ -4,6 +4,8 @@ This repo uses `uv` for Python tooling and runs PlatformIO through `uv run`.
This page is for building from source. If you just want firmware to flash, start with [Download and Flash Releases](./releases.md) instead.
Use this page when you are changing firmware, testing a target before release, or building a local artifact that is not available from GitHub Releases.
## Setup
From the repo root:
@@ -25,6 +27,8 @@ Plain PlatformIO build for a single target:
```bash
uv run pio run -e heltec_v4_repeater_mqtt
uv run pio run -e heltec_v4_companion_radio_wifi
uv run pio run -e heltec_v4_repeater_bridge_espnow
uv run pio run -e heltec_v4_repeater_mqtt_bridge
```
Flash a target:
@@ -43,7 +47,7 @@ uv run pio device monitor --port /dev/tty.usbmodemXXXX --baud 115200
If you want the same version metadata used by the release workflows, export the version variables first.
Companion WiFi:
Companion Wi-Fi:
```bash
export FIRMWARE_VERSION=v1.14.1
@@ -58,8 +62,28 @@ export EASTMESH_VERSION=v1.0.1
bash eastmesh-build.sh build-firmware heltec_v4_repeater_mqtt
```
Repeater ESP-NOW bridge:
```bash
export FIRMWARE_VERSION=v1.15.0
bash eastmesh-build.sh build-firmware heltec_v4_repeater_bridge_espnow
```
Repeater MQTT bridge:
```bash
export FIRMWARE_VERSION=v1.15.0
export EASTMESH_VERSION=v1.4.0
bash eastmesh-build.sh build-firmware heltec_v4_repeater_mqtt_bridge
```
This produces versioned artifacts in `out/`.
Versioning rule:
- `companion-wifi` and `repeater-bridge-espnow` use the upstream MeshCore version as `FIRMWARE_VERSION`
- `repeater-mqtt` and `repeater-mqtt-bridge` use the upstream MeshCore version as `FIRMWARE_VERSION` plus the EastMesh release version as `EASTMESH_VERSION`
## Supported `repeater_mqtt` Boards
These are the full PlatformIO env names used for local source builds and release artifact naming.
@@ -99,6 +123,28 @@ Xiao_C6_repeater_mqtt
Xiao_S3_WIO_repeater_mqtt
```
## Supported Bridge Boards
Bridge targets can be listed from the repo root:
```bash
bash eastmesh-build.sh list | grep '_repeater_bridge_espnow'
bash eastmesh-build.sh list | grep '_repeater_mqtt_bridge'
```
Common examples:
```text
heltec_v4_repeater_bridge_espnow
heltec_v4_repeater_mqtt_bridge
Station_G2_repeater_bridge_espnow
Station_G2_repeater_mqtt_bridge
T_Beam_S3_Supreme_SX1262_repeater_bridge_espnow
T_Beam_S3_Supreme_SX1262_repeater_mqtt_bridge
```
Bridge firmware is for local ESP-NOW bridge use between nearby repeaters. It is not MQTT-over-WAN or VPN bridging.
## Supported `companion_radio_wifi` Boards
These are the full PlatformIO env names used for local source builds and release artifact naming.
@@ -121,15 +167,15 @@ ThinkNode_M5_companion_radio_wifi
Xiao_S3_WIO_companion_radio_wifi
```
## Companion WiFi CLI
## Companion Wi-Fi CLI
Current companion WiFi builds support persisted WiFi rescue commands:
Current companion Wi-Fi builds support persisted Wi-Fi rescue commands:
- open a serial monitor at `115200` baud
- reboot the device
- long-press the user button within the first 8 seconds after boot to enter `CLI Rescue`
- wait for `========= CLI Rescue =========`
- then run the WiFi rescue commands below from the serial monitor
- then run the Wi-Fi rescue commands below from the serial monitor
```text
get wifi.status
eastmesh-docs/migration.md
+8
View File
@@ -14,12 +14,20 @@ Start by downloading the correct EastMesh release for your board from:
- [Download and Flash Releases](./releases.md)
## Quick Answer
Try a normal firmware flash first, without erasing the device. After flashing, re-enter the current EastMesh Wi-Fi and MQTT settings listed below.
Only do a full erase-flash if the repeater still behaves strangely after reflashing, reapplying settings, and rebooting.
## Before You Start
- you can flash the new firmware without erasing first
- after flashing, you will need to reapply your Wi-Fi and some MQTT settings
- you can do this either from the serial CLI or from the companion app
Older MQTT bridge settings from `xJARiD/MeshCore` do not migrate into the current EastMesh MQTT uplink settings. Re-enter the settings you still use now instead of expecting older broker/analyzer values to carry forward.
## Required Setup After Flashing
Once the new firmware is flashed, set:
eastmesh-docs/releases.md
+107 -26
View File
@@ -4,10 +4,38 @@ EastMesh release assets are published on:
- <https://github.com/xJARiD/MeshCore-EastMesh/releases>
There are currently two release tracks in this repo:
## Start Here
- `companion-wifi`
- `repeater-mqtt`
If this is your first time flashing EastMesh firmware, the easiest path is:
1. Open <https://flasher.eastmesh.au/>.
2. Select the firmware that matches what the device will do.
3. Select the board that matches your exact hardware.
4. Select the version. The flasher defaults to the latest available release.
5. Select the image type:
- `Update` for a normal firmware update
- `Full Flash` for a clean full-image flash
6. Click `Flash Firmware`.
7. After flashing, finish setup with `Open MeshCore Config Panel` or the `Serial Console`.
If you are not sure which track you need, start with `companion-wifi` for app-connected companion devices or `repeater-mqtt` for a fixed repeater that should publish to MQTT.
## Pick Your Track
EastMesh publishes four release tracks:
| Track | Use it when | Firmware filename suffix |
| ----- | ----------- | ------------------------ |
| `companion-wifi` | You want a companion device that connects over Wi-Fi instead of BLE or USB. | `*_companion_radio_wifi` |
| `repeater-mqtt` | You want a repeater with Wi-Fi and MQTT uplink, usually feeding broker visibility such as EastMesh/CoreScope. | `*_repeater_mqtt` |
| `repeater-bridge-espnow` | You want a local ESP-NOW bridge between nearby repeaters, without MQTT uplink or the EastMesh web panel. | `*_repeater_bridge_espnow` |
| `repeater-mqtt-bridge` | You want one repeater to provide both MQTT uplink and local ESP-NOW bridge duties. | `*_repeater_mqtt_bridge` |
!!! note "Bridge firmware is not a WAN bridge"
Bridge tracks are for bridging two nearby repeaters that operate on different MeshCore radio configs, for example `Australia (Narrow)` and `Australia (Mid)`.
They do not use MQTT to tunnel mesh traffic over the internet, WAN links, or VPNs.
## Pick The Right Asset
@@ -18,14 +46,25 @@ Examples:
- `heltec_v4_companion_radio_wifi-v1.14.1-abcdef.bin`
- `heltec_v4_repeater_mqtt-v1.14.1-eastmesh-v1.0.1-abcdef.bin`
- `heltec_v4_repeater_mqtt-v1.14.1-eastmesh-v1.0.1-abcdef-merged.bin`
- `heltec_v4_repeater_bridge_espnow-v1.15.0-abcdef.bin`
- `heltec_v4_repeater_mqtt_bridge-v1.15.0-eastmesh-v1.4.0-abcdef.bin`
The important part is the board/env prefix:
- `*_companion_radio_wifi`
- `*_repeater_mqtt`
- `*_repeater_bridge_espnow`
- `*_repeater_mqtt_bridge`
## Which File To Flash
If you are using <https://flasher.eastmesh.au/>, choose the image type in the flasher:
- `Update` = normal firmware update
- `Full Flash` = clean full-image flash
If you are manually downloading files from GitHub Releases, use the filename instead:
Use the standard `.bin` file when you are updating an existing device with the same target and partition layout.
Use the `-merged.bin` file when you want a clean install after erasing flash. This is the full ESP32 image and is intended to be flashed from address `0x0`.
@@ -37,10 +76,12 @@ Practical rule:
## Flashing Flow
1. Open the release page and download the file for your board.
2. Confirm the board name in the filename matches your hardware.
3. Choose one of the following: update existing firmware with the normal `.bin`, or erase the device first and flash the `-merged.bin`.
4. Reboot the device and complete any post-flash setup such as WiFi, MQTT, or radio settings.
1. Select firmware.
2. Select board.
3. Select version. The latest version is selected by default.
4. Select image type: `Update` or `Full Flash`.
5. Click `Flash Firmware`.
6. After flashing, use `Open MeshCore Config Panel` or the `Serial Console` for post-flash setup such as Wi-Fi, MQTT, bridge, or radio settings.
## Recommended Flasher
@@ -48,32 +89,29 @@ The recommended flasher is:
- <https://flasher.eastmesh.au/>
It includes native support for:
It includes native support for the common EastMesh firmware types and can also flash custom firmware files:
- `companion_radio_wifi` firmware
- `repeater_mqtt` firmware
- custom firmware files
For bridge releases, use the matching bridge option if the flasher shows one. Otherwise, download the release asset yourself and flash it as a custom firmware file.
Recommended usage:
- use the normal `.bin` there when you are updating an existing device
- use the `-merged.bin` there after an erase when you want a clean flash
- use `Update` when you are updating an existing device
- use `Full Flash` when you want a clean full-image flash
## Beginner Setup
After flashing, there are two useful setup paths in the flasher.
If this is your first time flashing EastMesh firmware, the easiest path is:
### Open MeshCore Config Panel
1. Open <https://flasher.eastmesh.au/>.
2. Select the firmware type you want: `Companion WiFi`, `Repeater MQTT`, or `Custom`.
3. Flash the correct firmware for your board.
4. Use the built-in setup tools in the flasher site to finish first-time configuration.
The flasher site includes two especially useful actions after flashing:
Use `Open MeshCore Config Panel` to access the guided MeshCore setup tools:
- `Repeater Setup`
- `Console`
### Repeater Setup
#### Repeater Setup
`Repeater Setup` is the guided first-time repeater flow.
@@ -90,11 +128,11 @@ It is the traditional way to configure a repeater after flashing, including:
As of `v1.2.1`, the local repeater web panel also includes the same common repeater settings, so users can complete initial setup there and return for occasional troubleshooting or configuration changes. On MQTT repeaters that need maximum headroom, it is still best to disable the panel again when you are finished.
### Console
#### Console
`Console` is the raw CLI interface.
It is especially useful, and often required, for the initial Wi-Fi setup on both firmware tracks:
It is especially useful, and often required, for initial Wi-Fi setup on Wi-Fi-capable firmware tracks:
- `set wifi.ssid <your-ssid>`
- `set wifi.pwd <your-password>`
@@ -103,8 +141,26 @@ This applies to:
- `companion_radio_wifi`
- `repeater_mqtt`
- `repeater_mqtt_bridge`
## Repeater MQTT Notes
### Serial Console
Use `Serial Console` when you want to connect over USB and type CLI commands directly.
The flasher can connect and disconnect from the device over USB. It also includes preset CLI commands that populate the command input for easier setup:
- `set wifi.ssid`
- `set wifi.pwd`
- `get wifi.status`
- `get mqtt.status`
- `set web on`
- `get web.status`
For `set` commands, complete the command in the input box before sending it. For example, select `set wifi.ssid`, add your Wi-Fi network name, then press `Send`.
## Common First Steps
### Repeater MQTT
`repeater_mqtt` builds include the EastMesh MQTT additions. Depending on the board, they may also include the local web panel.
@@ -117,12 +173,37 @@ Typical first steps after flashing:
- optionally set `mqtt.owner` and `mqtt.email`
- optionally enable `letsmesh-eu` or `letsmesh-us`
## Companion WiFi Notes
### Repeater MQTT Bridge
`companion_radio_wifi` builds are for companion devices that expose the app interface over WiFi instead of BLE or USB.
`repeater_mqtt_bridge` builds combine the MQTT repeater role with local ESP-NOW bridge support.
Typical first steps after flashing:
- set WiFi credentials
- set `wifi.ssid`
- set `wifi.pwd`
- set `mqtt.iata`
- confirm `get mqtt.status`
- check `get wifi.status` and note the connected Wi-Fi channel
- set `bridge.channel` to match that Wi-Fi channel
- set the same `bridge.secret` on every local ESP-NOW bridge node that should talk together
### Repeater ESP-NOW Bridge
`repeater_bridge_espnow` builds are for local ESP-NOW bridge nodes without MQTT uplink.
Typical first steps after flashing:
- configure the normal repeater settings for the board
- set the intended MeshCore radio preset/config
- set the same bridge channel and secret on the local bridge pair
- confirm both bridge repeaters are physically nearby enough for ESP-NOW to work
### Companion Wi-Fi
`companion_radio_wifi` builds are for companion devices that expose the app interface over Wi-Fi instead of BLE or USB.
Typical first steps after flashing:
- set Wi-Fi credentials
- confirm `get wifi.status`
- connect your client app to the companion over WiFi
- connect your client app to the companion over Wi-Fi
eastmesh-docs/web-panel.md
+44 -28
View File
@@ -4,9 +4,23 @@ This page is for end users running an EastMesh `*_repeater_mqtt` build with the
It covers how to reach the panel, what each section does, and what to expect when using it on desktop or mobile.
## Start Here
For normal first-time use:
1. Connect the repeater to Wi-Fi.
2. Run `get wifi.status` to find its IP address.
3. Open `https://<repeater-ip>/` in a browser.
4. Accept the self-signed certificate warning.
5. Log in with the repeater admin password.
6. Use the panel for setup or troubleshooting.
7. When finished, use `set web off` if the repeater needs maximum MQTT headroom.
Most users only need the panel for first setup, occasional setting changes, and troubleshooting. Leave it enabled only when browser access is worth the extra memory use.
## What It Is
The repeater web panel is a local HTTPS configuration page served directly by the repeater over WiFi.
The repeater web panel is a local HTTPS configuration page served directly by the repeater over Wi-Fi.
It gives you:
@@ -24,6 +38,28 @@ Operational guidance:
- when you are finished, prefer `set web off` on MQTT repeaters that need maximum headroom
- this leaves more internal heap available for MQTT/WSS activity, especially on dual-broker setups
## Common Tasks
### Check Wi-Fi And MQTT
1. Open the panel.
2. Press `wifi.status` in Quick `get` Commands.
3. Press `mqtt.status` in Quick `get` Commands.
4. Open `/stats` from the top navigation for the historical stats view.
### Change Device Name
1. Edit `Device Name`.
2. Press `Save`.
3. Confirm the generated command and reply in the CLI terminal box.
### Update MQTT Owner Or Email
1. Go to `MQTT Settings`.
2. Enter the new value.
3. Press `Save`.
4. Use the refresh button if you want to re-read the stored value from the repeater.
## Screenshot Overview
The screenshots below show the current split between the lighter `/app` admin page and the dedicated `/stats` status page.
@@ -43,7 +79,7 @@ The screenshots below show the current split between the lighter `/app` admin pa
You need:
- a supported `*_repeater_mqtt` firmware build
- WiFi configured on the repeater
- Wi-Fi configured on the repeater
- the repeater connected to your local network
- the repeater admin password
@@ -51,7 +87,7 @@ Some constrained targets disable the web panel to stay within flash limits. If y
## How To Open It
1. Connect the repeater to WiFi.
1. Connect the repeater to Wi-Fi.
2. Find its IP address.
3. Open `https://<repeater-ip>/` in a browser.
4. Accept the browser warning for the self-signed certificate.
@@ -59,7 +95,7 @@ Some constrained targets disable the web panel to stay within flash limits. If y
Useful CLI commands:
- `get wifi.status`: shows WiFi state, IP address, channel, and signal when connected.
- `get wifi.status`: shows Wi-Fi state, IP address, channel, and signal when connected.
- `get web.status`: shows whether the web panel is up and which URL to use.
Example:
@@ -294,29 +330,9 @@ On mobile:
- quick command buttons collapse into a two-column layout
- top navigation and action groups stay compact and touch-friendly
- input rows stay usable for touch interaction
- trend cards reorganize into single-column sections where needed
- trend cards reorganise into single-column sections where needed
## Common Tasks
### Check WiFi And MQTT
1. Open the panel.
2. Press `wifi.status` in Quick `get` Commands.
3. Press `mqtt.status` in Quick `get` Commands.
4. Open `/stats` from the top navigation for the historical stats view.
### Change Device Name
1. Edit `Device Name`.
2. Press `Save`.
3. Confirm the generated command and reply in the CLI terminal box.
### Update MQTT Owner Or Email
1. Go to `MQTT Settings`.
2. Enter the new value.
3. Press `Save`.
4. Use the refresh button if you want to re-read the stored value from the repeater.
## Advanced Tasks
### Start OTA
@@ -345,7 +361,7 @@ That is expected. The panel uses a self-signed certificate generated for local u
Check:
- the repeater is on WiFi
- the repeater is on Wi-Fi
- the IP address from `get wifi.status`
- `get web.status` reports the panel as up
- your board/firmware target supports the web panel
@@ -377,7 +393,7 @@ Try:
- refreshing the browser tab
- using `Refresh` on `/stats`
- logging out and back in
- checking WiFi stability with `get wifi.status`
- checking Wi-Fi stability with `get wifi.status`
### `/stats` is unavailable