mirror of
https://github.com/Colorado-Mesh/meshcore-bot-firmware.git
synced 2026-08-11 08:10:29 +00:00
Add repo scaffolding for Colorado-Mesh publish
Adds the project metadata and CI/release workflow needed to publish this repo under Colorado-Mesh/meshcore-bot-firmware. - LICENSE: MIT with attribution to upstream MeshCore (also MIT) - README: rewritten with badges, supported boards, install paths (web flasher / PlatformIO / esptool), bot command table, layout map, development quickstart - CONTRIBUTING: submodule + patch-queue workflow, what-goes-where, patch hygiene rules, PR expectations - RELEASE: cmesh-bot-vX.Y.Z tag scheme + procedure - CHANGELOG: Keep-a-Changelog format, seeded with the hop-coordination fix and patch-5 utility commands - Issue templates: bug_report (with bot stats prompt), feature_request, config.yml (no blank issues, link to upstream + community) - Pull request template: layer checklist, verification gates, prefs-schema impact prompt - .github/workflows/firmware-build.yml: keep PR check on representative envs (Heltec V3, RAK 4631 USB+BLE), add concurrency cancellation for PRs, scope cache key to PIO config hash - .github/workflows/release.yml: NEW; triggers on cmesh-bot-v* tag or manual dispatch, enumerates all 133 *_companion_radio_(usb|ble) envs from vendor/MeshCore/variants/, shards across 8 parallel matrix jobs, aggregates artifacts into a single draft release - scripts/verify.sh: respect MESHCORE_SKIP_APPLY_PATCHES like build-representative.sh does, so verify works when vendor already has patches applied as commits - .gitignore: add .forge.bak.*/ for forge backup directories
This commit is contained in:
cj-vana
152
README.md
152
README.md
@@ -1,15 +1,123 @@
|
||||
# Colorado MeshCore Bot Firmware
|
||||
# Colorado Mesh Bot Firmware
|
||||
|
||||
Wrapper repository for Colorado Mesh firmware-only bot work on top of upstream MeshCore companion firmware.
|
||||
[](https://github.com/Colorado-Mesh/meshcore-bot-firmware/actions/workflows/firmware-build.yml)
|
||||
[](https://github.com/Colorado-Mesh/meshcore-bot-firmware/releases)
|
||||
[](LICENSE)
|
||||
|
||||
Companion-radio firmware for the Colorado Mesh community, built on top of
|
||||
[MeshCore](https://github.com/meshcore-dev/MeshCore). It adds an in-firmware
|
||||
"firmware bot" that responds to chat commands like `ping`, `trace`, `path`,
|
||||
`status`, `neighbors`, and `magic8`, with multi-bot response coordination so
|
||||
nearby Colorado bots don't all reply at once.
|
||||
|
||||
The bot runs entirely on-device — no internet, no companion-app bridge, no
|
||||
cloud. Useful as a low-friction probe / utility node on the Colorado mesh.
|
||||
|
||||
## What's different from upstream MeshCore
|
||||
|
||||
The release-built firmware applies a patch queue (`patches/meshcore/`) on top
|
||||
of a pinned MeshCore commit. The patches add:
|
||||
|
||||
- A bot command registry (`help`, `cmd`, `ping`, `test`, `hello`, `about`,
|
||||
`roll`, `dice`, `status`, `channels`, `version`, `stats`, `magic8`, `path`,
|
||||
`trace`, `tracer`, `prefix`, `time`, `lora`, `id`, `neighbors`)
|
||||
- Channel-aware response policy (`#bot`, `#testing` for normal commands;
|
||||
`#emergency` for emergency forwards to `Public`; all other channels ignored)
|
||||
- Multi-bot response coordinator with hop-aware delay, bounded TTL, and
|
||||
fingerprint-based suppression so duplicates are avoided across the mesh
|
||||
- Direct-message (DM) prefixless command parsing
|
||||
- Two-byte path hash default for compact traces
|
||||
- Private-key import/export disabled in release builds
|
||||
- Host-side bot prefs (CLI tunable channels, delay, advert intervals,
|
||||
known-bot list)
|
||||
|
||||
See `patches/meshcore/` for the full set; each patch is a standalone commit
|
||||
re-exported from the submodule.
|
||||
|
||||
## Supported boards
|
||||
|
||||
The release workflow builds **every** `*_companion_radio_usb` and
|
||||
`*_companion_radio_ble` PlatformIO environment exposed by upstream MeshCore
|
||||
— 133 boards across ESP32, NRF52, RP2040, and STM32 platforms (Heltec V3,
|
||||
RAK 4631, LilyGo T-Echo, T-Beam, T-Deck, Xiao S3, Nano G2, ThinkNode,
|
||||
Meshtiny, Pico W, and many more). See the
|
||||
[latest release assets](https://github.com/Colorado-Mesh/meshcore-bot-firmware/releases/latest)
|
||||
for the full list.
|
||||
|
||||
PR CI builds a smaller "representative" matrix (Heltec V3 USB+BLE, RAK 4631
|
||||
USB+BLE) on every push, so the most common boards get fast feedback.
|
||||
|
||||
## Install
|
||||
|
||||
Three ways to flash:
|
||||
|
||||
### MeshCore web flasher (easiest)
|
||||
|
||||
1. Open [flasher.meshcore.io](https://flasher.meshcore.io) in Chrome/Edge.
|
||||
2. Pick "Custom firmware" and drag in the `*-merged.bin` (ESP32) or `*.uf2`
|
||||
(NRF52) file from the
|
||||
[latest release](https://github.com/Colorado-Mesh/meshcore-bot-firmware/releases/latest)
|
||||
for your board.
|
||||
3. Plug the board in, click "Connect", and flash.
|
||||
|
||||
### PlatformIO (from source)
|
||||
|
||||
```sh
|
||||
git clone --recurse-submodules https://github.com/Colorado-Mesh/meshcore-bot-firmware.git
|
||||
cd meshcore-bot-firmware
|
||||
python3 -m venv .venv && .venv/bin/python -m pip install --upgrade platformio
|
||||
bash scripts/apply-patches.sh
|
||||
cd vendor/MeshCore
|
||||
pio run -e Heltec_v3_companion_radio_usb -t upload --upload-port /dev/cu.usbserial-0001
|
||||
```
|
||||
|
||||
Swap the env name for your board (see
|
||||
`grep -rE '^\[env:' vendor/MeshCore/variants/`).
|
||||
|
||||
### esptool / nrfutil (manual)
|
||||
|
||||
ESP32 boards: `esptool.py write_flash 0x0 <board>-merged.bin`
|
||||
NRF52 boards: drag the `.uf2` onto the bootloader mass-storage volume, or
|
||||
use `adafruit-nrfutil dfu serial -pkg <board>.zip -p <port>`.
|
||||
|
||||
## Using the bot
|
||||
|
||||
Once flashed, the bot joins the channels configured in its prefs. By default
|
||||
those are `#bot`, `#testing`, `#emergency`, and `Public`. Send commands on
|
||||
`#bot` (or DM the bot directly) without any prefix — for example:
|
||||
|
||||
| Command | Response |
|
||||
|---|---|
|
||||
| `ping` | `Pong` |
|
||||
| `hello` | `Hello @[<your-name>], from <bot-name>` |
|
||||
| `path` | Compact route summary back to you, e.g. `Path 3h@2B SNR -6.25 \| 2751 -> ea4d -> 430d` |
|
||||
| `trace` | Active trace request along your reverse path |
|
||||
| `status` | Bot uptime, battery, storage, send counters |
|
||||
| `neighbors` | Nodes heard directly within the last hour |
|
||||
| `version` | Firmware version + build date |
|
||||
| `magic8 <question>` | Classic 8-ball answer |
|
||||
| `help` | List all commands |
|
||||
|
||||
In any other channel the bot stays silent (except `#emergency`, which it
|
||||
re-forwards to `Public`).
|
||||
|
||||
If you're testing alongside other Colorado bots, the response coordinator
|
||||
adds a hop-aware delay (~1.5 s per hop, capped at 8 s) so the closest bot
|
||||
wins the race and others suppress. This avoids spam on the channel.
|
||||
|
||||
## Layout
|
||||
|
||||
- `vendor/MeshCore/` — pinned upstream MeshCore submodule.
|
||||
- `patches/meshcore/` — ordered patch queue applied to the submodule.
|
||||
- `colorado/` — Colorado Mesh overlay files, fixtures, and notes.
|
||||
- `scripts/` — wrapper scripts for patch and build workflows.
|
||||
- `scripts/` — wrapper scripts for patch, build, verify, and size-report
|
||||
workflows.
|
||||
- `tests/firmware_bot/` — host-side C++ unit tests for the bot code
|
||||
(compile and run on your machine, no hardware required).
|
||||
- `.github/workflows/` — PR CI (`firmware-build.yml`) and tag-driven release
|
||||
(`release.yml`).
|
||||
|
||||
## Patch workflow
|
||||
## Local development
|
||||
|
||||
Initialize the submodule and apply patches:
|
||||
|
||||
@@ -18,25 +126,41 @@ git submodule update --init --recursive
|
||||
bash scripts/apply-patches.sh
|
||||
```
|
||||
|
||||
Develop firmware changes in `vendor/MeshCore`, commit them in that submodule worktree, then export the patch queue:
|
||||
Make firmware changes inside `vendor/MeshCore`, commit them in the submodule
|
||||
worktree, then export the patch queue:
|
||||
|
||||
```sh
|
||||
bash scripts/export-patches.sh origin/main
|
||||
```
|
||||
|
||||
## Representative builds
|
||||
|
||||
Build the release-gate companion environments and write size reports:
|
||||
Build the four representative companion environments and write size reports:
|
||||
|
||||
```sh
|
||||
bash scripts/build-representative.sh --baseline
|
||||
```
|
||||
|
||||
The build writes PlatformIO logs and `summary.json` to `out/size/`, and copied firmware artifacts to `out/firmware/`.
|
||||
Run host tests + safety checks:
|
||||
|
||||
Representative companion build environments:
|
||||
```sh
|
||||
python3 tests/firmware_bot/run_tests.py
|
||||
bash scripts/check-bot-safety.sh
|
||||
# Or all in one go:
|
||||
MESHCORE_SKIP_APPLY_PATCHES=1 bash scripts/verify.sh --no-build
|
||||
```
|
||||
|
||||
- `Heltec_v3_companion_radio_usb`
|
||||
- `Heltec_v3_companion_radio_ble`
|
||||
- `RAK_4631_companion_radio_usb`
|
||||
- `RAK_4631_companion_radio_ble`
|
||||
## Releases
|
||||
|
||||
Releases are cut by pushing a `cmesh-bot-vX.Y.Z` tag. See
|
||||
[RELEASE.md](RELEASE.md) for the full procedure.
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: edit inside
|
||||
`vendor/MeshCore`, re-export the patch queue, run `verify.sh`, open a PR.
|
||||
Patches stay in `patches/meshcore/` so reviewers can see exactly what
|
||||
deviates from upstream.
|
||||
|
||||
## License
|
||||
|
||||
MIT, including upstream MeshCore. See [LICENSE](LICENSE) and
|
||||
[vendor/MeshCore/license.txt](vendor/MeshCore/license.txt).
|
||||
|
||||
Reference in New Issue
Block a user