shade/MeshCoreTel-firmware
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

chore: update README

Browse Source
This commit is contained in:
Jared Dohrman
2026-04-09 17:12:40 +10:00
parent bd60d0e631
commit a9e197ddfc
2 changed files with 205 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/github-pages.yml
+5 -5
View File
@@ -14,12 +14,12 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout Repo
uses: actions/checkout@v6
uses: actions/checkout@v6.0.2
- name: Setup Python
uses: actions/setup-python@v6
uses: actions/setup-python@v6.2.0
with:
python-version: '3.11'
python-version: "3.11"
- name: Install uv
uses: astral-sh/setup-uv@v8.0.0
@@ -35,8 +35,8 @@ jobs:
run: printf '%s\n' "${{ vars.PAGES_CNAME }}" > site/CNAME
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v4
uses: peaceiris/actions-gh-pages@v4.0.0
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./site
publish_branch: 'gh-pages'
publish_branch: "gh-pages"
README.md
+200 -11
View File
@@ -1,25 +1,214 @@
# MeshCore-EastMesh
MeshCore-EastMesh is MeshCore with an EastMesh layer on top, focused on providing an out-of-the-box experience for EastMesh users.
EastMesh firmware builds for MeshCore, with MQTT repeaters, WiFi companions, and simple release downloads for supported boards.
The firmware remains MeshCore. This repository adds EastMesh-specific packaging, release automation, versioning, and integrations such as native WiFi and MQTT support, while staying aligned with upstream MeshCore releases.
This repository keeps the upstream MeshCore firmware intact and adds an EastMesh layer on top for packaging, release automation, WiFi-enabled companion builds, and MQTT-enabled repeater builds.
## Coming Soon
## What This Repo Adds
Documentation for flashing, configuration, supported hardware, and EastMesh-specific features is still being prepared.
- `*_repeater_mqtt` firmware targets with:
- native WiFi
- MQTT over WSS with JWT auth
- optional local HTTPS config panel on supported ESP32 targets
- `*_companion_radio_wifi` firmware targets for WiFi-connected companion devices
- 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
For now, this repository is primarily used for:
## Releases
- EastMesh firmware builds and release automation
- EastMesh versioning on top of upstream MeshCore releases
- ongoing integration of native WiFi and MQTT support
Prebuilt firmware is published on GitHub Releases:
## Development
- <https://github.com/xJARiD/MeshCore-EastMesh/releases>
Python tooling in this repo is managed with [`uv`](https://docs.astral.sh/uv/).
For flashing guidance, including when to use `.bin` vs `-merged.bin`, see:
- [docs/releases.md](./docs/releases.md)
The custom firmware flasher site is:
- <https://flasher.meshcore.io/>
## Install uv
This repo uses `uv` for Python tooling and runs PlatformIO through `uv run`.
Official install docs:
- <https://docs.astral.sh/uv/getting-started/installation/>
Common install methods:
macOS and Linux:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Homebrew:
```bash
brew install uv
```
Windows PowerShell:
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
## Common Repo Usage
Install tooling:
```bash
uv sync
```
See [RELEASE.md](./RELEASE.md) for the current release process and tag format.
List available build targets:
```bash
bash build.sh list
```
Build a single target:
```bash
uv run pio run -e heltec_v4_repeater_mqtt
uv run pio run -e heltec_v4_companion_radio_wifi
```
Build with release-style version metadata:
```bash
export FIRMWARE_VERSION=v1.14.1
export EASTMESH_VERSION=v1.0.1
bash build.sh build-firmware heltec_v4_repeater_mqtt
```
Flash a target:
```bash
uv run pio run -e heltec_v4_repeater_mqtt -t upload --upload-port /dev/tty.usbmodemXXXX
```
Open a serial monitor:
```bash
uv run pio device monitor --port /dev/tty.usbmodemXXXX --baud 115200
```
Build docs locally:
```bash
uv run --group docs mkdocs serve
uv run --group docs mkdocs build
```
## Key Files
- [`build.sh`](./build.sh)
- main local build wrapper
- injects `FIRMWARE_VERSION`, `CLIENT_VERSION`, and EastMesh release metadata
- [`pyproject.toml`](./pyproject.toml)
- Python tooling and docs dependencies
- [`platformio.ini`](./platformio.ini)
- root PlatformIO config and ESP32 helper scripts
- [`variants/eastmesh_mqtt/platformio.ini`](./variants/eastmesh_mqtt/platformio.ini)
- shared EastMesh MQTT repeater env definitions
- [`examples/simple_repeater/MyMesh.cpp`](./examples/simple_repeater/MyMesh.cpp)
- repeater CLI wiring, MQTT command surface, and web allowlist integration
- [`src/helpers/mqtt/MQTTUplink.cpp`](./src/helpers/mqtt/MQTTUplink.cpp)
- MQTT uplink implementation, HTTPS web panel, WSS/JWT handling, and repeater WiFi control
- [`examples/companion_radio`](./examples/companion_radio)
- companion firmware implementation
- [`RELEASE.md`](./RELEASE.md)
- tag formats and release workflow behavior
- [`docs/`](./docs)
- EastMesh-focused docs published to GitHub Pages
## Key EastMesh Features
### MQTT Repeater Additions
- hardcoded broker support for:
- `eastmesh-au`
- `letsmesh-eu`
- `letsmesh-us`
- WSS transport at `/mqtt`
- JWT auth using the device identity
- CLI controls for:
- WiFi credentials
- WiFi powersaving
- MQTT endpoint enablement
- MQTT packet and raw publishing
- owner public key and email
- local web panel enablement
### Local Web Panel
On supported `*_repeater_mqtt` 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`
Some constrained targets disable the panel to stay within flash limits. For example, `Xiao_C3_repeater_mqtt` builds with `WITH_WEB_PANEL=0`.
### Companion WiFi Additions
`*_companion_radio_wifi` targets now support persisted WiFi rescue commands:
- `get wifi.status`
- `get wifi.ssid`
- `get wifi.powersaving`
- `set wifi.ssid <ssid>`
- `set wifi.pwd <password>`
- `set wifi.powersaving none|min|max`
## Active GitHub Workflows
- `.github/workflows/build-companion-wifi-firmwares.yml`
- `.github/workflows/build-repeater-mqtt-firmwares.yml`
- `.github/workflows/pr-build-check.yml`
- `.github/workflows/push-build-check.yml`
- `.github/workflows/github-pages.yml`
The current release workflows intentionally focus only on:
- `companion-wifi`
- `repeater-mqtt`
## Release Tags
Current release tags are:
```bash
git tag companion-wifi-v1.14.1
git tag repeater-mqtt-eastmesh-v1.0.1
```
Companion WiFi uses the upstream MeshCore version in the tag.
Repeater MQTT uses:
- `OFFICIAL_MESHCORE_VERSION` from GitHub Actions variables as `FIRMWARE_VERSION`
- the EastMesh tag version as `EASTMESH_VERSION`
See [RELEASE.md](./RELEASE.md) for the full release flow.
## Documentation
Published docs site:
- <https://xjarid.github.io/MeshCore-EastMesh/>
Current docs pages:
- [Home](./docs/index.md)
- [Download and Flash Releases](./docs/releases.md)
- [Build Locally With uv](./docs/local-builds.md)
- [Custom CLI Commands](./docs/custom-cli.md)