back
loading skill details...
UIFlow2 MicroPython coding assistant. Use when writing, debugging, or explaining UIFlow2 MicroPython code for M5Stack devices. Provides accurate API lookup f...
---
name: uiflow2-coder
description: UIFlow2 MicroPython coding assistant. Use when writing, debugging, or explaining UIFlow2 MicroPython code for M5Stack devices. Provides accurate API lookup from official docs before generating any code.
---
## 核心原则
1. **API 正确性**：严禁凭经验编造代码。所有 API 调用必须先查阅 `docs/` 下的官方文档，再生成代码。
2. **性能优先**：代码不仅要能运行，还要运行良好。必须考虑性能、用户体验和资源效率。
3. **设备适配**：不同设备有不同的最佳实践。必须根据目标设备的特性进行适当的配置和优化。
4. 目录下如果有 _overview.md，先读它了解该模块的整体架构和使用注意事项，再查具体 API 文档。
---
## 完整文档文件树
所有官方文档位于本 Skill 的 `docs/` 目录。编程前必须对照此树定位目标文件路径。
```
docs/
└── advanced/
├── usb/
│ ├── device/
│ │ ├── keyboard.md
│ │ ├── mouse.md
│ ├── _overview.md
├── camera.md
├── code_scanner.md
├── dl.md
├── image.md
├── jpg.md
└── base/
├── atom_can.md
├── atom_gps.md
├── atom_socket.md
├── display.md
├── dtu_lorawan.md
├── dtu_lorawan_rui3.md
├── dtu_nbiot.md
├── dtu_nbiot2.md
├── dtu_nbiot2v11.md
├── echo.md
├── echo_pyramid.md
├── gpsv2.md
├── hdriver.md
├── motion.md
├── pwm.md
├── qrcode.md
├── qrcode2.md
├── rs232.md
├── rs485.md
├── speaker.md
├── stepmotor.md
├── tfcard.md
└── cap/
├── lora1262.md
├── lora868.md
└── chain/
├── angle.md
├── chainbus.md
├── encoder.md
├── joystick.md
├── key.md
├── tof.md
├── unit_bus.md
└── contribute/
├── template.md
└── controllers/
├── airq.md
├── atoms3-lite.md
├── atoms3r_cam.md
├── cardputer.md
├── coreink.md
├── dinmeter.md
├── dualkey.md
├── nesso-n1.md
├── paper.md
├── sticks3.md
└── get-started/
├── _overview.md
└── hardware/
├── adc.md
├── als.md
├── button.md
├── can.md
├── display.md
├── imu.md
├── ir.md
├── lora.md
├── mic.md
├── pin.md
├── plcio.digitalinput.md
├── plcio.md
├── plcio.relay.md
├── pwr485.md
├── rotary.md
├── scd40.md
├── sen55.md
├── sht30.md
├── speaker.md
├── touch.md
├── uart.md
├── wdt.md
└── hat/
├── adc.md
├── cardkb.md
├── dac.md
├── dac2.md
├── dlight.md
├── env.md
├── finger.md
├── heart.md
├── joyc.md
├── joystick.md
├── mini_encoder.md
├── mini_joy.md
├── ncir.md
├── neoflash.md
├── pir.md
├── servo.md
├── servo8.md
├── speaker.md
├── speaker2.md
├── thermal.md
├── tof.md
├── vibrator.md
└── iot-devices/
├── switchc6.md
└── m5ui/
├── _overview.md
├── arc.md
├── bar.md
├── button.md
├── buttonmatrix.md
├── calendar.md
├── canvas.md
├── chart.md
├── checkbox.md
├── dropdown.md
├── image.md
├── keyboard.md
├── label.md
├── led.md
├── line.md
├── list.md
├── menu.md
├── msgbox.md
├── page.md
├── roller.md
├── scale.md
├── slider.md
├── spinbox.md
├── spinner.md
├── switch.md
├── table.md
├── tabview.md
├── textarea.md
├── win.md
└── module/
├── 4in8out.md
├── ain4.md
├── asr.md
├── audio.md
├── bala2.md
├── cc1101.md
├── commu.md
├── dc_motor.md
├── display.md
├── dmx.md
├── dualkmeter.md
├── ecg.md
├── encoder4_motor.md
├── fan.md
├── gateway_h2.md
├── gnss.md
├── goplus2.md
├── gps.md
├── gpsv2.md
├── grbl.md
├── hmi.md
├── lan.md
├── llm.md
├── lora.md
├── lora868_v12.md
├── lorawan868.md
├── lte.md
├── nbiot.md
├── odrive.md
├── plus.md
├── pm25.md
├── pps.md
├── pwrcan.md
├── qrcode.md
├── rca.md
├── relay_2.md
├── rs232.md
├── servo2.md
├── step_motor_driver.md
├── usb.md
├── zigbee.md
└── quick-reference/
├── get-started.md
├── usb-mode.md
└── software/
├── easysocket.md
├── modbus.md
├── modbus.rtu.master.md
├── modbus.rtu.slave.md
├── modbus.tcp.client.md
├── modbus.tcp.server.md
├── requests2.md
├── tcp.client.md
├── tcp.server.md
├── udp.client.md
├── udp.server.md
├── umqtt.default.md
├── umqtt.md
└── stamplc/
├── ac.md
├── poe.md
└── system/
├── audio.md
├── audio.player.md
├── audio.recorder.md
├── bleuart.client.md
├── bleuart.md
├── bleuart.server.md
├── m5ble.md
├── m5espnow.md
├── power.md
├── time.md
├── wlan.ap.md
├── wlan.sta.md
└── unit/
├── ac_measure.md
├── accel.md
├── acssr.md
├── adc.md
├── adc_v11.md
├── ain4.md
├── angle.md
├── angle8.md
├── asr.md
├── audioplayer.md
├── bldc_driver.md
├── bps.md
├── button.md
├── buzzer.md
├── bytebutton.md
├── byteswitch.md
├── can.md
├── cardkb.md
├── cat1cn.md
├── catch.md
├── co2.md
├── co2l.md
├── color.md
├── dac.md
├── dac2.md
├── dcssr.md
├── dds.md
├── digi_clock.md
├── dlight.md
├── dmx.md
├── dualbutton.md
├── earth.md
├── encoder.md
├── encoder8.md
├── env.md
├── envpro.md
├── extencoder.md
├── extio.md
├── extio2.md
├── fader.md
├── finger.md
├── fingerprint2.md
├── flash_light.md
├── gateway_h2.md
├── glass.md
├── glass2.md
├── gps_v11.md
├── grove2grove.md
├── hall_effect.md
├── hbridge.md
├── heart.md
├── id.md
├── imu.md
├── imupro.md
├── ina226.md
├── ir.md
├── joystick.md
├── joystick2.md
├── key.md
├── kmeter.md
├── kmeter_iso.md
├── laser_rx.md
├── laser_tx.md
├── lcd.md
├── light.md
├── limit.md
├── lora_e220.md
├── lora_e220_433.md
├── lorawan_rui3.md
├── midi.md
├── minioled.md
├── miniscale.md
├── mq.md
├── mqtt.md
├── mqttpoe.md
├── nbiot.md
├── nbiot2.md
├── ncir.md
├── ncir2.md
├── neco.md
├── oled.md
├── op180.md
├── op90.md
├── pdm.md
├── pir.md
├── puzzle.md
├── qrcode.md
├── rca.md
├── reflective_ir.md
├── relay.md
├── relay2.md
├── relay4.md
├── rf433r.md
├── rf433t.md
├── rfid.md
├── rgb.md
├── roller485.md
├── rollercan.md
├── rtc.md
├── scales.md
├── scroll.md
├── servo180.md
├── servo360.md
├── servos8.md
├── ssr.md
├── step16.md
├── synth.md
├── thermal.md
├── timerpwr.md
├── tmos.md
├── tof.md
├── tof4m.md
├── tof90.md
├── tube_pressure.md
├── tvoc.md
├── uhf_rfid.md
├── ultrasonic.md
├── ultrasonic_io.md
├── uwb.md
├── vibrator.md
├── watering.md
├── weight.md
├── weight_i2c.md
├── zigbee.md
└── widgets/
├── _overview.md
├── circle.md
├── image+.md
├── image.md
├── label+.md
├── label.md
└── COPYRIGHT.md
```
不确定路径时，用脚本搜索：
```bash
./scripts/find_doc.sh <关键词>
```
Windows PowerShell：
```powershell
.\scripts\find_doc.ps1 <关键词>
```
---
## 编程流程（强制执行）
### 第 1 步：分析需求，定位文档
- 提取关键硬件/功能名称
- 在上方文件树中锁定目标路径
- 如不确定，运行 `./scripts/find_doc.sh <关键词>`（Windows PowerShell 用 `.\scripts\find_doc.ps1 <关键词>`）
### 第 2 步：读取原始 API（强制）
```bash
read docs/unit/env.md # 示例
```
从中提取：构造函数签名、方法参数、官方示例代码。
### 第 3 步：生成代码
**导入规范：**
```python
import M5
from M5 import * # 必须，初始化设备
# 按需引入，仅导入实际用到的：
from hardware import * # 硬件抽象：Pin、I2C、UART、ADC 等
from unit import * # Unit 系列
from module import * # Module 系列
from base import * # Base 系列
import m5ui # LVGL UI 控件
import lvgl as lv # LVGL 底层（如需直接操作）
```
- ❌ `from m5stack import *`（UIFlow1 旧写法，UIFlow2 不用）
- ❌ 根据文档路径推断导入（`docs/hardware/speaker.md` ≠ `from hardware import Speaker`）
- ✅ **必须查看文档示例代码中的实际 import 语句**（Speaker/Mic 通过 `from M5 import *` 导入，详见 `docs/hardware/speaker.md` 和 `docs/hardware/mic.md`）
- 禁止在代码头部添加版权注释，直接从 `import` 开始
**主循环规范：**
```python
while True:
M5.update() # 必须，否则触摸/按键事件无响应
# 业务逻辑...
time.sleep_ms(50) # 用 sleep_ms() 替代 sleep()
```
**内置设备 vs 外接模块（强制区分，否则系统崩溃）：**
| 设备类型 | 判断依据 | 访问方式 | 禁止操作 |
|---------|---------|---------|---------|
| 内置设备（IMU/触摸/电源/音频/显示） | 集成在主板上 | `M5.Imu.*` / `M5.Touch.*` / `Power.*` / `Speaker.*` | 禁止初始化 I2C/SPI（系统已占用） |
| 外接模块（Unit/HAT/Module） | Grove/I2C/SPI 连接 | 初始化 I2C + 创建设备对象 | - |
- **判断流程**：查设备文档 → 检查 `docs/system/` 和 `docs/hardware/` 是否有系统 API → 有则用 `M5.*`，无则按 Unit/HAT/Module 文档初始化
- **详细说明和示例**见 `docs/system/power.md`（Power API 与内置电源监测芯片的关系）
- **调试提示**：`I2C.scan()` 返回 `[]`、SDIO 错误、`ETIMEDOUT` → 检查是否触碰了系统总线
**m5ui 控件规范：**
- ✅ 所有控件必须传 `parent=page0`，否则 `screen_load()` 后黑屏（详见 `docs/m5ui/page.md`）
- ❌ 禁止假设参数通用：每个控件必须先读 `docs/m5ui/[widget].md` 验证构造函数参数（如 M5Label 不支持 `w/h`，详见 `docs/m5ui/label.md`）
- ❌ 禁止凭感觉选 LVGL 常量（字体、颜色等），只使用文档示例中出现的值
**API 返回值验证：**
- 检查文档 `:returns:` 标记 → `tuple` 必须解包或索引访问，禁止写 `result.x`
- 触摸 API 详细返回值和坐标转换规则见 `docs/hardware/touch.md`
- 单点触控用 `getX()/getY()`（已自动旋转），多点触控用 `getTouchPointRaw(i)` + 手动坐标转换
**LCD 渲染规范：**
- ❌ 禁止在 `loop()` 中 `Lcd.clear()` 或 `fillScreen()`（全屏闪烁，详见 `docs/hardware/display.md`）
- ✅ 静态背景只在 `setup()` 绘制一次，动态内容用 `fillRect()` 局部擦除+重绘
- ⚠️ 分层重绘：重绘底层后必须重绘被覆盖的上层元素（如钢琴黑键叠在白键上）
- 代码生成后检查所有函数调用是否有对应定义，确保无 `NameError`
**MicroPython 性能优化（数据处理/高频刷新场景强制）：**
| 优化点 | ❌ 错误模式 | ✅ 正确做法 |
|--------|-----------|-----------|
| 批量解包 | 循环逐个 `struct.unpack_from()` | 单次 `struct.unpack('<hh'*N, buf)` |
| 缓冲区复用 | `loop()` 中反复创建 `bytearray`/列表 | `setup()` 预分配，`loop()` 复用 |
| 零拷贝 | `buf[start:end]` 切片拷贝 | `memoryview(buf)[start:end]` |
| 图表刷新 | `set_series_values()` 全量替换 | `set_next_value()` + `SHIFT` 模式（详见 `docs/m5ui/chart.md`） |
| Mic DMA | 短缓冲频繁 `Mic.record()` | 加大缓冲至 50-100ms 降低启停开销 |
### 第 4 步：质量检查清单
| 检查项 | 问题模式 | 正确做法 |
|--------|---------|---------|
| 显示性能 | 循环中 `fillScreen()` 全屏重绘 | `fillRect()` 局部更新 |
| 屏幕旋转 | 横屏应用未设置旋转 | `Lcd.setRotation(1)` 或 `setRotation(3)` |
| 资源管理 | 循环中重复 `Speaker.begin()` | `setup()` 中初始化一次 |
| 算法效率 | 循环中 `item in list` 查找 | 改用字典/集合 |
| 用户体验 | 操作无即时视觉反馈 | 操作后立即更新 UI |
---
## 禁止行为
1. **禁止凭空编造 API**：未读文档前不得生成复杂 API 调用
2. **禁止主循环缺少 `M5.update()`**
3. **禁止使用 `from m5stack import *`**（UIFlow1 旧写法）
4. **禁止根据文档路径推断导入路径**：必须查看文档示例代码
5. **禁止为非 CoreS3 设备生成摄像头代码**：UIFlow2 摄像头 API 仅支持 CoreS3
6. **禁止假设控件参数通用**：每个 m5ui 控件必须单独验证参数
7. **禁止凭感觉选 LVGL 常量**：只用文档示例中出现的值
8. **禁止假设 API 返回对象**：检查 `:returns: tuple` 标记
9. **禁止在循环中全屏重绘**：用 `fillRect()` 局部更新
10. **禁止在循环中重复初始化硬件**
11. **禁止分层重绘时遗漏上层元素**
don't have the plugin yet? install it then click "run inline in claude" again.