安装
从发布页下载对应平台的最新版本。推荐（★）安装包支持应用内自动更新。
打开 GitHub 发布页Windows
- 下载 NSIS 安装包（*.exe）并运行，或下载便携版 .zip 解压。
- 从开始菜单（安装版）或解压目录（便携版）启动 tyutool。
macOS
- 下载 Universal .dmg（★），打开后将 tyutool 拖入"应用程序"。
- 由于安装包未经 Apple 签名，首次启动会被拦截 —— 请参见下方"故障排查"中一次性的"仍要打开"步骤。
Linux
- 下载 AppImage（★），赋予可执行权限：chmod +x tyutool-gui_*.AppImage 后运行。
- 或安装对应发行版的 .deb / .rpm，或解压便携版 .tar.gz。
在无界面环境或 CI 中工作？从同一发布页下载独立 CLI 版本，解压后将 tyutool_cli 放入 PATH —— 无需任何运行时。
烧录第一份固件
使用 GUI
- 打开 tyutool，停留在"烧录"标签页。
- 选择芯片（例如 T5AI 或 BK7231N）。
- 点击"浏览"选择固件 .bin（TuyaOpen 选择包含 _QIO 的文件）。
- 选择串口。在涂鸦开发板上，鼠标悬停串口会提示它是烧录/授权口还是日志口。
- 点击"开始烧录"，观察擦除、写入、校验的进度。
默认烧录波特率为 921600。若烧录不稳定可调低；若速度太慢可适当调高，但过高在长线缆下可能失败。
使用 CLI
在终端中完成同样的烧录 —— 仅连接一个串口时会自动检测：
# 自动检测串口
tyutool write -d t5ai -f app_QIO.bin
# 或显式指定串口
tyutool write -d bk7231n -p /dev/ttyUSB0 -f firmware.bin为设备授权
要接入涂鸦 IoT 云，设备需要写入 UUID + AuthKey。tyutool 通过与烧录相同的 UART 写入并校验它们。
- 打开"授权"标签页。
- 选择授权串口。
- 保持默认 UART 设置（波特率 115200、8 数据位、1 停止位、无校验）。
- 输入 UUID 和 AuthKey。
- 点击"开始授权"，随后回读状态以确认。
CLI 等价命令
# 读取当前授权状态
tyutool authorize -p /dev/ttyUSB0
# 写入新的 UUID + AuthKey（两者都必填）
tyutool authorize -p /dev/ttyUSB0 \
--uuid <UUID> --authkey <AUTHKEY>TuyaOpen 的 UUID/AuthKey 来自涂鸦开发者平台，也可批量购买。TuyaOpen 与 TuyaOS 的授权码不能互换使用。 涂鸦开发者平台.
只需授权（已烧录）的设备可使用授权专用的"other"芯片选项 —— 它会完全跳过烧录。
用串口调试查看日志
"串口调试"标签页是一个完整的串口监视器，让你无需第二个工具就能点亮和调试板子。
- 真实 ANSI 颜色渲染，并支持十六进制与 ASCII 视图。
- 逐行时间戳与 TX/RX 方向标记。
- 以文本或十六进制发送数据，行尾可选。
- 将会话抓取为 .txt 文件，或导出日志用于问题反馈。
开始烧录时，串口监视器会自动释放串口，因此两者不会争用同一连接。
批量烧录与授权
面向小批量产线，批量工具可在同一窗口同时驱动多个串口。
- 自动检测已连接串口，或过滤掉你不想操作的串口。
- 并行将同一固件烧录到每个串口，各自显示进度。
- 从表格驱动授权 —— 每台设备一行 UUID / AuthKey。
- 可单独取消或重试某个槽位，并实时统计成功 / 失败数量。
CLI 快速参考
每个命令在仅有一个串口时自动检测；存在多个串口时用 -p 指定。完整说明见仓库。
| 命令 | 作用 |
|---|---|
write -d <芯片> -f <文件> | 将 .bin 烧录到设备 |
read -d <芯片> -f <文件> | 将 Flash 内容导出到文件 |
erase -d <芯片> | 擦除一段 Flash 区域 |
authorize --uuid <U> --authkey <K> | 写入或读取 UUID + AuthKey |
reset -p <串口> | 通过 DTR/RTS 硬件复位 |
list-ports [--json] | 列出可用串口 |
update [--check] | 自我更新工具 |
completions <shell> | 生成 Shell 补全脚本 |
全局参数
--verbose | 同时向 stderr 打印开发者诊断信息 |
--plain | 纯 ASCII 输出，适合 CI / 管道 |
故障排查
macOS：提示"无法打开 tyutool，因为无法验证开发者"
安装包未经 Apple 签名 —— 这是预期行为。打开"系统设置 → 隐私与安全性"点击"仍要打开"，或在访达中按住 Control 点击 tyutool.app 选择"打开"。
macOS：看不到串口
在"系统设置 → 隐私与安全性 → 配件"中授予访问权限（不同 macOS 版本名称略有差异）。
Linux：窗口空白 / 全白（虚拟机中常见）
这是 WebKit2GTK 的 GPU 合成问题。关闭合成后再启动：
export WEBKIT_DISABLE_COMPOSITING_MODE=1
./tyutool-gui_linux_x86_64_*.AppImage烧录在"write"阶段总是失败（CH34x 板子）
安装或更新 CH34x USB 转串口驱动后重试。在 macOS 安装后需在"安全性"设置中允许该驱动 —— 安装成功时设备名以 cu.wchusb 开头。
获取帮助
仍未解决？一份好的问题反馈能让它被修复。
- 从 GUI 导出日志（或附上 CLI 日志文件），让维护者了解发生了什么。
- 注明你的操作系统、芯片型号，以及你运行的确切命令或步骤。
CLI 日志文件：~/.local/share/tyutool/tyutool.log（Linux）、~/Library/Application Support/tyutool/tyutool.log（macOS）、%APPDATA%\tyutool\tyutool.log（Windows）。