核心原则

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

不确定路径时，用脚本搜索：

./scripts/find_doc.sh <关键词>

编程流程（强制执行）

第 1 步：分析需求，定位文档

• 提取关键硬件/功能名称
• 在上方文件树中锁定目标路径
• 如不确定，运行 ./scripts/find_doc.sh <关键词>

第 2 步：读取原始 API（强制）

read docs/unit/env.md       # 示例

从中提取：构造函数签名、方法参数、官方示例代码。

第 3 步：生成代码

导入规范：

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 开始

主循环规范：

while True:
    M5.update()        # 必须，否则触摸/按键事件无响应
    # 业务逻辑...
    time.sleep_ms(50)  # 用 sleep_ms() 替代 sleep()

内置设备 vs 外接模块（强制区分，否则系统崩溃）：

• 判断流程：查设备文档 → 检查 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 性能优化（数据处理/高频刷新场景强制）：

第 4 步：质量检查清单

禁止行为

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. 禁止硬编码屏幕尺寸：用 Lcd.width()/height()
11. 禁止在循环中重复初始化硬件
12. 禁止分层重绘时遗漏上层元素