Skip to content

(Meshcore): runtime companion transport switching (BLE <-> WiFi/TCP) with persisted WiFi config + UI support#1968

Draft
just-stuff-tm wants to merge 22 commits intomeshcore-dev:devfrom
just-stuff-tm:feat/heltec-v3-runtime-transport-dev
Draft

(Meshcore): runtime companion transport switching (BLE <-> WiFi/TCP) with persisted WiFi config + UI support#1968
just-stuff-tm wants to merge 22 commits intomeshcore-dev:devfrom
just-stuff-tm:feat/heltec-v3-runtime-transport-dev

Conversation

@just-stuff-tm
Copy link

@just-stuff-tm just-stuff-tm commented Mar 8, 2026 •
edited
Loading

Feel Free To Fork and add additional board support And Submit PRs To this Branch, Lets get upstream to accept........

This PR adds a unified ESP32 companion transport layer for Heltec v3 that allows switching wireless companion transport at runtime between BLE and WiFi/TCP, without reflashing. It also adds persistent WiFi configuration, UI visibility/controls for active transport, and command documentation.

Base: upstream/dev
Diff scope: upstream/dev...feat/heltec-v3-runtime-transport-dev
Size: 10 files, +865/-31

What changed

  1. Added unified transport interface
  • New CompanionTransportInterface for ESP32 (COMPANION_ALL_TRANSPORTS) that wraps:
    • USB serial
    • BLE serial
    • WiFi TCP serial
  • Supports runtime mode switching:
    • WIRELESS_MODE_BLE
    • WIRELESS_MODE_TCP
  • Handles WiFi AP/client setup, start/stop behavior, and STA reconnect retry logic.
  1. Persisted new transport + WiFi preferences
  • Extended NodePrefs with:
    • transport_mode
    • wifi_mode
    • wifi_ssid, wifi_pwd
    • wifi_ap_ssid, wifi_ap_pwd
  • Updated DataStore read/write layout to persist these fields.
  1. Wired runtime config commands in companion logic
  • Added handling in MyMesh custom-var/CLI paths for:
    • transport (ble / tcp or wifi)
    • wifi.mode (ap / client|sta)
    • wifi.ssid, wifi.pwd
    • wifi.ap.ssid, wifi.ap.pwd
  • Applies settings immediately and saves on success.
  1. Startup initialization from saved prefs
  • main.cpp now initializes unified transport when COMPANION_ALL_TRANSPORTS is enabled.
  • Applies persisted WiFi credentials/mode and transport mode at boot.
  1. UI updates for transport awareness
  • Home screen pages split into dedicated BLE and WiFi transport pages.
  • Only relevant transport page is shown based on active mode.
  • Added long-press action to switch transport directly on-device (BLE <-> WiFi).
  • Added immediate UI refresh when transport/wifi mode changes remotely.
  • WiFi page shows AP/client status details (SSID/IP/password/open state as applicable).
  1. Build variant for Heltec v3
  • Added new PlatformIO env:
    • Heltec_v3_companion_radio_tcp_usb_ble
  • Enables COMPANION_ALL_TRANSPORTS and companion radio/UI sources.
  1. Added user docs
  • New docs/wifi_transport_command_examples.md with:
    • Raw framed protocol examples
    • Python examples
    • meshcore-cli and CLI rescue command examples
    • TCP test example

Why

This implements runtime companion transport switching for Heltec v3 and extends it to include WiFi AP/client configuration and persistence, improving field usability and reducing reflash cycles for transport changes.

Notes / compatibility

AI7NC and others added 9 commits March 6, 2026 15:22
@AI7NC
Update cli_commands.md to include path.hash.mode and loop.detect
992cc08 
Adding the new repeater cli commands introduced in 1.14

Ref: https://buymeacoffee.com/ripplebiz/path-diagnostics-improvements
@AI7NC
Update cli_commands.md
d2a6fda
@AI7NC @weebl2000
Apply suggestion from @weebl2000
721c21f 
Co-authored-by: Wessel <wessel@weebl.me>
@AI7NC @weebl2000
Apply suggestion from @weebl2000
0228d59 
Co-authored-by: Wessel <wessel@weebl.me>
@AI7NC @weebl2000
Apply suggestion from @weebl2000
4aaa557 
Co-authored-by: Wessel <wessel@weebl.me>
@AI7NC
Update cli_commands.md R399 updates
fe32f16
@AI7NC
Update cli_commands.md R402
bb45486
@AI7NC
Update cli_commands.md R400 grammer
36db50a 
Small grammar fix
@just-stuff-tm
feat(heltec_v3): unified BLE/USB/WiFi companion transport with runtim…
b872abd 
…e switching

Implements the core ask from meshcore-dev#1188 by enabling companion transport changes without re-flashing (BLE <-> serial/TCP path), and extends it per follow-up request to include WiFi/TCP network switching and CLI-configurable credentials.

- add CompanionTransportInterface for ESP32 all-transports mode
- support runtime transport switching: BLE <-> TCP/WiFi
- add WiFi config vars: wifi.mode (ap/client), wifi.ssid/pwd, wifi.ap.ssid/pwd
- persist new WiFi settings in NodePrefs/DataStore
- wire settings into startup path in main.cpp
- add MyMesh handlers for protocol + CLI Rescue commands
- update Heltec v3 tcp_usb_ble variant flags/build wiring
- improve UI: dedicated BLE/WiFi pages, hide inactive page, no overlap
- refresh UI immediately on command-driven mode changes
- show AP name/password/IP and client SSID/IP status on-device
- add docs/wifi_transport_command_examples.md with raw/python/CLI examples
@just-stuff-tm just-stuff-tm changed the title feat(heltec_v3): runtime companion transport switching (BLE <-> WiFi/TCP) with persisted WiFi config + UI support (Meshcore): runtime companion transport switching (BLE <-> WiFi/TCP) with persisted WiFi config + UI support Mar 8, 2026
@just-stuff-tm just-stuff-tm marked this pull request as draft March 8, 2026 05:53
just-stuff-tm and others added 13 commits March 8, 2026 14:50
@just-stuff-tm
update commands
43712e7
@just-stuff-tm
companion: harden runtime transport/wifi custom var controls
b61b00a
@just-stuff-tm
ui: add transport reboot countdown and wifi mode transition screens
df0cc1e
@just-stuff-tm
companion: finalize runtime transport/wifi UX, commands, and docs
fbd7105
@just-stuff-tm
heltec_v2: add all-transports companion target and build docs
dd166d2
@robekl
docs: sync CLI and payload docs with implementation
0d0b31e
@robekl
docs: sync companion and kiss protocol docs
6677b40
@ripplebiz
Merge pull request meshcore-dev#1952 from AI7NC/patch-1
c80bd9c 
Update cli_commands.md to include path.hash.mode and loop.detect
@robekl
set prv.key doc update
095f97b
@liamcottle
Merge pull request meshcore-dev#1977 from robekl/docs/implementation-…
82d1a3d 
…sync-release

Update docs to align with implementation
@just-stuff-tm
Merge branch 'meshcore-dev:main' into feat/heltec-v3-runtime-transpor…
ddf222c 
…t-dev
@just-stuff-tm
Fix companion transport state handling
9ef3b2b
@just-stuff-tm
Hide BLE PIN outside BLE mode
d07824b
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@just-stuff-tm @AI7NC @robekl @ripplebiz @liamcottle