Skip to content

Add companion radio debug bot firmware variant (multi-board)#2755

Closed
zfouts wants to merge 4 commits into
meshcore-dev:mainfrom
zfouts:feat/add_companion_meshbot
Closed

Add companion radio debug bot firmware variant (multi-board)#2755
zfouts wants to merge 4 commits into
meshcore-dev:mainfrom
zfouts:feat/add_companion_meshbot

Conversation

@zfouts

@zfouts zfouts commented Jun 12, 2026

Copy link
Copy Markdown

Implements the built-in debug bot discussed in #2754

What this adds

A new opt-in firmware type: the stock BLE companion with a small mesh debug
bot built in, for range testing and checking pathing in your local mesh.
When the node gets a direct message starting with ! it replies over the
mesh with diagnostics, and the message still gets forwarded to the phone app
like normal.

Commands: !ping (the requester's SNR/RSSI/hop count into the node), !rf,
!path (hop hashes resolved to contact names), !status, !stats,
!neighbors, !uptime, !time, !ver.

It can also answer in group channels, but only ones on an allow-list, which
is empty by default. So no spamming Public.

Keeping it polite on the airwaves

Replies are rate limited three ways: a global minimum gap between replies, a
per-sender cooldown, and a hard cap per minute. A flood of ! messages won't
turn the node into an airtime hog. Replies never start with ! so bots can't
trigger each other, and unknown commands are ignored silently.

Runtime configuration

No mesh-side config, so nobody on the mesh can mess with your bot. It's
controlled through the existing custom vars frames (CMD_GET_CUSTOM_VARS /
CMD_SET_CUSTOM_VAR), e.g. with meshcore-cli:

      set bot 0|1                      # enable/disable replies
      set bot.channels "#test,#bots"   # channel allow-list
      get custom

Settings persist to flash and survive reboots.

Design: zero changes to existing files

Everything lives in examples/companion_radio_bot/ plus one env file
(variants/bot_envs/platformio.ini). No upstream file is modified, so this
can't break any existing build:

  • main.cpp includes the stock companion main.cpp with MyMesh renamed
    to a BotMesh subclass that overrides onMessageRecv /
    onChannelMessageRecv. The env links the original symbol back with
    -Wl,--defsym,the_mesh=the_bot_mesh.
  • BotTarget.cpp compiles the board's stock target.cpp with the global
    sensors object swapped for a thin subclass that adds the two custom
    vars. Works unmodified across boards, including the T1000-E's custom
    T1000SensorManager.
  • The bot only uses MyMesh's public API. Stock builds never compile any
    of these files.

Boards

Xiao_S3_WIO, Xiao_nrf52, Heltec_v3, heltec_v4, RAK_4631,
RAK_3401 (WisMesh 1W Booster), t1000e, Heltec_t114, each as
<board>_companion_radio_ble_bot. Adding another board is about 12 lines
of platformio.ini that extend its stock BLE companion env. Full docs in
examples/companion_radio_bot/BOT_README.md.

Testing

  • All 8 envs build clean (ESP32-S3 and nRF52840 toolchains).
  • Tested on real hardware: Xiao S3 WIO, Xiao nRF52 WIO, Heltec V4, and the
    RAK WisMesh 1W Booster (RAK3401 + RAK13302).
  • Verified in the linked ELFs that sensors resolves to the wrapper and
    the_mesh to the bot subclass on both architectures.

liamcottle and others added 4 commits June 9, 2026 00:31
…on-parse-failure

Fix: CMD_SEND_RAW_PACKET not freeing packet on parse failure
A separate firmware type layering a mesh debug bot on top of the stock
BLE companion example without modifying upstream sources. Replies to
!-prefixed commands (!ping, !rf, !path, !status, !stats, !neighbors,
!uptime, !time, !ver) from direct messages or allow-listed channels,
with rate limiting.

Runtime config rides the companion protocol's custom vars ("bot",
"bot.channels") settable via meshcore-cli or the phone app, persisted
to flash. Envs for Xiao S3 WIO, Xiao nRF52, Heltec V3, Heltec V4,
RAK4631, RAK3401 (WisMesh 1W Booster), T1000-E and Heltec T114 in
variants/bot_envs/platformio.ini.
@zfouts zfouts force-pushed the feat/add_companion_meshbot branch from 875b4a3 to 65fef12 Compare June 12, 2026 15:46
@zfouts

zfouts commented Jun 12, 2026

Copy link
Copy Markdown
Author

Closing as this should not be a core feature.

@zfouts zfouts closed this Jun 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants