From 26784bcdbeb4598d4f680a8623847dde397c1326 Mon Sep 17 00:00:00 2001 From: YangJie Date: Wed, 29 Jul 2026 18:55:36 +0800 Subject: [PATCH 1/2] docs(tyutool): add standalone tyutool V3 guide section, parallel to SDK docs - Add docs/tyutool/* (en + zh) as its own Docusaurus sidebar and navbar entry, instead of nesting the new V3 guide inside the TuyaOpen SDK docs. - Fix the stale claim in tools-tyutool.md that V3 doesn't support batch flashing, and link forward to the new guide. - Replace the old custom /tyutool-guide page with the new docs section; redirect the old URL and update all internal links that pointed to it. - Add a reusable FeatureCardGrid component and use it for the guide's feature/role navigation instead of plain bullet lists. - Clean up sidebar ordering, admonition types, heading structure, and screenshots across the new guide based on review feedback. --- docs/tos-tools/tools-tyutool.md | 24 +- docs/tyutool/batch-auth-developer.md | 115 +++ docs/tyutool/batch-auth-operator.md | 204 +++++ docs/tyutool/batch-flash-auth.md | 45 ++ docs/tyutool/cli.md | 228 ++++++ docs/tyutool/concepts.md | 94 +++ docs/tyutool/faq.md | 135 ++++ docs/tyutool/flash.md | 127 +++ docs/tyutool/getting-started.md | 128 +++ docs/tyutool/index.md | 36 + docs/tyutool/serial-debug.md | 91 +++ docs/tyutool/settings.md | 83 ++ docusaurus.config.js | 11 +- .../current/tos-tools/tools-tyutool.md | 24 +- .../current/tyutool/batch-auth-developer.md | 115 +++ .../current/tyutool/batch-auth-operator.md | 204 +++++ .../current/tyutool/batch-flash-auth.md | 45 ++ .../current/tyutool/cli.md | 228 ++++++ .../current/tyutool/concepts.md | 94 +++ .../current/tyutool/faq.md | 135 ++++ .../current/tyutool/flash.md | 127 +++ .../current/tyutool/getting-started.md | 128 +++ .../current/tyutool/index.md | 36 + .../current/tyutool/serial-debug.md | 91 +++ .../current/tyutool/settings.md | 83 ++ sidebars.js | 25 + src/components/FeatureCardGrid.jsx | 29 + src/components/FeatureCardGrid.module.css | 39 + src/data/tutorials.js | 8 +- src/pages/learn/using-license-key.jsx | 2 +- src/pages/tutorials/using-license-key.jsx | 2 +- src/pages/tyutool-guide.jsx | 683 ---------------- src/pages/tyutool-guide.module.css | 736 ------------------ src/pages/tyutool.jsx | 3 +- src/pages/web-serial.jsx | 2 +- 35 files changed, 2707 insertions(+), 1453 deletions(-) create mode 100644 docs/tyutool/batch-auth-developer.md create mode 100644 docs/tyutool/batch-auth-operator.md create mode 100644 docs/tyutool/batch-flash-auth.md create mode 100644 docs/tyutool/cli.md create mode 100644 docs/tyutool/concepts.md create mode 100644 docs/tyutool/faq.md create mode 100644 docs/tyutool/flash.md create mode 100644 docs/tyutool/getting-started.md create mode 100644 docs/tyutool/index.md create mode 100644 docs/tyutool/serial-debug.md create mode 100644 docs/tyutool/settings.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-auth-developer.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-auth-operator.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-flash-auth.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tyutool/cli.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tyutool/concepts.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tyutool/faq.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tyutool/flash.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tyutool/getting-started.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tyutool/index.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tyutool/serial-debug.md create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/tyutool/settings.md create mode 100644 src/components/FeatureCardGrid.jsx create mode 100644 src/components/FeatureCardGrid.module.css delete mode 100644 src/pages/tyutool-guide.jsx delete mode 100644 src/pages/tyutool-guide.module.css diff --git a/docs/tos-tools/tools-tyutool.md b/docs/tos-tools/tools-tyutool.md index 665867cc9..494f4db14 100644 --- a/docs/tos-tools/tools-tyutool.md +++ b/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: tyutool flashing view -- ① 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 tyutool authorization view -- ① 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). diff --git a/docs/tyutool/batch-auth-developer.md b/docs/tyutool/batch-auth-developer.md new file mode 100644 index 000000000..7c19cf148 --- /dev/null +++ b/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 ` | Read current authorization | Authorized: two lines `` / `` then the prompt; empty/unauthorized: `Authorization read failure.`; partial echo placeholder `uuidxxxxxxxxxxxxxxxx` (treated as unauthorized) | +| `auth ` or `auth ` | 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 ` | +| OTP | `auth-read 1` | `auth 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 ` → `Authorization write succeeds.` (KV) / `...to OTP Succeeds.` (OTP). +7. A follow-up `auth-read` reads back the same UUID + AuthKey. +8. `auth ` → a length error and the authorization is unchanged. +9. (T5AI + OTP only) `auth 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). +::: diff --git a/docs/tyutool/batch-auth-operator.md b/docs/tyutool/batch-auth-operator.md new file mode 100644 index 000000000..d3eed4d06 --- /dev/null +++ b/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. + +Batch page — completion banner / dashboard (flash totals · auth totals · this batch) / config panel / toolbar (auto-assign · port filter · read-all · start-all) / port list + +*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. + +Configuration area — shared config panel + +*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. + +Batch auth configuration — sheet statistics + +*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? +::: + +Toolbar and port list — slots per port + +*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). + +Dashboard and completion banner (archive button on the right) + +*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. +::: + +When OTP is selected, the UI warns the write cannot be undone + +*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. +::: diff --git a/docs/tyutool/batch-flash-auth.md b/docs/tyutool/batch-flash-auth.md new file mode 100644 index 000000000..ddff6f939 --- /dev/null +++ b/docs/tyutool/batch-flash-auth.md @@ -0,0 +1,45 @@ +--- +title: Batch Flash & Auth +description: "Overview of tyutool batch flashing and authorization — flash firmware and write authorization codes to many devices in parallel, driven by an .xlsx sheet." +keywords: + - tyutool batch + - batch flashing + - batch authorization + - otp + - parallel flashing + - tuyaopen +--- + +import FeatureCardGrid from '@site/src/components/FeatureCardGrid'; + +Plug several devices into several serial ports and **flash firmware + write authorization codes in parallel**, with the authorization codes driven by an `.xlsx` sheet. This is the most complex feature in tyutool; when the storage mode is set to **OTP**, it performs irreversible eFuse operations (T5AI only). + +:::note[Where to find it] +In the desktop app, this feature lives under **Toolbox → Batch Flash & Auth**. +::: + +## Choose your guide + +This feature involves two very different kinds of people, with two separate guides: + + + +## What these guides cover + +Between them, the two guides cover: + +- The pre-flight checklist and the developer ↔ operator configuration handoff +- Wiring, starting a run, and reading per-slot results +- Archiving a completed batch and troubleshooting failures +- The UART CLI protocol a firmware must implement to be batch-authorizable +- KV vs. OTP storage modes, and the safety rules around irreversible OTP writes + +:::danger[The most important safety note] +When the storage mode is **OTP** (T5AI only), authorization codes are burned into the chip once and can **never** be erased or changed — one wrong configuration ruins the whole batch. Always validate on a single device before going to scale. See the Operator Guide's [Safety rules](./batch-auth-operator.md#safety-rules). +::: diff --git a/docs/tyutool/cli.md b/docs/tyutool/cli.md new file mode 100644 index 000000000..2b78eb395 --- /dev/null +++ b/docs/tyutool/cli.md @@ -0,0 +1,228 @@ +--- +title: Command Line +description: "Complete tyutool command-line reference — installation, global options, the 11 subcommands (write, read, erase, list-ports, reset, monitor, authorize, update, serve, completions, usb-port-survey), supported chips, and output modes." +keywords: + - tyutool cli + - command line + - write firmware + - authorize + - monitor + - tuyaopen +--- + + +`tyutool` is a command-line tool. This page ports the complete CLI reference into the docs. + +## When to use the CLI + +For scripting / CI / headless servers / when you prefer the terminal. It shares the same `tyutool-core` flashing logic as the desktop app. + +## Installation + +Download from [GitHub Releases](https://github.com/tuya/tyutool/releases). Release assets (five platforms; each release also ships a `latest.json` with `cli..sha256`): + +| Platform | Asset | +| :-- | :-- | +| Linux x86_64 | `tyutool-cli_linux_x86_64_*.tar.gz` | +| Linux aarch64 | `tyutool-cli_linux_aarch64_*.tar.gz` | +| macOS x86_64 | `tyutool-cli_macos_x86_64_*.tar.gz` | +| macOS aarch64 | `tyutool-cli_macos_aarch64_*.tar.gz` | +| Windows x86_64 | `tyutool-cli_windows_x86_64_*.zip` | + +Install: + +```bash +# Linux / macOS (tar.gz) +tar -xzf tyutool-cli_linux_x86_64_*.tar.gz +sudo mv tyutool_cli /usr/local/bin/tyutool +chmod +x /usr/local/bin/tyutool + +# Windows (.zip): extract tyutool_cli.exe and add its folder to PATH +``` + +Verify: + +```bash +tyutool --version +tyutool list-ports +``` + +:::note +The CLI supports self-update: `tyutool update`. +::: + +## Global options + +| Option | Meaning | +| :-- | :-- | +| `--verbose` | Emit diagnostic logs to stderr | +| `--plain` | Plain ASCII, no spinner | + +Log files: one per session, `tyutool-.log`, rolling at 10 MB, cleaned on startup. Locations: + +- Linux: `~/.local/share/tyutool/` +- macOS: `~/Library/Application Support/tyutool/` +- Windows: `%APPDATA%\tyutool\` + +:::note +The rolled file naming is `tyutool-.log` → `-1.log` → `-2.log`. +::: + +Port selection: if `-p` is omitted and there is a single port, it is used automatically; with multiple ports, you pick interactively (in CI this errors out). + +## Subcommands + +### write — flash firmware + +```bash +tyutool write -d -f [-p -b -s --end ] +``` + +Example: + +```bash +tyutool write -d bk7231n -f firmware.bin -p /dev/ttyUSB0 +``` + +### read — read the flash + +```bash +tyutool read -d -f [-p -b -s -l ] +``` + +`length` defaults to `0x200000`. + +### erase — erase + +```bash +tyutool erase -d [-p -b -s -l ] +``` + +Erases the region `start … start+length`; some chips require sector alignment. + +### list-ports — list serial ports + +```bash +tyutool list-ports [--json] +``` + +Default output: tab-separated columns `path / vid:pid / usb_interface / port_role / display_name`. + +### reset — DTR/RTS hardware reset + +```bash +tyutool reset [-p -d ] +``` + +`device` defaults to `bk7231n`. + +### monitor — live serial monitor + +```bash +tyutool monitor [-p -b -d -l] +``` + +Streams to stdout, forwards keypresses interactively; exit with `Ctrl+]` or `Ctrl+C`. In a non-TTY it forwards line by line. For `t5ai` the default monitor baud is 460800; for others 115200 (note: this differs from the flash baud). + +Examples: + +```bash +tyutool monitor -p /dev/ttyUSB0 +tyutool monitor -d bk7231n -b 115200 +tyutool monitor -d t5ai +``` + +### authorize (alias `auth`) — TuyaOpen authorization + +```bash +tyutool authorize [-p -d --uuid --authkey ] +``` + +A write must pass both `uuid` and `authkey`; pass neither for an auth-read. Credentials are written to KV storage and never burn OTP/eFuse (OTP is GUI-batch only). + +Read example: + +```bash +tyutool authorize -p /dev/ttyUSB0 +``` + +Write example: + +```bash +tyutool authorize -p /dev/ttyUSB0 --uuid --authkey +``` + +### update — self-update + +```bash +tyutool update [--check] [--source github|tuya] +``` + +### serve — WebSocket server + +```bash +tyutool serve +``` + +Dev/IDE mode; default port `9527`; serves tuyaopen-ide. + +### completions — generate shell completions + +```bash +tyutool completions bash +tyutool completions zsh +tyutool completions fish +``` + +(Also: `powershell`, `elvish`.) + +### usb-port-survey — USB/serial metadata dump + +```bash +tyutool usb-port-survey +``` + +Outputs raw USB/serial metadata as JSON for cross-system debugging. + +## Supported chips +| Chip | Default baud | +| :-- | :-- | +| `bk7231n` | 921600 | +| `t2` | 921600 | +| `t3` | 921600 | +| `t1` | 921600 | +| `t5ai` | 921600 | +| `ln882h` | 115200 | +| `esp32` | 460800 | +| `esp32c3` | 460800 | +| `esp32c6` | 460800 | +| `esp32p4` | 460800 | +| `esp32s3` | 460800 | + +Chip names are case-insensitive; `-b` overrides the baud. + +## Output modes +- **Rich mode** (TTY): spinner / ANSI progress bar / `✓`. +- **Plain mode** (CI): fixed-width stage labels, long stages tick every 10%. + +Plain-mode sample output (a `write` on BK7231N): + +```text +tyutool v3.2.7 linux/x86_64 +[scan ] scanning serial ports +[conn ] connecting /dev/ttyUSB0 @ 921600 +[write] 0% 10% 20% 30% 40% 50% 60% 70% 80% 90% 100% +[ok ] write complete +``` + +Success exit code is 0. + +:::note[Cancel] +During `write` / `read` / `erase` / `authorize`, `Ctrl+C` exits gracefully (closes the port and reports `Cancelled`); `monitor` exits with code 0 on `Ctrl+]` / `Ctrl+C`. +::: + +## Developer reference + +:::note[Authoritative markdown source] +The corresponding markdown lives in the repository at [`docs/cli.md`](https://github.com/tuya/tyutool/blob/refactor/v3/docs/cli.md). Any CLI change must update `docs/cli.md` first (per the repo's `AGENTS.md`). This page is a mirror; the markdown is authoritative. +::: diff --git a/docs/tyutool/concepts.md b/docs/tyutool/concepts.md new file mode 100644 index 000000000..80fdef6c6 --- /dev/null +++ b/docs/tyutool/concepts.md @@ -0,0 +1,94 @@ +--- +title: Concepts +description: "The vocabulary behind tyutool — firmware, flashing, erase, read, authorization, UART/baud, chip models, and the terminology you will see on every page." +keywords: + - tyutool concepts + - firmware + - flashing + - authorization + - uart + - baud rate + - tuyaopen +--- + +Before clicking any buttons, take a few minutes to read this glossary — it will make every later page make sense. This page covers concepts only, not specific operations. + +tyutool talks to a device over a serial link: commands from tyutool on your computer travel through a USB-to-serial adapter as UART electrical signals to the SoC on the device, which ultimately reads and writes the flash chip. The diagram below shows the full topology of this link. + +Figure 1 — Topology of the flashing link from tyutool to the device: tyutool → USB → adapter → UART (TX/RX/GND) → SoC → Flash chip + +*Figure 1 — Topology of the flashing link from tyutool to the device: tyutool → USB → adapter → UART (TX/RX/GND) → SoC → Flash chip.* + +:::note[Reading suggestion] +New to firmware flashing? Read the first six sections in order; sections 7 and 8 work as a quick terminology reference. +::: + +## What is firmware + +Firmware is the program stored in a device's flash chip. You flash firmware to **upgrade** the device (add features), **repair** it (fix a bug), or **customize** it (load your own build). Firmware is, at its core, a block of byte data. + +## What is flashing + +Flashing (also called "burning" or "writing") is the action of writing firmware bytes into a device's flash chip. The link carries the data like this: ① tyutool reads the firmware and chops it into blocks → ② the blocks go over USB to the adapter, which converts them to UART → ③ the UART lines (TX/RX/GND) reach the SoC, which writes the flash. + +:::warning +Flashing is an overwriting write. Back up important data by [reading](#read) it first. +::: + +## Erase + +Erase clears certain regions of the flash to `0xFF`. Typical uses: clearing a region before writing, or erasing the whole chip. Erase presets: + +| Preset | Meaning | +| :-- | :-- | +| `authInfo` | Erase only the authorization-info region (UUID/AuthKey), keeping firmware and other data | +| `fullChipNoRf` | Erase the whole chip but keep the RF calibration (RF cal) region | +| `fullChip` | Erase the entire chip completely (including RF calibration) | + +:::tip +`fullChipNoRf` is the most-used "safe thorough erase." +::: + +## Read +Read is the inverse of flashing: it reads bytes out of the flash chip, used for backup (whole-chip read or read by segment). + +## Authorize +Authorize (TuyaOpen UART auth) writes a `UUID` + `AuthKey` so the device can connect to the Tuya cloud. Authorization and firmware are two independent things. + +:::danger +The `UUID` and `AuthKey` are credentials you **purchase** from Tuya. Writing forged or duplicate credentials pollutes the device pool. +::: + +Authorization has two operations: authorization read (auth-read) and authorization write (auth-write). + +## Serial / UART / baud rate +Serial communication, the USB-to-serial adapter (CH340/CP2102/FT232), the three UART lines (TX/RX/GND, wired crossed), and the baud rate: + +| Baud rate | Typical use | +| :-- | :-- | +| `115200` | The most universal, most stable default rate | +| `460800` | Faster, still reasonably stable | +| `921600` | High-speed; needs the chip and cabling to support it | + +:::tip +Starting at `115200` is the safest bet. +::: + +## Chip models +The chip model decides the communication protocol, baud rate, and flash capacity. For the full list see [Firmware Flash](./flash.md#select-a-chip) and the [command line](./cli.md). + +## tyutool terminology + +| Term | Meaning | +| :-- | :-- | +| Flash | Write firmware into the flash chip | +| Erase | Clear flash regions to `0xFF` | +| Read | Read bytes out of the flash chip | +| Authorize | Write `UUID`/`AuthKey` credentials | +| UUID | A unique device identifier (credential) | +| AuthKey | The authentication key paired with a UUID | +| Baud | The serial communication rate | +| UART | The serial protocol over TX/RX/GND lines | +| Segment | One contiguous chunk of a multi-segment flash | +| Erase preset | A named erase scope (e.g. `authInfo`) | +| MAC | The device's media-access-control address | diff --git a/docs/tyutool/faq.md b/docs/tyutool/faq.md new file mode 100644 index 000000000..594229aae --- /dev/null +++ b/docs/tyutool/faq.md @@ -0,0 +1,135 @@ +--- +title: FAQ +description: "Symptom-first troubleshooting for tyutool — ports and connections, flashing failures, authorization, and platform issues (Linux blank window, Windows WebView2), plus how to report a bug with logs." +keywords: + - tyutool faq + - troubleshooting + - flashing fails + - authorize fails + - linux blank window + - webview2 + - tuyaopen +--- + + +This page is problem-first: it lists the **symptom**, then gives the shortest path to diagnose and fix it. Both CLI snippets and GUI actions are included. + +## Connection / ports + +### Device / serial port not in the dropdown +**Symptom:** the port selector is empty, or `tyutool list-ports` prints nothing. + +1. Unplug/replug, swap cable, swap port. +2. Install the driver (CH340/CP2102/FT232). +3. Re-check with the CLI: + +```bash +tyutool list-ports +tyutool usb-port-survey # raw USB metadata for cross-system debugging +``` + +4. On macOS see [macOS serial permission](#macos-serial-permission). +5. On Linux, confirm you are in the `dialout` / `tty` group and log out and back in. + +:::tip +Click refresh or reopen the app. +::: + +### macOS serial permission +**Symptom:** the port is visible but you get a permission error. + +```bash +sudo dseditgroup -o edit -a $USER -t user dialout +``` + +Then log out and back in. On newer macOS, allow it under **Privacy & Security → Accessories**. See the project [README Troubleshooting](https://github.com/tuya/tyutool#readme). + +### Port busy +**Symptom:** `Permission denied` / `Device or resource busy`. + +Close other programs (Serial Debug, Arduino IDE, minicom, picocom); avoid running the GUI and CLI at the same time; you can turn on auto-release. + +## Flashing + +### Flash fails / handshake fails +**Symptom:** Handshake failed / Failed to sync. + +Causes: wrong chip model (`-d bk7231n` / `-d esp32` / `-d t5ai`); wrong baud (drop to 115200 first); device not in download mode (`tyutool reset`); wiring / power. + +:::warning +First do a minimal repro: `tyutool read -d -p -l 0x1000`. +::: + +### Erase reports "unaligned" +**Symptom:** `unaligned` / `address not aligned` / `sector boundary`. + +Erase requires 4 KiB alignment: + +```bash +# Correct: both start and length aligned to 4 KiB +tyutool erase -d bk7231n -s 0x0000 -l 0x200000 +tyutool erase -d bk7231n -s 0x8000 -l 0x4000 + +# Wrong: 0x9000 is not a multiple of 4 KiB +tyutool erase -d bk7231n -s 0x9000 -l 0x1000 # ❌ reports unaligned +``` + +:::tip +Use the GUI's align action, or round down to a multiple of `0x1000`. +::: + +### Progress stalls +**Symptom:** a stage sits at 0% for a long time, or retries repeatedly. + +Drop the baud (921600 → 460800 → 115200); swap cable/power; turn on debug logs or CLI `--verbose` to debug/trace (location at [CLI · global options](./cli.md#output-modes)); cancel gracefully with `Ctrl+C`. + +## Authorization + +### Authorization fails +**Symptom:** authorize write failed / UUID/AuthKey invalid. + +Credentials are one-device-once (used ones are spent); first do an auth-read `tyutool authorize -p `; `--uuid` / `--authkey` must be passed together; specify `-d` for timing. + +:::note +Credentials come from the Tuya developer platform and are bound to a chip/product. +::: + +### Credential display issues +**Symptom:** you can't see the full value, or copying yields `****`. + +The GUI masks by default — click Show or the copy button. With the CLI, auth-read: + +```bash +tyutool authorize -p +tyutool authorize -p -d esp32 # read with chip-specific timing +``` + +Clear the clipboard promptly after copying. + +## Platform + +### Linux blank window (WebKit compositing failure) +```bash +export WEBKIT_DISABLE_COMPOSITING_MODE=1 +``` + +Then launch the AppImage; you can add it to `~/.bashrc`. See the project README. + +### Windows missing WebView2 +Install the Edge WebView2 Runtime Evergreen: download page → Evergreen Standalone Installer → run and restart. + +:::note +For enterprise/offline, the Fixed Version offline package works too. +::: + +## Logs & feedback + +### How to report a bug (with logs) +1. **Export / open logs.** GUI: Settings → Diagnostics → View logs → "Export logs and report a problem" = zip + pre-filled issue. CLI: read the `log:` line in the banner; `--verbose` prints to stderr. +2. **Use the issue template.** [Issues → New issue](https://github.com/tuya/tyutool/issues/new/choose), pick Bug report. +3. **Fill in the key fields:** Version / OS / Chip / Platform / baud / Steps / Expected vs actual. +4. **Attach the session log.** Drag the zip into the issue, or for the CLI paste `tyutool-.log`. + +:::warning +Logs may contain sensitive info (UUID/AuthKey) — mask it first. +::: diff --git a/docs/tyutool/flash.md b/docs/tyutool/flash.md new file mode 100644 index 000000000..88a475cf5 --- /dev/null +++ b/docs/tyutool/flash.md @@ -0,0 +1,127 @@ +--- +title: Firmware Flash +description: "Complete reference for the tyutool Flash page — connection bar, the Flash/Erase/Read/Authorize tabs, the chip list, multi-segment flashing, and the progress/log panel." +keywords: + - tyutool firmware flash + - erase + - read + - authorize + - chip models + - tuyaopen +--- + +This page is the complete reference for the **Firmware Flash** page: the connection bar, the four tabs (Flash / Erase / Read / Authorize), the chip list table, multi-segment flashing, erase presets, and the progress-and-log panel on the right. + +## Page overview + +The page has three parts: the connection bar at the top, the operation card on the left (the four tabs), and the progress-and-log panel on the right. + +Flash page connection bar — serial dropdown, baud rate, chip selector, status dot + +*Flash page connection bar — serial dropdown, baud rate, chip selector, status dot.* + +## Connection bar + +- **Serial** (rescanned each time you open it) +- **Baud rate** — `115200` / `460800` / `921600` / `1000000` / `1500000` / `2000000`, plus custom (300–4,000,000). Under the Authorize tab this is the authorization baud rate. +- **Chip selector** — under Authorize, an extra `other` option appears. +- **Status dot** — green = connected and ready; gray/red = not connected or handshake failed. + +:::note[Auto-connect / auto-release] +tyutool connects automatically when you start an operation and releases the port when it finishes. +::: + +## Select a chip +The authoritative chip list (source: `chip-manifests.ts`): + +| Chip (`-d`) | Flash baud | Auth baud | Flash capacity | Erase presets | +| :-- | :-- | :-- | :-- | :-- | +| `esp32` | 460800 | 115200 | 4 MiB | fullChip | +| `esp32c3` | 460800 | 115200 | 4 MiB | fullChip | +| `esp32c6` | 460800 | 115200 | 8 MiB | fullChip | +| `esp32p4` | 460800 | 115200 | 16 MiB | fullChip | +| `esp32s3` | 460800 | 115200 | 16 MiB | fullChip | +| `t5ai` (alias `t5`) | 921600 | 115200 | 8 MiB | authInfo, fullChipNoRf | +| `t1` | 921600 | 115200 | 8 MiB | authInfo, fullChipNoRf | +| `t3` | 921600 | 115200 | 4 MiB | authInfo, fullChipNoRf | +| `t2` | 921600 | 115200 | 2 MiB | authInfo, fullChipNoRf | +| `bk7231n` | 921600 | 115200 | 2 MiB | authInfo, fullChipNoRf | +| `ln882h` | 115200 | 115200 | 2 MiB | fullChip | +| `other` (auth only) | — | 115200 | — | none | + +:::note +`t5ai` is selected by default; the legacy `t5`/`T5` aliases normalize to `t5ai`. +::: + +:::tip +The flash baud is adjustable, but going above `2000000` is not recommended. +::: + +:::info +Erase requires 4 KiB alignment (a multiple of `0x1000`); only `other` is exempt. +::: + +## Flash tab — flashing +Multi-segment flashing: up to 10 segments, each with a firmware path (`.bin`/`.hex`/`.elf`/`.img`) plus a start/end address (hexadecimal). A new segment's start defaults to the previous segment's end; once you pick firmware, the end address is auto-computed as start + file size. The Flash button is only enabled once every segment is filled in. + +Flash tab — multi-segment flashing with firmware path and start/end addresses + +*Flash tab — multi-segment flashing with firmware path and start/end addresses.* + +:::tip +Typical use case: write a bootloader + app in one pass. +::: + +## Erase tab — erasing +Erase by address (alignment is validated in real time) or use an advanced erase preset (same meanings as in [Concepts](./concepts.md#authorize): `authInfo` / `fullChipNoRf` / `fullChip`). A confirmation dialog runs before execution; when an address is unaligned, an "align" action is offered. + +:::danger[Erase destroys data] +Erase is irreversible. A full-chip erase that clears the RF cal region may leave the device unable to connect to a network. Back up first. +::: + +Erase tab — erase by address and the advanced erase presets + +*Erase tab — erase by address and the advanced erase presets.* + +## Read tab — reading + +Used for backup. Choose the save directory (Tauri) or let the browser download; the default filename is `tyutool_read_.bin`; the end address defaults to the chip's full capacity (whole-chip read). If the file already exists, choose to overwrite or append a timestamp. + +:::note +Some chips do not support reading. +::: + +Read tab — read the flash to a file for backup + +*Read tab — read the flash to a file for backup.* + +## Authorize tab — authorizing + +TuyaOpen UART authorization writes `UUID` + `AuthKey` (shown masked, not copyable); a Copy credentials button is available. External links point to TuyaOpen authorization purchase and the localization docs. Operations: + +- **Read Auth** — reads authorization, only holds the port, writes nothing. +- **Authorize** — writes; requires `UUID` + `AuthKey` filled in first and runs a confirmation flow. + +:::danger +Keep your credentials safe (they are purchased). The `other` chip supports authorization only and has no flash plugin. +::: + +Authorize tab — UUID/AuthKey entry (masked), read-auth and authorize actions + +*Authorize tab — UUID/AuthKey entry (masked), read-auth and authorize actions.* + +## Progress and log + +The always-on panel on the right: a phased progress bar (each phase has its own color, percentage, and indeterminate state) plus a log panel (toggle auto-scroll, clear, copy). + +Progress bar and log panel — phased progress with log entries + +*Progress bar and log panel — phased progress with log entries.* + +## Port contention + +The Flash page shares the same set of serial ports with the [Serial Debug](./serial-debug.md#auto-release--auto-save) page. + +:::warning +When a port is busy, tyutool asks you to release it first; you can turn on auto-release in Serial Debug (see [Serial Debug](./serial-debug.md#auto-release--auto-save)). +::: diff --git a/docs/tyutool/getting-started.md b/docs/tyutool/getting-started.md new file mode 100644 index 000000000..c35a47dfb --- /dev/null +++ b/docs/tyutool/getting-started.md @@ -0,0 +1,128 @@ +--- +title: "Getting Started: First Flash" +sidebar_label: Getting Started +description: "Walk from a fresh tyutool install to a successful first firmware flash in 5–10 minutes — prerequisites, connection, and flashing steps." +keywords: + - tyutool getting started + - first flash + - connect device + - flashing + - tuyaopen +--- + +import FeatureCardGrid from '@site/src/components/FeatureCardGrid'; + +This page walks you from "I just downloaded the app" all the way to "I flashed my first device." The path is linear — read it in order and you will complete your first flash, typically in 5–10 minutes. + +:::tip[Read first] +If you have never flashed firmware before, read [Concepts](./concepts.md) first. +::: + +## Prerequisites + +Before you start, confirm everything on this checklist is ready — flashing needs both hardware and software, and none of it is optional. + +- **A supported device.** tyutool targets Tuya ecosystem IoT devices; for the exact supported chip models see the [firmware flash](./flash.md#select-a-chip) page. +- **A USB-to-serial adapter.** Connect it to the device's UART (TX/RX/GND, and power if needed). Wiring must be **crossed**: your computer's TX goes to the device's RX, and vice versa. +- **The device in download/flash mode.** Different devices enter this mode in different ways (button combinations, shorted solder pads, power-on timing). + +:::warning +Wiring and how to enter download mode are **device-specific** — there is no universal procedure. Check your device's manual or the [FAQ](./faq.md#device--serial-port-not-in-the-dropdown) first. tyutool **cannot** switch a device into download mode for you; you must do it manually. When the device is not in download mode, tyutool will keep waiting for the handshake and eventually time out. See [Concepts](./concepts.md#serial--uart--baud-rate) for the relevant terms (UART / download mode / baud rate). +::: + +## Download and install + +tyutool ships pre-built installers for Windows, macOS, and Linux. Go to the project README's download table, pick the build for your OS, and install it the usual way. Common platform pitfalls (full details in the [FAQ](./faq.md)): + +:::warning[macOS serial permission] +macOS forbids normal users from accessing serial devices by default. Add your user to the `dialout` group, then **log out and back in** for it to take effect: + +```bash +sudo dseditgroup -o edit -a $USER -t user dialout +``` + +See the [FAQ](./faq.md#macos-serial-permission) for more. +::: + +:::warning[Linux blank window] +On some Linux desktops tyutool starts with an empty, unrendered window. Work around it by setting this environment variable before launch: + +```bash +WEBKIT_DISABLE_COMPOSITING_MODE=1 ./tyutool-gui_linux_x86_64_appimage_x.x.x.AppImage +``` + +See the [FAQ](./faq.md#linux-blank-window-webkit-compositing-failure) for more. +::: + +:::tip +These snags are **environment** problems, unrelated to tyutool itself; once solved they tend to stay solved. +::: + +## First launch + +Once installed, start tyutool. The main window has two parts: a navigation **sidebar** on the left and the workspace for the active feature on the right. The sidebar has four main entries: + +- **Flash** (firmware flashing) — flash, read, and erase the flash chip. +- **Serial Debug** — send and receive serial data in real time and inspect device logs. +- **Toolbox** — a collection of auxiliary tools. +- **Settings** — configure paths, log levels, and other application options. + +The rest of this page all happens on the **Flash** page — the only entry point you need to care about for your first flash. + +tyutool main window on the Flash page, with the serial dropdown open and showing detected ports + +*tyutool main window on the Flash page, with the serial dropdown open and showing detected ports.* + +## Connect the device + +Once the wiring is checked and the device is in download mode, build the connection in tyutool in this order: + +1. Plug the USB-to-serial adapter into your computer's USB port. +2. On the Flash page, click the **serial** dropdown. +3. Select your adapter from the listed ports (e.g. `COM3` / `/dev/ttyUSB0` / `/dev/cu.SLAB_USBtoUART`). +4. Watch the **status dot** next to it: green means connected and ready; gray or red means not connected or handshake failed. + +After you pick a port, tyutool **auto-fills** the recommended baud rate and chip model — you can accept them as-is. **Higher** is faster but more prone to failure; **lower** is slower but steadier. See [Firmware Flash](./flash.md#flash-tab--flashing). + +Flash page top connection bar — serial dropdown open showing detected ports, plus baud-rate and chip options + +*Flash page top connection bar — serial dropdown open showing detected ports, plus baud-rate and chip options.* + +:::tip +If no ports show in the dropdown, first confirm the adapter is plugged in and its driver is installed (CH340/CP2102/FT232), and check your macOS/Linux serial access permissions (see the installation notes above). +::: + +## Complete your first flash + +Once the device is connected, the flash itself is short. Walk these steps in order to write your first firmware: + +1. **Select the chip model.** At the top of the Flash page, pick the chip that matches your device — the model decides the communication protocol and address layout, and picking the wrong one fails the flash. +2. **Select firmware.** Switch to the **Flash** tab, click to choose a firmware file, and pick a `.bin` firmware. +3. **Confirm the address.** After you pick firmware, the write address is **auto-filled** to a default and usually needs no change. +4. **Start flashing.** Click the **Flash** button to begin writing. +5. **Watch progress.** Keep an eye on the progress bar and the log below; it should advance steadily to 100%. +6. **Wait for reboot.** When writing finishes, the device **reboots automatically** and runs the new firmware — your first flash is complete. + +Flash page mid-flash — chip and firmware selected, port connected, and the flash in progress at 25%, with numbered callouts matching the steps above + +*Flash page mid-flash — chip and firmware selected, port connected, and the flash in progress at 25%, with numbered callouts matching the steps above.* + +For the advanced options at each step (address tweaking, erase strategy, verification, saving logs, etc.), see the [Firmware Flash](./flash.md) page. + +:::danger +While flashing, **never** unplug the USB cable or cut power — you may corrupt the data. If a flash fails, first drop to `115200` baud and retry; if it still fails, see the [FAQ](./faq.md#flash-fails--handshake-fails). +::: + +## Next steps + +Congratulations on your first flash! From here, dive into each feature page as needed: + + diff --git a/docs/tyutool/index.md b/docs/tyutool/index.md new file mode 100644 index 000000000..6008a68fd --- /dev/null +++ b/docs/tyutool/index.md @@ -0,0 +1,36 @@ +--- +title: tyutool V3 Usage Guide +description: "Welcome to tyutool — the desktop GUI and command-line tool for flashing, serial debugging, and batch authorization of Tuya ecosystem IoT devices." +keywords: + - tyutool + - v3 usage guide + - flashing + - serial debug + - batch authorization + - tuyaopen +--- + +import FeatureCardGrid from '@site/src/components/FeatureCardGrid'; + +## Welcome + +tyutool is a desktop GUI and command-line tool for flashing firmware, serial debugging, and batch authorization of Tuya ecosystem IoT devices. + +:::note[New here?] +If this is your first time, start with [Getting Started](./getting-started.md) — a 5–10 minute linear walkthrough from download to your first successful flash. +::: + +## Feature guide + +Explore each capability below: + + diff --git a/docs/tyutool/serial-debug.md b/docs/tyutool/serial-debug.md new file mode 100644 index 000000000..618cd4831 --- /dev/null +++ b/docs/tyutool/serial-debug.md @@ -0,0 +1,91 @@ +--- +title: Serial Debug +description: "Complete reference for the tyutool Serial Debug page — a serial terminal and log monitor covering connection, UART config, reset, ASCII/Hex views, the send bar, keyword filter tabs, and auto-release/auto-save." +keywords: + - tyutool serial debug + - uart config + - hex view + - filter tabs + - log monitor + - tuyaopen +--- + + +This page is the complete reference for the **Serial Debug** page: a serial terminal and log monitor covering connection and UART configuration, device reset, ASCII/Hex log views, the send bar, the hex popup, keyword filter tabs, and auto-release and auto-save. + +## Overview + +A full serial terminal. Keep-alive: if you jump to another page and come back, the background RX stream is not interrupted. + +Serial Debug overview — terminal workspace with log view and send bar + +*Serial Debug overview — terminal workspace with log view and send bar.* + +:::note +The serial ports here are shared with the [Firmware Flash](./flash.md) page. +::: + +## Connection and serial config +Serial selection (rescan) / connect-disconnect / status indicator. The advanced UART settings live in the serial-settings dialog: + +| Parameter | Options | Notes | +| :-- | :-- | :-- | +| Baud rate | `9600`–`921600` + custom | When unset, defaults to the current flash chip's log baud rate | +| Data bits | `5` / `6` / `7` / `8` | Data bits per frame | +| Parity | `none` / `odd` / `even` | None / odd / even | +| Stop bits | `1` / `1.5` / `2` | Stop bits per frame | + +:::tip[Baud follows the chip] +Pick a chip on the Flash page first and the Serial Debug baud rate aligns to it automatically. +::: + +## Device reset + +Reset via DTR/RTS. Reset the current session port, or reset another controlled port (use the runtime chip id to target a different port). + +:::note +Reset is not the same as disconnect. +::: + +## Log view +ASCII view / Hex view (8/16/32 bytes per row); ANSI coloring toggle; font size 10–18px; timestamp toggle; direction badges (TX/RX/SYS); clear; export. + +Log rows with RX badges and timestamps, with the Serial Settings dialog open — data bits, parity, stop bits, auto-release for flash, hex view, and ANSI color parsing + +*Log rows with RX badges and timestamps, with the Serial Settings dialog open — data bits, parity, stop bits, auto-release for flash, hex view, and ANSI color parsing.* + +:::warning[3000-line visible window cap] +Older rows are removed once the visible window exceeds 3000 lines. Use auto-save or export promptly. +::: + +## Send bar + +ASCII or Hex mode; optional `\r\n`; press `Enter` to send; history holds up to 20 entries, cycle with `↑` / `↓`. + +Send bar with a command list open above the input, and live log rows with RX badges in the background + +*Send bar with a command list open above the input, and live log rows with RX badges in the background.* + +## Hex popup + +Select a span of RX data and the popup shows hex + ASCII side by side. + +:::tip +Useful for checking structured binary (protocol frames, authorization replies). +::: + +## Filter tabs + +Give each keyword its own tab. A keyword can be plain text or a regular expression; tabs cycle through six colors, count matches live, and clicking a tab shows only matching rows. "All" restores the full view and "Load earlier" pages back. Filtering runs server-side against the whole session. + +Filter tabs — keyword tabs with live match counts and color coding + +*Filter tabs — keyword tabs with live match counts and color coding.* + +## Auto-release / auto-save +- **Auto-release** solves port contention. When the Flash page needs a port, Serial Debug releases it automatically (an optional confirmation prompt can be turned on); once flashing finishes, the connection is restored automatically. +- **Auto-save** keeps the full session log (also configurable under [Settings](./settings.md#serial-logs)). Set the save directory; filenames are timestamped; writes are chunked (max 128 KiB). + +:::note +Manual export = the current visible window; auto-save = the whole session. +::: diff --git a/docs/tyutool/settings.md b/docs/tyutool/settings.md new file mode 100644 index 000000000..833899af0 --- /dev/null +++ b/docs/tyutool/settings.md @@ -0,0 +1,83 @@ +--- +title: Settings +description: "Complete reference for the tyutool Settings page — update center, appearance and language, diagnostics and logs, serial logs, about, and how settings are persisted." +keywords: + - tyutool settings + - update center + - appearance + - diagnostics + - log files + - tuyaopen +--- + +This page is the complete reference for the **Settings** page: the update center, appearance and language, diagnostics and logs, serial logs, about, and how settings persist. + +## Update center +- **Installed build** — the current version. +- **Check for updates** — desktop (Tauri) only; opens the Update dialog and is not bound by the interval. +- **Auto-check interval** — silently checks on startup and only fires once the interval has elapsed. Options: `Off` / `1h` / `6h` / `12h` / `24h`. + +Update center — installed version, check-for-updates, auto-check interval + +*Update center — installed version, check-for-updates, auto-check interval.* + +:::note +The web build has no auto-update (it depends on the Tauri updater plugin). +::: + +## Appearance and language +- **Theme** — `Light` / `Dark` / `System` (applies immediately; System follows the OS). +- **Language** — `Auto` / `简体中文` / `English` (Auto: uses Chinese for a `zh`-prefixed locale). +- **Serial indicator** toggle. + +Appearance and language — theme, language, serial-indicator toggle + +*Appearance and language — theme, language, serial-indicator toggle.* + +:::info +Advanced UART parameters live on the Serial Debug page (see [Serial Debug](./serial-debug.md#connection-and-serial-config)). +::: + +## Diagnostics and logs +- **Debug log toggle** — the master switch; when off, the backend log level is set to `off`. +- **Log level** — Error / Warn / Info / Debug / Trace, applied to the Rust backend via `log::set_max_level`. +- **Open log folder.** +- **View logs** — opens the Log Viewer dialog. +- **Export logs and report a problem** — zips logs and opens a pre-filled GitHub issue (version/OS included); desktop only. + +Diagnostics and logs — log toggle, level, open/view/export actions + +*Diagnostics and logs — log toggle, level, open/view/export actions.* + +### How log files land + +Logs are written by `tauri-plugin-log`. Each session is named `tyutool-.log`; a file rolls over at 10 MB into `-1.log`, `-2.log`, and old files are cleaned up on startup. Log directories: + +- Linux: `~/.local/share/tyutool/` +- macOS: `~/Library/Application Support/tyutool/` +- Windows: `%APPDATA%\tyutool\` + +:::note +The level applies to the Rust backend. +::: + +## Serial logs +A mirror entry for Serial Debug's auto-save: the auto-save toggle, save directory, and timestamp format. + +:::note +This is the same store as the Serial Debug page. +::: + +## About +- **Application version.** +- **Open-source license** — opens the LICENSE page. + +## Persistence + +- **Desktop** writes `settings.json` (`tauri-plugin-store`). +- **Web** writes to `localStorage`. +- The theme is applied to the DOM (System mode watches the OS color scheme). + +:::note +On desktop, the `settings.json` key names correspond one-to-one with the web `localStorage` keys. +::: diff --git a/docusaurus.config.js b/docusaurus.config.js index 4952408fb..260302c0e 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -152,6 +152,7 @@ const config = { { type: 'docSidebar', sidebarId: 'hardwareSidebar', label: 'Hardware' }, { type: 'docSidebar', sidebarId: 'cloudSidebar', label: 'Cloud & AI' }, { type: 'docSidebar', sidebarId: 'duckyclawSidebar', label: 'TuyaOpenClaw' }, + { type: 'docSidebar', sidebarId: 'tyutoolSidebar', label: 'tyutool' }, ], }, { @@ -396,7 +397,15 @@ const config = { '@docusaurus/plugin-client-redirects', { // Legacy aliases that predate the per-product docs split. + // NOTE: this config runs once per locale build, and each locale's own + // build validates `to` against its own (locale-relative) route list — + // entries here must NOT be hand-prefixed with `/zh`. redirects: [ + // The standalone /tyutool-guide page was replaced by the tyutool docs section. + { + from: '/tyutool-guide', + to: '/docs/tyutool', + }, { from: '/docs/hardware-specific/t5ai-peripheral-mapping', to: '/docs/hardware/tuya-t5/t5ai-peripheral-mapping', @@ -482,7 +491,7 @@ const config = { ['/docs/cloud/device-ai/', '/docs/applications/tuya.ai/'], ['/docs/cloud/iot-client/', '/docs/applications/tuya_cloud/'], // tyutool pages moved off /tools/ (the web-serial tool owns /tools/). - // Substring match also covers /tyutool-guide and the /zh/ locale variants. + // Substring match also covers the /zh/ locale variant. ['/tyutool', '/tools/tyutool'], // The standalone web-serial docker (formerly /tools/) is now integrated // into the site at /web-serial. Redirect the old root URL. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tos-tools/tools-tyutool.md b/i18n/zh/docusaurus-plugin-content-docs/current/tos-tools/tools-tyutool.md index 2cbd48f9a..24cf96530 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/tos-tools/tools-tyutool.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tos-tools/tools-tyutool.md @@ -24,11 +24,11 @@ tyutool 支持 Windows、Linux 和 macOS，请根据自己的操作系统选择 tyutool 目前分为 **V2** 和 **V3** 两个版本，主要差异如下： -- **V3**（当前最新版本）：基于 **Rust（Tauri 2）+ Vue 3** 全新架构重写，跨平台兼容性更好，**推荐 Mac 用户使用**；暂不支持音频调试和批量烧录功能 -- **V2**：原有架构，功能更为完整，支持音频调试、批量烧录等高级功能 +- **V3**（当前最新版本）：基于 **Rust（Tauri 2）+ Vue 3** 全新架构重写，跨平台兼容性更好，**推荐 Mac 用户使用**；现已支持批量烧录与授权，暂不支持音频调试 +- **V2**：原有架构，功能更为完整，支持音频调试等高级功能 :::note -V3 版本暂不支持 V2 中的音频调试和批量烧录功能，如需使用这些功能请下载 V2 版本。 +V3 版本暂不支持 V2 中的音频调试功能，如需使用请下载 V2 版本。完整的 V3 功能说明（烧录、串口调试、设置、批量烧录授权、命令行参考）请见 [tyutool V3 使用指南](../tyutool/index.md)。 ::: | 平台 | 源码使用(推荐) | @@ -69,10 +69,10 @@ tyutool_gui 打开后界面如下显示： tyutool 烧录界面 -- ① 选择要烧录的芯片。 -- ② 点击 `浏览` 选择要烧录的固件文件（包含 `_QIO` 字样的 bin 文件）。 -- ③ 选择设备烧录端口。涂鸦官方开发板和部分生态伙伴开发板，将鼠标悬停在串口上会提示该串口为烧录授权串口还是日志串口。 -- ④ 点击 `开始烧录`。 +1. 选择要烧录的芯片。 +2. 点击 `浏览` 选择要烧录的固件文件（包含 `_QIO` 字样的 bin 文件）。 +3. 选择设备烧录端口。涂鸦官方开发板和部分生态伙伴开发板，将鼠标悬停在串口上会提示该串口为烧录授权串口还是日志串口。 +4. 点击 `开始烧录`。 :::tip 烧录波特率默认使用 921600，如果您感觉烧录速度过慢，可以适当调高波特率，但是调高波特率可能会导致固件烧录失败。 @@ -86,11 +86,11 @@ tyutool_gui 打开后界面如下显示： tyutool 授权界面 -- ① 点击 `授权` 选项卡。 -- ② 选择授权串口。 -- ③ 选择授权波特率。 -- ④ 填入 `UUID` 和 `AuthKey`。 -- ⑤ 点击 `开始授权`。 +1. 点击 `授权` 选项卡。 +2. 选择授权串口。 +3. 选择授权波特率。 +4. 填入 `UUID` 和 `AuthKey`。 +5. 点击 `开始授权`。 :::tip 授权 UART 和烧录 UART 为同一个，UART 保持默认配置即可（波特率：115200，数据位：8，停止位：1，校验位：无）。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-auth-developer.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-auth-developer.md new file mode 100644 index 000000000..6d21b2012 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-auth-developer.md @@ -0,0 +1,115 @@ +--- +title: "批量授权 · 开发者指南" +sidebar_label: 开发者指南 +description: "写给固件开发者——要让固件能被 tyutool 批量授权，必须实现一套 TuyaOpen UART CLI 命令。下面是完整协议契约与自测清单。" +keywords: + - tyutool 批量授权 + - 开发者指南 + - UART CLI 协议 + - 授权契约 + - 自测清单 + - tuyaopen +--- + +写给**固件开发者**：要让固件能被 tyutool 批量授权，必须实现一套 TuyaOpen UART CLI 命令。下面是完整协议契约与**自测清单**。 + +:::note[走错页了？] +操作员请看[操作员指南](./batch-auth-operator.md)。 +::: + +## 协议本质 + +授权协议是 **TuyaOpen 交互式 shell 的文本命令**（纯 ASCII，每条 `\r\n` 结尾，无帧头/校验和/操作码）。与烧录用的 Beken BootROM 二进制协议是两套独立的东西。波特率默认 `115200` 8N1；设备上电呈现 `tuya>` 提示符。权威源是 `tuya_authorize.c`。 + +:::tip[基于 TuyaOpen 时如何启用 CLI] +需固件主动注册：① `tal_cli_init()`（默认 uart0，非 uart0 用 `tal_cli_init_with_uart(uart_num)`）；② `tuya_authorize_init()`（注册 auth / auth-read / read_mac）。在 `user_main()` 成对调用。代码： + +```c +void user_main(void) +{ + // ... tal_kv_init / tal_sw_timer_init / tal_workq_init 等 +#if !defined(PLATFORM_UBUNTU) || (PLATFORM_UBUNTU == 0) + tal_cli_init(); // 初始化 CLI（默认 uart0） + tuya_authorize_init(); // 注册 auth / auth-read / read_mac 命令 + tuya_app_cli_init(); // 你的 App 自定义命令（可选） +#endif + // ... tuya_iot_init(...) 等 +} +``` + +:::note +基于 TuyaOpen 三行调用即可；命令表/自测清单主要面向自研或移植固件。 +::: + +## 必须实现的命令 + +| 命令(`\r\n` 结尾) | 用途 | 固件必须回显 | +| :-- | :-- | :-- | +| `sys_log_enable off` | 能力探测+关日志 | 新：`OK: log disabled`；旧：`No command` 或回 `tuya>` | +| `sys_version` | 读固件版本 | 一行 `project.version x.y.z` | +| `read_mac` | 读 MAC | `XX:XX:XX:XX:XX:FF`（6 段冒号分隔；或带前缀标签 `LABEL:XX:...:FF` 共 7 段） | +| `auth-read` 或 `auth-read ` | 读当前授权 | 已授权：两行 ``/`` 后提示符；空/未授权：`Authorization read failure.`；部分回显占位 `uuidxxxxxxxxxxxxxxxx`（视作未授权） | +| `auth ` 或 `auth ` | 写授权 | 长度非法：`uuid length must be 20/16, authkey length must be 32`（不执行）；KV 成功：`Authorization write succeeds.`（部分版本重启不打印，tyutool 用 auth-read 回读校验）；OTP 成功：`Authorization write to OTP Succeeds.`；OTP 失败：`Authorization write to OTP failure.` | + +:::note +固件应回显每条命令行；日志行（`[MM-DD HH:MM:SS ...]`）和 ANSI 转义会被 tyutool 自动剔除。 +::: + +## 凭据长度规则 + +- `UUID` 恰好 16 或 20 字符。 +- `AuthKey` 恰好 32 字符。 +- 占位 UUID 为 `uuidxxxxxxxxxxxxxxxx`。 +- UUID 合法字符：字母数字及 `- _ .`。 +- AuthKey：任意 ASCII 可见字符。 + +## KV 与 OTP 的差异 + +| 模式 | 读命令 | 写命令 | +| :-- | :-- | :-- | +| KV | `auth-read` | `auth ` | +| OTP | `auth-read 1` | `auth 1` | + +要点： + +- OTP 仅 T5AI。 +- OTP 烧写耗时长（60 秒总超时+30 秒静默窗口，读 30 秒静默）。 +- OTP 写失败重试最多 3 次（不损坏已写数据）。 +- 读空 OTP 区回 `Authorization read failure.`（视为未授权）。 + +:::danger +OTP 写一次不可逆；调试先 KV 验证。 +::: + +## MAC 校验规则 + +`read_mac` 必须返回有效 MAC：6 段冒号分隔两位十六进制（大小写不敏感，内部转大写）；可带非十六进制前缀标签（`LABEL:XX:...:XX` 共 7 段）；不识别横杠/等号/空格。T5/T5AI 出厂默认 MAC `C8:47:8C:00:00:18` 表示未个性化——读到它 tyutool 中止该设备授权。 + +## 自测清单 +用串口工具 115200 8N1 逐条核对： + +1. 出现 `tuya>` 提示符。 +2. `sys_log_enable off` → `OK: log disabled`（或旧固件 `No command`）。 +3. `sys_version` → `project.version x.y.z`。 +4. `read_mac` → 有效 MAC。 +5. `auth-read`（未授权）→ `Authorization read failure.`。 +6. `auth <合法 uuid+authkey>` → `Authorization write succeeds.`（KV）/ `...to OTP Succeeds.`（OTP）。 +7. 再 auth-read 能读回相同 UUID+AuthKey。 +8. `auth <过短 uuid> ` → 长度错误且不改授权。 +9. （仅 T5AI+OTP）`auth 1` → OTP 成功，`auth-read 1` 能读回。 + +:::tip +自测用合法购得的真实凭据；OTP 最后验。 +::: + +## 集成路径 + +- **路径 A（推荐）**：固件自带授权能力（基于 TuyaOpen 或自实现），批量用 `auth-only` 模式。 +- **路径 B**：用官方 auth-firmware（`assets/auth-firmware/` 按 chip 提供 `.bin`）临时烧入授权，对应批量 `flash-then-auth` 模式。 + +## 配置交接单 +逐项写给操作员：芯片型号；操作模式（A/B）；固件文件名+版本；两个波特率（烧录/授权）；存储模式（KV/OTP，OTP 显著标注）；冲突策略（跳过/覆盖，OTP 只能跳过）；接线说明（**务必确认 RTS 已正确连接到芯片复位脚**）；MAC 唯一性保障（每台 MAC 全球唯一互不重复；tyutool 不校验 MAC 冲突）；特殊事项。 + +:::note +交接单让操作员"照单执行"，事后排查可对[批次档案](./batch-auth-operator.md)还原约定。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-auth-operator.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-auth-operator.md new file mode 100644 index 000000000..639a6f029 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-auth-operator.md @@ -0,0 +1,204 @@ +--- +title: "批量授权 · 操作员指南" +sidebar_label: 操作员指南 +description: "写给使用 tyutool 进行批量烧录授权的操作员——照着做的顺序：开工前清单、配置、接线与启动、核对结果、归档与安全铁律。" +keywords: + - tyutool 批量授权 + - 操作员指南 + - 批量烧录流程 + - 归档 + - 安全铁律 + - tuyaopen +--- + +写给**使用 tyutool 进行批量烧录授权的操作员**，"照着做"的顺序，无需技术背景。 + +:::note +固件开发者请看[开发者指南](./batch-auth-developer.md)。 +::: + +工作流顺序：**① 开工前清单 → ② 配置 → ③ 接线与启动 → ④ 核对结果 · 出错速查 · 安全铁律**。 + +## 这个工具做什么 + +多台设备插多串口，点"全部开始"，同时烧录+授权，授权码从 Excel 自动读取。 + +批量页面——完成横幅 / 仪表盘（烧录累计·授权累计·本次批次）/ 配置面板 / 工具栏（自动分配·串口过滤·全部读取·全部开始）/ 端口列表 + +*批量页面——完成横幅 / 仪表盘（烧录累计·授权累计·本次批次）/ 配置面板 / 工具栏（自动分配·串口过滤·全部读取·全部开始）/ 端口列表。* + +## 开工前清单 + +| 准备项 | 怎么算就绪 | +| :-- | :-- | +| 桌面版 tyutool | 已安装并能启动 | +| 授权码 Excel | 至少有 `UUID` + `AuthKey` 两列；从 [tuyaopen.ai/zh/pricing](https://tuyaopen.ai/zh/pricing) 购买 | +| 设备 + 串口线 | 已接线，设备能进下载模式 | +| 串口驱动 | CH340/CP2102/FT232 已装 | +| 固件文件 | 本次批次用的 `.bin` | + +安装包（版本号仅作参考，始终以 [GitHub Releases](https://github.com/tuya/tyutool/releases) 为准）： + +| 平台 | 文件 | +| :-- | :-- | +| 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`（先 `chmod +x`） | + +:::warning[T5/T5AI 接线注意] +这些设备有两个串口——务必接烧录/授权口，不要接日志口。 +::: + +:::warning[授权码很贵重] +妥善保管 Excel。 +::: + +### 配置交接单 + +| 配置项 | 开发者填 | 操作员核对 | +| :-- | :-- | :-- | +| 芯片型号 | 如 `esp32` / `t5ai` | 与设备一致 | +| 操作模式 | 只授权 vs 先烧再授（路径 A/B） | "烧录固件"开关一致 | +| 固件文件与版本 | 文件名 + 版本 | `batch-summary.json` 记 SHA256 | +| 烧录波特率 | 如 921600 | 设置正确 | +| 授权波特率 | 如 115200 | 设置正确 | +| 存储模式 | KV / OTP | OTP → 先单台验证 | +| 冲突策略 | 跳过 / 覆盖 | OTP 只能跳过 | +| 授权表 | 剩余 ≥ 本批新设备数 | 恢复/重试已登记设备不占新码 | +| 接线 | 说明 | **确认 RTS 接到复位脚** | +| MAC 唯一性 | 每台 MAC 全球唯一 | tyutool **不校验** MAC 冲突，重复 MAC 让设备共用授权码 | +| 单台试通 | 已通过 | 上量前已做 | +| 特殊事项 | — | 阅读 | + +:::tip +对不上先停下来找开发者确认，不要自行改配置。 +::: + +## 操作流程 + +工具箱 → 批量烧录授权。 + +:::note +第一次进入会弹免责声明对话框（不可逆操作），可勾"不再提示"；重显见[设置](./settings.md)。 +::: + +### 阶段一 · 配置 + +1. 选芯片（ESP32 / T5AI；只授权选 `other`）。 +2. 烧录波特率。 +3. 授权波特率。 +4. 是否烧录固件（先烧再授）。 +5. 固件文件（本地 / 默认授权固件）。 +6. 选固件位置或选版本。 + +配置区——共享配置面板 + +*配置区——共享配置面板。* + +1. 选授权表（`.xlsx`）。 +2. 查看统计：总计 / 已用 / 占用中 / 剩余（给新设备分码需剩余 > 0；仅恢复/重试已登记设备剩余 0 也可启动，按 MAC 找回原码）。 +3. 已带授权设备：跳过（推荐）/ 覆盖。 + +批量授权配置——授权表统计 + +*批量授权配置——授权表统计。* + +（仅 T5AI）选存储模式：KV 可重写；OTP 写一次不可逆（见[安全](#安全铁律)）。 + +### 阶段二 · 接线与启动 + +:::tip +先 1 台完整跑通 → 2～4 台小批量试跑 → 再上整批。 +::: + +接好后两步： + +1. 点**自动分配**（扫描加插槽，每口一行"空闲"）。 +2. 点**全部开始**（空闲端口 > 8 时先弹确认）。 + +:::warning[启动前最后 30 秒检查] +逐行对照交接单核对配置；OTP 是否已单台验证？ +::: + +工具栏与端口列表——每口一个插槽 + +*工具栏与端口列表——每口一个插槽。* + +:::note[工具栏其他按钮] +**② 串口过滤 · ③ 全部读取（只读不写）· ④ 取消 · ⑤ 重试失败 · ⑦ 单口读取**。 +::: + +### 阶段三 · 等待与核对 + +1. 看仪表盘等完成（完成横幅：全部成功 / 全失败 / 部分成功 / 全跳过）。 +2. 逐行核对（失败看重试）。 +3. 整单跑完点"归档"（中间轮次不用归档）。 + +仪表盘与完成横幅（右侧归档按钮） + +*仪表盘与完成横幅（右侧归档按钮）。* + +## 看懂结果 + +| 状态 | 意思 | 做什么 | +| :-- | :-- | :-- | +| `done` | 完成，好品 | — | +| `failed` | 失败 | 重试 | +| `skipped` | 已有授权按策略跳过 | — | +| `no_code` | 新设备但剩余 = 0 | 补表重跑 | +| 其他 | 处理中 | 等 | + +## 归档 +一次"全部开始" = 一轮；一份授权表 = 一单（往往多轮）。归档以单为单位。 + +:::info +一键归档：选目录，建带时间戳文件夹 `batch-archive_20260717-143205_esp32/`，含：授权表副本 / 固件(含 SHA256) / logs.zip / `batch-summary.json` / `batch-slots.csv`。summary 的 lastRun 和 csv 只是最后一轮快照。 +::: + +档案内容： + +| 文件 | 是什么 | +| :-- | :-- | +| 授权表 Excel 副本 | 所用的表 | +| 固件文件 | 烧录的 `.bin` | +| logs.zip | 压缩日志 | +| batch-summary.json | 运行汇总 | +| batch-slots.csv | 最后一轮的按槽快照 | +| 完成横幅截图 | 可选记录 | + +:::warning +档案含 UUID + AuthKey，防泄露；排查只给日志和错误信息，授权表不外发。 +::: + +## 出错速查 + +| 现象 | 处理 | +| :-- | :-- | +| 应用打不开 / 白屏 | 见 [FAQ · Linux 白屏](./faq.md) | +| 端口没出现 | 换线换口、装驱动、关其他程序，见 [FAQ · 端口](./faq.md) | +| 全部失败 | 单台试通、降到 115200、查供电 | +| Excel"文件被占用" | 关掉 Excel/WPS 重选 | +| Excel 表无效 | 查 `UUID` + `AuthKey` 两列及长度 | +| 需详细日志 | 按[保存现场](#先保存现场)保存，见 [FAQ · 日志](./faq.md) | + +### 先保存现场 +趁现场点"归档"全存下；再手工补三样：界面截图（遮 AuthKey，UUID 可留）/ 问题设备实物（贴标签单独放）/ 一句话现象描述。 + +:::note +别拖也别泄露：当天归档；外发只给日志和错误信息。 +::: + +## 安全铁律 +这是唯一会触发不可逆硬件操作的功能。 + +:::danger[铁律一：OTP 写一次不可逆] +OTP（仅 T5AI）把授权烧进芯片后永远无法撤销。配错毁整批——务必先用一台完整跑通验证再批量。 +::: + +选 OTP 时界面提示写入后不可撤销 + +*选 OTP 时界面提示写入后不可撤销。* + +:::danger[铁律二：带"已写入后取消"危险徽标的设备必须单独放一边] +这类设备授权可能已写、状态不确定，既不能当好品也不能直接重跑，必须单独核实。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-flash-auth.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-flash-auth.md new file mode 100644 index 000000000..8d64dca96 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/batch-flash-auth.md @@ -0,0 +1,45 @@ +--- +title: 批量烧录授权 +description: "tyutool 批量烧录授权总览——把多台设备插到多个串口上，并行烧录固件并写入授权码，授权码由一份 .xlsx 表格驱动。" +keywords: + - tyutool 批量 + - 批量烧录 + - 批量授权 + - OTP + - 并行烧录 + - tuyaopen +--- + +import FeatureCardGrid from '@site/src/components/FeatureCardGrid'; + +把多台设备插到多个串口上，**并行**烧录固件 + 写入授权码，授权码由一份 `.xlsx` 表格驱动。这是 tyutool 里最复杂的功能，当存储模式选 **OTP** 时会进行不可逆的 eFuse 操作（仅 T5AI）。 + +:::note[在哪里找到它] +桌面客户端中，这个功能位于 **工具箱（Toolbox）→ 批量烧录授权**。 +::: + +## 选择你的指南 + +这个功能涉及两类完全不同的人，两份独立指南： + + + +## 这两份指南覆盖了什么 + +两份指南合起来覆盖： + +- 准备清单，以及开发者 ↔ 操作员之间的配置交接 +- 接线、启动批次、逐行查看结果 +- 归档已完成的批次、排查失败原因 +- 固件要实现的 UART CLI 协议契约（才能被批量授权） +- KV 与 OTP 两种存储模式，以及 OTP 不可逆写入的安全铁律 + +:::danger[最重要的安全提示] +存储模式选 **OTP**（仅 T5AI）时授权码一次性烧进芯片，永远无法擦除或修改——一次错配毁掉整批。务必先单台验证再批量。详见操作员指南的[安全铁律](./batch-auth-operator.md)。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/cli.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/cli.md new file mode 100644 index 000000000..83229fa5a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/cli.md @@ -0,0 +1,228 @@ +--- +title: 命令行工具 +description: "完整的 tyutool 命令行参考——安装、全局选项、11 个子命令（write、read、erase、list-ports、reset、monitor、authorize、update、serve、completions、usb-port-survey）、支持的芯片与输出模式。" +keywords: + - tyutool 命令行 + - CLI + - 烧录固件 + - 授权 + - 监视 + - tuyaopen +--- + + +`tyutool` 是一个命令行工具，本页是完整的 CLI 参考。 + +## 什么时候用 CLI + +脚本化 / CI / 无桌面服务器 / 习惯终端。与桌面应用共享同一套 `tyutool-core` 烧录逻辑。 + +## 安装 + +从 [GitHub Releases](https://github.com/tuya/tyutool/releases) 下载。各平台资产（五个平台；每个 release 还附带 `latest.json`，含 `cli..sha256`）： + +| 平台 | 资产 | +| :-- | :-- | +| Linux x86_64 | `tyutool-cli_linux_x86_64_*.tar.gz` | +| Linux aarch64 | `tyutool-cli_linux_aarch64_*.tar.gz` | +| macOS x86_64 | `tyutool-cli_macos_x86_64_*.tar.gz` | +| macOS aarch64 | `tyutool-cli_macos_aarch64_*.tar.gz` | +| Windows x86_64 | `tyutool-cli_windows_x86_64_*.zip` | + +安装： + +```bash +# Linux / macOS（tar.gz） +tar -xzf tyutool-cli_linux_x86_64_*.tar.gz +sudo mv tyutool_cli /usr/local/bin/tyutool +chmod +x /usr/local/bin/tyutool + +# Windows（.zip）：解压出 tyutool_cli.exe，把所在目录加入 PATH +``` + +验证： + +```bash +tyutool --version +tyutool list-ports +``` + +:::note +CLI 支持自更新：`tyutool update`。 +::: + +## 全局选项 + +| 选项 | 含义 | +| :-- | :-- | +| `--verbose` | 诊断日志输出到 stderr | +| `--plain` | 纯 ASCII，无 spinner | + +日志文件：每会话独立 `tyutool-<时间戳>.log`，10 MB 滚动，启动清理。位置： + +- Linux：`~/.local/share/tyutool/` +- macOS：`~/Library/Application Support/tyutool/` +- Windows：`%APPDATA%\tyutool\` + +:::note +滚动文件命名为 `tyutool-<时间戳>.log` → `-1.log` → `-2.log`。 +::: + +端口选择：`-p` 省略时单端口自动用，多端口交互选（CI 下报错）。 + +## 子命令 + +### write — 烧录固件 + +```bash +tyutool write -d <芯片> -f <固件> [-p <端口> -b <波特> -s <起始> --end <结束>] +``` + +示例： + +```bash +tyutool write -d bk7231n -f firmware.bin -p /dev/ttyUSB0 +``` + +### read — 读取 Flash + +```bash +tyutool read -d <芯片> -f <输出> [-p <端口> -b <波特> -s <起始> -l <长度>] +``` + +`length` 默认 `0x200000`。 + +### erase — 擦除 + +```bash +tyutool erase -d <芯片> [-p <端口> -b <波特> -s <起始> -l <长度>] +``` + +擦除区域 start…start+length；某些芯片按扇区对齐。 + +### list-ports — 列串口 + +```bash +tyutool list-ports [--json] +``` + +默认制表符分隔列：`path / vid:pid / usb_interface / port_role / display_name`。 + +### reset — DTR/RTS 硬件复位 + +```bash +tyutool reset [-p <端口> -d <设备>] +``` + +`device` 默认 `bk7231n`。 + +### monitor — 实时串口监视 + +```bash +tyutool monitor [-p <端口> -b <波特> -d <设备> -l] +``` + +透传到 stdout，交互式转发按键；用 `Ctrl+]` 或 `Ctrl+C` 退出。非 TTY 按行转发。`t5ai` 默认监视波特 460800，其他 115200（注意 ≠ 烧录波特）。 + +示例： + +```bash +tyutool monitor -p /dev/ttyUSB0 +tyutool monitor -d bk7231n -b 115200 +tyutool monitor -d t5ai +``` + +### authorize（别名 `auth`）— TuyaOpen 授权 + +```bash +tyutool authorize [-p <端口> -d <设备> --uuid --authkey ] +``` + +写入必须同时传 `uuid` + `authkey`；都不传则 auth-read。凭据写入 KV 存储，绝不烧 OTP/eFuse（OTP 仅 GUI 批量）。 + +读取示例： + +```bash +tyutool authorize -p /dev/ttyUSB0 +``` + +写入示例： + +```bash +tyutool authorize -p /dev/ttyUSB0 --uuid --authkey +``` + +### update — 自更新 + +```bash +tyutool update [--check] [--source github|tuya] +``` + +### serve — WebSocket 服务器 + +```bash +tyutool serve +``` + +开发/IDE 模式；默认端口 `9527`；供 tuyaopen-ide。 + +### completions — 生成 shell 补全 + +```bash +tyutool completions bash +tyutool completions zsh +tyutool completions fish +``` + +（另有 `powershell`、`elvish`。） + +### usb-port-survey — USB/串口元数据转储 + +```bash +tyutool usb-port-survey +``` + +输出原始 USB/串口元数据 JSON，便于跨系统排错。 + +## 支持的芯片 +| 芯片 | 默认波特率 | +| :-- | :-- | +| `bk7231n` | 921600 | +| `t2` | 921600 | +| `t3` | 921600 | +| `t1` | 921600 | +| `t5ai` | 921600 | +| `ln882h` | 115200 | +| `esp32` | 460800 | +| `esp32c3` | 460800 | +| `esp32c6` | 460800 | +| `esp32p4` | 460800 | +| `esp32s3` | 460800 | + +芯片名大小写不敏感；`-b` 可调波特。 + +## 输出模式 +- **Rich 模式**（TTY）：spinner / ANSI 进度条 / `✓`。 +- **Plain 模式**（CI）：固定宽度阶段标签，长阶段每 10% 一刻度。 + +Plain 模式样例输出（BK7231N 的 `write`）： + +```text +tyutool v3.2.7 linux/x86_64 +[scan ] scanning serial ports +[conn ] connecting /dev/ttyUSB0 @ 921600 +[write] 0% 10% 20% 30% 40% 50% 60% 70% 80% 90% 100% +[ok ] write complete +``` + +成功退出码为 0。 + +:::note[取消] +write / read / erase / authorize 期间 `Ctrl+C` 优雅退出（关串口报 `Cancelled`）；monitor 的 `Ctrl+]` / `Ctrl+C` 正常退出码 0。 +::: + +## 开发者参考 + +:::note[权威 markdown 源] +对应 markdown 在仓库内 [`docs/cli.md`](https://github.com/tuya/tyutool/blob/refactor/v3/docs/cli.md)。任何 CLI 变更必须先更新 `docs/cli.md`（AGENTS.md 规定）。本页只是镜像，以 markdown 为准。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/concepts.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/concepts.md new file mode 100644 index 000000000..7177055d9 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/concepts.md @@ -0,0 +1,94 @@ +--- +title: 基础概念 +description: "tyutool 背后的词汇表——固件、烧录、擦除、读取、授权、UART/波特率、芯片型号，以及你在每一页都会见到的术语。" +keywords: + - tyutool 基础概念 + - 固件 + - 烧录 + - 授权 + - UART + - 波特率 + - tuyaopen +--- + +在动手点击按钮之前，先花几分钟读懂这套词汇表——它能让你在后续每一页都看得明白。本页只讲概念，不涉及具体操作。 + +tyutool 通过一条串口链路与设备通信：电脑上的 tyutool 发出的指令，经由 USB 转串口适配器，以 UART 电信号的形式送达设备里的 SoC，最终读写那颗 flash 芯片。下图展示了这条链路的完整拓扑。 + +图 1 · tyutool 到设备的烧录链路拓扑：tyutool → USB → 适配器 → UART(TX/RX/GND) → SoC → Flash 芯片 + +*图 1 · tyutool 到设备的烧录链路拓扑：tyutool → USB → 适配器 → UART(TX/RX/GND) → SoC → Flash 芯片。* + +:::note[阅读建议] +第一次接触固件烧录？建议按顺序读完前 6 节；第 7、8 节可作为术语速查表。 +::: + +## 什么是固件 + +固件（firmware）就是存放在设备 flash 芯片里的程序。烧录固件通常是为了**升级**（增加功能）、**修复**（修复 bug）或**定制**（烧入你自己的构建）。固件本质上就是一段字节数据。 + +## 什么是烧录 / 刷写 + +烧录（flashing，也叫刷写/写入）就是把固件字节写入设备 flash 芯片的动作。链路传数据：① tyutool 读固件切块 → ② 经 USB 到适配器转 UART → ③ UART(TX/RX/GND) 到 SoC 写 flash。 + +:::warning +烧录是覆盖性写入。重要数据请先[读取](#读取-read)备份。 +::: + +## 擦除 Erase + +擦除把 flash 某些区域清空为 `0xFF`。典型场景：写入前清场 / 整片擦除。擦除预设： + +| 擦除预设 | 含义 | +| :-- | :-- | +| `authInfo` | 只擦除授权信息区（UUID/AuthKey），保留固件与其他数据 | +| `fullChipNoRf` | 整片擦除，但保留射频校准区（RF cal） | +| `fullChip` | 整片完全擦除（含射频校准） | + +:::tip +`fullChipNoRf` 是最常用的"安全彻底擦除"。 +::: + +## 读取 Read +读取是烧录的逆操作：把 flash 芯片里的字节读出来，用于备份（整片读取或分段读取）。 + +## 授权 Authorize +授权（TuyaOpen UART auth）写入 `UUID` + `AuthKey`，让设备能连涂鸦云。授权与固件是两件独立的事。 + +:::danger +`UUID` 与 `AuthKey` 是从涂鸦**购买**来的凭据，写入伪造/重复凭据会污染设备池。 +::: + +授权分两种操作：授权读取（auth-read）/ 授权写入（auth-write）。 + +## 串口 / UART / 波特率 +串口、USB 转串口适配器（CH340/CP2102/FT232）、UART 三线（TX/RX/GND，交叉接线）、波特率： + +| 波特率 | 典型用途 | +| :-- | :-- | +| `115200` | 最通用、最稳定的默认速率 | +| `460800` | 较快，稳定性仍较好 | +| `921600` | 高速，需芯片与线材支持 | + +:::tip +从 `115200` 开始最稳妥。 +::: + +## 芯片型号 +芯片型号决定了通信协议、波特率与 Flash 容量。完整列表见[固件烧录](./flash.md)与[命令行](./cli.md)。 + +## TY 工具术语表 + +| 术语 | 含义 | +| :-- | :-- | +| Flash | 把固件写入 flash 芯片 | +| Erase | 把 flash 区域清空为 `0xFF` | +| Read | 把 flash 芯片里的字节读出来 | +| Authorize | 写入 `UUID`/`AuthKey` 凭据 | +| UUID | 设备唯一标识（凭据） | +| AuthKey | 与 UUID 配对的认证密钥 | +| Baud | 串口通信速率 | +| UART | 走 TX/RX/GND 线的串口协议 | +| Segment | 多段烧录里的一段连续块 | +| Erase preset | 命名的擦除范围（如 `authInfo`） | +| MAC | 设备的媒体访问控制地址 | diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/faq.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/faq.md new file mode 100644 index 000000000..1f41c8bee --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/faq.md @@ -0,0 +1,135 @@ +--- +title: 常见问题与故障排查 +description: "以症状为先的 tyutool 故障排查——连接与端口、烧录失败、授权、平台问题（Linux 白屏、Windows WebView2），以及如何附日志反馈 bug。" +keywords: + - tyutool 常见问题 + - 故障排查 + - 烧录失败 + - 授权失败 + - Linux 白屏 + - WebView2 + - tuyaopen +--- + + +本页以问题为先：先列出**症状**，再给最小步骤的排查与修复。命令行片段与 GUI 操作并存。 + +## 连接 / 端口 + +### 设备 / 串口没出现在下拉框 +**症状**：端口选择器空 / `tyutool list-ports` 无输出。 + +1. 拔插换口换线。 +2. 装驱动（CH340/CP2102/FT232）。 +3. CLI 复核： + +```bash +tyutool list-ports +tyutool usb-port-survey # 输出原始 USB 元数据，便于跨系统排错 +``` + +4. macOS 见 [macOS 串口权限](#macos-串口权限)。 +5. Linux 确认在 dialout/tty 组并注销重登。 + +:::tip +点刷新或重开应用。 +::: + +### macOS 串口权限 +**症状**：端口看得见但权限错误。 + +```bash +sudo dseditgroup -o edit -a $USER -t user dialout +``` + +然后注销重登。较新 macOS 在 **隐私与安全性 → 配件** 里允许。详见项目 [README Troubleshooting](https://github.com/tuya/tyutool#readme)。 + +### 端口被占用 +**症状**：`Permission denied` / `Device or resource busy`。 + +关掉其他程序（串口调试、Arduino IDE、minicom、picocom）；避免 GUI+CLI 同时操作；可开自动释放。 + +## 烧录 + +### 烧录失败 / 握手失败 +**症状**：Handshake 失败 / Failed to sync。 + +原因：芯片型号选错（`-d bk7231n` / `-d esp32` / `-d t5ai`）；波特率不对（先降到 115200）；设备没进下载模式（`tyutool reset`）；接线/供电。 + +:::warning +先做最小复现：`tyutool read -d <芯片> -p <端口> -l 0x1000`。 +::: + +### 擦除报"未对齐" +**症状**：`unaligned` / `address not aligned` / `sector boundary`。 + +擦除要求 4 KiB 对齐： + +```bash +# 正确：起始与长度都对齐到 4 KiB +tyutool erase -d bk7231n -s 0x0000 -l 0x200000 +tyutool erase -d bk7231n -s 0x8000 -l 0x4000 + +# 错误：0x9000 不是 4 KiB 的整数倍 +tyutool erase -d bk7231n -s 0x9000 -l 0x1000 # ❌ 报未对齐 +``` + +:::tip +用 GUI 的对齐动作，或向下取整到 `0x1000` 的倍数。 +::: + +### 进度卡住 +**症状**：某阶段长时间 0% 或反复重试。 + +降波特（921600 → 460800 → 115200）；换线换供电；开调试日志或 CLI `--verbose` 到 debug/trace（位置见 [CLI · 全局选项](./cli.md)）；用 `Ctrl+C` 优雅取消。 + +## 授权 + +### 授权失败 +**症状**：authorize 写入失败 / UUID/AuthKey 无效。 + +凭证一机一次（用过作废）；先 auth-read `tyutool authorize -p <端口>`；`--uuid` / `--authkey` 必须同时给；指定 `-d` 时序。 + +:::note +凭证从涂鸦开发者平台获取，绑定芯片/产品。 +::: + +### 凭证显示问题 +**症状**：看不到完整 / 复制出 `****`。 + +GUI 默认掩码，点 Show 或复制按钮；CLI auth-read： + +```bash +tyutool authorize -p <端口> +tyutool authorize -p <端口> -d esp32 # 按芯片时序读取 +``` + +复制后及时清空剪贴板。 + +## 平台 + +### Linux 窗口空白（WebKit 合成失败） +```bash +export WEBKIT_DISABLE_COMPOSITING_MODE=1 +``` + +然后启动 AppImage；可加入 `~/.bashrc`。详见 README。 + +### Windows 缺少 WebView2 +装 Edge WebView2 Runtime Evergreen：官网下载页 → Evergreen Standalone Installer → 运行重启。 + +:::note +企业/离线可用 Fixed Version 离线包。 +::: + +## 日志与反馈 + +### 如何反馈 bug（附日志） +1. **导出/打开日志**。GUI：设置 → 诊断 → 查看日志 → "导出日志并报告问题" = zip + 预填 issue；CLI：看 banner 的 `log:` 行，`--verbose` 打 stderr。 +2. **用 issue 模板**。[Issues → New issue](https://github.com/tuya/tyutool/issues/new/choose)，选 Bug 报告。 +3. **填全关键字段**：Version / OS / Chip / Platform / baud / Steps / Expected vs actual。 +4. **附会话日志**：拖 zip 到 issue，或 CLI 贴 `tyutool-<时间戳>.log`。 + +:::warning +日志含敏感信息（UUID/AuthKey），先遮蔽。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/flash.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/flash.md new file mode 100644 index 000000000..dd748f1e2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/flash.md @@ -0,0 +1,127 @@ +--- +title: 固件烧录 +description: "固件烧录页的完整参考——连接栏、Flash/Erase/Read/Authorize 四个标签、芯片清单表、多段烧录、擦除预设，以及右侧进度与日志面板。" +keywords: + - tyutool 固件烧录 + - 擦除 + - 读取 + - 授权 + - 芯片型号 + - tuyaopen +--- + +本页是**固件烧录页**的完整参考：连接栏、Flash / Erase / Read / Authorize 四个标签、芯片清单表、多段烧录、擦除预设，以及右侧的进度与日志面板。 + +## 页面总览 + +页面分三部分：顶部连接栏 / 左侧操作卡片（四个标签）/ 右侧进度与日志面板。 + +Flash 页连接栏——串口下拉框、波特率、芯片选择器、状态点 + +*Flash 页连接栏——串口下拉框、波特率、芯片选择器、状态点。* + +## 连接栏 + +- **串口**（每次展开时重扫） +- **波特率** —— `115200` / `460800` / `921600` / `1000000` / `1500000` / `2000000`，外加自定义（300–4,000,000）。Authorize 标签下为授权波特率。 +- **芯片选择器** —— Authorize 下多出 `other` 选项。 +- **状态点** —— 绿色 = 已连接就绪；灰/红 = 未连接或握手失败。 + +:::note[自动连接 / 自动释放] +操作开始时 tyutool 自动连接，完成后自动释放端口。 +::: + +## 选择芯片 +权威芯片清单（来源：`chip-manifests.ts`）： + +| 芯片(`-d`) | 烧录波特率 | 授权波特率 | Flash 容量 | 擦除预设 | +| :-- | :-- | :-- | :-- | :-- | +| `esp32` | 460800 | 115200 | 4 MiB | fullChip | +| `esp32c3` | 460800 | 115200 | 4 MiB | fullChip | +| `esp32c6` | 460800 | 115200 | 8 MiB | fullChip | +| `esp32p4` | 460800 | 115200 | 16 MiB | fullChip | +| `esp32s3` | 460800 | 115200 | 16 MiB | fullChip | +| `t5ai`(别名 `t5`) | 921600 | 115200 | 8 MiB | authInfo, fullChipNoRf | +| `t1` | 921600 | 115200 | 8 MiB | authInfo, fullChipNoRf | +| `t3` | 921600 | 115200 | 4 MiB | authInfo, fullChipNoRf | +| `t2` | 921600 | 115200 | 2 MiB | authInfo, fullChipNoRf | +| `bk7231n` | 921600 | 115200 | 2 MiB | authInfo, fullChipNoRf | +| `ln882h` | 115200 | 115200 | 2 MiB | fullChip | +| `other`(仅授权) | — | 115200 | — | 无 | + +:::note +默认选中 `t5ai`；旧版 `t5`/`T5` 别名归一化为 `t5ai`。 +::: + +:::tip +烧录波特率可调高，但不建议超过 `2000000`。 +::: + +:::info +擦除要求 4 KiB 对齐（`0x1000` 倍数），仅 `other` 豁免。 +::: + +## Flash 标签 — 烧录 +多段烧录：最多 10 段，每段含固件路径(`.bin`/`.hex`/`.elf`/`.img`)+起始/结束地址（十六进制）。新段起始默认=上一段结束；选固件后结束地址自动算 = start+文件大小。所有段填好才启用 Flash 按钮。 + +Flash 标签——多段烧录，含固件路径与起始/结束地址 + +*Flash 标签——多段烧录，含固件路径与起始/结束地址。* + +:::tip +典型场景：bootloader + app 一次写入。 +::: + +## Erase 标签 — 擦除 +按地址擦除（实时校验对齐）或用高级擦除预设（含义同[基础概念](./concepts.md)：`authInfo` / `fullChipNoRf` / `fullChip`）。执行前有确认对话框；地址不对齐时提供"对齐"操作。 + +:::danger[擦除会破坏数据] +擦除不可撤销。整片擦除清空 RF cal 可能导致设备无法连网。请先备份。 +::: + +Erase 标签——按地址擦除与高级擦除预设 + +*Erase 标签——按地址擦除与高级擦除预设。* + +## Read 标签 — 读取 + +用于备份。选择保存目录（Tauri）或让浏览器下载；默认文件名 `tyutool_read_.bin`；结束地址默认取芯片完整容量（整片读取）。文件已存在时选覆盖或追加时间戳。 + +:::note +部分芯片不支持读取。 +::: + +Read 标签——把 flash 读取到文件用于备份 + +*Read 标签——把 flash 读取到文件用于备份。* + +## Authorize 标签 — 授权 + +TuyaOpen UART 授权，写 `UUID` + `AuthKey`（掩码显示、不可复制）；有 Copy credentials 按钮。外部链接指向 TuyaOpen 授权购买与本地化文档。操作： + +- **读取授权（Read Auth）** —— 只读，仅占用串口不写入。 +- **授权（Authorize）** —— 写入；需先填好 `UUID` + `AuthKey`，并有确认流程。 + +:::danger +凭据妥善保管（购买来的）；`other` 芯片仅授权、无 flash 插件。 +::: + +Authorize 标签——UUID/AuthKey 输入（掩码），读取授权与授权操作 + +*Authorize 标签——UUID/AuthKey 输入（掩码），读取授权与授权操作。* + +## 进度与日志 + +右侧常驻面板：分阶段进度条（每阶段主题色/百分比/indeterminate）+ 日志面板（锁定自动滚动/清空/复制）。 + +进度条与日志面板——分阶段进度与日志条目 + +*进度条与日志面板——分阶段进度与日志条目。* + +## 端口占用 + +固件烧录页与[串口调试](./serial-debug.md)页共用同一批串口。 + +:::warning +端口被占用时 tyutool 请你先释放；可在串口调试开自动释放（见[串口调试](./serial-debug.md)）。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/getting-started.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/getting-started.md new file mode 100644 index 000000000..cafd5ae5f --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/getting-started.md @@ -0,0 +1,128 @@ +--- +title: "快速上手：第一次烧录" +sidebar_label: 快速上手 +description: "本页带你从「下载了 App」一路走到「成功烧录第一台设备」——前置准备、连接、烧录步骤，预计 5–10 分钟。" +keywords: + - tyutool 快速上手 + - 第一次烧录 + - 连接设备 + - 固件烧录 + - tuyaopen +--- + +import FeatureCardGrid from '@site/src/components/FeatureCardGrid'; + +本页带你从「下载了 App」一路走到「成功烧录第一台设备」。整条路径是线性的，按顺序读完即可完成第一次烧录，预计 5–10 分钟。 + +:::tip[先读] +如果你完全没接触过固件刷写，先看[基础概念](./concepts.md)。 +::: + +## 前置准备 + +动手前请确认以下清单均已就绪——烧录需要软硬件齐备，缺一不可。 + +- **一台受支持的设备**：tyutool 面向涂鸦生态 IoT 设备，具体支持的芯片型号见[固件烧录](./flash.md)页。 +- **一个 USB 转串口适配器**：正确接到设备的 UART（TX/RX/GND，视情况再接电源）。接线时必须**交叉**：电脑端 TX 接设备端 RX，反之亦然。 +- **设备进入下载/烧录模式**：不同设备进入方式各异（按键组合、短接焊点、上电时序等）。 + +:::warning +接线方式与进入下载模式的方法是**设备相关**的，没有通用步骤——请先查阅你的设备说明或[常见问题](./faq.md)。tyutool **无法**替你把设备切进下载模式，这一步必须由你手动完成；设备没进下载模式时，tyutool 会一直等待握手并最终超时。相关概念（UART / 下载模式 / 波特率）见[基础概念](./concepts.md)。 +::: + +## 下载与安装 + +tyutool 为 Windows、macOS、Linux 提供预编译安装包。请到项目的 README 下载表，按你的操作系统选择对应版本，下载后照常规方式安装即可。各平台的常见坑点如下（完整说明见[常见问题](./faq.md)）。 + +:::warning[macOS 串口权限] +macOS 默认禁止普通用户访问串口设备。请把当前用户加入 `dialout` 组，然后**注销重新登录**生效： + +```bash +sudo dseditgroup -o edit -a $USER -t user dialout +``` + +详见[常见问题](./faq.md)。 +::: + +:::warning[Linux 白屏] +部分 Linux 桌面下，tyutool 启动后窗口空白不渲染。在启动命令前加上该环境变量可绕过： + +```bash +WEBKIT_DISABLE_COMPOSITING_MODE=1 ./tyutool-gui_linux_x86_64_appimage_x.x.x.AppImage +``` + +详见[常见问题](./faq.md)。 +::: + +:::tip +上面这些小坑都属于**环境**问题，与 tyutool 本身无关；解决后通常一劳永逸，之后不会再遇到。 +::: + +## 首次启动 + +安装完成后启动 tyutool，主窗口分为两部分：左侧是导航**侧边栏**，右侧是当前功能的工作区。侧边栏提供四个主要入口： + +- **Flash**（固件烧录）——烧录、读取、擦除 flash 芯片。 +- **Serial Debug**（串口调试）——实时收发串口数据、查看设备日志。 +- **Toolbox**（工具箱）——辅助工具集合。 +- **Settings**（设置）——配置路径、日志级别等应用选项。 + +本页剩下的步骤都在 **Flash** 页完成——它是你第一次烧录时唯一需要关心的入口。 + +tyutool 主窗口停在 Flash 页，串口下拉框展开、显示已检测到的端口 + +*tyutool 主窗口停在 Flash 页，串口下拉框展开、显示已检测到的端口。* + +## 连接设备 + +接线检查无误、设备已进入下载模式后，按下面顺序在 tyutool 里建立连接。 + +1. 把 USB 转串口适配器插到电脑的 USB 口。 +2. 在 tyutool 的 Flash 页，点击**串口**下拉框。 +3. 在列出的端口里选择你的适配器（如 `COM3` / `/dev/ttyUSB0` / `/dev/cu.SLAB_USBtoUART`）。 +4. 留意旁边的**状态点**：绿色表示已连接并就绪；灰色或红色表示未连上或握手失败。 + +选好端口后，波特率与芯片型号由 tyutool **自动填入推荐值**，可直接采用。**调高**更快但易失稳失败，**调低**更慢更稳。详见[固件烧录](./flash.md)。 + +Flash 页顶部连接栏——串口下拉框展开、显示已检测到的端口，波特率与芯片选项 + +*Flash 页顶部连接栏——串口下拉框展开、显示已检测到的端口，波特率与芯片选项。* + +:::tip +如果下拉框里看不到任何端口，先确认适配器已插好、驱动已装（CH340/CP2102/FT232），并检查 macOS/Linux 的串口访问权限（见上方安装小节）。 +::: + +## 完成第一次烧录 + +设备连上后，烧录本身的操作非常简短。按顺序走完以下步骤即可写入第一份固件。 + +1. **选择芯片型号**：在 Flash 页顶部选择你设备对应的芯片（型号决定了通信协议与地址布局，选错会烧录失败）。 +2. **选择固件**：切到 **Flash** 标签，点击选择固件文件，挑一份 `.bin` 固件。 +3. **确认地址**：选好固件后，写入地址会**自动填入**默认值，一般无需修改。 +4. **点击烧录**：点击 **Flash** 按钮开始写入。 +5. **观察进度**：盯着进度条与下方日志，正常会一路推进到 100%。 +6. **等待重启**：写入完成后设备会**自动重启**并运行新固件——到这里你的第一次烧录就完成了。 + +烧录页正在写入——已选好芯片与固件、端口已连接，烧录进度 25%，图上编号对应上方各步骤 + +*烧录页正在写入——已选好芯片与固件、端口已连接，烧录进度 25%，图上编号对应上方各步骤。* + +各步骤的进阶选项（地址微调、擦除策略、校验、保存日志等）请见[固件烧录](./flash.md)页。 + +:::danger +烧录期间**切勿**拔掉 USB 线或断电，否则可能写坏数据。万一烧录失败，先降到 `115200` 波特率重试；仍不行则参考[常见问题](./faq.md)。 +::: + +## 下一步 + +恭喜完成第一次烧录！接下来可以按需求深入各个功能页： + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/index.md new file mode 100644 index 000000000..cf2ed773a --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/index.md @@ -0,0 +1,36 @@ +--- +title: tyutool V3 使用指南 +description: "欢迎使用 tyutool — 涂鸦生态 IoT 设备的桌面 GUI + 命令行工具，用于固件烧录、串口调试与批量授权。" +keywords: + - tyutool + - V3 使用指南 + - 固件烧录 + - 串口调试 + - 批量授权 + - tuyaopen +--- + +import FeatureCardGrid from '@site/src/components/FeatureCardGrid'; + +## 欢迎使用 + +tyutool 是一款桌面 GUI + 命令行工具，用于对涂鸦生态的 IoT 设备进行固件烧录、串口调试与批量授权。 + +:::note[第一次使用？] +如果你是第一次使用，请先阅读[快速上手](./getting-started.md) —— 一条 5–10 分钟的线性路径，带你从下载走到第一次成功烧录。 +::: + +## 功能导览 + +点击下方各功能入口深入了解： + + diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/serial-debug.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/serial-debug.md new file mode 100644 index 000000000..1ea4f5ae5 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/serial-debug.md @@ -0,0 +1,91 @@ +--- +title: 串口调试 +description: "串口调试页的完整参考——串口终端与日志监视器，覆盖连接与 UART 配置、设备复位、ASCII/Hex 日志视图、发送栏、Hex 弹窗、关键词过滤标签，以及自动释放与自动保存。" +keywords: + - tyutool 串口调试 + - UART 配置 + - Hex 视图 + - 过滤标签 + - 日志监视 + - tuyaopen +--- + + +本页是**串口调试**页的完整参考：串口终端 / 日志监视器，覆盖连接与 UART 配置、设备复位、ASCII/Hex 日志视图、发送栏、Hex 弹窗、关键词过滤标签，以及自动释放与自动保存。 + +## 总览 + +一个完整的串口终端。保活机制：跳到其他页面再回来，后台 RX 流不中断。 + +串口调试总览——终端工作区，含日志视图与发送栏 + +*串口调试总览——终端工作区，含日志视图与发送栏。* + +:::note +这里的串口与[固件烧录](./flash.md)页共用。 +::: + +## 连接与串口配置 +串口选择（重扫）/ 连接-断开 / 状态指示。高级 UART 设置在串口设置弹窗： + +| 参数 | 可选值 | 说明 | +| :-- | :-- | :-- | +| 波特率 Baud | `9600`–`921600` + 自定义 | 未覆盖时默认取当前 flash 芯片的日志波特率 | +| 数据位 Data bits | `5` / `6` / `7` / `8` | 每帧数据位数 | +| 校验位 Parity | `none` / `odd` / `even` | 无/奇/偶 | +| 停止位 Stop bits | `1` / `1.5` / `2` | 每帧停止位 | + +:::tip[波特率跟随芯片] +先在烧录页选好芯片，串口调试波特率自动对齐。 +::: + +## 设备复位 + +通过 DTR/RTS 复位。复位当前会话端口 / 复位其他控制端口（用 runtime chip id 指定另一端口）。 + +:::note +复位 ≠ 断开。 +::: + +## 日志视图 +ASCII 视图 / Hex 视图（每行 8/16/32 字节）；ANSI 着色开关；字号 10–18px；时间戳开关；方向徽标（TX/RX/SYS）；清空；导出。 + +日志视图——ASCII 与 Hex 行，带方向徽标与时间戳 + +*日志视图——ASCII 与 Hex 行，带方向徽标与时间戳。* + +:::warning[可见窗口上限 3000 行] +超出旧行移除；请用自动保存或及时导出。 +::: + +## 发送栏 + +ASCII 或 Hex 模式；可选 `\r\n`；按 `Enter` 发送；历史最多 20 条，用 `↑` / `↓` 翻选。 + +发送栏——ASCII/Hex 模式切换、发送按钮、历史 + +*发送栏——ASCII/Hex 模式切换、发送按钮、历史。* + +## Hex 弹窗 + +选中一段 RX 数据后并排展示 hex + ASCII。 + +:::tip +适合核对结构化二进制（协议帧/授权回复）。 +::: + +## 过滤标签 + +给关键词各建一标签。关键词可纯文本或正则；6 色循环配色；实时计数命中条数；点标签只看匹配行；"全部"恢复；"加载更早"分页。过滤在服务端针对整个会话执行。 + +过滤标签——关键词标签，带实时命中计数与配色 + +*过滤标签——关键词标签，带实时命中计数与配色。* + +## 自动释放 / 自动保存 +- **自动释放（Auto-release）**：解决端口争用。固件烧录页需要端口时串口调试自动释放（可开启确认提示）；烧录结束后自动恢复连接。 +- **自动保存（Auto-save）**：留存完整会话日志（也可在[设置](./settings.md)配置）。设置保存目录；时间戳文件名；分块写入（最大 128 KiB）。 + +:::note +手动导出 = 当前可见窗口；自动保存 = 整个会话。 +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/settings.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/settings.md new file mode 100644 index 000000000..276acf6d2 --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/settings.md @@ -0,0 +1,83 @@ +--- +title: 设置 +description: "设置页的完整参考——更新中心、外观与语言、诊断与日志、串口日志、关于，以及设置的持久化方式。" +keywords: + - tyutool 设置 + - 更新中心 + - 外观 + - 诊断 + - 日志文件 + - tuyaopen +--- + +本页是**设置**页的完整参考：更新中心、外观与语言、诊断与日志、串口日志、关于，以及设置的持久化方式。 + +## 更新中心 +- **当前版本（Installed build）**。 +- **检查更新** —— 仅桌面端（Tauri），打开 Update 对话框，不受间隔限制。 +- **自动检查间隔** —— 启动时静默检查，超间隔才触发。选项：`Off` / `1h` / `6h` / `12h` / `24h`。 + +更新中心——当前版本、检查更新、自动检查间隔 + +*更新中心——当前版本、检查更新、自动检查间隔。* + +:::note +Web 端无自动更新（依赖 Tauri updater 插件）。 +::: + +## 外观与语言 +- **主题** —— `Light` / `Dark` / `System`（立即生效，System 跟随系统）。 +- **语言** —— `Auto` / `简体中文` / `English`（Auto：`zh` 开头用中文）。 +- **串口指示器** 开关。 + +外观与语言——主题、语言、串口指示器开关 + +*外观与语言——主题、语言、串口指示器开关。* + +:::info +高级 UART 参数在串口调试页（见[串口调试](./serial-debug.md)）。 +::: + +## 诊断与日志 +- **调试日志开关** —— 总开关，关闭则后端 log level = `off`。 +- **日志级别** —— Error / Warn / Info / Debug / Trace，经 `log::set_max_level` 应用到 Rust 后端。 +- **打开日志文件夹。** +- **查看日志** —— 打开 LogViewer 对话框。 +- **导出日志并报告问题** —— 打包日志并打开预填的 GitHub issue（含版本/OS）；仅桌面端。 + +诊断与日志——日志开关、级别、打开/查看/导出操作 + +*诊断与日志——日志开关、级别、打开/查看/导出操作。* + +### 日志文件如何落地 + +日志由 `tauri-plugin-log` 写入。按会话命名 `tyutool-<时间戳>.log`；10 MB 滚动到 `-1.log`、`-2.log`，启动时清理旧文件。日志目录： + +- Linux：`~/.local/share/tyutool/` +- macOS：`~/Library/Application Support/tyutool/` +- Windows：`%APPDATA%\tyutool\` + +:::note +级别作用在 Rust 后端。 +::: + +## 串口日志 +串口调试自动保存的镜像入口：自动保存开关、保存目录、时间戳格式。 + +:::note +与串口调试页是同一份 store。 +::: + +## 关于 +- **应用版本。** +- **开源许可** —— 打开 LICENSE 页面。 + +## 持久化 + +- **桌面端**写 `settings.json`（`tauri-plugin-store`）。 +- **Web 端**写 localStorage。 +- 主题应用到 DOM（System 模式监听系统配色）。 + +:::note +桌面端 `settings.json` 键名与 Web 端 localStorage 一一对应。 +::: diff --git a/sidebars.js b/sidebars.js index 558875e4e..12516ed82 100644 --- a/sidebars.js +++ b/sidebars.js @@ -7,6 +7,7 @@ // hardwareSidebar -> Hardware (/docs/hardware/*) // cloudSidebar -> Cloud & AI (/docs/cloud/*) // duckyclawSidebar -> TuyaOpenClaw (/docs/duckyclaw/*) (brand formerly DuckyClaw; route kept) +// tyutoolSidebar -> tyutool (/docs/tyutool/*) // // SHARED / UNIVERSAL DOCS // ----------------------- @@ -558,9 +559,33 @@ const duckyclawSidebar = [ 'duckyclaw/DuckyClaw-TuyaClaw', ] +// ============================================================================= +// tyutool (parallel to the TuyaOpen SDK docs — not nested inside them) +// ============================================================================= +const tyutoolSidebar = [ + { type: 'doc', id: 'tyutool/index', label: 'Overview' }, + // Concepts before Getting Started: both pages tell readers new to flashing + // to read Concepts first, so the sidebar order should match that advice. + 'tyutool/concepts', + 'tyutool/getting-started', + 'tyutool/flash', + 'tyutool/serial-debug', + 'tyutool/settings', + { + type: 'category', + label: 'Batch Flash & Auth', + collapsed: false, + link: { type: 'doc', id: 'tyutool/batch-flash-auth' }, + items: ['tyutool/batch-auth-operator', 'tyutool/batch-auth-developer'], + }, + 'tyutool/cli', + 'tyutool/faq', +] + module.exports = { sdkSidebar, hardwareSidebar, cloudSidebar, duckyclawSidebar, + tyutoolSidebar, } diff --git a/src/components/FeatureCardGrid.jsx b/src/components/FeatureCardGrid.jsx new file mode 100644 index 000000000..91b59e3af --- /dev/null +++ b/src/components/FeatureCardGrid.jsx @@ -0,0 +1,29 @@ +import React from 'react'; +import clsx from 'clsx'; +import Link from '@docusaurus/Link'; +import styles from './FeatureCardGrid.module.css'; + +export default function FeatureCardGrid({ items = [], columns = 3 }) { + if (!items.length) return null; + + const colClass = `col--${Math.max(1, Math.round(12 / columns))}`; + + return ( +
+ {items.map((item) => ( +
+ + + {item.icon && ( + + {item.icon} + + )} + {item.title} + {item.description} + +
+ ))} +
+ ); +} diff --git a/src/components/FeatureCardGrid.module.css b/src/components/FeatureCardGrid.module.css new file mode 100644 index 000000000..255416687 --- /dev/null +++ b/src/components/FeatureCardGrid.module.css @@ -0,0 +1,39 @@ +.card { + height: 100%; + padding: 1.25rem 1.5rem; + text-decoration: none !important; + color: var(--ifm-font-color-base); + transition: + transform 0.15s ease, + box-shadow 0.15s ease, + border-color 0.15s ease; +} + +.card:hover { + transform: translateY(-3px); + box-shadow: var(--ifm-global-shadow-md); + border-color: var(--ifm-color-primary); + color: var(--ifm-font-color-base); +} + +.icon { + display: block; + font-size: 1.75rem; + line-height: 1; + margin-bottom: 0.6rem; +} + +.title { + display: block; + font-weight: 600; + font-size: 1.05rem; + color: var(--ifm-heading-color); + margin-bottom: 0.35rem; +} + +.description { + display: block; + font-size: 0.875rem; + color: var(--ifm-color-emphasis-700); + line-height: 1.5; +} diff --git a/src/data/tutorials.js b/src/data/tutorials.js index defbccbc2..be8663002 100644 --- a/src/data/tutorials.js +++ b/src/data/tutorials.js @@ -163,8 +163,8 @@ export const tutorials = { { id: 'tyutool-guide', category: 'basics', - kind: 'interactive', - href: '/tyutool-guide', + kind: 'markdown', + href: '/docs/tyutool', title: 'tyutool — flashing & authorization guide', description: 'Install tyutool, flash your first board, authorize it for Tuya IoT, and fix common hiccups (GUI + CLI).', @@ -589,8 +589,8 @@ export const tutorials = { { id: 'tyutool-guide', category: 'basics', - kind: 'interactive', - href: '/tyutool-guide', + kind: 'markdown', + href: '/docs/tyutool', title: 'tyutool —— 烧录与授权指南', description: '安装 tyutool、烧录第一块板子、为涂鸦 IoT 授权，并解决常见问题（GUI + CLI）。', tags: ['flashing', 'cli'], diff --git a/src/pages/learn/using-license-key.jsx b/src/pages/learn/using-license-key.jsx index b2c0130ec..71464bb8e 100644 --- a/src/pages/learn/using-license-key.jsx +++ b/src/pages/learn/using-license-key.jsx @@ -164,7 +164,7 @@ export default function UsingLicenseKey() { const locale = i18n.currentLocale === 'zh' ? 'zh' : 'en'; const c = content[locale]; const pricingHref = locale === 'zh' ? '/zh/pricing' : '/pricing'; - const tyutoolHref = locale === 'zh' ? '/zh/tyutool-guide' : '/tyutool-guide'; + const tyutoolHref = locale === 'zh' ? '/zh/docs/tyutool' : '/docs/tyutool'; return ( diff --git a/src/pages/tutorials/using-license-key.jsx b/src/pages/tutorials/using-license-key.jsx index b2c0130ec..71464bb8e 100644 --- a/src/pages/tutorials/using-license-key.jsx +++ b/src/pages/tutorials/using-license-key.jsx @@ -164,7 +164,7 @@ export default function UsingLicenseKey() { const locale = i18n.currentLocale === 'zh' ? 'zh' : 'en'; const c = content[locale]; const pricingHref = locale === 'zh' ? '/zh/pricing' : '/pricing'; - const tyutoolHref = locale === 'zh' ? '/zh/tyutool-guide' : '/tyutool-guide'; + const tyutoolHref = locale === 'zh' ? '/zh/docs/tyutool' : '/docs/tyutool'; return ( diff --git a/src/pages/tyutool-guide.jsx b/src/pages/tyutool-guide.jsx deleted file mode 100644 index de10478c1..000000000 --- a/src/pages/tyutool-guide.jsx +++ /dev/null @@ -1,683 +0,0 @@ -import Head from '@docusaurus/Head'; -import React, { useEffect, useRef, useState } from 'react'; -import Layout from '@theme/Layout'; -import Link from '@docusaurus/Link'; -import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; -import { clsx } from 'clsx'; -import useFromLearn from '@site/src/components/useFromLearn'; -import styles from './tyutool-guide.module.css'; - -const GITHUB = 'https://github.com/tuya/tyutool'; -const GITHUB_RELEASES = 'https://github.com/tuya/tyutool/releases/latest'; -const GITHUB_ISSUES = 'https://github.com/tuya/tyutool/issues/new'; -const PLATFORM = 'https://platform.tuya.com/purchase/index?type=6'; - -// Real product screenshots (hosted on the Tuya CDN). -const SHOTS = { - flashing: 'https://images.tuyacn.com/fe-static/docs/img/273ba9fc-5077-47bd-94d2-275747ca7232.png', - debug: 'https://images.tuyacn.com/fe-static/docs/img/3634a0b1-5aa0-44ad-bb0f-ce97b4a0d52c.png', - batch: 'https://images.tuyacn.com/fe-static/docs/img/986071e4-cd89-4f7a-8519-316f48de3763.png', - auth: 'https://images.tuyacn.com/fe-static/docs/img/aa0e7635-2952-4322-8696-3a866b01a6ec.png', -}; - -/* ----------------------------------------------------------------------- */ -/* Bilingual copy */ -/* ----------------------------------------------------------------------- */ - -const content = { - en: { - meta: 'tyutool help guide — install, flash, authorize, debug, and troubleshoot.', - breadcrumb: 'tyutool', - badge: 'Help guide', - title: 'tyutool guide', - subtitle: 'Install the tool, flash your first board, authorize it for Tuya IoT, and fix the common hiccups — GUI and CLI side by side.', - backToOverview: '← Back to tyutool overview', - tocTitle: 'On this page', - nav: [ - { id: 'install', label: 'Install' }, - { id: 'first-flash', label: 'First flash' }, - { id: 'authorize', label: 'Authorization' }, - { id: 'serial-debug', label: 'Serial debug' }, - { id: 'batch', label: 'Batch flash & auth' }, - { id: 'cli', label: 'CLI reference' }, - { id: 'troubleshooting', label: 'Troubleshooting' }, - { id: 'help', label: 'Getting help' }, - ], - install: { - title: 'Install', - intro: 'Download the latest build for your platform from the releases page. The recommended (★) packages support in-app auto-update.', - releasesBtn: 'Open GitHub releases', - platforms: [ - { - name: 'Windows', - steps: [ - 'Download the NSIS installer (*.exe) and run it, or grab the portable .zip and unzip it.', - 'Launch tyutool from the Start menu (installer) or the extracted folder (portable).', - ], - }, - { - name: 'macOS', - steps: [ - 'Download the Universal .dmg (★), open it, and drag tyutool to Applications.', - 'First launch is blocked because the build is not Apple-signed — see Troubleshooting below for the one-time "Open Anyway" step.', - ], - }, - { - name: 'Linux', - steps: [ - 'Download the AppImage (★), then make it executable: chmod +x tyutool-gui_*.AppImage and run it.', - 'Or install the .deb / .rpm for your distribution, or unpack the portable .tar.gz.', - ], - }, - ], - cliNote: 'Working headless or in CI? Download the standalone CLI build from the same releases page, extract it, and put tyutool_cli on your PATH — no runtime required.', - }, - firstFlash: { - title: 'Flash your first firmware', - guiTitle: 'With the GUI', - guiSteps: [ - 'Open tyutool and stay on the Flash tab.', - 'Select your chip (for example T5AI or BK7231N).', - 'Click Browse and choose the firmware .bin (for TuyaOpen, the file containing _QIO).', - 'Pick the serial port. On Tuya boards, hovering a port shows whether it is the flash/auth or the log port.', - 'Click Start flash and watch the progress through erase, write, and verify.', - ], - guiShot: 'Flashing a development board over USB-serial', - tip: 'The default flash baud rate is 921600. If flashing is unreliable, lower it; if it is slow, raising it can help but may fail on long cables.', - cliTitle: 'With the CLI', - cliIntro: 'The same flash, from a terminal — the port is auto-detected when only one is connected:', - cliCode: `# Auto-detect the port -tyutool write -d t5ai -f app_QIO.bin - -# Or name the port explicitly -tyutool write -d bk7231n -p /dev/ttyUSB0 -f firmware.bin`, - }, - authorize: { - title: 'Authorize a device', - intro: 'To use the Tuya IoT cloud, a device needs a UUID + AuthKey written to it. tyutool writes and verifies them over the same UART you flash with.', - guiSteps: [ - 'Open the Authorize tab.', - 'Select the authorization serial port.', - 'Keep the default UART settings (baud 115200, 8 data bits, 1 stop bit, no parity).', - 'Enter the UUID and AuthKey.', - 'Click Start authorization, then read back the state to confirm.', - ], - authShot: 'tyutool — authorization tab', - cliTitle: 'CLI equivalent', - cliCode: `# Read the current authorization state -tyutool authorize -p /dev/ttyUSB0 - -# Write a new UUID + AuthKey (both required) -tyutool authorize -p /dev/ttyUSB0 \\ - --uuid --authkey `, - where: 'Where do credentials come from?', - whereBody: 'TuyaOpen UUID/AuthKey pairs come from the Tuya Developer Platform, or can be purchased in bulk. The authorization codes for TuyaOpen and TuyaOS are not interchangeable.', - platformLink: 'Tuya Developer Platform', - authOnly: 'Devices that only need a license (already flashed) can use the auth-only "other" chip option — it skips flashing entirely.', - }, - serial: { - title: 'Watch logs with serial debug', - intro: 'The Serial debug tab is a full serial monitor for bringing up and debugging a board without a second tool.', - points: [ - 'Real ANSI color rendering, plus hex and ASCII views.', - 'Per-line timestamps and TX/RX direction badges.', - 'Send data as text or hex, with selectable line endings.', - 'Capture the session to a .txt file, or export logs for a bug report.', - ], - shot: 'Serial monitor showing live device logs', - note: 'The serial monitor releases the port automatically when you start a flash, so the two never fight over the connection.', - }, - batch: { - title: 'Batch flash & authorize', - intro: 'For small production runs, the batch tool drives many ports at once from a single window.', - points: [ - 'Auto-detect connected ports, or filter out the ones you do not want to touch.', - 'Flash the same firmware to every port in parallel, each with its own progress.', - 'Authorize from a spreadsheet — one UUID / AuthKey row per device.', - 'Cancel or retry an individual slot, and keep a running success / failure tally.', - ], - shot: 'Flashing and authorizing many boards at once', - }, - cli: { - title: 'CLI quick reference', - intro: 'Every command auto-detects a single port; pass -p to choose when several are present. Full details live in the repository.', - headers: ['Command', 'What it does'], - rows: [ - ['write -d -f ', 'Flash a .bin to the device'], - ['read -d -f ', 'Dump flash contents to a file'], - ['erase -d ', 'Erase a flash region'], - ['authorize --uuid --authkey ', 'Write or read UUID + AuthKey'], - ['reset -p ', 'Hardware-reset via DTR/RTS'], - ['list-ports [--json]', 'List available serial ports'], - ['update [--check]', 'Self-update the tool'], - ['completions ', 'Generate a shell completion script'], - ], - globalsTitle: 'Global flags', - globals: [ - ['--verbose', 'Also print developer diagnostics to stderr'], - ['--plain', 'ASCII-only output for CI / piping'], - ], - fullRef: 'Full CLI reference on GitHub', - }, - trouble: { - title: 'Troubleshooting', - items: [ - { - q: 'macOS: "tyutool can\'t be opened because the developer cannot be verified"', - body: 'Builds are not Apple-signed — this is expected. Open System Settings → Privacy & Security and click Open Anyway, or Control-click tyutool.app in Finder and choose Open.', - }, - { - q: 'macOS: no serial port appears', - body: 'Grant access under System Settings → Privacy & Security → Accessories (the label varies by macOS version).', - }, - { - q: 'Linux: blank / white window (common in VMs)', - body: 'This is a WebKit2GTK GPU compositing issue. Launch with compositing disabled:', - code: 'export WEBKIT_DISABLE_COMPOSITING_MODE=1\n./tyutool-gui_linux_x86_64_*.AppImage', - }, - { - q: 'Flashing always fails during "write" (CH34x boards)', - body: 'Install or update the CH34x USB-serial driver, then retry. After installing on macOS, allow the driver in Security settings — a working install shows the device as cu.wchusb*.', - links: [ - { label: 'Windows driver', href: 'https://www.wch.cn/downloads/ch343ser_exe.html' }, - { label: 'macOS driver', href: 'https://www.wch.cn/downloads/CH34XSER_MAC_ZIP.html' }, - ], - }, - ], - }, - help: { - title: 'Getting help', - intro: 'Still stuck? A good bug report makes it fixable.', - points: [ - 'Export logs from the GUI (or attach the CLI log file) so the maintainers can see what happened.', - 'Note your OS, the chip, and the exact command or steps you ran.', - ], - logPaths: 'CLI log file: ~/.local/share/tyutool/tyutool.log (Linux), ~/Library/Application Support/tyutool/tyutool.log (macOS), %APPDATA%\\tyutool\\tyutool.log (Windows).', - issueBtn: 'Open an issue on GitHub', - repoBtn: 'Browse the repository', - }, - }, - zh: { - meta: 'tyutool 帮助指南 —— 安装、烧录、授权、调试与故障排查。', - breadcrumb: 'tyutool', - badge: '帮助指南', - title: 'tyutool 使用指南', - subtitle: '安装工具、烧录第一块板子、为涂鸦 IoT 授权，并解决常见小问题 —— GUI 与 CLI 并列讲解。', - backToOverview: '← 返回 tyutool 概览', - tocTitle: '本页内容', - nav: [ - { id: 'install', label: '安装' }, - { id: 'first-flash', label: '首次烧录' }, - { id: 'authorize', label: '设备授权' }, - { id: 'serial-debug', label: '串口调试' }, - { id: 'batch', label: '批量烧录与授权' }, - { id: 'cli', label: 'CLI 参考' }, - { id: 'troubleshooting', label: '故障排查' }, - { id: 'help', label: '获取帮助' }, - ], - install: { - title: '安装', - intro: '从发布页下载对应平台的最新版本。推荐（★）安装包支持应用内自动更新。', - releasesBtn: '打开 GitHub 发布页', - platforms: [ - { - name: 'Windows', - steps: [ - '下载 NSIS 安装包（*.exe）并运行，或下载便携版 .zip 解压。', - '从开始菜单（安装版）或解压目录（便携版）启动 tyutool。', - ], - }, - { - name: 'macOS', - steps: [ - '下载 Universal .dmg（★），打开后将 tyutool 拖入"应用程序"。', - '由于安装包未经 Apple 签名，首次启动会被拦截 —— 请参见下方"故障排查"中一次性的"仍要打开"步骤。', - ], - }, - { - name: 'Linux', - steps: [ - '下载 AppImage（★），赋予可执行权限：chmod +x tyutool-gui_*.AppImage 后运行。', - '或安装对应发行版的 .deb / .rpm，或解压便携版 .tar.gz。', - ], - }, - ], - cliNote: '在无界面环境或 CI 中工作？从同一发布页下载独立 CLI 版本，解压后将 tyutool_cli 放入 PATH —— 无需任何运行时。', - }, - firstFlash: { - title: '烧录第一份固件', - guiTitle: '使用 GUI', - guiSteps: [ - '打开 tyutool，停留在"烧录"标签页。', - '选择芯片（例如 T5AI 或 BK7231N）。', - '点击"浏览"选择固件 .bin（TuyaOpen 选择包含 _QIO 的文件）。', - '选择串口。在涂鸦开发板上，鼠标悬停串口会提示它是烧录/授权口还是日志口。', - '点击"开始烧录"，观察擦除、写入、校验的进度。', - ], - guiShot: '通过 USB 串口为开发板烧录固件', - tip: '默认烧录波特率为 921600。若烧录不稳定可调低；若速度太慢可适当调高，但过高在长线缆下可能失败。', - cliTitle: '使用 CLI', - cliIntro: '在终端中完成同样的烧录 —— 仅连接一个串口时会自动检测：', - cliCode: `# 自动检测串口 -tyutool write -d t5ai -f app_QIO.bin - -# 或显式指定串口 -tyutool write -d bk7231n -p /dev/ttyUSB0 -f firmware.bin`, - }, - authorize: { - title: '为设备授权', - intro: '要接入涂鸦 IoT 云，设备需要写入 UUID + AuthKey。tyutool 通过与烧录相同的 UART 写入并校验它们。', - guiSteps: [ - '打开"授权"标签页。', - '选择授权串口。', - '保持默认 UART 设置（波特率 115200、8 数据位、1 停止位、无校验）。', - '输入 UUID 和 AuthKey。', - '点击"开始授权"，随后回读状态以确认。', - ], - authShot: 'tyutool —— 授权标签页', - cliTitle: 'CLI 等价命令', - cliCode: `# 读取当前授权状态 -tyutool authorize -p /dev/ttyUSB0 - -# 写入新的 UUID + AuthKey（两者都必填） -tyutool authorize -p /dev/ttyUSB0 \\ - --uuid --authkey `, - where: '凭据从哪里来？', - whereBody: 'TuyaOpen 的 UUID/AuthKey 来自涂鸦开发者平台，也可批量购买。TuyaOpen 与 TuyaOS 的授权码不能互换使用。', - platformLink: '涂鸦开发者平台', - authOnly: '只需授权（已烧录）的设备可使用授权专用的"other"芯片选项 —— 它会完全跳过烧录。', - }, - serial: { - title: '用串口调试查看日志', - intro: '"串口调试"标签页是一个完整的串口监视器，让你无需第二个工具就能点亮和调试板子。', - points: [ - '真实 ANSI 颜色渲染，并支持十六进制与 ASCII 视图。', - '逐行时间戳与 TX/RX 方向标记。', - '以文本或十六进制发送数据，行尾可选。', - '将会话抓取为 .txt 文件，或导出日志用于问题反馈。', - ], - shot: '串口监视器显示设备实时日志', - note: '开始烧录时，串口监视器会自动释放串口，因此两者不会争用同一连接。', - }, - batch: { - title: '批量烧录与授权', - intro: '面向小批量产线，批量工具可在同一窗口同时驱动多个串口。', - points: [ - '自动检测已连接串口，或过滤掉你不想操作的串口。', - '并行将同一固件烧录到每个串口，各自显示进度。', - '从表格驱动授权 —— 每台设备一行 UUID / AuthKey。', - '可单独取消或重试某个槽位，并实时统计成功 / 失败数量。', - ], - shot: '同时为多块开发板烧录与授权', - }, - cli: { - title: 'CLI 快速参考', - intro: '每个命令在仅有一个串口时自动检测；存在多个串口时用 -p 指定。完整说明见仓库。', - headers: ['命令', '作用'], - rows: [ - ['write -d <芯片> -f <文件>', '将 .bin 烧录到设备'], - ['read -d <芯片> -f <文件>', '将 Flash 内容导出到文件'], - ['erase -d <芯片>', '擦除一段 Flash 区域'], - ['authorize --uuid --authkey ', '写入或读取 UUID + AuthKey'], - ['reset -p <串口>', '通过 DTR/RTS 硬件复位'], - ['list-ports [--json]', '列出可用串口'], - ['update [--check]', '自我更新工具'], - ['completions ', '生成 Shell 补全脚本'], - ], - globalsTitle: '全局参数', - globals: [ - ['--verbose', '同时向 stderr 打印开发者诊断信息'], - ['--plain', '纯 ASCII 输出，适合 CI / 管道'], - ], - fullRef: 'GitHub 上的完整 CLI 参考', - }, - trouble: { - title: '故障排查', - items: [ - { - q: 'macOS：提示"无法打开 tyutool，因为无法验证开发者"', - body: '安装包未经 Apple 签名 —— 这是预期行为。打开"系统设置 → 隐私与安全性"点击"仍要打开"，或在访达中按住 Control 点击 tyutool.app 选择"打开"。', - }, - { - q: 'macOS：看不到串口', - body: '在"系统设置 → 隐私与安全性 → 配件"中授予访问权限（不同 macOS 版本名称略有差异）。', - }, - { - q: 'Linux：窗口空白 / 全白（虚拟机中常见）', - body: '这是 WebKit2GTK 的 GPU 合成问题。关闭合成后再启动：', - code: 'export WEBKIT_DISABLE_COMPOSITING_MODE=1\n./tyutool-gui_linux_x86_64_*.AppImage', - }, - { - q: '烧录在"write"阶段总是失败（CH34x 板子）', - body: '安装或更新 CH34x USB 转串口驱动后重试。在 macOS 安装后需在"安全性"设置中允许该驱动 —— 安装成功时设备名以 cu.wchusb 开头。', - links: [ - { label: 'Windows 驱动', href: 'https://www.wch.cn/downloads/ch343ser_exe.html' }, - { label: 'macOS 驱动', href: 'https://www.wch.cn/downloads/CH34XSER_MAC_ZIP.html' }, - ], - }, - ], - }, - help: { - title: '获取帮助', - intro: '仍未解决？一份好的问题反馈能让它被修复。', - points: [ - '从 GUI 导出日志（或附上 CLI 日志文件），让维护者了解发生了什么。', - '注明你的操作系统、芯片型号，以及你运行的确切命令或步骤。', - ], - logPaths: 'CLI 日志文件：~/.local/share/tyutool/tyutool.log（Linux）、~/Library/Application Support/tyutool/tyutool.log（macOS）、%APPDATA%\\tyutool\\tyutool.log（Windows）。', - issueBtn: '在 GitHub 提交 issue', - repoBtn: '浏览仓库', - }, - }, -}; - -/* ----------------------------------------------------------------------- */ -/* Helpers */ -/* ----------------------------------------------------------------------- */ - -function Shot({ label, src, tall }) { - if (src) { - return {label}; - } - return ( -
- - 🖼️ - - {label} -
- ); -} - -function Code({ children }) { - return ( - 
-      {children}
-
- ); -} - -/* ----------------------------------------------------------------------- */ -/* Page */ -/* ----------------------------------------------------------------------- */ - -export default function TyutoolGuidePage() { - const { i18n } = useDocusaurusContext(); - const locale = i18n.currentLocale === 'zh' ? 'zh' : 'en'; - const c = content[locale]; - const overviewHref = locale === 'zh' ? '/zh/tyutool' : '/tyutool'; - const { fromLearn, href: learnHref, label: learnLabel } = useFromLearn(); - - const [activeId, setActiveId] = useState(c.nav[0].id); - const contentRef = useRef(null); - - // Highlight the nav item for the section currently in view. - useEffect(() => { - const root = contentRef.current; - if (!root || typeof IntersectionObserver === 'undefined') return undefined; - const sections = root.querySelectorAll('section[id]'); - const io = new IntersectionObserver( - (entries) => { - entries.forEach((entry) => { - if (entry.isIntersecting) setActiveId(entry.target.id); - }); - }, - { rootMargin: '-30% 0px -60% 0px', threshold: 0 }, - ); - sections.forEach((s) => io.observe(s)); - return () => io.disconnect(); - }, [locale]); - - const authImg = SHOTS.auth; - const flashImg = SHOTS.flashing; - const serialImg = SHOTS.debug; - const batchImg = SHOTS.batch; - - return ( - - -
- {/* -------------------------------------------------------- Hero */} -
-
-
- - {fromLearn ? learnLabel : c.backToOverview} - - {c.badge} -

{c.title}

-

{c.subtitle}

-
-
- -
- {/* ----------------------------------------------------- TOC */} - - - {/* ------------------------------------------------- Content */} -
- {/* Install */} -
-

{c.install.title}

-

{c.install.intro}

- - {c.install.releasesBtn} - -
- {c.install.platforms.map((p) => ( -
-

{p.name}

-
    - {p.steps.map((s, i) => ( -
  1. {s}
    2. - ))} -
-
- ))} -
-
- ℹ️ -

{c.install.cliNote}

-
-
- - {/* First flash */} -
-

{c.firstFlash.title}

-
-
-

{c.firstFlash.guiTitle}

-
    - {c.firstFlash.guiSteps.map((s, i) => ( -
  1. {s}
    2. - ))} -
-
- -
-
- 💡 -

{c.firstFlash.tip}

-
-

{c.firstFlash.cliTitle}

-

{c.firstFlash.cliIntro}

- {c.firstFlash.cliCode} -
- - {/* Authorize */} -
-

{c.authorize.title}

-

{c.authorize.intro}

-
-
    - {c.authorize.guiSteps.map((s, i) => ( -
  1. {s}
    2. - ))} -
-
- {c.authorize.authShot} -
{c.authorize.authShot}
-
-
-

{c.authorize.cliTitle}

- {c.authorize.cliCode} -
- ℹ️ -
- {c.authorize.where} -

- {c.authorize.whereBody}{' '} - - {c.authorize.platformLink} - - . -

-

{c.authorize.authOnly}

-
-
-
- - {/* Serial debug */} -
-

{c.serial.title}

-

{c.serial.intro}

-
-
    - {c.serial.points.map((p, i) => ( -
  • {p}
    • - ))} -
- -
-
- 💡 -

{c.serial.note}

-
-
- - {/* Batch */} -
-

{c.batch.title}

-

{c.batch.intro}

-
-
    - {c.batch.points.map((p, i) => ( -
  • {p}
    • - ))} -
- -
-
- - {/* CLI reference */} -
-

{c.cli.title}

-

{c.cli.intro}

-
- - - - - - - - - {c.cli.rows.map((r, i) => ( - - - - - ))} - -
{c.cli.headers[0]}{c.cli.headers[1]}
- {r[0]} - {r[1]}
-
-

{c.cli.globalsTitle}

-
- - - {c.cli.globals.map((r, i) => ( - - - - - ))} - -
- {r[0]} - {r[1]}
-
- - {c.cli.fullRef} → - -
- - {/* Troubleshooting */} -
-

{c.trouble.title}

-
- {c.trouble.items.map((item, i) => ( -
- {item.q} -
-

{item.body}

- {item.code && {item.code}} - {item.links && ( -
- {item.links.map((l) => ( - - {l.label} → - - ))} -
- )} -
-
- ))} -
-
- - {/* Getting help */} -
-

{c.help.title}

-

{c.help.intro}

-
    - {c.help.points.map((p, i) => ( -
  • {p}
    • - ))} -
-

{c.help.logPaths}

- -
-
-
-
- - ); -} diff --git a/src/pages/tyutool-guide.module.css b/src/pages/tyutool-guide.module.css deleted file mode 100644 index ce9550a31..000000000 --- a/src/pages/tyutool-guide.module.css +++ /dev/null @@ -1,736 +0,0 @@ -/* ----------------------------------------------------------------------- */ -/* tyutool help guide — shares the landing design language */ -/* ----------------------------------------------------------------------- */ - -.root { - --brand-primary: #7c5cff; - --brand-primary-light: #a78bfa; - --brand-primary-dark: #5b3fd6; - --brand-accent: #ff6b35; - --neutral-50: #f8fafc; - --neutral-100: #f1f5f9; - --neutral-200: #e2e8f0; - --neutral-300: #cbd5e1; - --neutral-400: #94a3b8; - --neutral-500: #64748b; - --neutral-600: #475569; - --neutral-700: #334155; - --neutral-800: #1e293b; - --neutral-900: #0f172a; - - font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; - color: var(--neutral-900); - /* clip (not hidden) so the sticky TOC isn't trapped in a scroll container. */ - overflow-x: clip; -} - -[data-theme='dark'] .root { - color: #e2e8f0; -} - -/* ------------------------------------------------------------------ Hero */ -.hero { - position: relative; - padding: 3.5rem 1rem 3rem; - background: linear-gradient(135deg, #0f172a 0%, #312e81 50%, var(--brand-primary) 100%); - overflow: hidden; -} - -.hero::before { - content: ''; - position: absolute; - inset: 0; - background-image: - linear-gradient(rgba(124, 92, 255, 0.08) 1px, transparent 1px), - linear-gradient(90deg, rgba(124, 92, 255, 0.08) 1px, transparent 1px); - background-size: 60px 60px; - pointer-events: none; -} - -.heroGlow { - position: absolute; - width: min(500px, 90vw); - height: min(500px, 90vw); - background: radial-gradient(circle, rgba(124, 92, 255, 0.35) 0%, transparent 70%); - top: -200px; - right: -100px; - pointer-events: none; -} - -.heroInner { - position: relative; - z-index: 1; - max-width: 1180px; - margin: 0 auto; - width: 100%; -} - -.breadcrumb { - display: block; - width: fit-content; - color: rgba(255, 255, 255, 0.8) !important; - font-size: 0.875rem; - font-weight: 600; - margin-bottom: 1.25rem; - text-decoration: none !important; -} - -.breadcrumb:hover { - color: #fff !important; -} - -.heroBadge { - display: inline-block; - background: rgba(255, 107, 53, 0.2); - border: 1px solid rgba(255, 107, 53, 0.35); - padding: 0.4rem 0.9rem; - border-radius: 9999px; - font-size: 0.8rem; - font-weight: 600; - color: #fff; - margin-bottom: 1rem; -} - -.heroTitle { - font-size: clamp(2rem, 4.5vw, 2.85rem); - font-weight: 800; - line-height: 1.1; - color: #fff; - margin-bottom: 0.75rem; -} - -.heroSubtitle { - font-size: 1.1rem; - line-height: 1.65; - color: rgba(255, 255, 255, 0.88); - max-width: 46rem; - margin: 0; -} - -/* ---------------------------------------------------------- Layout */ -.layout { - max-width: 1180px; - margin: 0 auto; - padding: 2.5rem 1rem 4.5rem; - display: grid; - grid-template-columns: 1fr; - gap: 2.5rem; -} - -@media (min-width: 997px) { - .layout { - grid-template-columns: 220px 1fr; - gap: 3rem; - } -} - -/* ------------------------------------------------------------- TOC */ -.toc { - display: none; -} - -@media (min-width: 997px) { - .toc { - display: block; - } -} - -.tocSticky { - position: sticky; - top: 5rem; -} - -.tocTitle { - font-size: 0.75rem; - font-weight: 700; - text-transform: uppercase; - letter-spacing: 0.08em; - color: var(--neutral-500); - margin-bottom: 0.85rem; -} - -.toc ul { - list-style: none; - padding: 0; - margin: 0; - border-left: 2px solid var(--neutral-200); -} - -[data-theme='dark'] .toc ul { - border-left-color: var(--neutral-700); -} - -.tocLink { - display: block; - padding: 0.4rem 0 0.4rem 1rem; - margin-left: -2px; - border-left: 2px solid transparent; - color: var(--neutral-600); - font-size: 0.9rem; - text-decoration: none !important; - transition: color 0.2s, border-color 0.2s; -} - -.tocLink:hover { - color: var(--brand-primary); -} - -[data-theme='dark'] .tocLink { - color: var(--neutral-400); -} - -.tocLinkActive { - color: var(--brand-primary); - border-left-color: var(--brand-primary); - font-weight: 700; -} - -[data-theme='dark'] .tocLinkActive { - color: var(--brand-primary-light); - border-left-color: var(--brand-primary-light); -} - -/* --------------------------------------------------------- Content */ -.content { - min-width: 0; -} - -.block { - margin-bottom: 3.5rem; - scroll-margin-top: 5rem; -} - -.h2 { - font-size: clamp(1.5rem, 3vw, 2rem); - font-weight: 800; - color: var(--neutral-900); - margin-bottom: 1rem; - padding-bottom: 0.6rem; - border-bottom: 1px solid var(--neutral-200); -} - -[data-theme='dark'] .h2 { - color: #f1f5f9; - border-bottom-color: var(--neutral-700); -} - -.h3 { - font-size: 1.2rem; - font-weight: 700; - color: var(--neutral-800); - margin: 1.75rem 0 0.85rem; -} - -[data-theme='dark'] .h3 { - color: #e2e8f0; -} - -.lead { - font-size: 1.05rem; - line-height: 1.7; - color: var(--neutral-600); - margin-bottom: 1.25rem; -} - -[data-theme='dark'] .lead { - color: var(--neutral-400); -} - -.content p { - line-height: 1.7; - color: var(--neutral-700); -} - -[data-theme='dark'] .content p { - color: var(--neutral-300); -} - -/* --------------------------------------------------------- Buttons */ -.btnPrimary, -.btnGhost { - display: inline-flex; - align-items: center; - gap: 0.4rem; - padding: 0.65rem 1.25rem; - border-radius: 8px; - font-weight: 600; - font-size: 0.92rem; - text-decoration: none !important; - transition: transform 0.2s, box-shadow 0.2s, background 0.2s, border-color 0.2s; -} - -.btnPrimary { - background: var(--brand-primary); - color: #fff !important; - border: none; -} - -.btnPrimary:hover { - background: var(--brand-primary-dark); - transform: translateY(-1px); - box-shadow: 0 4px 14px rgba(124, 92, 255, 0.35); -} - -.btnGhost { - background: transparent; - color: var(--brand-primary) !important; - border: 1px solid var(--neutral-300); -} - -.btnGhost:hover { - border-color: var(--brand-primary); - background: rgba(124, 92, 255, 0.05); -} - -[data-theme='dark'] .btnGhost { - color: var(--brand-primary-light) !important; - border-color: var(--neutral-600); -} - -/* ---------------------------------------------------- Platform grid */ -.platformGrid { - display: grid; - grid-template-columns: 1fr; - gap: 1.25rem; - margin: 1.5rem 0; -} - -@media (min-width: 700px) { - .platformGrid { - grid-template-columns: repeat(3, 1fr); - } -} - -.platformCard { - background: var(--neutral-50); - border: 1px solid var(--neutral-200); - border-radius: 14px; - padding: 1.5rem; -} - -[data-theme='dark'] .platformCard { - background: var(--neutral-800); - border-color: var(--neutral-700); -} - -/* ----------------------------------------------------------- Steps */ -.steps { - margin: 0; - padding-left: 1.25rem; - display: grid; - gap: 0.6rem; - counter-reset: step; -} - -.steps li { - line-height: 1.6; - color: var(--neutral-700); -} - -[data-theme='dark'] .steps li { - color: var(--neutral-300); -} - -/* ------------------------------------------------------- Two-column */ -.twoCol { - display: grid; - grid-template-columns: 1fr; - gap: 1.5rem; - align-items: start; - margin: 1.25rem 0; -} - -@media (min-width: 760px) { - .twoCol { - grid-template-columns: 1fr 1fr; - gap: 2rem; - } -} - -/* -------------------------------------------------------- Check list */ -.checkList { - list-style: none; - padding: 0; - margin: 0; - display: grid; - gap: 0.65rem; -} - -.checkList li { - position: relative; - padding-left: 1.75rem; - color: var(--neutral-700); - line-height: 1.6; -} - -[data-theme='dark'] .checkList li { - color: var(--neutral-300); -} - -.checkList li::before { - content: '✓'; - position: absolute; - left: 0; - top: 0.1rem; - width: 1.2rem; - height: 1.2rem; - display: inline-flex; - align-items: center; - justify-content: center; - font-size: 0.7rem; - font-weight: 800; - color: #fff; - background: var(--brand-primary); - border-radius: 50%; -} - -/* ------------------------------------------------------ Code block */ -.codeBlock { - background: var(--neutral-900); - color: #e2e8f0; - border-radius: 12px; - padding: 1.1rem 1.25rem; - font-family: 'JetBrains Mono', ui-monospace, monospace; - font-size: 0.82rem; - line-height: 1.7; - overflow-x: auto; - margin: 1rem 0; - border: 1px solid rgba(148, 163, 184, 0.15); -} - -.codeBlock code { - font-family: inherit; - white-space: pre; - color: #e2e8f0; - background: transparent; - border: none; - padding: 0; -} - -/* ---------------------------------------------------------- Figures */ -.figure { - margin: 0; -} - -.figureImg { - width: 100%; - border-radius: 12px; - border: 1px solid var(--neutral-200); - box-shadow: - 0 1px 2px rgba(15, 23, 42, 0.06), - 0 4px 12px rgba(15, 23, 42, 0.08), - 0 12px 28px rgba(15, 23, 42, 0.1); -} - -[data-theme='dark'] .figureImg { - border-color: var(--neutral-700); -} - -.figure figcaption { - margin-top: 0.6rem; - font-size: 0.82rem; - color: var(--neutral-500); - text-align: center; -} - -/* --------------------------------------------------- Shot placeholder */ -.shotImg { - width: 100%; - display: block; - border-radius: 12px; - border: 1px solid var(--neutral-200); - box-shadow: - 0 1px 2px rgba(15, 23, 42, 0.06), - 0 4px 12px rgba(15, 23, 42, 0.08), - 0 12px 28px rgba(15, 23, 42, 0.1); -} - -[data-theme='dark'] .shotImg { - border-color: var(--neutral-700); -} - -.shotPlaceholder { - display: flex; - flex-direction: column; - align-items: center; - justify-content: center; - gap: 0.5rem; - width: 100%; - min-height: 220px; - border: 2px dashed var(--neutral-300); - border-radius: 12px; - background: - repeating-linear-gradient( - 45deg, - rgba(124, 92, 255, 0.03), - rgba(124, 92, 255, 0.03) 12px, - transparent 12px, - transparent 24px - ); - color: var(--neutral-500); - text-align: center; - padding: 1.5rem; -} - -[data-theme='dark'] .shotPlaceholder { - border-color: var(--neutral-600); - color: var(--neutral-400); -} - -.shotTall { - min-height: 300px; -} - -.shotIcon { - font-size: 1.85rem; - opacity: 0.8; -} - -.shotLabel { - font-size: 0.85rem; - font-weight: 600; -} - -/* -------------------------------------------------------- Callouts */ -.callout { - display: flex; - gap: 0.85rem; - align-items: flex-start; - padding: 1.1rem 1.25rem; - border-radius: 12px; - margin: 1.5rem 0; - border: 1px solid transparent; - border-left-width: 4px; -} - -.callout p { - margin: 0; -} - -.callout p + p { - margin-top: 0.5rem; -} - -.calloutIcon { - font-size: 1.1rem; - line-height: 1.5; - flex-shrink: 0; -} - -.calloutMuted { - color: var(--neutral-500) !important; - font-size: 0.9rem; -} - -.calloutTip { - background: rgba(16, 185, 129, 0.08); - border-color: rgba(16, 185, 129, 0.5); -} - -.calloutInfo { - background: rgba(124, 92, 255, 0.07); - border-color: rgba(124, 92, 255, 0.5); -} - -[data-theme='dark'] .calloutTip { - background: rgba(16, 185, 129, 0.12); -} - -[data-theme='dark'] .calloutInfo { - background: rgba(167, 139, 250, 0.12); -} - -.callout strong { - display: block; - margin-bottom: 0.25rem; - color: var(--neutral-900); -} - -[data-theme='dark'] .callout strong { - color: #f1f5f9; -} - -.callout a { - color: var(--brand-primary); - font-weight: 600; -} - -[data-theme='dark'] .callout a { - color: var(--brand-primary-light); -} - -/* ----------------------------------------------------------- Table */ -.tableWrap { - overflow-x: auto; - margin: 1rem 0; - border: 1px solid var(--neutral-200); - border-radius: 12px; -} - -[data-theme='dark'] .tableWrap { - border-color: var(--neutral-700); -} - -.table { - width: 100%; - border-collapse: collapse; - font-size: 0.9rem; - margin: 0; -} - -.table th { - text-align: left; - background: var(--neutral-50); - font-weight: 700; - color: var(--neutral-800); - padding: 0.75rem 1rem; - border-bottom: 1px solid var(--neutral-200); -} - -[data-theme='dark'] .table th { - background: var(--neutral-800); - color: #f1f5f9; - border-bottom-color: var(--neutral-700); -} - -.table td { - padding: 0.7rem 1rem; - border-bottom: 1px solid var(--neutral-200); - color: var(--neutral-700); - vertical-align: top; -} - -[data-theme='dark'] .table td { - border-bottom-color: var(--neutral-700); - color: var(--neutral-300); -} - -.table tr:last-child td { - border-bottom: none; -} - -.table code { - font-family: 'JetBrains Mono', ui-monospace, monospace; - font-size: 0.82rem; - background: rgba(124, 92, 255, 0.08); - color: var(--brand-primary-dark); - padding: 0.2rem 0.45rem; - border-radius: 6px; - white-space: nowrap; -} - -[data-theme='dark'] .table code { - background: rgba(167, 139, 250, 0.16); - color: var(--brand-primary-light); -} - -/* ------------------------------------------------------------- FAQ */ -.faqList { - display: grid; - gap: 0.85rem; -} - -.faqItem { - border: 1px solid var(--neutral-200); - border-radius: 12px; - background: var(--neutral-50); - overflow: hidden; -} - -[data-theme='dark'] .faqItem { - background: var(--neutral-800); - border-color: var(--neutral-700); -} - -.faqQ { - cursor: pointer; - padding: 1rem 1.25rem; - font-weight: 700; - color: var(--neutral-900); - list-style: none; - position: relative; - padding-right: 2.5rem; -} - -.faqQ::-webkit-details-marker { - display: none; -} - -.faqQ::after { - content: '+'; - position: absolute; - right: 1.25rem; - top: 50%; - transform: translateY(-50%); - font-size: 1.25rem; - font-weight: 400; - color: var(--brand-primary); -} - -.faqItem[open] .faqQ::after { - content: '−'; -} - -[data-theme='dark'] .faqQ { - color: #f1f5f9; -} - -.faqA { - padding: 0 1.25rem 1.25rem; -} - -.faqA p { - margin: 0 0 0.5rem; - color: var(--neutral-700); -} - -[data-theme='dark'] .faqA p { - color: var(--neutral-300); -} - -.driverLinks { - display: flex; - flex-wrap: wrap; - gap: 0.6rem; - margin: 0.75rem 0; -} - -.driverShots { - display: grid; - grid-template-columns: 1fr; - gap: 1.25rem; - margin-top: 1rem; -} - -@media (min-width: 700px) { - .driverShots { - grid-template-columns: 1fr 1fr; - } -} - -/* -------------------------------------------------------- Get help */ -.pathNote { - font-family: 'JetBrains Mono', ui-monospace, monospace; - font-size: 0.8rem; - background: var(--neutral-50); - border: 1px solid var(--neutral-200); - border-radius: 10px; - padding: 0.85rem 1rem; - color: var(--neutral-600) !important; - margin: 1.25rem 0; - line-height: 1.6; - word-break: break-word; -} - -[data-theme='dark'] .pathNote { - background: var(--neutral-800); - border-color: var(--neutral-700); - color: var(--neutral-400) !important; -} - -.helpButtons { - display: flex; - flex-wrap: wrap; - gap: 0.75rem; - margin-top: 1.25rem; -} diff --git a/src/pages/tyutool.jsx b/src/pages/tyutool.jsx index 24f0dca81..a88a05853 100644 --- a/src/pages/tyutool.jsx +++ b/src/pages/tyutool.jsx @@ -395,8 +395,7 @@ export default function TyutoolPage() { // Docusaurus internal links are not locale-prefixed automatically here, so // build the guide path for the active locale (en = root, zh = /zh). - const base = locale === 'zh' ? '/zh' : ''; - const guideHref = `${base}/tyutool-guide`; + const guideHref = locale === 'zh' ? '/zh/docs/tyutool' : '/docs/tyutool'; // Scroll-reveal: fade sections in as they enter the viewport. useEffect(() => { diff --git a/src/pages/web-serial.jsx b/src/pages/web-serial.jsx index 521634319..4a495119b 100644 --- a/src/pages/web-serial.jsx +++ b/src/pages/web-serial.jsx @@ -114,7 +114,7 @@ function ToolBody({locale, t}) { {t.desktop_download} ↗ {t.desktop_features} → - {t.desktop_guide} → + {t.desktop_guide} → From f157f067334b53730921a6e449b1c1e96fd32f7c Mon Sep 17 00:00:00 2001 From: YangJie Date: Wed, 29 Jul 2026 19:14:50 +0800 Subject: [PATCH 2/2] docs(tyutool): dedupe getting-started screenshots, capitalize navbar label MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove the duplicate/mismatched screenshot in "Connect the device" (en + zh) — it was the same image already shown under "First launch". - Capitalize the "tyutool" navbar Docs-dropdown label to "Tyutool". --- docs/tyutool/getting-started.md | 4 ---- docusaurus.config.js | 2 +- .../current/tyutool/getting-started.md | 4 ---- 3 files changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/tyutool/getting-started.md b/docs/tyutool/getting-started.md index c35a47dfb..d406a877e 100644 --- a/docs/tyutool/getting-started.md +++ b/docs/tyutool/getting-started.md @@ -84,10 +84,6 @@ Once the wiring is checked and the device is in download mode, build the connect After you pick a port, tyutool **auto-fills** the recommended baud rate and chip model — you can accept them as-is. **Higher** is faster but more prone to failure; **lower** is slower but steadier. See [Firmware Flash](./flash.md#flash-tab--flashing). -Flash page top connection bar — serial dropdown open showing detected ports, plus baud-rate and chip options - -*Flash page top connection bar — serial dropdown open showing detected ports, plus baud-rate and chip options.* - :::tip If no ports show in the dropdown, first confirm the adapter is plugged in and its driver is installed (CH340/CP2102/FT232), and check your macOS/Linux serial access permissions (see the installation notes above). ::: diff --git a/docusaurus.config.js b/docusaurus.config.js index 260302c0e..b364587b5 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -152,7 +152,7 @@ const config = { { type: 'docSidebar', sidebarId: 'hardwareSidebar', label: 'Hardware' }, { type: 'docSidebar', sidebarId: 'cloudSidebar', label: 'Cloud & AI' }, { type: 'docSidebar', sidebarId: 'duckyclawSidebar', label: 'TuyaOpenClaw' }, - { type: 'docSidebar', sidebarId: 'tyutoolSidebar', label: 'tyutool' }, + { type: 'docSidebar', sidebarId: 'tyutoolSidebar', label: 'Tyutool' }, ], }, { diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/getting-started.md b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/getting-started.md index cafd5ae5f..13fafafcc 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/getting-started.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/tyutool/getting-started.md @@ -84,10 +84,6 @@ WEBKIT_DISABLE_COMPOSITING_MODE=1 ./tyutool-gui_linux_x86_64_appimage_x.x.x.AppI 选好端口后，波特率与芯片型号由 tyutool **自动填入推荐值**，可直接采用。**调高**更快但易失稳失败，**调低**更慢更稳。详见[固件烧录](./flash.md)。 -Flash 页顶部连接栏——串口下拉框展开、显示已检测到的端口，波特率与芯片选项 - -*Flash 页顶部连接栏——串口下拉框展开、显示已检测到的端口，波特率与芯片选项。* - :::tip 如果下拉框里看不到任何端口，先确认适配器已插好、驱动已装（CH340/CP2102/FT232），并检查 macOS/Linux 的串口访问权限（见上方安装小节）。 :::