mirror of https://github.com/Colorado-Mesh/meshcore-bot-firmware.git synced 2026-08-11 08:10:29 +00:00

Files

cj-vana 74dcf979a9 Update MeshCore base to v1.16.0; add sig/air/coin; ship 139 boards

- Bump vendor/MeshCore pin 910b1bee -> bbb58cce (upstream v1.16.0,
  272 commits) and rebase the 14-patch bot queue onto it; one trivial
  conflict in the MyMesh constructor.
- New patch 15: sig/air/coin commands plus registry-derived help and
  cmd listings ('cmd diag' for the diagnostic set). BOT_PREFS_VERSION
  bumped to 7. Host tests cover the new commands and assert every
  discoverable registry entry appears in a listing.
- Re-include six boards fixed upstream (Pico W, RAK 11310, Waveshare
  RP2040 LoRa, Xiao RP2040, Nibble USB+BLE) after local test builds;
  remaining exclusions are BLE flash-size only.
- Fix release env enumeration to strip CR line endings so envs in CRLF
  variant files (Minewsemi ME25LS01, Wio WM1110, Nibble) are counted
  and built; verified all three build locally.
- Refresh README/CHANGELOG/RELEASE/CONTRIBUTING for the new base and
  command set.

Verified: host tests, safety checks, 4 representative builds, and 9
additional env builds all pass; the 15-patch queue applies cleanly to
pristine bbb58cce.

2026-07-10 15:34:07 -06:00

4.6 KiB

Raw Permalink Blame History

Contributing to Colorado Mesh Bot Firmware

Thanks for your interest. This repo is a thin wrapper around upstream MeshCore: most firmware code lives in vendor/MeshCore/ (a git submodule) and is applied via the patch queue in patches/meshcore/. Colorado-only overlay files, tests, and tooling live at the wrapper level.

Quick reference

Task	Command
Bootstrap	`git submodule update --init --recursive && bash scripts/apply-patches.sh`
Run host tests + safety checks	`MESHCORE_SKIP_APPLY_PATCHES=1 bash scripts/verify.sh --no-build`
Build representative firmwares	`bash scripts/build-representative.sh --baseline`
Export patch queue after edits	`bash scripts/export-patches.sh origin/main`

Development workflow

The submodule is a real git repo. Iterate inside it like normal:

Bootstrap once (clone with --recurse-submodules, or run git submodule update --init --recursive).
Apply patches with bash scripts/apply-patches.sh. This commits the patch queue on top of origin/main in the submodule, leaving you with a clean tree pinned to a known state.
Edit inside vendor/MeshCore/. Compile with pio run -e <env> and commit your changes in the submodule with descriptive messages.
Re-export the patch queue with bash scripts/export-patches.sh origin/main. This deletes patches/meshcore/*.patch and regenerates it from the submodule commits since origin/main. Each patch corresponds to one submodule commit, so keep commits small and focused.
Run host tests (python3 tests/firmware_bot/run_tests.py). Fast, no hardware needed.
Run safety checks (bash scripts/check-bot-safety.sh), which verify the firmware doesn't expose private keys, network bridges, or other debug-only features in release builds.
(Optional) Build representative envs with bash scripts/build-representative.sh --baseline to confirm the binaries still link and to inspect size impact in out/size/summary.json.
Commit at the wrapper level with the regenerated patches, any test/script changes, and the updated submodule pointer. PR-ready.

What goes where

Firmware and library code that must live inside MeshCore for PlatformIO builds is developed inside vendor/MeshCore/ and exported as a patch.
Host-side C++ tests live in tests/firmware_bot/ at the wrapper level. They #include MeshCore headers via the script's -I flag.
Tooling, build scripts, and CI live in scripts/ and .github/ at the wrapper level.
Colorado-specific docs, fixtures, and board notes live in colorado/.

Patch hygiene

One conceptual change per patch / submodule commit.
Prefer additive changes (#if CMESH_BOT_ENABLED guards, new files in examples/companion_radio/) over edits to broadly-used upstream code. This keeps merges with upstream MeshCore manageable.
When changing a stored format (e.g., bot prefs), bump BOT_PREFS_VERSION so deployed bots reset to the new defaults instead of loading broken legacy state.
Add a host test for new behavior whenever it's testable without hardware. The bot has 48+ host tests covering the registry, parser, policy, coordinator, and command output strings.

CI

PRs run .github/workflows/firmware-build.yml, which:

Runs host tests + safety checks (scripts/verify.sh --no-build).
Builds the four representative companion environments (Heltec V3 and RAK 4631, USB + BLE).
Uploads firmware + size reports as workflow artifacts.

Releases run .github/workflows/release.yml on cmesh-bot-v* tags and build every non-excluded companion USB+BLE environment (139 at the current pin); see RELEASE.md.

Pull request expectations

One PR per logical change. Bundle related patches; keep unrelated work in separate PRs.
Describe the why as well as the what.
If you touched response timing, coordination, or anything that could silently drop messages, include a host test that exercises the failure mode and explain how you verified on hardware (which boards, what commands, what hop counts).
CI must be green.
Don't commit .forge/ workflow artifacts, the .venv/ directory, or PlatformIO build output. They're gitignored.

Reporting bugs

Open an issue. For firmware bugs, include the output of bot stats (over USB CLI rescue), the firmware version, board, and a minimal reproduction.

Code of conduct

Be respectful, be patient, assume good faith. We're all volunteers building infrastructure for a mesh community.

4.6 KiB Raw Permalink Blame History