# 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.