fix: use stable by-id path for dongle, add flashing docs, BL706 firmware v1.00.01

2026-08-01 21:22:45 -07:00
parent 9e85a6d538
commit da72ab3cba
6 changed files with 448 additions and 164 deletions
@@ -0,0 +1,87 @@
+# ThirdReality BL706 USB Dongle — Firmware Flashing Reference
+
+Based on the [ThirdReality Zigbee 3.0 USB Dongle](https://github.com/thirdreality/ThirdReality-Zigbee-3.0-USB-dongle)
+repo (cloned at `/opt/david/src/ThirdReality-Zigbee-3.0-USB-dongle/`).
+
+## Hardware
+
+- Chip: Bouffalo Lab **BL706** (NOT BL702 — different firmware!)
+- USB bridge: CH340 (`1a86:7523`, appears as `/dev/ttyUSB0`)
+- Protocol: **BLZ** (not ZiGate — firmware v1.00+)
+- Config: `adapter: blz`, `baudrate: 2000000` in zigbee2mqtt `configuration.yaml`
+
+## CRITICAL: BL702 vs BL706 firmware
+
+The ThirdReality dongle uses a **BL706** chip. The DevCube flashing tool
+takes `--chipname=bl702` (flash layout), but the **firmware binary itself**
+must be built for BL706, not BL702.
+
+Firmware files named `R3_bl702_dongle.bin` (v1.00.07, v1.00.12) are for
+**BL702 chips** and will NOT boot on BL706. Always use firmware files
+named `R3_706_dongle*.bin`.
+
+## Working firmware: BLZ v1.00.01 (confirmed on BL706)
+
+Saved in this repo at:
+- `infra/zigbee2mqtt/R3_706_dongle_v1.00.01.bin`
+- `infra/zigbee2mqtt/partition_cfg_2M.toml`
+
+## Entering Bootloader Mode
+
+Hold the **boot button** (pinhole on the dongle) while plugging into USB.
+Release after ~1 second. **No LED** when in bootloader mode.
+
+## Flashing
+
+```bash
+BFLASH="/opt/david/src/ThirdReality-Zigbee-3.0-USB-dongle/Flashing-Tool
+  /BouffaloLabDevCube-v1.9.0/bflb_iot_tool-ubuntu"
+FIRMWARE="./infra/zigbee2mqtt/R3_706_dongle_v1.00.01.bin"
+PARTITION="./infra/zigbee2mqtt/partition_cfg_2M.toml"
+
+$BFLASH \
+  --chipname=bl702 \
+  --interface=uart \
+  --port=/dev/ttyUSB0 \
+  --baudrate=2000000 \
+  --xtal=32M \
+  --firmware=$FIRMWARE \
+  --pt=$PARTITION
+```
+
+### Critical flags
+
+| Flag | Value | Why |
+|---|---|---|
+| `--chipname` | `bl702` | Flash layout (not chip model — BL706 uses BL702 layout) |
+| `--interface` | `uart` | CH340 provides serial passthrough |
+| `--baudrate` | `2000000` | Must match the dongle's bootloader rate |
+| `--xtal` | `32M` | Crystal frequency for bootheader generation |
+| `--pt` | `partition_cfg_2M.toml` | **Must use 2M** — firmware overflows 1M |
+
+## After Flashing
+
+1. Tool prints `[All Success]` with SHA verification
+2. **Fully unplug** the dongle (wait 5s for power drain)
+3. Replug **without** holding any button
+4. LED should light up immediately — chip is running the new firmware
+
+## Firmware Compatibility
+
+| Version | File name | BL706 compatible? |
+|---|---|---|
+| BLZ v1.00.01 | `R3_706_dongle_v1.00.01.bin` | **YES** (confirmed working) |
+| BLZ v1.00.07 | `R3_bl702_dongle.bin` (misnamed) | NO — built for BL702 |
+| BLZ v1.00.12 | `R3_bl702_dongle.bin` (misnamed) | NO — built for BL702 |
+| Legacy ZiGate v0.00.21 | `R3_706_dongle.bin` | Untested (no BLZ support) |
+
+The v1.00.01 firmware file is in the ThirdReality repo at
+`Image/Coordinator/blz/v1.00.01/R3_706_dongle_v1.00.01/`.
+
+## Recurring Issue
+
+After power loss, the BL706 firmware can corrupt itself (reports
+`deviceId: 0xBEEF`, `addEndpoint` fails with `frameId:21`). The chip
+responds to UART resets but refuses all application-layer commands.
+The fix is always to **reflash with BL706-compatible firmware** —
+there's no software recovery.