diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml index c77ef1ea..c78baa5f 100644 --- a/.github/workflows/github-pages.yml +++ b/.github/workflows/github-pages.yml @@ -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" diff --git a/README.md b/README.md index 84082525..bbce26d7 100644 --- a/README.md +++ b/README.md @@ -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 +- -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: + +- + +## Install uv + +This repo uses `uv` for Python tooling and runs PlatformIO through `uv run`. + +Official install docs: + +- + +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 ` +- `set wifi.pwd ` +- `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: + +- + +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)