Imported from xJARiD/MeshCore-EastMesh (
AGENTS.md). Install upstream withnpx skills add xJARiD/MeshCore-EastMesh. Copyright stays with the author.
AGENTS.md
Purpose
EastMesh layer on top of upstream MeshCore.
Default: preserve upstream behavior.
Only modify code for clearly scoped EastMesh features:
*_repeater_observer*_companion_radio_wifi- MQTT uplink/broker
- repeater web panel
- docs, releases, automation
Principles
- Minimal, targeted changes
- Prefer additive over modifying upstream code
- Avoid unrelated refactors
- Maintain parity with upstream behavior
Guardrails
Upstream
- Do not modify unrelated MeshCore logic
- Do not change CLI semantics unless explicitly required
- Do not introduce breaking changes to existing targets
Docs (update in same PR when practical)
| Change | File |
|---|---|
| CLI | eastmesh-docs/custom-cli.md |
| Web panel UI/behavior | eastmesh-docs/web-panel.md |
| Releases | release-notes.yml |
| Flashing guidance | eastmesh-docs/releases.md |
Web Panel Gate
If editing examples/simple_repeater/MyMesh.cpp, also update eastmesh-docs/custom-cli.md.
Tooling
- Use
uv+ PlatformIO viauv run - Do not assume global
pio
Build Policy
Builds are expensive. Avoid unless necessary.
Do NOT build for:
- docs / HTML / CSS only
Prefer:
- user-run local builds
- reasoning over execution
Build only if:
- high-risk change
- firmware behavior must be verified
Commands
uv sync
uv run pio run -e <env>
uv run pio device monitor --port <port> --baud 115200
uv run --group docs zensical serve
uv run --group docs zensical build
Do not assume pio is installed globally.
Common Commands
List build targets:
bash eastmesh-build.sh list
Build a single target:
uv run pio run -e heltec_v4_repeater_observer
uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_observer
uv run pio run -e heltec_v4_companion_radio_wifi
uv run pio run -e T_Beam_S3_Supreme_SX1262_companion_radio_wifi
Build with release-style metadata:
export FIRMWARE_VERSION=v1.15.0
export EASTMESH_VERSION=v2026.5.1
bash eastmesh-build.sh build-firmware heltec_v4_repeater_observer
bash eastmesh-build.sh build-firmware T_Beam_S3_Supreme_SX1262_repeater_observer
Flash a target:
uv run pio run -e heltec_v4_repeater_observer -t upload --upload-port /dev/tty.usbmodemXXXX
uv run pio run -e T_Beam_S3_Supreme_SX1262_repeater_observer -t upload --upload-port /dev/tty.usbmodemXXXX
Key Files
eastmesh-build.sh— EastMesh build wrapperbuild.sh— upstream MeshCore build wrapper retained for merge hygieneplatformio.inivariants/eastmesh/platformio.iniexamples/simple_repeater/MyMesh.cppsrc/helpers/mqtt/MQTTUplink.cppeastmesh-docs/*.mdRELEASE.mdrelease-notes.yml
Workflow Ownership
EastMesh workflows use the eastmesh-*.yml prefix in .github/workflows/.
Upstream MeshCore workflows may remain under their original filenames for merge hygiene. Do not adapt them for EastMesh behavior; keep them close to upstream and disable them in GitHub Actions for this repository.
Docs Sync Requirements
If you change any of the following, update docs in the same PR when practical:
- Web-panel commands:
- update
eastmesh-docs/custom-cli.md
- update
- Web-panel user-facing behavior, sections, controls, or troubleshooting:
- update
eastmesh-docs/web-panel.md
- update
- EastMesh CLI additions or changed semantics:
- update
eastmesh-docs/custom-cli.md
- update
- Release/tag preparation:
- update
release-notes.yml
- update
- Flashing/release asset guidance:
- update
eastmesh-docs/releases.md
- update
Observer Notes
*_repeater_observer builds may include the local HTTPS web panel on supported ESP32 targets.
Operational guidance already reflected in docs:
- use for initial setup and troubleshooting
- prefer
set web offafterward for maximum heap headroom
Companion WiFi Notes
*_companion_radio_wifi targets support persisted Wi-Fi rescue commands via serial CLI Rescue.
Do not document companion rescue commands in repeater docs. Do not assume web-panel behavior applies.
Companion release/version rule:
- companion tags use the official upstream MeshCore release version only
- the current official MeshCore version is
v1.15.0 - companion releases are only cut when
meshcore-dev/MeshCorehas made an official release - do not invent separate EastMesh companion version numbers
Release Workflow
Current tag formats:
git tag companion-wifi-v1.15.0
git tag repeater-bridge-espnow-v1.15.0
git tag observer-eastmesh-bridge-espnow-v2026.5.1
git tag observer-eastmesh-bridge-mqtt-v2026.7.0
git tag observer-eastmesh-v2026.5.1
Rules:
companion-wifitags use the upstream MeshCore version directlyrepeater-bridge-espnowtags use the upstream MeshCore version directlyobserver-eastmesh-bridge-espnowtags use the EastMesh release version in the tagobserver-eastmesh-bridge-mqtttags use the EastMesh release version in the tagobserver-eastmeshtags use the EastMesh release version in the tag- GitHub Actions variable
OFFICIAL_MESHCORE_VERSIONsupplies the upstream base version for Observer EastMesh, Observer ESP-NOW EastMesh, and Observer MQTT Bridge EastMesh release builds - if the upstream MeshCore release version changes, update
OFFICIAL_MESHCORE_VERSIONin GitHub before cutting release tags
Typical release flow:
- Update
OFFICIAL_MESHCORE_VERSIONif upstream changed. - Update
release-notes.ymlondevelop. - Merge the release PR from
developtomain. - Create the desired release tag or tags on the target commit on
main. - Push the tags.
Upstream Sync Workflow
When asked to pull from upstream MeshCore:
- pull from
meshcore-dev/MeshCore:dev - start from local
develop - create a temporary integration branch off
develop - merge upstream
devinto that temporary integration branch - resolve conflicts in a way that preserves EastMesh-specific changes
- merge the finished integration branch back into
develop
Do not merge upstream directly into main.
Scope Boundaries
Do NOT (unless asked):
- rename tracks
- change tag formats
- expand cli without updating docs
- change upstream CLI semantics
- introduce new versioning schemes
Commit Messages
Use concise, conventional prefixes:
feat:new functionalityfix:bug fixesdocs:documentation changeschore:maintenance, tooling, non-functionalrefactor:code changes without behavior change
Keep messages short and scoped.
Decision Rule
If a change is not clearly EastMesh-specific, do not modify the code. When uncertain, prefer no change or request clarification.
