Fix Companion pairing PIN display and truthful identity startup

This commit is contained in:
mikecarper committed 2026-10-02 12:42:26 -07:00
1 parent a2854f8f43
commit 202930de8f
31 files changed
+1915 -148

No files matched your search

+13
View File
@@ -916,6 +916,19 @@ timer. This also applies to previously saved button modes. Saved `off` and
pairing-only modes still suppress the boot screen. Repeaters, room servers,
and sensors do not gain this Companion-only boot wake.
Startup shows `Loading identity` while reading a saved identity. `Generating key`
and its spinner are used only when creating a replacement/new identity;
they end before flash persistence, which shows `Saving identity`. A normal
boot with a valid saved identity never regenerates it. An erased filesystem
does require a new identity unless one is restored.
On Full Companion screens, an unpaired Bluetooth PIN takes priority over a
USB/TCP connected label. Button wake shows the PIN banner without requiring
USB to be disconnected; a second navigation press can leave this preview.
An actual phone pairing request wakes pairing-enabled display modes and keeps
the banner visible until completion or its two-minute expiry. Bluetooth
scanning alone is not a pairing request.
- `off`: stays dark, including boot and pairing.
- `on`: stays on while the device is awake.
- `button`: a physical button, keyboard/navigation input, or supported touch
@@ -0,0 +1,114 @@
# Heltec V4 preview4 Bluetooth/OLED regression validation
Date: 2026-10-02. These are observations on one physical Heltec V4.3 OLED,
not qualification of every board or phone. The preview4 images are local,
unreleased builds with uncommitted changes on `keymindCascade` at
`7324bf06efef236009dac2d507775fa4e19bc856`.
## Target and method
- Host: MercerWoodMesh Raspberry Pi, built-in BlueZ Bluetooth controller.
- Target: Heltec V4.3 OLED, ESP32-S3 revision 0.2, 16 MB flash, 2 MB PSRAM;
exact USB serial `44:1B:F6:69:CF:98`.
- Version under test: `v1.17.1.8-preview4`, build 02-Oct-2026, USA Cascade
Full Companion, OLED, no expansion, NimBLE-Arduino 2.5.1.
- Diagnostic environment: `heltec_v4_companion_pairing_ui_hil_preview4` in
`platformio.heltec-v4-preview4.ini`.
- Diagnostic application SHA-256:
`df0c109e7c3e99e43ec388a4017da8971f41572f51afeac779cddc4a56e69d14`.
- Helper: `tools/hil/v4_pairing_stealth.py`; Linux `bleak`, `dbus-fast`,
`pyserial`, target-restricted passkey agent. Test PIN **246810**, deliberately
different from NimBLE's 123456 callback sentinel.
A complete, hash-checked 16 MB original flash backup was taken first. Only
`otadata` and the application were written for the temporary diagnostic image;
the bootloader, partition table, NVS and SPIFFS were retained. No other Pi radio
was flashed. The helper did not request LoRa transmissions; ordinary background
radio activity was not disabled.
`COMPANION_PAIRING_UI_HIL` is an opt-in diagnostic macro, absent from production
builds. It records actual startup phases, display power/pairing/USB state, public
identity, and the real 1024-byte SSD1306 framebuffer. It does not access the
private key. Frame capture occurred during an actual outstanding passkey
request, not a manually invoked firmware callback.
## Observed hardware results
| Check | Result |
| --- | --- |
| Fresh pairing with a non-default PIN | Passed twice: exactly one actual passkey request per fresh pairing; BlueZ reported Paired and Bonded. |
| PIN display while USB remains connected | Passed twice: display on, pairing active, USB present, and captured frame containing `PAIR PIN 246810`. This verifies the display driver's real framebuffer and wake state, not an optical photograph. |
| Protected BLE transport | Passed: MTU 179, 82-byte device-info response and 176-byte ATT command payload, live CLI/status responses, zero core error flags. |
| Custom MAC with stealth | Passed: fresh discovery/pairing, live `bonded-peer-only advertising` status, bonded reconnect with no new PIN, then USB-commanded reboot and another bonded reconnect with no new PIN. |
| Saved random MAC | Passed: USB-commanded reboot retained its address with stealth enabled. |
| `random-after-connect`, unused boot | Passed: reboot over USB, without BLE authentication, retained the address. |
| `random-after-connect`, authenticated boot | Passed: actual authenticated BLE connection armed the next boot; address stayed unchanged during that session and changed on the following USB reboot. The new address was discoverable with stealth retained. |
| `random-every-boot` | Passed: two successive USB-commanded boots used different addresses, with stealth enabled. |
| Saved identity startup | Passed: Starting/Loading phases only, no Generating/Saving phase. The same public identity was retained throughout the run. |
The suite finished with `suite_passed`, six observed application addresses,
two captured OLED frames, and `identity_preserved: true`. An earlier harness
attempt stopped because it did not recognize a terminal prompt immediately
followed by a diagnostic line; the parser was corrected and the complete suite
rerun. This was not a BLE pairing failure.
Stealth on ESP32 uses minimal, unnamed, allowlisted advertising after pairing;
it is not radio invisibility. Bonded reconnection and policy/rotation behavior
were tested here. Actual advertising-payload capture and rejection of an
unbonded second central were not part of this run.
## Original target restored
After the suite, the complete original 16 MB image was written back. Esptool
verified the flash data hash. Live serial readback then confirmed:
- Original version:
`v1.18.0.1-halo-keymind-cascade-dev-app-wifi-test-6f6d1a2a`,
protocol 14, build 01-Oct-2026.
- Original board and public identity unchanged.
- Bluetooth on, factory/default MAC, stealth off.
- Original default Bluetooth name, USB display mode `button-pairing`, and
USB logging off.
The full backup remains private on the Pi. Raw diagnostic logs and captured
OLED pixels remain in the ignored local preview4 output folder; neither the
backup nor unreviewed radio logs are published. Only test-created BlueZ device
records were removed by the helper.
## Automated regression coverage and builds
- 117 targeted native cases passed across identity generation, display layout,
serial routing, and Companion preferences. This was not the entire native
suite.
- 39 Python cases passed across the real NimBLE adapter, pairing UI, saved/new
identity startup, startup display, display power, MAC/stealth contracts,
settings persistence, inbox rendering, preference transaction, and Bluetooth
control suites. Executable C++ fixtures use the production implementation;
sanitizer-enabled fixtures also passed.
- The unit-test workflow now includes the real NimBLE callback dispatch,
USB-connected pairing display, identity-startup, and startup-screen suites.
No GitHub run was triggered for these uncommitted changes.
- Production V3 and V4 Full Companion preview4 builds passed linked-memory
qualification. Available/required internal heap: V3 200,144/182,016 bytes;
V4 252,152/177,920 bytes. Diagnostic V4: 252,136/177,920 bytes.
The NimBLE regression fixture reproduces the pinned library's dispatch rule:
a non-default static passkey bypasses `onPassKeyDisplay()`. Firmware now leaves
NimBLE's sentinel at 123456 and returns the actual configured PIN through that
callback, preserving authentication while notifying the UI. Tests cover random
and saved PINs, USB coexistence, button wake/navigation, disabled display/BLE,
saved identity, generation, persistence failures, and removal of the generation
label once generation finishes.
## Remaining hardware gates
- Physical Heltec V3, including its user button; the Pi board here was V4.
- Optical OLED inspection and physical button gestures (covered in executable
host fixtures, not remotely actuated on this board).
- Android/iOS MeshCore apps, privacy-address reconnection, and an unbonded
second physical central.
- Actual post-pairing advertising payload capture.
- All-power-removed cold boot; this run used commanded reboots only.
- Destructive missing/corrupt identity and bond/write-failure injection on
hardware; these branches were exercised by host fixtures without erasing
the real node's identity.
@@ -4,6 +4,10 @@ This preview contains USA Cascade builds for RAK3401 Repeater and Heltec V4 OLED
The [RAK3401 source test run](https://github.com/mikecarper/MeshCore/actions/runs/36810565194) and [Heltec V4 source test run](https://github.com/mikecarper/MeshCore/actions/runs/36826971285) passed. The RAK3401 UF2 and DFU application payloads match, with verified DFU CRCs. Both RAK3401 packages passed capability and memory checks. The four Heltec V4 OLED variants passed capability and memory qualification. These are build/package checks, not physical on-device tests of every variant.
## Preview4 local regression validation
- [Heltec V4 Bluetooth pairing, USB OLED, stealth and MAC rotation hardware results](heltec-v4-preview4-bluetooth-oled.md) — 2026-10-02, unreleased local preview4 build; the original Pi V4 firmware and settings were restored afterward.
## RAK3401 package results
- [Build information](BUILD-INFO.json)