MicroPython pyboard 快速参考指南：核心 API 实战速查与源码级解读

MicroPython pyboard 快速参考指南：核心 API 实战速查与源码级解读

【免费下载链接】micropythonMicroPython - a lean and efficient Python implementation for microcontrollers and constrained systems项目地址: https://gitcode.com/gh_mirrors/mi/micropython

本指南以 pyboard（PYBv1.1）为对象，系统梳理 MicroPython 在该开发板上的核心 API 用法：从 GPIO、LED、定时器到 UART/SPI/I2C/I2S/CAN 等外设，每个示例均可直接复制到 REPL 或main.py中运行，并结合当前仓库源码说明其底层实现与引脚映射，帮助开发者快速上手并深入理解 pyboard 的硬件控制模型。

引言：pyboard 与本文适用范围

pyboard 是 MicroPython 官方推出的 STM32 开发板，本文所对应的快速参考文档（docs/pyboard/quickref.rst）面向PYBv1.1硬件版本。该板基于 STM32F405RG 芯片，板载 4 个 LED、1 个用户按键、1 个三轴加速度计（MMA7660），并引出 X/Y 两排 GPIO 与多种外设总线。

从源码结构看，pyboard 的移植层位于 ports/stm32，板级定义见 ports/stm32/boards/PYBV11/mpconfigboard.h。文档中涉及的引脚名（如 X1、Y6）与板载资源映射，均可在该配置文件中找到对应的硬件定义，例如板名定义为"PYBv1.1"、MCU 为"STM32F405RG"，并启用了 RNG、RTC、Servo、DAC、USB、SD 卡等外设功能。

如果你是第一次接触该开发板，建议先阅读 docs/pyboard/general.rst（本地文件系统、启动模式、故障诊断等）与 docs/pyboard/tutorial/index.rst（入门教程），再回到本文进行 API 速查。

板级资源一览（PYBv1.1）

资源	说明	源码定义位置
MCU	STM32F405RG	ports/stm32/boards/PYBV11/mpconfigboard.h
4 个 LED	红(A13)/绿(A14)/黄(A15)/蓝(B4)	同上 L84-L92
用户按键 USRSW	B3，按下为低电平，内部上拉	同上 L78-L82
加速度计	MMA7660，AVDD 引脚 B5	同上 L104-L105
SD 卡	检测引脚 A8	同上 L94-L97
RTC	32kHz 外部晶振（LSE）	同上 L22-L25
I2C 总线	I2C1 命名为 "X"、I2C2 命名为 "Y"	同上 L47-L53
SPI 总线	SPI1 命名为 "X"、SPI2 命名为 "Y"	同上 L55-L65
CAN 总线	CAN1 命名为 "YA"、CAN2 命名为 "YB"	同上 L70-L76

需要说明的是：本文快速参考面向 PYBv1.1，其他版本（PYBv1.0、PYBLITEv1.0-AC、PYBLITEv1.0）的引脚图可在官方资源站点查看，本文不再列出外部链接。

通用板级控制

pyb模块提供对开发板整体的控制接口。以下代码演示了 REPL 串口重定向、低功耗等待与 CPU 频率操作：

import pyb pyb.repl_uart(pyb.UART(1, 9600)) # 将 REPL 复制到 UART(1) pyb.wfi() # 暂停 CPU，等待中断唤醒 pyb.freq() # 获取 CPU 与总线频率 pyb.freq(60000000) # 将 CPU 频率设置为 60MHz pyb.stop() # 停止 CPU，等待外部中断唤醒

从源码角度可以验证这些接口的实现：

• pyb.repl_uart()在 ports/stm32/modpyb.c 中实现，注释明确指出这是一个legacy 函数，推荐使用os.dupterm替代；它负责将 REPL 输出复制到指定的 UART 对象（uart_attach_to_repl）。
• pyb.wfi()在 ports/stm32/modpyb.c 中实现，对应machine.idle()；其底层通过执行 WFI（Wait For Interrupt）指令降低功耗，见 ports/stm32/modmachine.c 中的__WFI()调用。
• pyb.freq()与pyb.stop()属于 legacy 别名，分别映射到machine.freq与machine.stop（见 ports/stm32/modpyb.c 的模块表）。其中频率设置最终调用powerctrl_set_sysclk完成 PLL 重配置（ports/stm32/modmachine.c），非法频率会抛出ValueError。

提示：在旧版固件上pyb.freq()也可直接获取频率；设置频率时建议先查询当前值再修改，并注意 USB 等外设的时钟依赖。

延时与计时

使用标准库time即可实现延时与高精度计时：

import time time.sleep(1) # 休眠 1 秒 time.sleep_ms(500) # 休眠 500 毫秒 time.sleep_us(10) # 休眠 10 微秒 start = time.ticks_ms() # 获取毫秒计数器当前值 delta = time.ticks_diff(time.ticks_ms(), start) # 计算时间差

ticks_ms()返回的毫秒计数存在回绕，因此计算差值必须使用ticks_diff()而非直接相减；ticks_diff在 py/runtime.c 与 extmod/modtime.c 中有对应实现，它正确处理了有符号回绕语义。

内部 LED

板载 4 个 LED 通过pyb.LED控制，编号 1=红、2=绿、3=黄、4=蓝：

from pyb import LED led = LED(1) # 1=red, 2=green, 3=yellow, 4=blue led.toggle() led.on() led.off() # LED 3 和 4 支持 PWM 亮度调节（0-255） LED(4).intensity() # 获取亮度 LED(4).intensity(128) # 设置为一半亮度

从板级配置看，LED3 与 LED4 的 PWM 通道在 ports/stm32/boards/PYBV11/mpconfigboard.h 中定义为：

#define MICROPY_HW_LED1 (pin_A13) // red #define MICROPY_HW_LED2 (pin_A14) // green #define MICROPY_HW_LED3 (pin_A15) // yellow #define MICROPY_HW_LED4 (pin_B4) // blue #define MICROPY_HW_LED3_PWM { TIM2, 2, TIM_CHANNEL_1, GPIO_AF1_TIM2 } #define MICROPY_HW_LED4_PWM { TIM3, 3, TIM_CHANNEL_1, GPIO_AF2_TIM3 }

即 LED3 复用 TIM2 的通道 1，LED4 复用 TIM3 的通道 1，这正是intensity()能够调节亮度的硬件基础。实现细节可参考 ports/stm32/led.c（若需深入）。

内部用户按键

用户按键通过pyb.Switch读取，支持查询与中断回调两种模式：

from pyb import Switch sw = Switch() sw.value() # 返回 True 或 False sw.callback(lambda: pyb.LED(1).toggle())

该按键连接在 B3 引脚，配置为内部上拉、下降沿中断触发（见上文板级配置 L78-L82），因此value()在按下时返回False（低电平有效），代码中常见写法为not sw.value()判断按下。中断回调在按键事件触发时由底层 EXTI 机制调用。

引脚与 GPIO

X/Y 排针上的引脚可通过名称或Pin对象操作，支持输出、输入、上下拉等模式：

from pyb import Pin p_out = Pin('X1', Pin.OUT_PP) p_out.high() p_out.low() p_in = Pin('X2', Pin.IN, Pin.PULL_UP) p_in.value() # 获取电平，0 或 1

Pin的常用模式包括：

模式	含义
Pin.OUT_PP	推挽输出
Pin.OUT_OD	开漏输出
Pin.IN	输入
Pin.IN_PULL_UP/Pin.IN_PULL_DOWN	上拉/下拉输入
Pin.PULL_NONE/Pin.PULL_UP/Pin.PULL_DOWN	上下拉配置

完整的引脚能力（复用功能、模拟输入等）可查阅 docs/library/pyb.Pin.rst 与 docs/library/machine.Pin.rst。

舵机控制

pyb.Servo支持标准舵机与连续旋转舵机的控制：

from pyb import Servo s1 = Servo(1) # 舵机位于位置 1（X1, VIN, GND 三个引脚） s1.angle(45) # 转到 45 度 s1.angle(-60, 1500) # 在 1500ms 内转到 -60 度 s1.speed(50) # 用于连续旋转舵机

angle(deg, time)的第一参数为目标角度（范围约 -90 到 90），第二参数可选，指定过渡时间（毫秒）。角度信号由定时器 PWM 生成，板级配置中启用了MICROPY_HW_ENABLE_SERVO（ports/stm32/boards/PYBV11/mpconfigboard.h）。接线示意图与更多用法见 docs/pyboard/tutorial/servo.rst。

外部中断（ExtInt）

外部中断允许在引脚电平跳变时触发回调：

from pyb import Pin, ExtInt callback = lambda e: print("intr") ext = ExtInt(Pin('Y1'), ExtInt.IRQ_RISING, Pin.PULL_NONE, callback)

常用触发模式：

常量	触发条件
ExtInt.IRQ_RISING	上升沿
ExtInt.IRQ_FALLING	下降沿
ExtInt.IRQ_RISING_FALLING	双边沿

回调函数接收一个参数（触发事件），可用于打印日志或置位标志位。详细说明见 docs/library/pyb.ExtInt.rst。

定时器（Timer）

pyb.Timer提供硬件定时器，可配置频率与周期回调：

from pyb import Timer tim = Timer(1, freq=1000) tim.counter() # 获取计数器当前值 tim.freq(0.5) # 0.5 Hz tim.callback(lambda t: pyb.LED(1).toggle())

• Timer(id, freq=...)以指定频率创建定时器；
• counter()返回当前计数值；
• freq()可读取或重新设置频率；
• callback()注册周期中断回调，参数为定时器对象本身。

定时器还可与 PWM、输入捕获等模式结合使用（见下文 PWM 小节）。注意tim.callback(None)可取消回调。

RTC（实时时钟）

板载 RTC 基于 32kHz 外部晶振（LSE）运行，掉电后由后备电池维持（若硬件提供）：

from pyb import RTC rtc = RTC() rtc.datetime((2017, 8, 23, 0, 1, 12, 48, 0)) # 设置日期时间，如 2017/8/23 1:12:48 # 星期字段（第 4 个值，此处为 0）会被忽略 rtc.datetime() # 读取日期时间

datetime元组格式为(year, month, day, weekday, hours, minutes, seconds, subseconds)，其中 weekday（0-6）与 subseconds 在设置时被忽略。板级配置中MICROPY_HW_RTC_USE_LSE (1)表明使用外部低速晶振（ports/stm32/boards/PYBV11/mpconfigboard.h）。pyb.RTC的完整方法（含闹钟、唤醒）见 docs/library/pyb.RTC.rst。

PWM（脉冲宽度调制）

PWM 通过定时器通道输出，可精确控制占空比：

from pyb import Pin, Timer p = Pin('X1') # X1 复用 TIM2 的 CH1 tim = Timer(2, freq=1000) ch = tim.channel(1, Timer.PWM, pin=p) ch.pulse_width_percent(50)

• 引脚 X1 对应 TIM2 通道 1（配置见 ports/stm32/boards/PYBV11/mpconfigboard.h 中 SPI 与定时器复用定义，X1-X8 对应 SPI1 的 NSS/SCK/MISO/MOSI 所在引脚，其中 X1 即 PA0/A4 相邻区域，具体以官方引脚图为准）；
• tim.channel(channel, mode, pin=...)将定时器通道绑定到指定引脚；
• pulse_width_percent(0-100)以百分比设置占空比，也可用pulse_width()以微秒为单位设置脉冲宽度。

注意：不同引脚可复用的定时器/通道不同，使用时需对照引脚图选择匹配组合；同一定时器不同通道可输出多路同频 PWM。

ADC（模数转换）

板载 12 位 ADC，读取电压转换为 0-4095 的整数值：

from pyb import Pin, ADC adc = ADC(Pin('X19')) adc.read() # 读取值，范围 0-4095

• ADC(pin)以引脚创建 ADC 对象；
• read()返回 12 位采样值（0-4095），对应 0-3.3V 输入（参考电压由硬件决定）；
• 更精确的电压换算可乘以3.3 / 4095。

machine.ADC模块还提供 16 位过采样模式，见 docs/library/machine.ADC.rst 与 docs/library/pyb.ADC.rst。

DAC（数模转换）

板载 8 位 DAC，可将数字值转换为模拟电压输出：

from pyb import Pin, DAC dac = DAC(Pin('X5')) dac.write(120) # 输出值介于 0 和 255 之间

• DAC(pin)创建 DAC 对象（仅特定引脚支持，如 X5）；
• write(value)输出 0-255 对应的电压（0V 到参考电压）；
• 还可使用write_timed()配合定时器输出波形，见 docs/library/pyb.DAC.rst。

板级配置中MICROPY_HW_ENABLE_DAC (1)（ports/stm32/boards/PYBV11/mpconfigboard.h）表明该功能已启用。

UART 串口通信

pyb.UART提供异步串口通信：

from pyb import UART uart = UART(1, 9600) uart.write('hello') uart.read(5) # 读取最多 5 字节

• UART(id, baudrate)创建串口对象，pyboard 上常见串口编号为 1、2、3、4、6；
• write()发送字节串；
• read(n)阻塞读取最多 n 字节（可返回少于 n 字节），readline()读取一行，any()查询接收缓冲区是否有数据。

板级配置中 UART1 命名为 "XB"、UART2 无命名、UART3 命名为 "YB"、UART4 命名为 "XA"、UART6 命名为 "YA"（ports/stm32/boards/PYBV11/mpconfigboard.h），这些命名对应板上的 XA/XB/YA/YB 串口引脚组合。pyb.repl_uart(pyb.UART(1, 9600))可将 REPL 复制到 UART1（见前文）。详细方法见 docs/library/pyb.UART.rst。

SPI 总线

pyb.SPI提供主机（Controller）模式 SPI 通信：

from pyb import SPI spi = SPI(1, SPI.CONTROLLER, baudrate=200000, polarity=1, phase=0) spi.send('hello') spi.recv(5) # 在总线上接收 5 字节 spi.send_recv('hello') # 发送并接收 5 字节

• 参数含义：baudrate波特率、polarity时钟极性（0/1）、phase时钟相位（0/1），二者组合定义 SPI 模式（CPOL/CPHA）；
• send()/recv()/send_recv()分别对应发送、接收、全双工收发。

板级配置中 SPI1 命名为 "X"（对应 X5=X8 引脚），SPI2 命名为 "Y"（对应 Y5=Y8 引脚）（ports/stm32/boards/PYBV11/mpconfigboard.h）。注意 I2S 与 SPI 共享引脚资源。machine.SPI提供更通用的接口，见 docs/library/machine.SPI.rst。

I2C 总线

pyboard 同时支持硬件 I2C 与软件 I2C：

from machine import I2C i2c = I2C('X', freq=400000) # 创建硬件 I2C 对象（X 半区） i2c = I2C(scl='X1', sda='X2', freq=100000) # 创建软件 I2C 对象（指定引脚） i2c.scan() # 返回总线上从设备地址列表 i2c.writeto(0x42, 'hello') # 向地址 0x42 的从设备写入 5 字节 i2c.readfrom(0x42, 5) # 从地址 0x42 的从设备读取 5 字节 i2c.readfrom_mem(0x42, 0x10, 2) # 从从设备 0x42 的内存地址 0x10 读取 2 字节 i2c.writeto_mem(0x42, 0x10, 'xy') # 向从设备 0x42 的内存地址 0x10 写入 2 字节

• 硬件 I2C 可通过总线名I2C('X')/I2C('Y')或外设整数编号I2C(1)创建；板级配置中 I2C1 命名为 "X"（SCL=B6, SDA=B7），I2C2 命名为 "Y"（SCL=B10, SDA=B11），见 ports/stm32/boards/PYBV11/mpconfigboard.h；
• 软件 I2C 通过显式指定scl与sda引脚创建，可自由选择任意 GPIO；
• scan()返回检测到的从设备地址列表，常用于总线调试；
• readfrom_mem/writeto_mem用于带寄存器地址的器件读写（如传感器、EEPROM）。

兼容性说明：旧版pyb.I2C仍可使用，但新项目推荐使用machine.I2C，其完整 API 见 docs/library/machine.I2C.rst。

I2S 总线（音频）

I2S 用于数字音频传输，支持发送（TX）与接收（RX）模式：

from machine import I2S, Pin # 发送模式：播放音频 i2s = I2S(2, sck=Pin('Y6'), ws=Pin('Y5'), sd=Pin('Y8'), mode=I2S.TX, bits=16, format=I2S.STEREO, rate=44100, ibuf=40000) i2s.write(buf) # 将音频采样缓冲区写入 I2S 设备 # 接收模式：录制音频 i2s = I2S(1, sck=Pin('X5'), ws=Pin('X6'), sd=Pin('Y4'), mode=I2S.RX, bits=16, format=I2S.MONO, rate=22050, ibuf=40000) i2s.readinto(buf) # 从 I2S 设备填充音频采样缓冲区

参数说明：

参数	含义
id	I2S 外设编号（PYBv1.0/v1.1 只有一个 I2S 总线，id=2；PYBD-SFxW 有两个，id=1 和 id=2）
sck/ws/sd	位时钟、左右声道时钟（字选择）、数据引脚
mode	I2S.TX或I2S.RX
bits	采样位深（如 16）
format	I2S.STEREO或I2S.MONO
rate	采样率（Hz），如 44100
ibuf	内部缓冲区字节数

重要提示：I2S 类当前为Technical Preview（技术预览）状态。预览期间欢迎用户反馈，基于反馈 API 与实现可能会调整。此外，I2S 与 SPI 共享引脚，使用时需避免冲突；板级配置中MICROPY_HW_I2S2 (1)（ports/stm32/boards/PYBV11/mpconfigboard.h）确认 PYBv1.1 启用 id=2 的 I2S。详细说明见 docs/library/machine.I2S.rst。

CAN 总线

pyboard 支持 CAN 总线通信，可用于车载/工业现场总线场景：

from pyb import CAN can = CAN(1, CAN.LOOPBACK) can.setfilter(0, CAN.LIST16, 0, (123, 124, 125, 126)) can.send('message!', 123) # 发送 ID 为 123 的消息 can.recv(0) # 在 FIFO 0 上接收消息

• CAN(id, mode)：CAN.NORMAL正常模式、CAN.LOOPBACK回环模式（自发自收，便于测试）；
• setfilter(bank, mode, fifo, params)：配置接收过滤器，CAN.LIST16表示 16 位 ID 列表模式；
• send(data, id)发送消息，recv(fifo)从指定 FIFO 接收。

板级配置中 CAN1 命名为 "YA"（TX=B9/Y4, RX=B8/Y3），CAN2 命名为 "YB"（TX=B13/Y6, RX=B12/Y5），见 ports/stm32/boards/PYBV11/mpconfigboard.h。完整方法见 docs/library/pyb.CAN.rst。

板载加速度计

板载 MMA7660 三轴加速度计可通过pyb.Accel读取：

from pyb import Accel accel = Accel() print(accel.x(), accel.y(), accel.z(), accel.tilt())

• x()/y()/z()返回三轴加速度读数；
• tilt()返回倾斜方向（0-7，对应 8 个方向之一）。

板级配置中MICROPY_HW_HAS_MMA7660 (1)（ports/stm32/boards/PYBV11/mpconfigboard.h）与 MMA 的 AVDD 供电引脚 B5（同上 L104-L105）定义了该外设；启动流程中也会调用accel_init()完成初始化（ports/stm32/main.c）。教程示例见 docs/pyboard/tutorial/accel.rst。

实战：将各模块组合为一个小程序

将上述 API 组合，可以快速验证板载外设是否工作正常。以下脚本将每秒读取加速度计并闪烁 LED：

import time from pyb import LED, Accel led = LED(1) accel = Accel() while True: x, y, z = accel.x(), accel.y(), accel.z() print("accel: x=%d y=%d z=%d" % (x, y, z)) led.toggle() time.sleep_ms(1000)

将脚本保存为main.py放入 pyboard 的 USB 闪存盘，复位后即可自动运行（参见 docs/pyboard/general.rst 中关于 boot 文件系统的说明）。

深入阅读

• docs/pyboard/general.rst：本地文件系统（/flash、/sd、SKIPSD）、启动模式、LED 故障指示；
• docs/pyboard/tutorial/index.rst：面向初学者的分步教程；
• docs/library/index.rst：pyb与machine模块完整 API 文档；
• ports/stm32/boards/PYBV11/mpconfigboard.h：PYBv1.1 板级硬件映射源码；
• ports/stm32/main.c：启动流程、文件系统挂载与 boot 序列源码。

【免费下载链接】micropythonMicroPython - a lean and efficient Python implementation for microcontrollers and constrained systems项目地址: https://gitcode.com/gh_mirrors/mi/micropython