API类库参考

本文引用的文件

产品概述

本手册面向mPython掌控板及其ESP32-S3升级产品线，提供“内置库（MicroPython C级扩展）—MicroPython类库—Python标准库”三层API的完整参考，并给出与固件源码的对照关系。文档覆盖：

  • mPython专属库：板载传感器、显示、音频、无线、网络等高级封装

  • MicroPython类库：machine、network、neopixel、framebuf等底层能力

  • Python标准库：ujson、uos、utime等微型化标准模块 同时标注各API在固件中的实现位置（C级builtins或Python级modules），便于开发者定位源码、理解行为差异与限制。

核心业务流程

  • 传感器采集流程：MPythonPin/Touch/Button读取 → MOTION(加速度/陀螺仪/磁力计) → 可选BME280环境数据 → 通过wifi/网络上传或本地处理

  • 显示流程：OLED/TFT_displayer绘制 → framebuf缓冲 → show刷新

  • 音频流程：music播放音符/曲库；audio录音/播放/音量控制；可选讯飞TTS在线合成

  • 通信流程：WiFi STA/AP连接 → urequests/umqtt发送HTTP/MQTT；radio/ubluetooth进行短距通信

  • 存储流程：NVS持久化（校准偏移等）→ flashbdev文件系统 → SD卡扩展

sequenceDiagram
participant App as "应用代码"
participant MP as "mpython模块"
participant MB as "machine/驱动"
participant Net as "network/urequests"
participant FS as "NVS/文件系统"
App->>MP : 初始化传感器/显示/网络
MP->>MB : 配置Pin/I2C/ADC/PWM
MB-->>MP : 传感器原始数据
MP->>FS : 读取/写入校准参数(NVS)
App->>Net : 连接WiFi/发起HTTP请求
Net-->>App : 返回数据
App->>MP : 更新显示/播放音频

图表来源

章节来源

功能模块清单

  • mPython专属库

    • mpython：板载资源统一封装（显示、按键、触摸、传感器、RGB、I2C、WiFi）

    • music：兼容micro:bit的音乐播放与曲库

    • audio：ESP32音频编解码、录音、TTS（需联网）

    • radio：2.4G无线广播收发

    • urequests：HTTP客户端

    • umqtt.simple：轻量MQTT客户端

    • servo：舵机控制

    • bluebit/parrot：扩展板驱动

    • ds18x20：单总线温度传感器

    • bluetooth：BLE基础能力

    • iat：语音识别（讯飞）

    • 其他：sdcard、gui等

  • MicroPython类库

    • machine：Pin/ADC/PWM/I2C/SPI/UART/Timer/RTC/WDT等硬件抽象

    • network：WiFi/以太网等网络栈

    • neopixel：WS2812灯带控制

    • framebuf：帧缓冲绘图

    • 其他：ubluetooth、cryptolib、uctypes、random、ntptime、onewire等

  • Python标准库（微型化）

    • builtins/array/math/sys/ubinascii/ucollections/uerrno/uhashlib/uheapq/uio/ujson/uos/ure/uselect/usocket/ussl/ustruct/utime/uzlib等

章节来源

数据与状态

  • 传感器数据模型

    • 加速度/角速度/磁场：单位分别为mg、°/s、mG；支持量程、分辨率、偏移校准与NVS持久化

    • 环境传感器：BME280温度/气压/湿度；DHT温湿度；SPL06气压；MAX30102心率；APDS9960/PJ7620手势

  • 显示状态

    • OLED：128x64黑白，继承framebuf，支持文本模式、自定义字体、图形绘制

    • TFT_displayer（ESP32-S3）：320x172 RGB565，字符显示与刷新

  • 音频状态

    • 播放器/录音器状态机：初始化、播放、暂停、停止、释放

    • TTS：在线服务调用，依赖网络与配置

  • 网络状态

    • WiFi STA/AP切换、连接超时、断开清理

    • HTTP/MQTT会话生命周期管理

  • 存储状态

    • NVS键值对用于保存校准偏移、设备ID等

    • 文件系统：flashbdev虚拟块设备、SD卡挂载

classDiagram
class MOTION {
+Accelerometer
+Gyroscope
+Magnetic
+set_offset()
+get_nvs_offset()
+set_nvs_offset()
}
class Display {
+oled / TFT_displayer
+DispChar()
+show()
+fill()/pixel()/rect()
}
class Audio {
+player_init()
+play()/pause()/stop()
+recorder_init()
+record()
+xunfei_tts()
}
class Network {
+connectWiFi()
+enable_APWiFi()
+disconnectWiFi()
}
class Storage {
+NVS读写
+flashbdev/SD
}
MOTION --> Storage : "持久化偏移"
Display --> Storage : "缓存/刷新"
Audio --> Network : "TTS在线"
Network --> Storage : "配置/日志"

图表来源

章节来源

关键约束与边界

  • 平台差异

    • ESP32：内置modradio/modcodec/modnetwork/modrgbLED5x5/modxunfeiAI等C级模块

    • ESP32-S3：移除部分C级模块，新增machine_i2c_extmod/network_wlan独立模块；显示替换为TFT_displayer

  • 引脚与外设限制

    • P4/P10分别用于光线/声音传感器，不可作为通用IO

    • I2C默认使用P19/P20；不同板型引脚映射可能不同

  • 性能与功耗

    • WiFi开启会增加功耗，不使用时建议关闭

    • 高频采样/刷屏会影响实时性与电量

  • 兼容性

    • music模块兼容micro:bit，但曲库与接口以固件实现为准

    • 标准库采用u前缀命名（如ujson），可通过同名Python模块覆盖以实现兼容

  • 安全与稳定性

    • 回调在中断上下文执行，避免阻塞操作

    • 网络/音频在线功能依赖外部服务，需处理超时与异常

章节来源

附录：API与固件源码对照（按层级）

一、mPython专属库（Python层为主，部分C级实现）

  • mpython

    • 职责：板载资源统一封装（显示、按键、触摸、传感器、RGB、I2C、WiFi）

    • 源码路径：firmware/port/boards/*/modules/mpython.py（多板型共享/定制）

    • 文档路径：docs/docs/zh_CN/library/mPython/mpython.rst

    • 关联C模块：modmachine/machine_pin/machine_touchpad/modmotion/esp32_nvs/modframebuf

  • music

    • 职责：播放音符/曲库，兼容micro:bit

    • 源码路径：firmware/port/builtins/modmusic.c, modmusictunes.c

    • 文档路径：docs/docs/zh_CN/library/mPython/music.rst

  • audio（仅ESP32）

    • 职责：音频播放/录音/音量控制/讯飞TTS

    • 源码路径：firmware/port/builtins/modcodec.c

    • 文档路径：docs/docs/zh_CN/library/mPython/audio.rst

  • radio（仅ESP32）

    • 职责：2.4G无线广播收发

    • 源码路径：firmware/port/builtins/modradio.c

    • 文档路径：docs/docs/zh_CN/library/mPython/radio.rst

  • urequests

    • 职责：HTTP客户端

    • 源码路径：firmware/port/modules/urequests.py

    • 文档路径：docs/docs/zh_CN/library/mPython/urequests.rst

  • umqtt.simple

    • 职责：轻量MQTT客户端

    • 源码路径：firmware/port/modules/umqtt/simple.py（仓库中常见）

    • 文档路径：docs/docs/zh_CN/library/mPython/umqtt.simple.rst

  • servo

    • 职责：舵机控制

    • 源码路径：firmware/port/builtins/machine_servo.c（C级PWM/定时器）

    • 文档路径：docs/docs/zh_CN/library/mPython/servo.rst

  • bluebit/parrot

    • 职责：扩展板驱动

    • 源码路径：firmware/port/modules/bluebit.py, parrot.py

    • 文档路径：docs/docs/zh_CN/library/mPython/bluebit.rst, parrot.rst

  • ds18x20

    • 职责：单总线温度传感器

    • 源码路径：firmware/port/modules/ds18x20.py（依赖onewire）

    • 文档路径：docs/docs/zh_CN/library/mPython/ds18x20.rst

  • bluetooth

    • 职责：BLE基础能力

    • 源码路径：MicroPython ubluetooth（端口实现）

    • 文档路径：docs/docs/zh_CN/library/mPython/bluetooth.rst

  • iat（语音识别）

    • 职责：讯飞语音听写

    • 源码路径：firmware/port/builtins/modxunfeiAI.c

    • 文档路径：docs/docs/zh_CN/library/mPython/iat.rst

  • 其他

    • sdcard：firmware/port/modules/sdcard.py

    • gui：firmware/port/modules/gui.py（GUI绘制辅助）

章节来源

二、MicroPython类库（底层能力）

  • machine

    • 职责：Pin/ADC/PWM/I2C/SPI/UART/Timer/RTC/WDT等

    • 源码路径：firmware/port/builtins/modmachine.c, machine_pin.c, machine_touchpad.c, machine_servo.c

    • 文档路径：docs/docs/zh_CN/library/micropython/machine/machine.rst

  • network

    • 职责：WiFi/以太网等网络栈

    • 源码路径：firmware/port/builtins/modnetwork.c（ESP32）/network_wlan（ESP32-S3）

    • 文档路径：docs/docs/zh_CN/library/micropython/network.rst（由索引引用）

  • neopixel

    • 职责：WS2812灯带控制

    • 源码路径：firmware/port/modules/neopixel.py

    • 文档路径：docs/docs/zh_CN/library/micropython/neopixel.rst

  • framebuf

    • 职责：帧缓冲绘图

    • 源码路径：firmware/port/builtins/modframebuf.c

    • 文档路径：docs/docs/zh_CN/library/micropython/framebuf.rst

  • 其他

    • ubluetooth/cryptolib/uctypes/random/ntptime/onewire等：见micropython索引

章节来源

三、Python标准库（微型化）

  • builtins/array/math/sys/...

    • 职责：微型化标准函数与模块

    • 源码路径：MicroPython内置（C级）

    • 文档路径：docs/docs/zh_CN/library/pythonStd/builtins.rst 及对应子模块文档

章节来源

详细组件分析

mpython模块（板载封装）

  • 职责：统一封装OLED/TFT显示、按键/触摸、传感器、RGB、I2C、WiFi等

  • 关键类与方法

    • 显示：oled.DispChar/DispChar_font/show/fill/pixel/rect等

    • 传感器：accelerometer/gyroscope/magnetic/BME280

    • 输入：Button/Touch/MPythonPin

    • 网络：wifi.connectWiFi/disconnectWiFi/enable_APWiFi/disable_APWiFi

  • 源码路径：firmware/port/boards/*/modules/mpython.py

  • 文档路径：docs/docs/zh_CN/library/mPython/mpython.rst

flowchart TD
Start["应用调用"] --> Mode{"选择功能"}
Mode --> |显示| Disp["oled/tft_displayer<br/>DispChar/show"]
Mode --> |传感器| Sens["accelerometer/gyroscope/magnetic<br/>read/set_range/set_offset"]
Mode --> |输入| Inp["Button/Touch/MPythonPin<br/>is_pressed/read/write"]
Mode --> |网络| Net["wifi.connectWiFi/enable_APWiFi"]
Disp --> End["刷新/绘制"]
Sens --> End["获取/校准/持久化"]
Inp --> End["事件/状态"]
Net --> End["连接/断开"]

图表来源

章节来源

music模块（音乐播放）

  • 职责：播放音符列表/内置曲目，设置节奏，兼容micro:bit

  • 关键方法：play/pitch/stop/set_tempo/get_tempo/reset

  • 源码路径：firmware/port/builtins/modmusic.c, modmusictunes.c

  • 文档路径：docs/docs/zh_CN/library/mPython/music.rst

章节来源

audio模块（音频与TTS，ESP32）

  • 职责：音频播放/录音/音量控制；讯飞TTS在线合成

  • 关键方法：player_init/play/pause/stop/set_volume/recorder_init/record/xunfei_tts_config/xunfei_tts

  • 源码路径：firmware/port/builtins/modcodec.c

  • 文档路径：docs/docs/zh_CN/library/mPython/audio.rst

章节来源

radio模块（无线广播，ESP32）

  • 职责：2.4G无线广播发送/接收

  • 关键方法：on/off/send/send_bytes/receive/receive_bytes/config

  • 源码路径：firmware/port/builtins/modradio.c

  • 文档路径：docs/docs/zh_CN/library/mPython/radio.rst

章节来源

网络与存储

  • urequests：HTTP客户端（Python层）

    • 源码路径：firmware/port/modules/urequests.py

    • 文档路径：docs/docs/zh_CN/library/mPython/urequests.rst

  • umqtt.simple：MQTT客户端（Python层）

    • 文档路径：docs/docs/zh_CN/library/mPython/umqtt.simple.rst

  • NVS存储：校准偏移、设备ID等

    • 源码路径：firmware/port/builtins/esp32_nvs.c

  • 文件系统：flashbdev/SD卡

    • 源码路径：firmware/port/modules/flashbdev.py, sdcard.py

章节来源

传感器与外设

  • 六轴传感器（MOTION）：加速度/陀螺仪/磁力计

    • 源码路径：firmware/port/builtins/modmotion.c

  • 单总线与温度：onewire/ds18x20

    • 源码路径：firmware/port/modules/onewire.py, ds18x20.py

  • 手势与环境：apds9960/paj7620/spl06_001/max30102

    • 源码路径：firmware/port/modules/apds9960.py, paj7620.py, spl06_001.py, max30102.py

  • 电机与灯带：mddrv8837/apa106/neopixel

    • 源码路径：firmware/port/modules/mddrv8837.py, apa106.py, neopixel.py

  • 其他：pm25/weather/solar/ATGM336H_5N(CSK6011A)/acd1200/ir_remote

    • 源码路径：对应modules文件

章节来源

  • firmware/port/builtins/modmotion.c

  • firmware/port/modules/onewire.py

  • firmware/port/modules/ds18x20.py

  • firmware/port/modules/apds9960.py

  • firmware/port/modules/paj7620.py

  • firmware/port/modules/spl06_001.py

  • firmware/port/modules/max30102.py

  • firmware/port/modules/mddrv8837.py

  • firmware/port/modules/apa106.py

  • firmware/port/modules/neopixel.py

  • firmware/port/modules/pm25.py

  • firmware/port/modules/weather.py

  • firmware/port/modules/solar.py

  • firmware/port/modules/ATGM336H_5N.py

  • firmware/port/modules/CSK6011A.py

  • firmware/port/modules/acd1200.py

  • firmware/port/modules/ir_remote.py

显示与GUI

  • OLED（ESP32）：SSD1106驱动，framebuf衍生

    • 源码路径：firmware/port/modules/ssd1106.py

  • TFT_displayer（ESP32-S3）：LCD彩屏，framebuf衍生

    • 文档路径：docs/docs/zh_CN/library/mPython/mpython.rst（TFT相关）

  • GUI工具：gui.py、lv_utils（ESP32-S3）

    • 源码路径：firmware/port/modules/gui.py

章节来源

蓝牙与扩展库

  • mpython_ble：BLE高级库（包结构advertising/application/characteristics/descriptors/gatts/services）

    • 源码路径：firmware/port/modules/mpython_ble/*

  • bluebit/parrot：扩展板驱动

    • 源码路径：firmware/port/modules/bluebit.py, parrot.py

章节来源

  • firmware/port/modules/mpython_ble/*

  • firmware/port/modules/bluebit.py

  • firmware/port/modules/parrot.py

工具与系统模块

  • logging：日志记录

    • 源码路径：firmware/port/modules/logging.py

  • webrepl：Web REPL

    • 源码路径：firmware/port/modules/webrepl.py

  • upip/upip_utarfile：包管理器

    • 源码路径：firmware/port/modules/upip.py, upip_utarfile.py

  • 其他：hrcalc/forece/adafruit_miniqr/inisetup等

    • 源码路径：对应modules文件

章节来源

  • firmware/port/modules/logging.py

  • firmware/port/modules/webrepl.py

  • firmware/port/modules/upip.py

  • firmware/port/modules/upip_utarfile.py

  • firmware/port/modules/hrcalc.py

  • firmware/port/modules/forece.py

  • firmware/port/modules/adafruit_miniqr.py

  • firmware/port/modules/inisetup.py

依赖分析

  • 模块耦合

    • mpython依赖machine/SSD1106/neopixel/framebuf/NVS等底层能力

    • audio/music依赖machine（PWM/定时器）与网络（TTS）

    • radio依赖底层射频驱动（ESP32）

    • 传感器模块普遍依赖I2C/单总线/ADC

  • 外部依赖

    • 网络：WiFi路由器/云端服务（HTTP/MQTT/TTS）

    • 存储：NVS/Flash/SD卡

  • 潜在循环依赖

    • 通过分层设计（应用→mpython→machine→驱动）降低耦合

graph TB
App["应用代码"] --> MP["mpython模块"]
MP --> MB["machine/驱动"]
MP --> NET["network/urequests"]
MP --> FS["NVS/文件系统"]
MP --> DISP["SSD1106/framebuf"]
MP --> AUDIO["modcodec/modmusic"]
MP --> RADIO["modradio"]
NET --> Cloud["云端服务"]
FS --> Flash["Flash/SD"]

图表来源

章节来源

结论

本参考手册系统化梳理了mPython掌控板的三层API（内置库、MicroPython类库、Python标准库），并提供与固件源码的明确对照，帮助开发者快速定位实现、理解行为差异与限制。建议在开发中优先使用mPython高层封装提升效率，必要时深入machine/驱动层优化性能与功耗；网络与在线功能需考虑可靠性与异常处理；跨平台差异（ESP32 vs ESP32-S3）应在选型与适配阶段充分考虑。