Windows 开发指南

概述

tos.py 是 TuyaOpen 的构建工具，支持项目创建、编译、配置等多种功能。本文档将指导您在 Windows 10/11 系统下使用 tos.py 工具进行TuyaOpen项目开发调试。

功能特点

支持项目创建和编译
提供项目配置管理
支持固件烧录
支持设备日志监控
支持版本管理和环境检查

前提条件

在开始使用之前，请确保您的系统满足以下要求：

Windows 10/11 操作系统
Python 3.10.0 或更高版本 [https://apps.microsoft.com/detail/9pjpw5ldxlz5]
- Windows Store App 商城下载安装
Git 2.0.0 或更高版本 [https://git-scm.com/downloads/win]
- 下载安装包，手动进行安装
CMake 4.0.2 或更高版本 [https://cmake.org/download/]
- 下载安装包，手动进行安装
Ninja 1.11.1 或更高版本 [https://github.com/ninja-build/ninja/releases]
Ninja 安装说明
1. 下载 Ninja
  
  访问 Ninja 发布页面
  
  下载最新版本的 ninja-win.zip
2. 安装步骤
  
  解压下载的 ninja-win.zip 文件
  
  将解压出的 ninja.exe 复制到以下任一位置：
  
  C:\Windows（需要管理员权限）
  
  或添加到系统环境变量 Path 中的任意目录
  
  或直接放在 TuyaOpen 项目根目录下
3. 验证安装
  
  ninja --version
- 如果选择将 ninja.exe 放在项目目录下，确保在运行 export.bat 时 ninja.exe 已经存在
- 建议将 ninja.exe 放在系统目录或添加到环境变量中，这样可以全局使用

使用限制

提示

提示 2025/05/30 目前 Windows 开发环境下的 tos.py 工具暂时只支持 ESP32。 Tuya T5 芯片计划6月中支持

快速开始

克隆 TuyaOpen 仓库

# PowerShell 或 CMD
git clone https://github.com/tuya/TuyaOpen.git
cd TuyaOpen
git submodule update --init

配置开发环境

# PowerShell 或 CMD
.\export.bat

验证环境

# PowerShell 或 CMD
tos.py version

退出开发环境

# PowerShell 或 CMD
exit

提示

命令行选择您可以使用以下任意一种命令行工具：

PowerShell（推荐）
Windows 命令提示符（CMD）

注意

注意 Git Bash（类 Linux 环境）与 tos.py 工具不兼容，请使用 PowerShell 或 CMD。

`tos.py` 使用说明

基本命令

tos.py [OPTIONS] COMMAND [ARGS]...

选项:
  -d, --debug  显示调试信息
  -h, --help   显示帮助信息

命令:
  version  显示版本信息
  check    检查依赖工具
  config   配置文件操作
  build    构建项目
  clean    清理项目
  flash    烧录固件
  monitor  显示设备日志

常用操作示例

检查环境

# 工程目录下
tos.py check

确保工具链符合要求。如果有缺失工具，参照此文档上述方法进行安装。

(tos) $ tos.py check
[INFO]: Running tos.py ...
[INFO]: [git] (2.49.0 >= 2.0.0) is ok.
[ERROR]: [cmake] not found, please install.
[INFO]: [ninja] (1.12.1 >= 1.6.0) is ok.
[INFO]: Downloading submoudules ...
[INFO]: Download submoudules successfully.

编译项目

# 工程目录下
tos.py build

清理项目

# 工程目录下
tos.py clean

烧录固件

# 工程目录下
tos.py flash

烧录流程
- 连接 USB 到开发板上的USB串口
- tos.py flash 运行串口烧写命令后：
  - T5 复位按键
  - ESP32 复位+Boot按键

配置项目 (芯片/功能等)
```
# 工程目录下
tos.py config
```
输出：
```
Usage: tos.py config [OPTIONS] COMMAND [ARGS]...

Configuration file operation.

Options:
-h, --help  Show this message and exit.

Commands:
choice  Choice config file.
menu    Menuconfig.
save    Save minimal config.
```
5.1. 配置芯片平台
- TuyaOpen 支持了芯片跨平台能力。tos.py config choice命令能让项目编译底层芯片平台时, 进行切换兼容适配不同芯片平台。
  
  提示
  重要提示要实现芯片平台的自由切换，您的项目代码必须使用 Tuya 提供的硬件抽象层（Hardware Abstraction Layer）API，即 tkl API。这些 API 封装了底层硬件细节，使您的应用代码能够与不同的芯片平台无缝对接。如果您的代码直接调用了特定芯片的原生 API，将无法实现跨平台切换。
```
# 工程目录下
tos.py config choice
```
输出：
```
[INFO]: Running tos.py ...
--------------------
1. BK7231X.config
2. ESP32-C3.config
3. ESP32-S3.config
4. ESP32.config
5. LN882H.config
6. T2.config
7. T3.config
8. T5AI.config
9. Ubuntu.config
--------------------
Input "q" to exit.
Choice config file:
```

常见问题

问题：找不到 tos.py 命令解决方案：
- 确保已经执行 .\export.bat 进入开发环境
- 检查是否在 TuyaOpen 目录下
问题：pip 安装依赖包失败解决方案：
- 检查网络连接
- 尝试使用国内镜像源：
```
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

后续操作

查看项目示例了解更多使用场景，开始编译项目。

概述​

功能特点​

前提条件​

使用限制​

快速开始​

tos.py 使用说明​

基本命令​

常用操作示例​

常见问题​

后续操作​

概述