MicroPython 开发

本章节包含以下部分，请按需阅读：

MicroPython 入门教程
配置开发环境
示例程序

MicroPython 入门教程

初次接触 Pico MicroPython 开发，想要快速上手？我们为您准备了一套通用的入门教程。此教程旨在帮助开发者快速熟悉 Thonny IDE 并上手开发。教程内容涵盖环境搭建、项目创建、组件使用及外设编程等，帮助您迈出 MicroPython 编程的第一步。

配置开发环境

请参考 安装和配置 Thonny IDE 教程 下载安装 Thonny IDE。

示例程序

MicroPython 示例程序位于示例程序包的 examples\MicroPython 目录中。

示例程序	基础例程说明	依赖库
01_SD	挂载 SD 卡	-
02_RTC	获取 RTC 数据	-
03_GUI	GUI 显示程序	-
04_KEY	按键测试	-
05_SHTC3	温湿度传感器测试	-
06_TOUCH	触摸屏测试	-
07_ES8311	ES8311 音频录音与播放测试	-

01_SD

【程序说明】

使用 SPI 与 SD 卡通讯，并将 SD 卡挂载到开发板，挂载成功后，可通过 Thonny 查看和修改 SD 卡中的内容。

【硬件连接】

插入 SD 卡
使用 USB 线把板子接入电脑

【代码分析】

sdcard.SDCard(spi, cs, baudrate)：创建 SD 卡对象，并将初始化的 SPI 接口与 CS 引脚绑定到 SD 卡驱动中。
uos.mount(sd, '/sd')：将 SD 卡文件系统挂载到 /sd 目录下。挂载成功后，用户即可通过 /sd 路径对 SD 卡进行文件读写操作，例如创建、读取或删除文件。

【运行效果】

通过 thonny 将 01_SD 文件下的所有 py 文件上传到开发板中，并复位。开发板复位后会根据 boot.py 的程序，自动将 SD 挂载到 sd 目录下。

02_RTC

【程序说明】

使用 I2C 与板载 RTC 芯片通讯，设定并读取 RTC 时间数据，同时测试 RTC 中断是否正常。

【硬件连接】

使用 USB 线把板子接入电脑

【代码分析】

RTC = PCF85063()：创建 RTC 对象。
RTC.setDate(weekday, day, month, year)：设置 RTC 日期。
RTC.setTime(hour, minute, second)：设置 RTC 时间。
RTC.readTime()：读取 RTC 时间。
RTC.setAlarm(second, minute, hour, day, weekday)：设置 RTC 闹钟。
RTC.enableAlarm()：使能 RTC 闹钟。

【运行效果】

使用 thonny 运行 02_RTC 文件下的 py 文件。

03_GUI

【程序说明】

通过 SPI 通信驱动显示屏，利用 GUI 绘图函数绘制文字、边框与色块，刷新屏幕完成显示。

【硬件连接】

使用 USB 线把板子接入电脑

【代码分析】

epd = EPD_1in54 ：创建 LCD 对象。
epd.Clear(0xff)：清除全屏。
epd.fill(0xff)：填充全屏颜色。
epd.text("RP2350-Touch-ePaper-1.54", 0, 30, 0x00)：在屏幕上写文字。
epd.hline(10, 150, 80, 0x00)：画水平线。
epd.vline(10, 90, 60, 0x00)：画垂直线。
epd.display(epd.buffer)：刷新屏幕（真正显示出来）。

【运行效果】

使用 thonny 运行 03_GUI 文件下的 py 文件。

04_KEY

【程序说明】

演示 RP2350 MicroPython 下的两路按键输入与常用按键事件识别：BOOT（BOOTSEL 特殊按键）与 POWER（普通 GPIO24）。
支持事件：down、up、click（单击）、double（双击）、long（长按），并在串口/Thonny Shell 中打印事件日志。
示例代码文件：key_events.py（可作为库导入复用，也可作为主程序脚本直接运行）。

【硬件连接】

BOOT：使用板载 BOOTSEL 按键。
POWER：使用板载 POWER 按键（内部接到 GPIO24）。
使用 USB 线把板子接入电脑，并用 Thonny 连接 MicroPython 解释器。

【代码分析】

BootKey：BOOTSEL 读取封装
- BOOTSEL 不是普通 GPIO，MicroPython 一般通过 rp2.bootsel_button()（或部分版本用 machine.bootsel_button()）提供读取接口。
- pressed()：返回当前是否按下（True 表示按下）。
GpioKey：普通 GPIO 按键读取封装
- Pin(pin, Pin.IN, pull)：将指定 GPIO 配置为输入，并配置上拉/下拉。
- active_low=True：表示按下为 0，松开为 1（常见接法）。
Key：按键事件状态机（轮询式）
- debounce_ms：消抖时间。只有当电平变化稳定持续超过该时间，才认为状态真的变化。
- double_ms：双击判定窗口。单击事件会在“松开后等待 double_ms”确认没有第二次点击后才发出。
- long_ms：长按阈值。按住超过 long_ms 时立即触发一次 long（不必等待松开）。
- poll(now)：每隔一段时间调用一次，内部完成：
  - 读取原始电平（raw）
  - 消抖得到稳定状态（stable），并在稳定按下/松开时发送 down/up
  - 长按检测：稳定按下持续超过 long_ms 发送 long
  - 单击/双击聚合：松开后累积点击次数，超时后将 1 次转换为 click，2 次转换为 double
main(banner=False, poll_ms=10)：程序入口
- banner=True 时打印操作提示（适合“作为主程序脚本”运行时引导初学者）。
- poll_ms 为轮询间隔，越小越灵敏但占用 CPU 越多（常用 5~20ms）。

【运行效果】

通过 Thonny 直接运行 04_KEY 文件夹下的 py 文件。
- 在电脑上用 Thonny 打开 key_events.py，确认解释器选择的是开发板对应的 MicroPython 端口。
- 点击绿色 Run 按钮，Thonny 会把脚本发送到开发板执行。
- 这种方式下脚本通常会以 __main__ 方式执行，因此会自动进入 main(banner=True)，直接看到提示与按键事件输出。
- 如果你想把它当库来用（导入但不自动运行），请把文件上传到开发板后在自己的 main.py 里显式调用 key_events.main(...)。
作为主程序脚本运行（上电自动执行）
- 将 key_events.py 上传到开发板根目录并重命名为 main.py。
- 复位后会先打印提示信息（banner），随后按键触发时输出事件，例如：
  - power down / power up / power click
  - power double
  - power long
  - boot down / boot up / boot click ...
作为可复用库运行（推荐）
- 保持文件名 key_events.py 不变，上传到开发板。
- 在你自己的 main.py 中显式调用：
  - import key_events
  - key_events.main(banner=True)（或 banner=False）
停止运行
- Thonny 点击 Stop（中断）按钮，或在 Shell/REPL 中按 Ctrl+C 结束轮询循环并返回交互提示符。

05_SHTC3

【程序说明】

演示 RP2350 MicroPython 下通过 I2C 读取 SHTC3 温湿度传感器。
支持读取：
- 温度（°C）
- 相对湿度（%RH）

【硬件连接】

已内置传感器：SHTC3（I2C）I2C 地址：默认 0x70
用 USB 线把板子接入电脑，并用 Thonny 连接 MicroPython 解释器。

【代码分析】

常量配置
I2C 默认参数（见 shtc3.py 文件头部的常量）：
- SHTC3_I2C_NUM：I2C 控制器编号
- SHTC3_I2C_SCL / SHTC3_I2C_SDA：默认引脚
- SHTC3_I2C_ADDR：I2C 地址
- SHTC3_I2C_FREQ：I2C 频率
SHTC3 指令集：
- SHTC3_REG_WAKEUP / SHTC3_REG_SLEEP / SHTC3_REG_SOFTRESET / SHTC3_REG_READID
- SHTC3_MEAS_ALL：根据 stretch/low_power/hum_first 组合选择“测量指令”
SHTC3：传感器驱动类
__init__(..., i2c=None, crc_fail_return=(None, None))
- i2c：允许外部传入已创建好的 I2C 对象，方便多设备共享总线
- crc_fail_return：CRC 校验失败时的返回值（默认 (None, None)）
- 初始化阶段会执行：
  - wakeup()：唤醒
  - soft_reset()：软复位
crc8(buffer)
- 用于校验 SHTC3 返回的 CRC-8（多项式 0x31，初值 0xFF）
read_id()
- 读取设备 ID，并验证 CRC；CRC 不通过返回 None
measurement(hum_first=False, low_power_meas=False, stretch=False, ...)
- 读取一次温湿度并返回 (temperature_c, humidity_rh)
- 参数说明：
  - low_power_meas=True：低功耗测量（更省电，但重复性/精度表现略受影响，温度影响更明显）
  - stretch=True：启用 clock stretching（是否需要取决于你的 I2C 总线/驱动实现）
  - hum_first：传感器返回的两个数据块（温度/湿度）谁在前
- 兼容参数：
  - hum_frist：保留了旧示例中的拼写（typo）兼容
read(low_power=False, stretch=False, ...)
- 更友好的别名：等价于 measurement(hum_first=False, ...)
main(...)：示例入口（单文件一体化）
当 shtc3.py 作为脚本直接运行时，会执行：
- main()：循环读取并打印温湿度
- Ctrl+C 可中断循环
参数说明：
- interval_s：打印间隔（秒）
- crc_fail_return：可覆盖驱动默认 CRC 失败返回值

【运行效果】

方式 A：通过 Thonny 直接运行 05_SHTC3 文件夹下的 py 文件。
在电脑上用 Thonny 打开 shtc3.py，确认解释器选择的是开发板对应的 MicroPython 端口。
点击 Run 执行，默认会进入 main()，看到类似输出：
- SHTC3 ID: 0x....
- Temperature: 25.12 °C, Humidity: 45.67 %
停止运行：Thonny 点击 Stop，或在 REPL 里按 Ctrl+C。
方式 B：作为库导入复用（推荐）

将 shtc3.py 上传到开发板文件系统（与 main.py 同目录通常最方便）。
在你自己的 main.py 里使用：

import time
from shtc3 import SHTC3

shtc3 = SHTC3()
while True:
    t, rh = shtc3.read()
    if t is not None and rh is not None:
        print(t, rh)
    time.sleep(1)

mpy_shtc3

06_TOUCH

【程序说明】

该例程仅限于 RP2350-Touch-ePaper-1.54 使用。
这是一个“触摸测试界面”示例：在 1.54 英寸 200×200 墨水屏上画 4 个触摸区域（Area A~D），触摸后在屏幕下方显示坐标与区域名称，并在串口打印触摸坐标。
屏幕显示采用：先全刷显示“底图”，再切换到局刷模式做交互更新（更快、更省时间）。
触摸芯片为 FT6336U：通过 I2C 读取触摸点坐标，使用 INT 引脚中断触发读取，再由主循环取出触摸点。
示例代码文件：
- main.py
- FT6336U.py

【硬件连接】

使用 USB 线把板子接入电脑，并用 Thonny 连接 MicroPython 解释器。

【代码分析】

EPD_1in54：墨水屏驱动 + FrameBuffer 绘图封装（main.py）
- 继承 framebuf.FrameBuffer：把 buffer 当作 200×200 单色画布使用，然后把 buffer 推到屏幕。
- send_command() / send_data()：通过 SPI 写命令/数据到屏幕控制器。
- ReadBusy()：轮询 BUSY 引脚等待屏幕空闲（墨水屏刷新期间必须等待）。
- displayPartBaseImage()：把“底图”写入两次缓冲区（0x24/0x26），用于后续局刷更稳定（减少残影的常见做法）。
- init(update)：两种刷新模式初始化
  - FULL_UPDATE：全刷，慢但干净
  - PART_UPDATE：局刷，快但可能有残影，需要底图配合
touch_ft6336u：FT6336U 触摸驱动（FT6336U.py）
- I2C 初始化（__init__）
  - machine.I2C(id=1, scl=Pin(7), sda=Pin(6), freq=400_000)：使用 I2C1，400kHz。
  - int = Pin(8, IN, PULL_UP)：触摸中断脚，下降沿触发回调。
  - rst = Pin(16, OUT)：复位脚，上电时按时序拉高/拉低复位芯片。
- init_chip()：初始化与读 ID
  - 读取寄存器 0xA3 获取 chip id，示例里期望 0x64，并打印 “init ok” 或 “ID error”。
- 中断读取触摸（int_cb / read_touch_data）
  - int_cb() 触发后调用 read_touch_data()，先读 TD_STATUS(0x02) 得到触摸点数，再读 TOUCH1_X(0x03) 起的 4 字节拼出 x/y。
  - 这里做的是“单点触摸”：只解析 Touch1。
- 主循环取点（get_touch_xy）
  - 有新点时返回 [{"x":..., "y":...}]，并把 point_count 清零，保证一次触摸只取一次（更像“事件”而不是连续坐标流）。
主程序流程（main.py）
- 初始化屏幕并清屏：epd = EPD_1in54()、epd.Clear(0xff)（0xff 表示白色）。
- 初始化触摸：touch = touch_ft6336u()，会在串口看到 FT6336U ID 相关输出。
- 绘制静态 UI：标题、分割线、4 个矩形按钮区域（Area A~D）、坐标显示区。
- 全刷显示底图：epd.displayPartBaseImage(epd.buffer)，然后 epd.init(epd.part_update) 切到局刷模式。
- 触摸消抖与轮询：
  - touch_debounce = 500：500ms 内只响应一次触摸，避免中断/抖动导致连发。
  - touch.get_touch_xy()：拿到一次触摸点后：
    - 更新屏幕下方坐标与区域名称
    - 对对应区域做“黑底白字”高亮
    - displayPartial() 局刷
    - 1 秒后恢复按钮原样，再局刷一次

【运行效果】

方式 A：通过 Thonny 直接运行运行 06_TOUCH 文件夹下的 py 文件。
- Thonny 选择正确的 MicroPython 解释器端口。
- 将 FT6336U.py 上传到设备内置 RP2350 的 MicroPython 文件系统根目录。
- 打开并运行 main.py。
- 串口/Thonny Shell 预期输出包含：
  - Initializing e-Paper...
  - Initializing touch screen...
  - FT6336U ID = 0x64、FT6336U init ok!
  - 触摸时打印：Touch detected: (x, y)
- 屏幕预期显示：
  - 顶部 “Touch Test”
  - 4 个区域按钮（Area A~D）
  - 下方实时更新 Touch: 区域名与 Pos: 坐标
方式 B：作为上电自启程序
- 将 main.py 与 FT6336U.py 上传到设备内置 RP2350 的 MicroPython 文件系统根目录。
- 复位后自动运行。

07_ES8311

【程序说明】

演示 RP2350 MicroPython 下驱动 ES8311 音频 Codec：通过 I2C 配置寄存器，通过 PIO 实现 I2S 音频数据收发，并用 PIO 输出 MCLK；固件支持 rp2.DMA 时可启用 DMA 加速。
参考示例默认参数（可在 main.py 中修改）：
- 采样率：24kHz（SAMPLE_FREQ = 24000，支持的采样率组合由 es8311.py 的 COEFF_DIV 表决定）
- 位宽：ADC 16bit（res_in=16）、DAC 16bit（res_out=16）
- 录音：单通道 int16（PIO RX 只采集一个 16-bit 通道，便于 DMA 对齐与稳定）
- 回放：可配置为单声道复制到双声道（示例默认 channel_count = 2）
示例代码文件：
- main.py：可直接运行的录音回放环回测试
- es8311.py：ES8311 I2C 寄存器驱动（时钟/格式/音量/静音/麦克风增益）
- audio_pio_mpy.py：PIO I2S + MCLK 输出（可选 DMA 接口）

【硬件连接】

使用 Type-C 线把产品接入电脑，并用 Thonny 连接 MicroPython 解释器即可进行测试与调试。

【代码分析】

es8311.py：ES8311 寄存器驱动（I2C）
- write_reg() / read_reg()：单寄存器写/读封装。
- COEFF_DIV + sample_frequency_config(mclk, rate)：按 MCLK 与采样率查表配置分频（示例 MCLK = SAMPLE_FREQ * 256）。
- fmt_config(res_in, res_out)：设置 I2S 数据位宽与工作模式（示例使用 I2S 格式，并打开相关模式位）。
- init(...)：芯片复位 -> 时钟配置 -> 格式配置 -> ADC/DAC 相关寄存器初始化 -> 设置音量与麦克风增益。
- volume_set()/volume_get()、mute()、microphone_gain_set()：常用控制接口。
audio_pio_mpy.py：PIO I2S 收发 + MCLK 输出（可选 DMA）
- mclk_pio()：极简方波输出，用 StateMachine 产生 MCLK。
- audio_pio_out()：等待 ES8311 输出的 LRCLK/BCLK，同步输出数据；每次 pull() 取一个 32-bit 帧（左 16bit + 右 16bit）。
- audio_pio_in()：等待 LRCLK/BCLK，同步采样输入数据；autopush=True, push_thresh=16，只采集一个 16-bit 通道并推入 RX FIFO。
- AudioPIO：
  - mclk_pio_init()/dout_pio_init()/din_pio_init()：初始化各 StateMachine 及引脚方向。
  - audio_in_into()：轮询从 RX FIFO 取样（带超时提示，便于定位 BCLK/LRCLK/DIN 连接问题）。
  - dma_record_into() / dma_play_from_i16()：固件支持 rp2.DMA 时使用 DMA 从/到 PIO FIFO 直接搬运，提高实时性并降低 CPU 占用。
main.py：录音回放环回示例
- 参数区：SAMPLE_FREQ、MCLK_FREQ、RECORD_DURATION_MS、DAC_VOLUME、MIC_GAIN、USE_DMA 等。
- init_hardware()：打开功放使能脚（PA_CTRL_PIN）并初始化 I2C。
- init_es8311()：读取 Chip ID，调用 codec.init(...)，解除静音。
- init_audio_pio()：配置 PIO 引脚与 StateMachine ID（默认 SM_DOUT_ID=0, SM_DIN_ID=5, SM_MCLK_ID=2）。
- 主循环：录音（DMA/非 DMA）-> 打印 min/max/clipped -> condition_mic_samples() 去直流与衰减 -> 回放（DMA/非 DMA）。

【运行效果】

通过 Thonny 运行
- 通过 thonny 将 07_ES8311 文件夹下的所有 py 文件上传到设备根目录。
- 在电脑上用 Thonny 打开 main.py，点击 Run 运行。
- 正常运行后，串口会打印 I2C 扫描结果、ES8311 Chip ID，以及每次环回的录音/回放统计信息（Cycle 计数、录音耗时、min/max、clipped 等）。
上传到设备运行
- 通过 thonny 将 07_ES8311 文件夹下的所有 py 文件上传到设备根目录。
- 将设备复位/重新上电，设备会自动执行根目录的 main.py（请确保 3 个文件都已上传：main.py、es8311.py、audio_pio_mpy.py）。
停止运行
- Thonny 点击 Stop（中断）按钮，或在 Shell/REPL 中按 Ctrl+C 结束循环并返回交互提示符。

文档反馈

MicroPython 入门教程​

配置开发环境​

示例程序​

01_SD​

02_RTC​

03_GUI​

04_KEY​

05_SHTC3​

06_TOUCH​

07_ES8311​

MicroPython 入门教程

配置开发环境

示例程序

01_SD

02_RTC

03_GUI

04_KEY

05_SHTC3

06_TOUCH

07_ES8311