板载功能库（mpython）

本文引用的文件

产品概述

本模块为 mPython 掌控板的板载功能封装，面向 K12 创客教育场景，提供开箱即用的显示、输入、传感器与网络能力。通过统一的 Python API，开发者可快速实现：

  • OLED/TFT 显示与绘图

  • 按键与触摸事件处理

  • 加速度计、陀螺仪、磁力计等运动感知

  • 光线与声音采集

  • WiFi 连接与热点模式

  • RGB 灯控制与工具函数

该模块屏蔽了底层 I2C/ADC/PWM/TouchPad 等硬件细节，使初学者也能以直观方式完成交互项目。

Section sources

核心业务流程

  • 初始化流程：模块加载时自动创建全局对象（如 oled、light、sound、button_a/b、touchPad_*、rgb），并检测可用设备（OLED、MOTION、Magnetic）。

  • 显示流程：调用 DispChar/DispChar_font 写入帧缓冲，show() 刷新到屏幕；支持自动换行与多种文本模式。

  • 输入流程：Button/Touch 通过中断回调或轮询读取状态，支持按下/释放事件与计数。

  • 传感器流程：Accelerometer/Gyroscope/Magnetic 通过 I2C 读取原始数据并进行单位换算、偏移校准与角度计算。

  • 网络流程：wifi.connectWiFi 扫描并连接 AP；enable_APWiFi 开启热点；disconnectWiFi/disable_APWiFi 关闭连接/AP。

sequenceDiagram
participant App as "用户程序"
participant MP as "mpython 模块"
participant HW as "I2C/ADC/PWM/TouchPad"
participant OLED as "SSD1106/OLED"
participant NET as "network.WLAN"
App->>MP : 导入 mpython
MP->>HW : 初始化 I2C/ADC/PWM/TouchPad
MP->>OLED : 检测并实例化 OLED(128x64)
MP->>MP : 创建 light/sound/button/touchpad/rgb
App->>MP : oled.DispChar("你好", x, y)
MP->>OLED : 写入字符位图到帧缓冲
App->>MP : oled.show()
MP->>OLED : 刷新显示
App->>MP : wifi.connectWiFi(ssid, pwd)
MP->>NET : 扫描并连接 STA
Note over MP,NET : 超时则抛出异常

Diagram sources

  • firmware/port/boards/mpython/modules/mpython.py:91-204

  • firmware/port/boards/mpython/modules/mpython.py:1205-1254

Section sources

  • firmware/port/boards/mpython/modules/mpython.py:91-204

  • firmware/port/boards/mpython/modules/mpython.py:1205-1254

功能模块清单

  • 显示

    • OLED 类：DispChar/DispChar_font/fill/pixel/scroll/blit/text/rect/hline/vline/line/show/poweron/poweroff/contrast/invert

    • ESP32-S3 TFT_displayer：DispChar/DispChar_font/clear/show（ST7789 LCD，320x172）

  • 输入

    • Button：is_pressed/was_pressed/get_presses/value/status/event_pressed/event_released/irq

    • Touch：config/is_pressed/was_pressed/get_presses/read/event_pressed/event_released

  • 传感器

    • Accelerometer：get_x/y/z/set_range/set_resolution/set_offset/roll_pitch_angle/事件常量

    • Gyroscope：get_x/y/z/set_range/set_ODR/set_offset

    • Magnetic：get_x/y/z/get_field_strength/get_heading/calibrate/peeling/clear_peeling

  • 环境传感

    • LightSensor（可选）：value（lux 换算）

    • BME280（可选）：temperature/pressure/humidity

  • 音频

    • music：play/pitch/stop/set_tempo/get_tempo/reset（内置曲目）

    • audio（ESP32）：player_init/play/pause/resume/stop/set_volume/player_status/player_deinit；录音与TTS

  • 网络

    • wifi：connectWiFi/disconnectWiFi/enable_APWiFi/disable_APWiFi

  • 其他

    • rgb：NeoPixel 派生，write/fill/brightness

    • MPythonPin：read_digital/write_digital/read_analog/write_analog/irq

    • 工具：sleep/sleep_ms/sleep_us/numberMap/uuid

Section sources

数据与状态

  • 显示缓冲区

    • OLED：128x64 单色帧缓冲，字符位图来自内嵌字体；DispChar 返回 (宽度, 下一坐标) 便于连续排版。

    • TFT_displayer：RGB565 帧缓冲，支持颜色绘制与自定义字体。

  • 传感器数据

    • 加速度：mg 单位，范围±2/4/8/16g，分辨率10/12/14bit；roll/pitch 由三轴向量归一化计算。

    • 角速度：°/s，量程±16~2048dps；支持 ODR 设置与偏移持久化。

    • 磁场：mG 单位，强度为三轴矢量和；heading 基于 atan2 计算，需水平放置与校准。

  • 输入状态

    • Button/Touch：维护“是否按下”“上次按下”“计数”状态；中断触发后通过 schedule 调度回调。

  • 网络状态

    • STA/AP 双接口；连接过程包含扫描、认证、DHCP 等待与超时处理。

classDiagram
class MOTION {
+Accelerometer
+Gyroscope
}
class Accelerometer {
+get_x()
+get_y()
+get_z()
+set_range()
+set_resolution()
+set_offset()
+roll_pitch_angle()
}
class Gyroscope {
+get_x()
+get_y()
+get_z()
+set_range()
+set_ODR()
+set_offset()
}
class Magnetic {
+get_x()
+get_y()
+get_z()
+get_field_strength()
+get_heading()
+calibrate()
+peeling()
+clear_peeling()
}
MOTION --> Accelerometer : "组合"
MOTION --> Gyroscope : "组合"

Diagram sources

  • firmware/port/boards/mpython/modules/mpython.py:206-641

  • firmware/port/boards/mpython/modules/mpython.py:643-1007

Section sources

  • firmware/port/boards/mpython/modules/mpython.py:206-641

  • firmware/port/boards/mpython/modules/mpython.py:643-1007

关键约束与边界

  • 引脚限制

    • P4 用于光线传感器，P10 用于声音传感器，不可用作通用 IO。

    • PWM/ANALOG/OUT_DRAIN 对引脚有明确支持列表，非法模式将抛 TypeError。

  • 传感器可用性

    • OLED 仅在 I2C 地址 0x60 存在时初始化；MOTION 需检测到 MSA300/QMI8658C；Magnetic 需检测到 MMC5983MA/MMC5603NJ。

  • 精度与环境

    • 仅用加速度计算的 roll/pitch 适用于静态重力场景；强振动会引入误差。

    • 磁力计 heading 需保持水平并校准，避免强磁干扰。

  • 网络行为

    • connectWiFi 默认超时 10 秒，失败抛 OSError；AP 模式可配置信道与密码。

  • 版本差异

    • v2.3+ 移除加速度计运动侦测事件；ESP32-S3 使用 TFT_displayer 替代 OLED。

Section sources

详细API说明

OLED 显示（ESP32）

  • 类与方法

    • DispChar(s, x, y, mode=TextMode.normal, auto_return=False)：显示多语言字符，mode 支持 normal/rev/trans/xor；auto_return 启用自动换行。

    • DispChar_font(font, s, x, y, invert=False)：使用 font_to_py 转换的自定义字体显示。

    • fill/pixel/scroll/blit/text/rect/hline/vline/line：继承 framebuf 绘图能力。

    • poweron/poweroff/contrast/invert：电源与对比度控制。

  • 示例

    • 多语言 hello world 显示见示例文件。

flowchart TD
Start(["调用 DispChar"]) --> LoadFont["读取字符位图"]
LoadFont --> Mode{"文本模式"}
Mode --> |normal| DrawWhite["写白色像素"]
Mode --> |rev| DrawBlack["写黑色像素"]
Mode --> |trans| Overlay["叠加到已有内容"]
Mode --> |xor| Xor["翻转背景像素"]
DrawWhite --> NextChar["下一个字符"]
DrawBlack --> NextChar
Overlay --> NextChar
Xor --> NextChar
NextChar --> End(["返回(宽度, 下一坐标)"])

Diagram sources

  • firmware/port/boards/mpython/modules/mpython.py:100-164

Section sources

按键与触摸

  • Button

    • is_pressed/was_pressed/get_presses/value/status：查询当前/历史状态与计数。

    • event_pressed/event_released：注册回调，内部通过 Pin.irq 触发。

    • irq：支持下降沿/上升沿/电平触发。

  • Touch

    • config(threshold)：设置触摸阈值。

    • read/is_pressed/was_pressed/get_presses：读取原始值与状态。

    • event_pressed/event_released：触摸事件回调。

  • 示例

    • 按键事件回调与触摸按键播放音阶示例。

sequenceDiagram
participant User as "用户"
participant Btn as "Button/Touch"
participant IRQ as "Pin.irq"
participant App as "应用回调"
User->>Btn : 按下/释放
Btn->>IRQ : 触发中断
IRQ-->>Btn : 回调 handler
Btn->>App : 调用 event_pressed/event_released
App-->>User : 执行业务逻辑

Diagram sources

  • firmware/port/boards/mpython/modules/mpython.py:1270-1382

Section sources

加速度计、陀螺仪、磁力计

  • Accelerometer

    • get_x/y/z：返回 mg 单位；set_range/set_resolution 配置量程与分辨率；set_offset 校准偏移；roll_pitch_angle 计算欧拉角。

    • 事件常量：tilt_left/right/up/down、face_up/down、single/double click、freefall（v2.3+ 移除事件）。

  • Gyroscope

    • get_x/y/z：°/s；set_range/set_ODR 配置量程与输出速率；set_offset 校准。

  • Magnetic

    • get_x/y/z：mG；get_field_strength：矢量模；get_heading：航向角（需水平与校准）；calibrate：引导旋转校准；peeling/clear_peeling：去皮/恢复。

flowchart TD
A["读取三轴加速度"] --> N["归一化向量"]
N --> R["roll = -asin(y)"]
N --> P["pitch = atan2(x, z)"]
R --> Out["返回 (roll, pitch)"]
P --> Out

Diagram sources

  • firmware/port/boards/mpython/modules/mpython.py:497-507

Section sources

光线与声音

  • 光线

    • light.read()：ADC 原始值 0~4095；LightSensor.value()（可选）：转换为 lux。

  • 声音

    • sound.read()：ADC 原始值 0~4095；audio.loudness()（ESP32）：录音响度。

Section sources

网络（WiFi）

  • wifi.connectWiFi(ssid, passwd, timeout=10)：扫描并连接，超时抛异常。

  • wifi.disconnectWiFi()：断开并关闭 STA。

  • wifi.enable_APWiFi(essid, password=b'', channel=10)：开启热点。

  • wifi.disable_APWiFi()：关闭热点。

sequenceDiagram
participant App as "应用"
participant W as "wifi"
participant N as "network.WLAN"
App->>W : connectWiFi(ssid, pwd)
W->>N : sta.scan()
W->>N : sta.connect(ssid, pwd)
loop 等待IP
W->>N : ifconfig()
end
alt 成功
W-->>App : 打印连接信息
else 超时
W-->>App : 抛出OSError
end

Diagram sources

  • firmware/port/boards/mpython/modules/mpython.py:1205-1254

Section sources

RGB 灯与引脚

  • rgb：NeoPixel 派生，write/fill/brightness 控制 3 颗 WS2812。

  • MPythonPin：支持 IN/OUT/PWM/ANALOG/OUT_DRAIN；read_digital/write_digital/read_analog/write_analog/irq；注意 P4/P10 保留给传感器。

Section sources

依赖分析

  • 底层依赖

    • machine.I2C/ADC/PWM/TouchPad/Pin：硬件抽象层。

    • ssd1106.SSD1106_I2C：OLED 驱动。

    • neopixel.NeoPixel：RGB 灯控制。

    • framebuf：帧缓冲绘图基础。

    • network.WLAN：WiFi 网络栈。

    • NVS：存储加速度/陀螺仪偏移。

  • 模块耦合

    • mpython.py 集中管理全局对象与传感器初始化，各子模块（OLED/MOTION/Magnetic/Button/Touch）通过 i2c/adc/pwm 访问硬件。

    • 事件系统通过 micropython.schedule 在安全上下文中调用用户回调。

graph TB
MP["mpython.py"] --> SSD["ssd1106"]
MP --> FB["framebuf"]
MP --> NP["neopixel"]
MP --> NET["network.WLAN"]
MP --> NVS["NVS"]
MP --> I2C["machine.I2C"]
MP --> ADC["machine.ADC"]
MP --> PWM["machine.PWM"]
MP --> TP["machine.TouchPad"]

Diagram sources

  • firmware/port/boards/mpython/modules/mpython.py:11-24

Section sources

  • firmware/port/boards/mpython/modules/mpython.py:11-24

性能与最佳实践

  • 显示优化

    • 批量绘制后统一 show()，减少频繁刷新。

    • 使用 auto_return 自动换行简化排版。

  • 传感器采样

    • 合理设置量程与分辨率，平衡精度与功耗。

    • 使用 set_offset 与 calibrate 提升测量准确性。

  • 输入响应

    • 优先使用事件回调降低轮询开销。

    • 触摸阈值根据环境调整，避免误触。

  • 网络

    • 连接前确认 SSID 与密码正确，必要时增加重试与超时策略。

    • 不使用 WiFi 时及时 disconnect/disable AP 以降低功耗。

[本节为通用指导，不直接分析具体文件]

故障排查

  • OLED 未显示

    • 检查 I2C 地址 0x60 是否存在；确认 oled.init 与 show() 调用。

  • 传感器无数据

    • 检查 MOTION/Magnetic 初始化是否成功；确认 I2C 总线正常。

  • 按键/触摸无响应

    • 检查引脚映射与上拉配置；确认事件回调已注册。

  • WiFi 连接失败

    • 检查 SSID/密码与时区；查看超时日志；尝试 disable AP 后再连接。

Section sources

  • firmware/port/boards/mpython/modules/mpython.py:200-204

  • firmware/port/boards/mpython/modules/mpython.py:1205-1254

结论

mpython 模块为掌控板提供了完整且易用的板载功能封装，覆盖显示、输入、传感器与网络等核心能力。通过清晰的 API 与丰富的示例，开发者可以快速构建交互项目。建议在实际项目中结合传感器校准、事件驱动与资源管理，以获得稳定高效的体验。

[本节为总结性内容，不直接分析具体文件]