Docs/tyutool guide section

docs/tos-tools/tools-tyutool.md

@@ -24,11 +24,11 @@ tyutool runs on Windows, Linux, and macOS. Choose the version that matches your
 
 tyutool is currently available in two versions, **V2** and **V3**, with the following key differences:
 
-- **V3** (latest): Completely rewritten with a **Rust (Tauri 2) + Vue 3** architecture for better cross-platform compatibility. **Recommended for Mac users.** Audio debugging and batch flashing are not yet supported.
-- **V2**: Original architecture with full feature support, including audio debugging and batch flashing.
+- **V3** (latest): Completely rewritten with a **Rust (Tauri 2) + Vue 3** architecture for better cross-platform compatibility. **Recommended for Mac users.** Now supports batch flashing and authorization; audio debugging is not yet supported.
+- **V2**: Original architecture with full feature support, including audio debugging.
 
 :::note
-V3 does not yet support audio debugging and batch flashing from V2. If you need these features, please download V2.
+V3 does not yet support V2's audio debugging — download V2 if you need it. For the complete V3 feature set (flashing, serial debug, settings, batch flash & auth, CLI reference), see the [tyutool V3 usage guide](../tyutool/index.md).
 :::
 
 | Platform | Source (Recommended) |
@@ -69,10 +69,10 @@ After opening tyutool_gui, the interface is displayed as follows:
 
 <img src="https://images.tuyacn.com/fe-static/docs/img/273ba9fc-5077-47bd-94d2-275747ca7232.png" alt="tyutool flashing view" width="800" />
 
-- ① Select the chip.
-- ② Click `Browse` and select the firmware file to flash (the bin file containing `_QIO`).
-- ③ Select the device port for flashing. For Tuya official development boards and some partner development boards, hovering over a serial port indicates whether it is a flashing/authorization port or a log port.
-- ④ Click `Start flash` to begin flashing the firmware.
+1. Select the chip.
+2. Click `Browse` and select the firmware file to flash (the bin file containing `_QIO`).
+3. Select the device port for flashing. For Tuya official development boards and some partner development boards, hovering over a serial port indicates whether it is a flashing/authorization port or a log port.
+4. Click `Start flash` to begin flashing the firmware.
 
 :::tip
 The default baud rate for flashing is 921600. If you find the flashing speed too slow, you can increase the baud rate appropriately. However, increasing the baud rate may cause the firmware flashing to fail.
@@ -86,11 +86,11 @@ After opening tyutool_gui, click the `Authorize` tab. The interface is as follow
 
 <img src="https://images.tuyacn.com/fe-static/docs/img/aa0e7635-2952-4322-8696-3a866b01a6ec.png" alt="tyutool authorization view" width="800" />
 
-- ① Click the `Authorize` tab.
-- ② Select the authorization serial port.
-- ③ Select the authorization baud rate.
-- ④ Enter the `UUID` and `AuthKey`.
-- ⑤ Click `Start Authorization`.
+1. Click the `Authorize` tab.
+2. Select the authorization serial port.
+3. Select the authorization baud rate.
+4. Enter the `UUID` and `AuthKey`.
+5. Click `Start Authorization`.
 
 :::tip
 The authorization UART and the flashing UART are the same. Keep the UART default configuration (baud rate: 115200, data bits: 8, stop bits: 1, parity: none).

docs/tyutool/batch-auth-developer.md

@@ -0,0 +1,115 @@
+---
+title: "Batch Auth: Developer Guide"
+sidebar_label: Developer Guide
+description: "For firmware developers — the TuyaOpen UART CLI command contract a firmware must implement to be batch-authorizable by tyutool, plus a self-test checklist."
+keywords:
+  - tyutool batch auth
+  - developer guide
+  - uart cli protocol
+  - authorize contract
+  - self-test
+  - tuyaopen
+---
+
+Written for **firmware developers**: to make a firmware batch-authorizable by tyutool, it must implement a set of TuyaOpen UART CLI commands. Below is the complete protocol contract and a **self-test checklist**.
+
+:::note[On the wrong page?]
+Operators should read the [Operator Guide](./batch-auth-operator.md).
+:::
+
+## Protocol essence
+
+The authorization protocol is a set of **text commands for the TuyaOpen interactive shell** (pure ASCII, each terminated by `\r\n`, no frame header / checksum / opcode). It is a completely separate thing from the Beken BootROM binary protocol used for flashing. The default baud rate is `115200` 8N1; on power-up the device presents a `tuya>` prompt. The authoritative source is `tuya_authorize.c`.
+
+:::tip[How to enable the CLI on a TuyaOpen-based firmware]
+The firmware must register it actively: ① `tal_cli_init()` (defaults to uart0; for a different uart use `tal_cli_init_with_uart(uart_num)`); ② `tuya_authorize_init()` (registers `auth` / `auth-read` / `read_mac`). Call both in `user_main()`. Code:
+
+```c
+void user_main(void)
+{
+    // ... tal_kv_init / tal_sw_timer_init / tal_workq_init etc.
+#if !defined(PLATFORM_UBUNTU) || (PLATFORM_UBUNTU == 0)
+    tal_cli_init();          // Initialize the CLI (default uart0)
+    tuya_authorize_init();   // Register auth / auth-read / read_mac commands
+    tuya_app_cli_init();     // Your app-specific commands (optional)
+#endif
+    // ... tuya_iot_init(...) etc.
+}
+```
+
+:::note
+On a TuyaOpen-based firmware, three lines are enough. The command table and self-test checklist below mainly target self-built or ported firmware.
+:::
+
+## Commands you must implement
+
+| Command (`\r\n` terminated) | Purpose | What the firmware must echo |
+| :-- | :-- | :-- |
+| `sys_log_enable off` | Capability probe + disable logging | New: `OK: log disabled`; old: `No command` or just `tuya>` |
+| `sys_version` | Read firmware version | One line: `project.version x.y.z` |
+| `read_mac` | Read MAC | `XX:XX:XX:XX:XX:FF` (6 colon-separated segments; or with a prefix label `LABEL:XX:...:FF` — 7 segments) |
+| `auth-read` or `auth-read <n>` | Read current authorization | Authorized: two lines `<uuid>` / `<authkey>` then the prompt; empty/unauthorized: `Authorization read failure.`; partial echo placeholder `uuidxxxxxxxxxxxxxxxx` (treated as unauthorized) |
+| `auth <uuid> <authkey>` or `auth <uuid> <authkey> <n>` | Write authorization | Bad length: `uuid length must be 20/16, authkey length must be 32` (not executed); KV success: `Authorization write succeeds.` (some versions don't print on reboot; tyutool re-reads via auth-read to verify); OTP success: `Authorization write to OTP Succeeds.`; OTP failure: `Authorization write to OTP failure.` |
+
+:::note
+The firmware should echo each command line. Log lines (`[MM-DD HH:MM:SS ...]`) and ANSI escapes are stripped automatically by tyutool.
+:::
+
+## Credential length rules
+
+- `UUID` is exactly 16 or 20 characters.
+- `AuthKey` is exactly 32 characters.
+- The placeholder UUID is `uuidxxxxxxxxxxxxxxxx`.
+- UUID legal characters: alphanumeric plus `- _ .`.
+- AuthKey: any printable ASCII character.
+
+## KV vs OTP
+
+| Mode | Read command | Write command |
+| :-- | :-- | :-- |
+| KV | `auth-read` | `auth <uuid> <authkey>` |
+| OTP | `auth-read 1` | `auth <uuid> <authkey> 1` |
+
+Key points:
+
+- OTP is T5AI only.
+- OTP writes are slow (60s total timeout + 30s silent window; reads have a 30s silent window).
+- OTP write failure retries at most 3 times (does not corrupt already-written data).
+- Reading an empty OTP region returns `Authorization read failure.` (treated as unauthorized).
+
+:::danger
+OTP writes are irreversible. Always validate with KV first.
+:::
+
+## MAC validation rules
+
+`read_mac` must return a valid MAC: 6 colon-separated two-digit-hex segments (case-insensitive, uppercased internally); a non-hex prefix label is allowed (`LABEL:XX:...:XX` — 7 segments); dashes, equals signs, and spaces are not recognized. The T5/T5AI factory default MAC `C8:47:8C:00:00:18` means "not personalized" — if tyutool reads it, it aborts authorization for that device.
+
+## Self-test checklist
+With a serial tool at 115200 8N1, verify each item:
+
+1. The `tuya>` prompt appears.
+2. `sys_log_enable off` → `OK: log disabled` (or `No command` on old firmware).
+3. `sys_version` → `project.version x.y.z`.
+4. `read_mac` → a valid MAC.
+5. `auth-read` (unauthorized) → `Authorization read failure.`.
+6. `auth <valid uuid+authkey>` → `Authorization write succeeds.` (KV) / `...to OTP Succeeds.` (OTP).
+7. A follow-up `auth-read` reads back the same UUID + AuthKey.
+8. `auth <too-short uuid> <key>` → a length error and the authorization is unchanged.
+9. (T5AI + OTP only) `auth <uuid> <authkey> 1` → OTP success, and `auth-read 1` reads it back.
+
+:::tip
+Self-test with real, purchased credentials; do OTP last.
+:::
+
+## Integration paths
+
+- **Path A (recommended):** the firmware carries its own authorization capability (TuyaOpen-based or self-implemented); the batch run uses `auth-only` mode.
+- **Path B:** flash the official auth-firmware (`assets/auth-firmware/` provides a `.bin` per chip) to temporarily bring up authorization; the corresponding batch mode is `flash-then-auth`.
+
+## Configuration handoff
+Fill these in for the operator, one item per line: chip model; operation mode (A/B); firmware filename + version; the two baud rates (flash / auth); storage mode (KV/OTP — flag OTP prominently); conflict policy (skip/overwrite — OTP can only skip); wiring notes (**confirm RTS is correctly wired to the chip's reset pin**); MAC uniqueness guarantee (each device's MAC must be globally unique and non-repeating; tyutool does not validate MAC conflicts); special notes.
+
+:::note
+The handoff sheet lets the operator "just execute it"; for later troubleshooting you can reconstruct the agreement against the [batch archive](./batch-auth-operator.md#archiving).
+:::

docs/tyutool/batch-auth-operator.md

@@ -0,0 +1,204 @@
+---
+title: "Batch Auth: Operator Guide"
+sidebar_label: Operator Guide
+description: "For operators using tyutool for batch flashing and authorization — the do-it-in-order workflow from prep checklist through configuration, wiring, running, reading results, archiving, and safety."
+keywords:
+  - tyutool batch auth
+  - operator guide
+  - batch flashing workflow
+  - archive
+  - safety rules
+  - tuyaopen
+---
+
+Written for **operators using tyutool for batch flashing and authorization** — a "just do it" order, no technical background needed.
+
+:::note
+Firmware developers should read the [Developer Guide](./batch-auth-developer.md).
+:::
+
+The workflow, in order: **① Pre-flight checklist → ② Configuration → ③ Wiring & start → ④ Read results · troubleshooting · safety rules**.
+
+## What this tool does
+
+Plug several devices into several serial ports, click "Start all", and flash + authorize them simultaneously, with authorization codes read automatically from an Excel sheet.
+
+<img src="https://images.tuyacn.com/fe-static/docs/img/3e3b6ba5-5431-40cc-b108-f3bd08553c64.png" alt="Batch page — completion banner / dashboard (flash totals · auth totals · this batch) / config panel / toolbar (auto-assign · port filter · read-all · start-all) / port list" width="800" />
+
+*Batch page — completion banner / dashboard (flash totals · auth totals · this batch) / config panel / toolbar (auto-assign · port filter · read-all · start-all) / port list.*
+
+## Pre-flight checklist
+
+| Item | How to know it is ready |
+| :-- | :-- |
+| Desktop tyutool | Installed and launches |
+| Authorization-code Excel | Has at least `UUID` + `AuthKey` columns; purchased from [tuyaopen.ai/pricing](https://tuyaopen.ai/pricing) |
+| Devices + serial cables | Wired and devices can enter download mode |
+| Serial drivers | CH340/CP2102/FT232 installed |
+| Firmware file | The `.bin` for this batch |
+
+Installer packages (version pinned for reference — always check [GitHub Releases](https://github.com/tuya/tyutool/releases) for the latest):
+
+| Platform | File |
+| :-- | :-- |
+| Windows | `..._windows_x86_64_nsis_x.x.x.exe` |
+| macOS (Universal) | `..._macos_universal_dmg_x.x.x.dmg` |
+| Linux | `..._linux_x86_64_appimage_x.x.x.AppImage` (run `chmod +x` first) |
+
+:::warning[T5/T5AI wiring]
+These devices have two serial ports — be sure to connect the flashing/authorization port, not the log port.
+:::
+
+:::warning[Authorization codes are valuable]
+Keep the Excel safe.
+:::
+
+### Configuration handoff
+
+| Config item | Developer fills | Operator verifies |
+| :-- | :-- | :-- |
+| Chip model | e.g. `esp32` / `t5ai` | Matches the device |
+| Operation mode | auth-only vs flash-then-auth (Path A/B) | "Flash firmware" switch matches |
+| Firmware file & version | filename + version | `batch-summary.json` records SHA256 |
+| Flash baud rate | e.g. 921600 | Set correctly |
+| Auth baud rate | e.g. 115200 | Set correctly |
+| Storage mode | KV / OTP | OTP → single-device validation first |
+| Conflict policy | skip / overwrite | OTP can only skip |
+| Authorization sheet | remaining ≥ new devices in this batch | Recover/retry of registered devices doesn't consume new codes |
+| Wiring | notes | **Confirm RTS wired to reset pin** |
+| MAC uniqueness | each MAC globally unique | tyutool does **not** check MAC conflicts — a duplicate MAC makes devices share an auth code |
+| Single-device smoke test | passed | Done before scaling |
+| Special notes | — | Read |
+
+:::tip
+If something doesn't line up, stop and confirm with the developer — don't change the configuration yourself.
+:::
+
+## Workflow
+
+Go to **Toolbox → Batch flash & auth**.
+
+:::note
+The first time you enter, a disclaimer dialog appears (irreversible operation). You can tick "don't show again"; to re-show it see [Settings](./settings.md#about).
+:::
+
+### Phase 1 — Configuration
+
+1. Pick the chip (ESP32 / T5AI; for auth-only choose `other`).
+2. Flash baud rate.
+3. Auth baud rate.
+4. Whether to flash firmware (flash-then-auth).
+5. Firmware file (local / default auth-firmware).
+6. Pick the firmware location or choose a version.
+
+<img src="https://images.tuyacn.com/fe-static/docs/img/54fcbb92-0ecd-491e-9b31-9d69a7da1a9c.png" alt="Configuration area — shared config panel" width="800" />
+
+*Configuration area — shared config panel.*
+
+1. Pick the authorization sheet (`.xlsx`).
+2. View statistics: total / used / in-use / remaining (assigning codes to new devices needs remaining > 0; recovering/retrying already-registered devices can start even with remaining 0 — they find their original code by MAC).
+3. Devices already carrying authorization: skip (recommended) / overwrite.
+
+<img src="https://images.tuyacn.com/fe-static/docs/img/1af06abc-e83e-4714-9ab6-20f169839b1c.png" alt="Batch auth configuration — sheet statistics" width="800" />
+
+*Batch auth configuration — sheet statistics.*
+
+(T5AI only) Pick the storage mode: KV is rewritable; OTP writes once and is irreversible (see [Safety](#safety-rules)).
+
+### Phase 2 — Wiring & start
+
+:::tip
+First run one device all the way through → small-batch 2–4 devices → then the whole batch.
+:::
+
+Once wired, two steps:
+
+1. Click **Auto-assign** (scans and adds slots, one row per port showing "idle").
+2. Click **Start all** (if more than 8 idle ports, a confirmation prompt appears first).
+
+:::warning[Last 30-second check before start]
+Re-read each config line against the handoff sheet. If OTP: single-device validation done?
+:::
+
+<img src="https://images.tuyacn.com/fe-static/docs/img/ba1412f6-fa8a-411d-b67c-cfbe3e4991b2.png" alt="Toolbar and port list — slots per port" width="800" />
+
+*Toolbar and port list — slots per port.*
+
+:::note[Other toolbar buttons]
+**② Port filter · ③ Read all (read-only, no write) · ④ Cancel · ⑤ Retry failed · ⑦ Read single port**.
+:::
+
+### Phase 3 — Wait and verify
+
+1. Watch the dashboard until it completes (the banner shows: all success / all failed / partial success / all skipped).
+2. Verify row by row (on failure, look at retry).
+3. Once the whole order is done, click "Archive" (you don't need to archive mid-batch rounds).
+
+<img src="https://images.tuyacn.com/fe-static/docs/img/15b90b10-3ea7-4ff5-8192-1aff75260d80.png" alt="Dashboard and completion banner (archive button on the right)" width="800" />
+
+*Dashboard and completion banner (archive button on the right).*
+
+## Reading results
+
+| Status | Meaning | What to do |
+| :-- | :-- | :-- |
+| `done` | Complete, good unit | — |
+| `failed` | Failed | Retry |
+| `skipped` | Already authorized, skipped per policy | — |
+| `no_code` | New device but remaining = 0 | Top up the sheet and rerun |
+| other | In progress | Wait |
+
+## Archiving
+One "Start all" = one round; one authorization sheet = one order (often many rounds). Archiving is per order.
+
+:::info
+One-click archive: pick a directory and it creates a timestamped folder `batch-archive_20260717-143205_esp32/` containing: authorization-sheet copy / firmware (with SHA256) / logs.zip / `batch-summary.json` / `batch-slots.csv`. The summary's `lastRun` and the CSV are only a snapshot of the last round.
+:::
+
+Archive contents:
+
+| File | What it is |
+| :-- | :-- |
+| Authorization-sheet Excel copy | The sheet used |
+| Firmware file | The flashed `.bin` |
+| logs.zip | Compressed logs |
+| batch-summary.json | Run summary |
+| batch-slots.csv | Per-slot snapshot of the last round |
+| Completion banner screenshot | Optional record |
+
+:::warning
+The archive contains UUID + AuthKey — prevent leaks. For troubleshooting, share only the logs and error info; do not send the authorization sheet out.
+:::
+
+## Troubleshooting
+
+| Symptom | What to do |
+| :-- | :-- |
+| App won't open / blank screen | See [FAQ · Linux blank window](./faq.md#linux-blank-window-webkit-compositing-failure) |
+| Port doesn't appear | Swap cable/port, install drivers, close other apps — see [FAQ · ports](./faq.md#device--serial-port-not-in-the-dropdown) |
+| All failed | Run a single device through, drop to 115200, check power supply |
+| Excel "file in use" | Close Excel/WPS and reselect |
+| Excel sheet invalid | Check the `UUID` + `AuthKey` columns and their lengths |
+| Need detailed logs | Save per [Save the scene](#save-the-scene-first), see [FAQ · logs](./faq.md#how-to-report-a-bug-with-logs) |
+
+### Save the scene first
+While the scene is still live, click "Archive" to save everything; then manually add three things: a UI screenshot (mask the AuthKey, UUID can stay) / the problem device itself (label it and set it aside) / a one-line symptom description.
+
+:::note
+Don't wait and don't leak: archive the same day; when sharing out, give only the logs and error info.
+:::
+
+## Safety rules
+This is the only feature that triggers irreversible hardware operations.
+
+:::danger[Rule 1: OTP writes are irreversible]
+OTP (T5AI only) burns authorization into the chip once and can never be undone. A wrong configuration ruins the whole batch — always validate by running one device all the way through before going to scale.
+:::
+
+<img src="https://images.tuyacn.com/fe-static/docs/img/024dd799-e550-451b-8694-f7c8759242a1.png" alt="When OTP is selected, the UI warns the write cannot be undone" width="800" />
+
+*When OTP is selected, the UI warns the write cannot be undone.*
+
+:::danger[Rule 2: devices marked "cancelled after write" must be set aside]
+Devices carrying the "cancelled-after-write" danger badge may already have had authorization written and their state is uncertain — they are neither good units nor safe to rerun directly. Set them aside and verify individually.
+:::