经典项目案例

本文引用的文件

产品概述

本项目围绕 mPython 掌控板（ESP32 双核 MicroPython）提供一系列面向 K12 创客教育的经典实战案例，覆盖基础 IO、传感器、音频、网络与游戏等主题。通过“呼吸灯、音乐盒、照度计、温湿度、舵机、时钟、气象站、物联网、游戏”等案例，帮助学习者从入门到进阶，掌握硬件驱动、数据读取、UI 显示、网络通信与简单算法的综合能力。

  • 目标用户：K12 学生、创客教师、初学者开发者

  • 核心价值：以可运行的示例代码串联底层驱动与上层应用，强调“所见即所得”的学习体验

  • 适用场景：课堂实验、课后拓展、竞赛训练、家庭创客实践

核心业务流程

以下流程展示了典型项目的端到端链路：输入感知 → 数据处理 → 输出呈现/控制 → 可选联网或交互。

flowchart TD
A["上电启动"] --> B["初始化模块<br/>OLED/按键/传感器/网络"]
B --> C{"是否联网?"}
C -- 否 --> D["本地循环: 读取传感器/按键"]
C -- 是 --> E["连接WiFi并获取时间/天气"]
E --> F["解析JSON/时间数据"]
D --> G["映射/滤波/阈值判断"]
F --> G
G --> H["更新UI/播放声音/驱动舵机/LED"]
H --> I{"事件触发?"}
I -- 是 --> J["中断/回调处理"]
I -- 否 --> D
J --> D

该流程贯穿呼吸灯、音乐盒、照度计、温湿度、舵机、时钟、气象站与游戏等案例，体现“感知—计算—执行—反馈”的闭环。

功能模块清单

  • 呼吸灯

    • 职责：使用 PWM 控制 LED 亮度，实现平滑渐变效果

    • 验收要点：亮度变化连续无闪烁；周期可调；支持开关控制

    • 参考实现：breathing_light.py

  • 音乐盒

    • 职责：基于内置曲目或自定义音符序列，结合按键切换歌曲

    • 验收要点：按键响应及时；播放/切换稳定；屏幕显示当前曲目索引

    • 参考实现：musicbox.rst、PlayMusic.py

  • 照度计/噪声计

    • 职责：读取光线与声音传感器值，映射为百分比并在 UI 展示

    • 验收要点：数值范围合理；条形图刷新流畅；单位标注清晰

    • 参考实现：lux&sound_Cal.rst

  • 温湿度（DHT11）

    • 职责：通过单总线读取温湿度，显示在 OLED

    • 验收要点：读数稳定；异常时提示；引脚连接正确

    • 参考实现：dht11.rst

  • 舵机

    • 职责：PWM 控制舵机角度，结合加速度计实现倾斜控制

    • 验收要点：角度映射准确；抖动小；安全脉宽范围

    • 参考实现：servo.rst

  • 时钟（数字/模拟）

    • 职责：联网同步 NTP 时间，定时刷新显示

    • 验收要点：时间同步成功；刷新周期稳定；异常提示友好

    • 参考实现：clock.rst、DigitalClock.py

  • 气象站（网络天气）

    • 职责：调用心知天气 API，解析 JSON 并显示实况与预报

    • 验收要点：API 请求成功；图标/温度/城市显示正确；定时刷新

    • 参考实现：weather.rst

  • 物联网（OneNET/通用）

    • 职责：将传感器数据上报至云平台，或接收云端指令

    • 验收要点：连接稳定；数据格式正确；断线重连机制

    • 参考入口：oneNET/index.rst

  • 游戏（贪吃蛇/俄罗斯方块/Pong/Flappy Bird）

    • 职责：利用按键/触摸/加速度计进行交互，渲染帧动画

    • 验收要点：帧率稳定；碰撞检测准确；状态切换清晰

    • 参考实现：game/index.rst、snake.py、tetris.py

章节来源

数据与状态

  • 传感器数据流

    • 光线/声音：ADC 采样 → numberMap 映射 → UI 条形图

    • 温湿度：DHT11 单总线协议 → 温度/湿度整数 → 文本显示

    • 加速度/陀螺仪：六轴传感器 → 角度/角速度 → 舵机角度映射

  • 时间与网络数据

    • NTP 时间：ntptime.settime() → time.localtime() → 格式化显示

    • 天气数据：urequests.get → JSON 解析 → 图标/温度/城市 → 定时刷新

  • 游戏状态机

    • 贪吃蛇：方向/移动/生长/碰撞/胜负 → 帧循环刷新

    • 俄罗斯方块：块生成/旋转/下落/消行/计分 → 触摸/按键交互

  • 关键状态边界

    • 网络连接失败：超时异常捕获并提示

    • 传感器读取失败：重试/默认值/错误提示

    • 游戏结束：分数显示与重置入口

sequenceDiagram
participant U as "用户"
participant M as "主控程序"
participant S as "传感器/外设"
participant N as "网络(NTP/天气)"
participant D as "显示/音频/执行器"
U->>M : 启动/按键/触摸
M->>S : 读取光照/声音/温湿度/加速度
S-->>M : 原始数据
M->>N : 连接WiFi/获取时间/天气
N-->>M : 时间/天气JSON
M->>M : 数据映射/滤波/阈值判断
M->>D : 更新UI/播放声音/驱动舵机/LED
D-->>U : 视觉/听觉反馈

章节来源

  • docs/examples/pin/breathing_light.py:1-26

  • docs/examples/board_inside/PlayMusic.py:1-29

  • docs/examples/network/时钟/DigitalClock.py:1-34

  • docs/examples/game/snake.py:1-230

  • docs/examples/game/tetris.py:1-261

关键约束与边界

  • 硬件与引脚

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

    • 舵机脉宽范围因型号而异，需根据实际器件调整最小/最大脉宽

  • 网络与环境

    • WiFi 连接与 NTP/天气 API 依赖外部网络，需考虑超时与重试

    • 天气服务需要有效的 API Key，且遵循其速率限制与参数规范

  • 性能与功耗

    • 高频刷新（UI/音频/舵机）可能增加功耗与发热，需合理设置刷新周期

    • 游戏帧率需平衡流畅性与资源占用

  • 可靠性与容错

    • 传感器读取失败应降级处理（默认值/提示）

    • 网络异常需捕获并给出明确提示，避免程序崩溃

  • 扩展性

    • 模块化设计便于替换传感器/平台（如 ESP32 与 ESP32-S3 的差异）

    • 统一的数据映射与 UI 接口降低耦合度

章节来源