编程教程

本文引用的文件

• docs/docs/zh_CN/index.rst

• docs/docs/zh_CN/tutorials/basics/index.rst

• docs/docs/zh_CN/tutorials/advance/index.rst

• docs/docs/zh_CN/tutorials/basics/repl.rst

• docs/docs/zh_CN/tutorials/basics/oled.rst

• docs/docs/zh_CN/tutorials/basics/buttons.rst

• docs/docs/zh_CN/tutorials/basics/accelerometer.rst

• docs/docs/zh_CN/tutorials/advance/random.rst

• docs/docs/zh_CN/tutorials/advance/filesystem.rst

• docs/docs/zh_CN/tutorials/advance/timer.rst

• docs/docs/zh_CN/tutorials/advance/radio.rst

产品概述

本教程面向K12创客教育场景，提供从入门到进阶的系统化学习路径，覆盖掌控板全部板载功能。内容以“入门教程（basics）+ 进阶教程（advance）”为主线，结合示例代码与API文档，帮助学习者快速掌握MicroPython在掌控板上的开发方法。项目基于ESP32双核芯片的mPython掌控板，兼容micro:bit部分生态（如music模块），并提供丰富的扩展库与社区资源。

• 目标用户：初学者、教师、创客爱好者

• 核心价值：循序渐进、贴近硬件、可立即验证

• 适用场景：课堂实验、课后练习、项目原型开发

章节来源

• docs/docs/zh_CN/index.rst:6-30

核心业务流程

本节梳理从“环境搭建—交互调试—外设控制—数据持久化—通信组网”的完整学习链路，对应教程目录与示例工程。

flowchart TD
A["开始：安装驱动与串口终端"] --> B["REPL交互调试<br/>导入 mpython 模块"]
B --> C["基础外设控制<br/>OLED显示/按键/触摸/声音/光线/加速度"]
C --> D["进阶能力<br/>随机数/文件系统/定时器/无线广播"]
D --> E["综合实践<br/>示例工程与经典案例"]
E --> F["拓展方向<br/>网络/IoT/蓝牙/传感器扩展"]

章节来源

• docs/docs/zh_CN/tutorials/basics/index.rst:4-19

• docs/docs/zh_CN/tutorials/advance/index.rst:4-15

功能模块清单

以下按“入门→进阶”顺序列出各模块职责、用户价值与验收要点，便于对照学习与自测。

• REPL（交互式调试）

  • 职责：通过串口终端进行即时代码执行与调试

  • 用户价值：降低试错成本，快速验证想法

  • 验收要点：能连接串口、进入>>>提示符、执行print与简单表达式、使用Tab补全与粘贴模式

  • 参考：docs/docs/zh_CN/tutorials/basics/repl.rst:9-147

• OLED显示

  • 职责：文本、图形、图片绘制与刷新

  • 用户价值：直观反馈程序状态与结果

  • 验收要点：DispChar显示中文、fill/pixel/hline/vline/rect等绘图、bitmap显示图片、show刷新

  • 参考：docs/docs/zh_CN/tutorials/basics/oled.rst:12-136, docs/docs/zh_CN/tutorials/basics/oled.rst:139-235

• 按键与中断

  • 职责：读取A/B按键电平与事件；配置中断回调

  • 用户价值：实现人机交互与低功耗响应

  • 验收要点：value()判断按下/松开；irq()下降沿触发回调；回调函数含参数

  • 参考：docs/docs/zh_CN/tutorials/basics/buttons.rst:15-58

• 加速度计

  • 职责：读取三轴加速度并计算角度/倾斜

  • 用户价值：感知姿态变化，用于水平仪、摇一摇等

  • 验收要点：get_x/y/z获取mg值；映射numberMap到屏幕坐标；反余弦计算倾角

  • 参考：docs/docs/zh_CN/tutorials/basics/accelerometer.rst:16-145

• 随机数

  • 职责：生成随机整数、浮点数与选择元素

  • 用户价值：游戏逻辑、动画效果、测试数据

  • 验收要点：randint/randrange/random/uniform；seed可重现序列

  • 参考：docs/docs/zh_CN/tutorials/advance/random.rst:1-103

• 文件系统

  • 职责：读写文件、列举/删除文件、boot.py/main.py启动流程

  • 用户价值：持久化配置、素材存储、模块化组织

  • 验收要点：open with上下文管理；write/read；os.listdir/remove；main.py自动运行

  • 参考：docs/docs/zh_CN/tutorials/advance/filesystem.rst:28-178

• 定时器

  • 职责：周期性或单次触发回调

  • 用户价值：定时任务、节拍控制、异步事件

  • 验收要点：Timer.init(period, mode, callback)；value()读计数；注意UI刷新延时

  • 参考：docs/docs/zh_CN/tutorials/advance/timer.rst:14-45

• 无线广播（radio）

  • 职责：2.4G短距无线收发，多设备组网

  • 用户价值：对讲机、电报机、分布式传感

  • 验收要点：on()/config(channel)/send()/receive()；可选返回MAC地址

  • 参考：docs/docs/zh_CN/tutorials/advance/radio.rst:14-57

章节来源

• docs/docs/zh_CN/tutorials/basics/index.rst:4-19

• docs/docs/zh_CN/tutorials/advance/index.rst:4-15

数据与状态

• 输入数据流

  • 传感器：加速度计三轴值（mg）、按键电平（0/1）、触摸阈值原始值

  • 外部通信：radio接收字符串或字节，可选附带MAC

  • 文件：读取文本/二进制数据（如图片帧）

• 内部状态

  • 显示缓冲：FrameBuffer/OLED缓冲区，需show刷新

  • 定时器：周期计数与回调队列

  • 随机种子：seed决定伪随机序列

• 输出数据流

  • 显示：字符、图形、图片帧

  • 音频/灯光：音乐播放、RGB指示

  • 通信：radio发送消息

• 数据所有权边界

  • 板载模块（mpython.*）负责硬件抽象与状态封装

  • 应用层（用户脚本）负责业务逻辑与数据编排

  • 文件系统仅作为持久化载体，不持有运行时状态

graph LR
S["传感器/IO"] --> M["mpython 模块"]
M --> D["显示缓冲/定时器/随机状态"]
D --> O["OLED/音乐/RGB"]
M --> N["radio 收发"]
M --> FS["文件系统(持久化)"]

关键约束与边界

• 平台与环境

  • 串口波特率115200；Windows需安装cp2104驱动

  • MicroPython为精简版，文件系统为平面结构（无多级目录）

• 硬件限制

  • 特定引脚不可用作通用IO（如P4/P10分别用于光线/声音传感器）

  • 显示刷新需调用show()；UI刷新可能引入延时影响定时精度

• 通信与网络

  • radio为同频短距通信，需设置相同channel；receive(True)可获取MAC

  • 网络相关能力在进阶与扩展中涉及（本仓库示例涵盖网络类示例）

• 性能与功耗

  • 频繁刷新显示与I/O会占用CPU与电量，建议批量更新与休眠策略

  • 定时器回调应避免耗时操作，必要时拆分任务

章节来源

• docs/docs/zh_CN/tutorials/basics/repl.rst:9-147

• docs/docs/zh_CN/tutorials/advance/filesystem.rst:21-25

• docs/docs/zh_CN/tutorials/advance/timer.rst:39-45

• docs/docs/zh_CN/tutorials/advance/radio.rst:29-32