# micropython_tuya

**Repository Path**: wth_iw0/micropython_tuya

## Basic Information

- **Project Name**: micropython_tuya
- **Description**: Tuya开发板的micropython移植，支持t5,gd32vw553，目前已经实现IIC,SPI,UART,Timer,PWM,RTC,AudioCodec等machine外设功能，支持asyncio,threading，网络栈功能较为完善，基本保持esp32风格，生态可以无缝兼容
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 12
- **Forks**: 2
- **Created**: 2026-07-27
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MicroPython 移植 — TuyaOpen

本仓库是 MicroPython 的 fork，把 MicroPython 移植到 **TuyaOpen SDK** 上。移植以「库」的
形式编译成 `libmicropython.a`，再合并进 TuyaOpen 的 `libtuyaapp.a`，由各平台的链接流程
产出最终固件，提供交互式 REPL。

- MicroPython 基线版本：v1.29.0
- SDK：[TuyaOpen](https://gitee.com/tuya-open/TuyaOpen)（以子模块形式挂在 `lib/TuyaOpen`）

## 两个端口：用哪个

| 端口 | 状态 | 覆盖芯片 |
| --- | --- | --- |
| **[ports/tuya/](ports/tuya/)** | ✅ **推荐** | T5AI (BK7258, Cortex-M33)、GD32VW553 (RISC-V Nuclei)、Hi3863 (WS63, RISC-V RV32IMFC) |
| [ports/t5ai/](ports/t5ai/) | ⚠️ 工程遗留 | 仅 T5AI |

**`ports/t5ai` 是工程遗留**——它是最早只针对 T5AI 写的版本，芯片私有调用散落在各处，
不再跟进新功能。后来重构出的 **`ports/tuya` 是通用端口**：一套源码通过
**chip（芯片）+ board（板）两层**配置适配不同芯片，通用外壳里没有芯片私有调用。
T5AI 的全部功能在 `ports/tuya` 上都已验证等价。

> **新使用者、新板型、新芯片请直接用 [ports/tuya/](ports/tuya/)。**
> `ports/t5ai` 保留仅为历史参考与回归对照。

详细的构建、烧录、板级适配说明见 **[ports/tuya/README.md](ports/tuya/README.md)**。

## 已实现的模块

`machine`（Pin / I2C / SoftI2C / SPI / SoftSPI / PWM / Timer / UART / RTC / ADC / WDT /
AudioCodec）、`network`（WiFi STA+AP）、`socket`（含可中断的 TCP 服务端）、`asyncio`、
`_thread`、`ssl` / `hashlib`（走 SDK 内置 mbedtls 3.1.0）、`os`/littlefs VFS、
冻结的 `requests`/`mip`。

各模块在不同芯片上的支持程度不同（GD32 的 ADC/SSL 等有已知限制），
见 [ports/tuya/README.md](ports/tuya/README.md) 的模块支持矩阵。

---

## 快速开始

### 1. 下载工具

- **T5AI**：进入 `https://github.com/tuya/tyutool/releases/`，找到最新的适合你系统的
  发行版下载，解压或者安装
- **GD32VW553**：用兆易创新官方的 **GD32AllInOneProgrammer**
- **Hi3863**：用海思官方的 **BurnTool**（WS63 专用烧录工具）

### 2. 下载固件

进入 `https://gitee.com/wth_iw0/micropython_tuya/releases/`，找到最新固件，下载

### 3. 烧录

- **T5AI**：进入 tyutool，找到标注 `USB-Enhanced-SERIAL-A` 的串口，这个是主串口
  UART0，选择下载的固件，不用管地址，地址会自动填入，进行烧录，注意检查串口是否有
  应用占用
- **GD32VW553**：用 GD32AllInOneProgrammer 把 `tuyampy_QIO_1.0.0.bin` 烧到
  `0x08000000`，板子需手动进下载模式
- **Hi3863**：使用 BurnTool 烧录 `tuyampy_1.0.0.fwpkg`。**注意**：Hi3863 平台目前未接入
  TuyaOpen 的 `tos.py flash` 自动烧录，必须手动使用 BurnTool

**Hi3863 串口说明**：REPL 在 **UART_BUS_1**（GPIO15/16，连接板载 CH340，115200），
与 T5AI（UART0）不同。SDK 日志/TuyaOpen 输出在 UART_BUS_0（921600），不会污染 REPL。

### 4. 使用

使用 PyriteIDE，thonny，mpremote 或者其他 mpy 串口工具或 IDE 进行使用（波特率
115200），可以从 `https://github.com/pyrite-project/pyrite-ide` 的发行版标签下载
PyriteIDE

---

## 一、获取源码与依赖库（lib 设置）

本仓库是 MicroPython 的 fork。`lib/` 下的第三方库**全部以 git 子模块**形式引用（包括
TuyaOpen SDK），仓库里存的是**指针**，不是库本身。克隆后需要初始化子模块。

```bash
# 1. 克隆本 fork
git clone https://gitee.com/wth_iw0/micropython_tuya.git
cd micropython_tuya

# 2. 初始化本移植所需的子模块
#    只需要 TuyaOpen（内含平台/工具链）与 micropython-lib（冻结库）
git submodule update --init lib/TuyaOpen lib/micropython-lib

#    TuyaOpen 自身还有嵌套子模块（platform/T5AI 等），进入其中递归初始化
git -C lib/TuyaOpen submodule update --init --recursive
```

> `lib/TuyaOpen` 指针锁定在上游 `v1.9.0-10-g89debf53`（commit `89debf53`）。
> 换其它版本可能需要同步调整 `sdk_includes` 与 adapter 头文件路径。

> **GD32 平台代码不在子模块里**：TuyaOpen 按 `platform/platform_config.yaml` 在首次
> 构建时自行拉取 `platform/GD32`。GD32 目标需要一份实现了 `tkl_io_pinmux_config`
> 且修正了 `uart.h` 板宏判断的 GD32 平台；上游若尚未合入，需自行指向修好的平台仓库。

---

## 二、编译

app 源码在 [ports/tuya/tuyaopen_app/tuyampy/](ports/tuya/tuyaopen_app/tuyampy/)，
**就地构建，不需要拷进 `lib/TuyaOpen/apps/`**。仓库根目录的
[tuyampy.sh](tuyampy.sh) / [tuyampy.ps1](tuyampy.ps1)
已把切 SDK config、选板、清陈旧产物三件事原子化。

> **在 Windows 上请用 [tuyampy.ps1](tuyampy.ps1)（PowerShell），不要用 `.sh`。**
> TuyaOpen 的 `tos.py` 工具链在 Windows 上并不支持 MSYS2 / Cygwin 这类类 Unix
> 模拟环境，路径、进程、烧录工具都会出问题。仓库根目录的 [tuyampy.sh](tuyampy.sh)
> 依赖一套很特殊的类 Unix 环境（本项目的构建/维护时用的是能同时看到 Windows 原生
> Python/CMake 又提供 POSIX shell 的 AI 执行器环境），**普通 Windows 用户在
> Git-Bash / MSYS2 里直接跑 `.sh` 基本跑不通**。`.sh` 仅作维护参考保留，
> Windows 用户请一律使用下面的 PowerShell 版本。

**原生 PowerShell / pwsh（Windows 命令行，推荐）：**

Windows 默认执行策略（RemoteSigned）会静默阻止脚本内的 `Get-Command` 查找，
导致 `SH_OVERRIDE` 未设置、make 回退到 cmd.exe 的 shell，POSIX 命令报错。
**必须加 `-ExecutionPolicy Bypass` 运行**：

```powershell
powershell -ExecutionPolicy Bypass -File .\tuyampy.ps1 list
powershell -ExecutionPolicy Bypass -File .\tuyampy.ps1 build t5
powershell -ExecutionPolicy Bypass -File .\tuyampy.ps1 build gd32-start
powershell -ExecutionPolicy Bypass -File .\tuyampy.ps1 build hi3863
powershell -ExecutionPolicy Bypass -File .\tuyampy.ps1 flash t5 -p COM32
```

如果系统装了 pwsh（PowerShell 7+），把上面的 `powershell` 替换成 `pwsh` 即可。
直接 `.\tuyampy.ps1` 运行会因执行策略问题静默跳过 sh.exe 检测，**不能这样用**。

**Linux / macOS（原生类 Unix，`.sh` 可正常使用）：**

```bash
./tuyampy.sh list                    # 列出目标
./tuyampy.sh build t5                # T5AI
./tuyampy.sh build gd32-start        # GD32VW553 eval
./tuyampy.sh build hi3863            # Hi3863 (WS63)
./tuyampy.sh flash t5 -p COM32       # 烧录（参数透传给 tos.py flash）
```

> **Hi3863 平台代码不在本仓库里**：它作为 `lib/TuyaOpen/platform/Hi3863` 子模块引入，
> 仓库在 [gitee.com/wth_iw0/TuyaOpen-HiSilicon](https://gitee.com/wth_iw0/TuyaOpen-HiSilicon)。
> 该平台内嵌海思 WS63 SDK（`ws63_os`），推荐用打好补丁的 fork
> [gitee.com/wth_iw0/fbb_ws63](https://gitee.com/wth_iw0/fbb_ws63)（内置 MinGW DLLs 与
> `threading_alt.h`）。构建脚本仅支持 Windows。详见该仓库 `PORTING.md`。

前置环境、手动构建流程、构建陷阱（换板必须删 `ports/tuya/build/`、
`libmicropython.a` 的合并不被 ninja 追踪等）详见
**[ports/tuya/README.md](ports/tuya/README.md)**。

---

## 三、烧录

**只能串口烧录，不能用 OTA 升级**——OTA flash 区域已被 littlefs VFS 占用（见下方
分区说明）。

- **T5AI**：`./tuyampy.sh flash t5 -p COM32`（底层调用 tyutool），COM 口换成你板子的
  下载口。参考开发板串口约定：COM32 (CH342-A) = REPL / 下载 @115200，
  COM31 (CH342-B) = TuyaOS 日志 @460800。
- **GD32VW553**：用 GD32AllInOneProgrammer 烧 `tuyampy_QIO_1.0.0.bin` 到
  `0x08000000`，板子需手动进下载模式。注意 `tuyampy.bin`/`.hex`/`.elf` **不能烧**，
  只有 `_QIO_` 那个是含 MBL 引导的完整镜像。
- **Hi3863**：用海思官方 **BurnTool** 烧录 `tuyampy_1.0.0.fwpkg`。Hi3863 平台目前未接入
  `tos.py flash` 自动烧录，必须手动使用 BurnTool。REPL 在 **UART_BUS_1**（GPIO15/16，
  连接板载 CH340，115200），SDK 日志输出在 UART_BUS_0（921600），两路互不干扰。

烧录完成后用串口终端连 **115200** 即可进入 MicroPython REPL。

---

## 四、文件系统 / Flash 分区

两块芯片都采用 **VFS-on-OTA**：littlefs2 托管在 OTA 分区——串口烧录的开发板上这块是
空闲的，代价是放弃 OTA 升级能力。

| 芯片 | Flash | VFS 基址 | VFS 大小 |
| --- | --- | --- | --- |
| T5AI | 8MB | `0x004ea000` | 2940 KB |
| GD32VW553 | 4MB | `0x001ea000` | 1024 KB |
| Hi3863 | 4MB | `0x00200000` | 1536 KB |

分区由 `ports/tuya/boards/<板>/board_config.h` 的 `BOARD_FS_FLASH_BASE` /
`BOARD_FS_FLASH_SIZE` 界定，改板级宏即可迁移。VFS 块设备走
`tkl_flash_read/write/erase`（4KB 扇区），**不使用 PSRAM 作为 VFS**。

---

## 五、GPIO / 外设引脚速查

### Hi3863（BearPi-Pico H3863）

| machine 用法 | TKL / GPIO id | 板标 | 可选功能 |
| --- | :---: | :---: | --- |
| `Pin(9)` / `PWM(9)` | 9 | P9 | GPIO / PWM ch7 |
| `Pin(10)` / `PWM(10)` | 10 | P10 | GPIO / PWM ch6 |
| `UART(0)` TX | 7 | P7 | UART_BUS_2 TX / I2C1 SCL |
| `UART(0)` RX | 8 | P8 | UART_BUS_2 RX / SPI0 MISO |
| `I2C(0)` SCL | 14 | P14 | I2C_BUS_0 |
| `I2C(0)` SDA | 15 | P15 | I2C_BUS_0（也是 REPL TX，不要同时用） |
| `I2C(1)` SCL | 7 | P7 | I2C_BUS_1 |
| `I2C(1)` SDA | 6 | P6 | I2C_BUS_1 |
| `SPI(0)` SCK | 11 | P11 | SPI0 |
| `SPI(0)` CS | 13 | P13 | SPI0 |
| `SPI(0)` MOSI | 12 | P12 | SPI0 |
| `SPI(0)` MISO | 8 | P8 | SPI0 |
| `ADC(0)` | ch0 → GPIO26 | P26 | ADC，pin mode 3 |
| `ADC(1)` | ch1 → GPIO27 | P27 | ADC |
| `ADC(2)` | ch2 → GPIO28 | P28 | ADC |
| REPL（保留） | 15 TX / 16 RX | — | UART_BUS_1，板载 CH340，115200 |
| SDK 日志（保留） | 17 TX / 18 RX | — | UART_BUS_0，921600 |

VFS 分区：Flash 偏移 `0x00200000`，大小 1.5MB（OTA 分区复用）。

---

### GD32VW553（TuyaOpen eval board）

| machine 用法 | TKL / GPIO id（tuya编号） | 芯片 pad | 可选功能 |
| --- | :---: | :---: | --- |
| `UART(0)` TX | 6 | PA6 | USART2 TX |
| `UART(0)` RX | 7 | PA7 | USART2 RX |
| `I2C(0)` SCL | 2 | PA2 | I2C0 |
| `I2C(0)` SDA | 3 | PA3 | I2C0 |
| `I2C(1)` SCL | 15 | PA15 | I2C1 |
| `I2C(1)` SDA | 8 | PA8 | I2C1（也是 REPL RX，不要同时用） |
| `SPI(0)` SCK | 2 | PA2 | SPI0 |
| `SPI(0)` CS | 12 | PA12 | SPI0 |
| `SPI(0)` MOSI | 0 | PA0 | SPI0 |
| `SPI(0)` MISO | 1 | PA1 | SPI0 |
| `PWM(8)` | ch0 → GPIO8 | PA8 | TIMER0 CH0 |
| `PWM(23)` | ch1 → GPIO23 | PB13 | TIMER15 CH0 |
| `PWM(10)` | ch2 → GPIO10 | PA10 | TIMER16 CH0 |
| `ADC(0..7)` | ch0–7 → GPIO0–7 | PA0–PA7 | ADC channels |
| `ADC(8)` | ch8 → GPIO16 | PB0 | ADC channel 8 |
| REPL（保留） | 24 TX / 8 RX | PB15/PA8 | USART0，115200 |
| SDK 日志（保留） | UART1 | — | 921600 |

VFS 分区：Flash 偏移 `0x001ea000`，大小 1MB（OTA 分区复用）。

> GD32 注意：`I2C(1)` 的 SDA（GPIO8/PA8）与 REPL RX 共用，不能同时使用；
> `SPI(0)` SCK（GPIO2）与 `I2C(0)` SCL 共用，同一时间只能用其中一个。

---

### T5AI（BK7258，TuyaOpen DevKit）

| machine 用法 | TKL / GPIO id | 可选功能 |
| --- | :---: | --- |
| `UART(0)` TX | 31 或 41 | UART2 TX（两组备选） |
| `UART(0)` RX | 30 或 40 | UART2 RX |
| `I2C(0)` SCL | 20 | I2C0 |
| `I2C(0)` SDA | 21 | I2C0 |
| `I2C(1)` SCL | 14 | I2C1（默认） |
| `I2C(1)` SDA | 15 | I2C1（默认），备选：(0,1) / (38,39) / (42,43) |
| `SPI(0)` SCK | 14 | SPI0（默认组） |
| `SPI(0)` CS | 15 | SPI0 |
| `SPI(0)` MOSI | 16 | SPI0 |
| `SPI(0)` MISO | 17 | SPI0 |
| `PWM(9)` | ch7 → GPIO9 | 板载 LED |
| `PWM(8)` | ch6 → GPIO8 | |
| `PWM(18)` | ch0 → GPIO18 | |
| `ADC(1)` | ch1 → GPIO25 | |
| `ADC(2)` | ch2 → GPIO24 | |
| `ADC(3)` | ch3 → GPIO23 | |
| `ADC(4)` | ch4 → GPIO28 | 默认开分压 |
| `ADC(5)` | ch5 → GPIO22 | |
| `ADC(6)` | ch6 → GPIO21 | |
| `ADC(10)` | ch10 → GPIO8 | |
| `ADC(12..15)` | ch12–15 → GPIO0,1,12,13 | |
| REPL（保留） | UART0 | 115200，CH342-A |
| SDK 日志（保留） | UART1 | 460800，CH342-B |

VFS 分区：Flash 偏移 `0x004ea000`，大小 2940KB（OTA 分区复用）。

---

## 六、项目定位与未来方向

### 核心定价值

这个项目的价值不止于"让某几块芯片跑 MicroPython"，更是一个**跨生态的 MicroPython 接入层**：

- **成本置换**：只需填 TKL 基础接口（system/memory/thread/uart + 外设），上层网络栈、连云、OTA、mbedtls、AI 全部由 TuyaOpen 提供。TKL 是"芯片 SDK ↔ Tuya 框架"的唯一适配层，SDK 实现一次，所有 port 分摊。
- **结构可持续，持续吃上游 MicroPython 更新**：保持标准 fork + `ports/tuya/` 结构（与 `ports/zephyr/` 同构），Makefile include 上游 `py.mk`/`extmod.mk`，不改 `py/` 内核。可以随时 merge 上游 MicroPython 新版本，语言特性、标准库修复、内核优化都能直接拿到，而不会像 RT-Thread v1.13 那样因为目录重组导致四年半卡在旧版本。
- **人力可替代性**：实现高级功能需要懂 MicroPython 内核（极稀缺）；填 TKL 只需查原厂 SDK 手册（每家原厂都有 FAE）。这才是门槛真正降下来的地方。
- **可验收性**：REPL 亮了 → system/memory/uart 对；点灯 → GPIO 对；扫 I2C → 时序对。从"跑起来才知对不对"变成逐项验收，这决定了项目能不能交接给第二个人——比省时间更重要。
- **跨生态扩展**：TuyaOpen 的 platform 本就是"TKL 桥接某芯片 SDK"，底层跑什么 RTOS 无所谓。RT-Thread/Zephyr 已有的 BSP（几百上千款）都可以当作"芯片 SDK"桥接，一次填 TKL，获得 TuyaOpen 上层服务 + MicroPython 完整功能面。

### 当前覆盖

| 芯片 | 架构 | 状态 | 特性 |
| --- | --- | :---: | --- |
| T5AI (BK7258) | Cortex-M33 | ✅ 完整验证 | 16MB PSRAM，AudioCodec，WiFi |
| GD32VW553 | RISC-V Nuclei | ✅ 完整验证 | 320KB SRAM，WiFi+BLE |
| Hi3863 (WS63) | RISC-V RV32IMFC | ✅ 完整验证 | 606KB SRAM，WiFi+BLE+SLE |

### 下一步方向

1. **引导宏体系**（NO_PIN_MUX 范式推广）：三层设计——`ONBOARDING_STAGE`（0=仅 core，1=+UART/REPL，2=+常用外设，3=全部）+ `ENABLE_TKL_xxx`（对齐官方命名）+ `TKL_STUB_VERBOSE`（启动时打印所有未实现 TKL），让移植过程从"黑盒调试"变成"按阶段验收"。

2. **RTOS platform 桥接模板**：把"通过 TKL 接入 RT-Thread/Zephyr BSP"从潜能变成可用路径。RT-Thread BSP 生态最多，且其官方 MicroPython 包已停滞四年半（v1.13，无法跟随上游），是最实在的切入点。

3. **定位为 TKL 验收套件**：MicroPython 天然是 TKL 的交互式验收器——哪步挂了立刻定位哪个 TKL。对 TuyaOpen 生态而言，这是一个质量阀门：没有它，降低门槛只会涌入一堆半成品 platform。

> 维护现状（2026-09）：价值保持的关键是维持标准 fork 结构、持续吃上游 MicroPython——否则就是 RT-Thread v1.13 的结局：置换来的优势被无法跟随上游慢慢耗光。

---

- **[ports/tuya/](ports/tuya/)** — 通用端口（推荐）。`common/` 通用外壳 +
  `chips/` 芯片层 + `boards/` 板层 + `arch/` 架构层；app 集成层在
  `tuyaopen_app/tuyampy/`。详见 [ports/tuya/README.md](ports/tuya/README.md)
- [ports/t5ai/](ports/t5ai/) — 早期仅 T5AI 的端口，**工程遗留**，不再跟进
- [tuyampy.sh](tuyampy.sh) — 多芯片/板级一键构建、烧录封装脚本
- `lib/TuyaOpen` — TuyaOpen SDK（git 子模块，锁定 `v1.9.0-10-g89debf53`）