Skip to main content
โ† Back to tyutool overviewHelp guide

tyutool guide

Install the tool, flash your first board, authorize it for Tuya IoT, and fix the common hiccups โ€” GUI and CLI side by side.

Install

Download the latest build for your platform from the releases page. The recommended (โ˜…) packages support in-app auto-update.

Open GitHub releases

Windows

  1. Download the NSIS installer (*.exe) and run it, or grab the portable .zip and unzip it.
  2. Launch tyutool from the Start menu (installer) or the extracted folder (portable).

macOS

  1. Download the Universal .dmg (โ˜…), open it, and drag tyutool to Applications.
  2. First launch is blocked because the build is not Apple-signed โ€” see Troubleshooting below for the one-time "Open Anyway" step.

Linux

  1. Download the AppImage (โ˜…), then make it executable: chmod +x tyutool-gui_*.AppImage and run it.
  2. Or install the .deb / .rpm for your distribution, or unpack the portable .tar.gz.

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.

Flash your first firmware

With the GUI

  1. Open tyutool and stay on the Flash tab.
  2. Select your chip (for example T5AI or BK7231N).
  3. Click Browse and choose the firmware .bin (for TuyaOpen, the file containing _QIO).
  4. Pick the serial port. On Tuya boards, hovering a port shows whether it is the flash/auth or the log port.
  5. Click Start flash and watch the progress through erase, write, and verify.
Flashing a development board over USB-serial

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.

With the CLI

The same flash, from a terminal โ€” the port is auto-detected when only one is connected:

# 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 a device

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.

  1. Open the Authorize tab.
  2. Select the authorization serial port.
  3. Keep the default UART settings (baud 115200, 8 data bits, 1 stop bit, no parity).
  4. Enter the UUID and AuthKey.
  5. Click Start authorization, then read back the state to confirm.
tyutool โ€” authorization tab
tyutool โ€” authorization tab

CLI equivalent

# Read the current authorization state
tyutool authorize -p /dev/ttyUSB0

# Write a new UUID + AuthKey (both required)
tyutool authorize -p /dev/ttyUSB0 \
    --uuid <UUID> --authkey <AUTHKEY>
Where do credentials come from?

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. Tuya Developer Platform.

Devices that only need a license (already flashed) can use the auth-only "other" chip option โ€” it skips flashing entirely.

Watch logs with serial debug

The Serial debug tab is a full serial monitor for bringing up and debugging a board without a second tool.

  • 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.
Serial monitor showing live device logs

The serial monitor releases the port automatically when you start a flash, so the two never fight over the connection.

Batch flash & authorize

For small production runs, the batch tool drives many ports at once from a single window.

  • 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.
Flashing and authorizing many boards at once

CLI quick reference

Every command auto-detects a single port; pass -p to choose when several are present. Full details live in the repository.

CommandWhat it does
write -d <chip> -f <file>Flash a .bin to the device
read -d <chip> -f <file>Dump flash contents to a file
erase -d <chip>Erase a flash region
authorize --uuid <U> --authkey <K>Write or read UUID + AuthKey
reset -p <port>Hardware-reset via DTR/RTS
list-ports [--json]List available serial ports
update [--check]Self-update the tool
completions <shell>Generate a shell completion script

Global flags

--verboseAlso print developer diagnostics to stderr
--plainASCII-only output for CI / piping
Full CLI reference on GitHub โ†’

Troubleshooting

macOS: "tyutool can't be opened because the developer cannot be verified"

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.

macOS: no serial port appears

Grant access under System Settings โ†’ Privacy & Security โ†’ Accessories (the label varies by macOS version).

Linux: blank / white window (common in VMs)

This is a WebKit2GTK GPU compositing issue. Launch with compositing disabled:

export WEBKIT_DISABLE_COMPOSITING_MODE=1
./tyutool-gui_linux_x86_64_*.AppImage
Flashing always fails during "write" (CH34x boards)

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

Windows driver โ†’macOS driver โ†’

Getting help

Still stuck? A good bug report makes it fixable.

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

CLI log file: ~/.local/share/tyutool/tyutool.log (Linux), ~/Library/Application Support/tyutool/tyutool.log (macOS), %APPDATA%\tyutool\tyutool.log (Windows).

Open an issue on GitHubBrowse the repository โ†’