Add opt-in NimBLE Full Companion trials for V4 and XIAO S3

This commit is contained in:
mikecarper committed 2026-09-08 09:30:31 -07:00
1 parent 7ff11a2d64
commit 7f1bd8b1d2
11 files changed
+789 -27

No files matched your search

+111
View File
@@ -0,0 +1,111 @@
# ESP32-S3 NimBLE Full Companion trial
These optional builds use NimBLE-Arduino 2.5.1 with the existing ESP32 Arduino
2.0.17 toolchain. They are hardware qualification builds, outside the normal
release matrix and firmware picker.
| Hardware | Trial environment | Contacts | Channels | Offline queue |
| --- | --- | ---: | ---: | ---: |
| Heltec V4.2/V4.3 OLED, FEM on | `heltec_v4_2_v4_3_companion_radio_full_femon_nimble` | 350 | 40 | 512 |
| XIAO ESP32-S3 with WIO SX1262 | `Xiao_S3_WIO_companion_radio_full_nimble` | 350 | 40 | 256 |
The XIAO profile uses WIO radio pins CS 41, DIO1 39, BUSY 40 and RESET 42.
It is not the generic XIAO profile for separately wired radio modules. Both
boards retain their parent Full Companion features, USB mOTA sender, WiFi
update slots, and PSRAM-backed offline queue. The V4 also retains direct MQTT.
## Build
Enable the optional configuration in the ignored `platformio.local.ini`:
```ini
[platformio]
extra_configs =
variants/*/platformio.ini
platformio.nimble.ini
```
If that file already contains local settings, merge this list with them. Run
one PlatformIO/build.sh command at a time. Both commands below use USA Cascade:
```sh
OUTPUT_DIR=.releases/nimble-v4 bash build.sh build-firmware \
heltec_v4_2_v4_3_companion_radio_full_femon_nimble \
--firmware-version v1.17.1.5-halo-keymind-cascade-nimble-test \
--radio-preset usa-cascadia --profile cascade --standard --require-ota
OUTPUT_DIR=.releases/nimble-xiao bash build.sh build-firmware \
Xiao_S3_WIO_companion_radio_full_nimble \
--firmware-version v1.17.1.5-halo-keymind-cascade-nimble-test \
--radio-preset usa-cascadia --profile cascade --standard --require-ota
```
Use the merged image at address 0 for a USB installation. The V4 uses 16 MB
flash; the XIAO uses 8 MB. Both use DIO flash mode. Use the application-only
`.bin` for an existing, matching WiFi OTA layout. Remove the optional config
entry when finished to return to the ordinary release matrix.
## Bluetooth identity and pairing
All existing MAC settings remain available from the ASCII USB terminal and
the app's authenticated local CLI. A setting takes effect after reboot.
| Command | Behavior |
| --- | --- |
| `get bluetooth.mac` | Show the saved MAC policy. |
| `set bluetooth.mac C2:17:15:04:00:01` | Use this custom random-static address. |
| `set bluetooth.mac random` | Generate one address and retain it across boots. |
| `set bluetooth.mac random-every-boot` | Generate a new address on each boot. |
| `set bluetooth.mac random-after-connect` | Rotate on the next boot after an authenticated connection; otherwise retain the address. |
| `set bluetooth.mac default` | Restore the factory Bluetooth address. |
| `set bluetooth.stealth on` | Pair once, then accept the saved bonded peer. |
| `set bluetooth.stealth off` | Restore ordinary discovery without changing the MAC policy. |
| `get bluetooth.stealth` | Show pairing or bonded-peer-only state. |
The `ble.mac` and `ble.stealth` aliases also work. A literal custom address must
be a valid BLE random-static address (first byte C0-FF). Forget the old entry
in the phone's Bluetooth settings and pair again after an address change or
switching Bluetooth libraries. Existing Bluedroid bonds are not migrated.
Stealth does not disable the selected rotation policy. If rotation changes
the address on reboot, first pairing opens again for the new identity.
Pairing requires encryption, PIN authentication and a stored bond. NimBLE's
controller byte order is converted explicitly, so a custom address appears
over the air in the order entered. Failed identity setup stops advertising
and retries initialization instead of advertising the wrong address.
## V4 WiFi setup QR
The active WiFi setup page displays a compact QR code with a one-pixel white
border. The normal open setup network fits a 44 x 44 pixel code, with 2 x 2
pixel modules. The SSID, portal address and `HOLD STOP` hint remain beside it.
Short-click to leave the page; hold the button on this page to start or stop
the setup AP. From USB, `start webconfig ap` starts the same setup session.
## Regression checks
```sh
python3 -B test/test_nimble_companion.py
python3 -B test/test_bluetooth_mac_contract.py
python3 -B test/test_bluetooth_pairing_ui.py
python3 -B test/test_heltec_v4_wifi_setup_page.py
python3 -B test/test_firmware_ram.py
python3 -B test/test_esp32_dram.py
python3 -B test/test_shared_mota_queue.py
pio test -e native -f test_companion_node_prefs \
-f test_ble_tx_stall_watchdog -f test_companion_frame_queue \
-f test_display_driver
```
The adapter test compiles the actual transport under address/undefined-behavior
sanitizers with API doubles. It injects allocation, identity and bond failures;
checks PIN authentication and stealth; and exercises 176-byte frames, MTU and
notification subscription gating, retry and duplicate prevention. Embedded
builds compile against the pinned real library. RAM reports retain the existing
wireless budget; linked headroom is not a measurement of live free heap.
Hardware qualification must additionally verify pairing and reconnection,
advertised addresses for every MAC policy, contact synchronization, WiFi/BLE
coexistence, and uptime under load. BlueZ results do not establish iOS or
Android camera/pairing compatibility.