MicroPython pyb.LED 类完全指南:从开关控制到 PWM 亮度调节的源码级解析
MicroPython pyb.LED 类完全指南:从开关控制到 PWM 亮度调节的源码级解析
导读
pyb.LED 是 MicroPython 在 STM32(pyboard)移植版中提供的 LED 控制对象,用于驱动开发板上的单个发光二极管(Light Emitting Diode)。本指南以 pyb.LED 官方文档 为骨架,结合 ports/stm32/led.c 的实现与 tests/ports/stm32/led.py 的测试用例,完整讲解 LED 对象的构造方式、on/off/toggle/intensity 四大方法的语义,以及背后基于定时器 PWM 实现平滑亮度调节的底层原理。读完本文,你将能在 pyboard 及其兼容开发板上熟练控制板载 LED,实现闪烁、呼吸灯、状态指示等实战效果,并理解如何通过板级配置宏为任意 STM32 开发板启用 LED PWM 功能。
LED 对象概述
pyb.LED 类位于 pyb 模块中,文档定义如下:
The LED object controls an individual LED (Light Emitting Diode).
即"LED 对象控制单个发光二极管"。它是 MicroPython pyb 模块在 STM32 移植版(ports/stm32)中提供的一等公民对象,与 pyb.Pin、pyb.Timer 等对象平级。注意它并非通用的 machine 模块对象,而是 pyb 专有类,因此仅在 pyboard 系列(PYBv1.x、PYBLITEv1.x、PYBD 系列)等 STM32 移植板上可用。
从源码看,LED 对象在 C 层被定义为:
typedef struct _pyb_led_obj_t {
mp_obj_base_t base;
mp_uint_t led_id;
const machine_pin_obj_t *led_pin;
} pyb_led_obj_t;
见 ports/stm32/led.c。每个 LED 对象持有两个关键字段:LED 编号 led_id 和它绑定的 GPIO 引脚对象 led_pin,其中引脚在板级配置中静态确定,运行时不可更改。
构造函数:LED(id)
from pyb import LED
led = LED(1) # 1=red, 2=green, 3=yellow, 4=blue
构造语法为 LED(id),其中 id 是 LED 编号,取值范围 1-4(pyboard 标准四色 LED)。构造函数的行为在 ports/stm32/led.c 中实现:
- 必须恰好传入 1 个位置参数(
mp_arg_check_num(n_args, n_kw, 1, 1, false)),否则抛TypeError; - 若
id超出当前板卡实际定义的 LED 数量(NUM_LEDS),抛出ValueError,错误信息为LED(%d) doesn't exist; - 合法时直接返回一个静态预分配对象(
&pyb_led_obj[led_id - 1]),不分配堆内存,因此创建 LED 对象成本极低,可放心反复调用。
值得注意的实现细节:对象是静态数组而非动态分配,数组元素在编译期由板级宏展开而来:
static const pyb_led_obj_t pyb_led_obj[] = {
{{&pyb_led_type}, 1, MICROPY_HW_LED1},
#if defined(MICROPY_HW_LED2)
{{&pyb_led_type}, 2, MICROPY_HW_LED2},
...
};
见 ports/stm32/led.c。也就是说,板卡上有几个 LED 就编译几个对象;NUM_LEDS 由宏数组长度计算得出。如果某个板卡一个 LED 都没有(未定义 MICROPY_HW_LED1),led_init、led_state、led_toggle 都会被编译为空函数(见 led.c),此时调用 LED(id) 会得到 "doesn't exist" 的 ValueError。
板级 LED 编号与引脚映射
LED 编号与引脚、颜色的对应关系在板级配置头文件中定义。以经典 pyboard(PYBV11)为例,见 ports/stm32/boards/PYBV11/mpconfigboard.h:
// The pyboard has 4 LEDs
#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 }
#define MICROPY_HW_LED_ON(pin) (mp_hal_pin_high(pin))
#define MICROPY_HW_LED_OFF(pin) (mp_hal_pin_low(pin))
对应的命名引脚在 ports/stm32/boards/PYBV11/pins.csv 中登记:
LED_RED,PA13
LED_GREEN,PA14
LED_YELLOW,PA15
LED_BLUE,PB4
可见编号 1-4 依次对应红、绿、黄、蓝四色 LED,其中 LED3(黄)与 LED4(蓝)额外定义了 PWM 配置宏。而像 NUCLEO-F411RE 这类仅有一颗板载 LED 的板卡,只需定义 MICROPY_HW_LED1(见 ports/stm32/boards/NUCLEO_F411RE/mpconfigboard.h):
// LEDs
#define MICROPY_HW_LED1 (pin_A5) // Green LD2 LED on Nucleo
#define MICROPY_HW_LED_ON(pin) (mp_hal_pin_high(pin))
#define MICROPY_HW_LED_OFF(pin) (mp_hal_pin_low(pin))
极性与初始化
默认 LED 为高电平点亮(不反相),可通过 MICROPY_HW_LED_INVERTED 宏反转极性:
#ifndef MICROPY_HW_LED_INVERTED
#define MICROPY_HW_LED_INVERTED (0)
#endif
见 ports/stm32/led.c。在系统启动阶段,led_init() 会遍历所有 LED,使能 GPIO 时钟、将引脚配置为输出并先全部关闭(见 led.c),保证上电后 LED 处于确定状态。
方法详解
pyb.LED 共提供 4 个方法:on()、off()、toggle() 和 intensity(<a href="https://link.gitcode.com/i/32fa750d5ab4fbcb3b287253ae1b5029" target="_blank">value])。它们的方法表在 [led.c 中注册:
static const mp_rom_map_elem_t led_locals_dict_table[] = {
{ MP_ROM_QSTR(MP_QSTR_on), MP_ROM_PTR(&led_obj_on_obj) },
{ MP_ROM_QSTR(MP_QSTR_off), MP_ROM_PTR(&led_obj_off_obj) },
{ MP_ROM_QSTR(MP_QSTR_toggle), MP_ROM_PTR(&led_obj_toggle_obj) },
{ MP_ROM_QSTR(MP_QSTR_intensity), MP_ROM_PTR(&led_obj_intensity_obj) },
};
LED.on() —— 打开
将 LED 打开至最大亮度。C 实现为 led_state(self->led_id, 1)(见 led.c),即把对应引脚置为点亮电平(MICROPY_HW_LED_ON)。若此前 LED 正以 PWM 非满亮度运行,led_state 内部会先调用 led_pwm_deinit 撤销 PWM 配置,把引脚还原为普通 GPIO 输出后再点亮(见 led.c)。
LED.off() —— 关闭
将 LED 关闭。对应 led_state(self->led_id, 0)(见 led.c),与 on() 同样会先清理可能存在的 PWM 状态。
LED.toggle() —— 翻转
在"开(最大亮度)"与"关"之间切换。其实现(led.c)有一个关键语义:
- 若 LED 当前正以 PWM 运行(即亮度为非零但非满值),则直接视为"开着",
toggle()将其关闭; - 否则直接翻转 GPIO 输出数据寄存器:
led_pin->gpio->ODR ^= led_pin->pin_mask。
注意这里的"翻转"是直接对寄存器做异或操作,不经过 led_state,因此速度极快,适合在中断回调中频繁调用。同时,翻转操作是有状态持久的:连续两次 toggle() 必然恢复原状。
LED.intensity([value]) —— 读取/设置亮度
这是 LED 对象功能最丰富的接口,语义如下(led.c):
intensity():无参数调用时返回当前亮度值,范围 0(灭)到 255(全亮);intensity(value):传入参数时设置亮度并返回None。
亮度值的读写由 led_get_intensity / led_set_intensity 实现(led.c)。其取值逻辑遵循一套"降级"规则:
| 传入亮度 | 行为 |
|---|---|
0 |
直接关闭 LED(GPIO 低电平/反相时高电平) |
1 ~ 254 |
若该 LED 配置了 PWM,则启动定时器 PWM 并写入对应占空比;未配置 PWM 的 LED 退化为"点亮" |
255 |
满亮度,等同 on() |
从 led.c 可以看出,led_set_intensity 只在 intensity > 0 && intensity < 255 时尝试走 PWM 路径;若 pwm_cfg->tim == NULL(该 LED 未配置 PWM 宏),则退化为 led_state(led, intensity > 0),即只能开关不能调光。
定时器 PWM 与 Timer(2)/Timer(3)
文档明确指出:
Only LED(3) and LED(4) can have a smoothly varying intensity, and they use timer PWM to implement it. LED(3) uses Timer(2) and LED(4) uses Timer(3).
即在标准 pyboard 上,只有 LED(3) 和 LED(4) 支持平滑亮度调节,分别使用 Timer(2) 和 Timer(3) 实现 PWM。这一映射来自板级宏:
MICROPY_HW_LED3_PWM { TIM2, 2, TIM_CHANNEL_1, GPIO_AF1_TIM2 }—— LED3 用 TIM2 通道 1;MICROPY_HW_LED4_PWM { TIM3, 3, TIM_CHANNEL_1, GPIO_AF2_TIM3 }—— LED4 用 TIM3 通道 1。
(见 ports/stm32/boards/PYBV11/mpconfigboard.h。)该四元组结构体的含义在 led.c 中定义:
typedef struct _led_pwm_config_t {
TIM_TypeDef *tim; // 定时器外设基址
uint8_t tim_id; // 定时器编号(1/2/3)
uint8_t tim_channel; // TIM 通道(CH1-CH4)
uint8_t alt_func; // 引脚的复用功能编号
} led_pwm_config_t;
这些定时器并非被 LED 独占。文档强调:
These timers are only configured for PWM if the intensity of the relevant LED is set to a value between 1 and 254. Otherwise the timers are free for general purpose use.
即只有当对应 LED 的亮度被设置为 1~254 之间的值时,定时器才被配置为 PWM 模式;其余时间定时器完全空闲,可供 pyb.Timer 通用用途使用。源码用 led_pwm_state 位图记录哪些 LED 正在使用 PWM(led.c):
led_pwm_init(led):按需配置引脚为复用功能、使能定时器时钟(__TIM1_CLK_ENABLE/__TIM2_CLK_ENABLE/__TIM3_CLK_ENABLE)、初始化 PWM 并启动,随后置位led_pwm_state(led.c);led_pwm_deinit(led):把引脚恢复为普通 GPIO 输出模式并清除状态位(led.c)。
PWM 计数周期 LED_PWM_TIM_PERIOD 为 10000,定时器预分频被配置为让 TIM 以 1MHz 运行、每 10ms 触发一次(led.c):
#define LED_PWM_TIM_PERIOD (10000) // TIM runs at 1MHz and fires every 10ms
亮度 0~255 与占空比的换算在写回 CCR 比较寄存器时完成:CCR = intensity * (LED_PWM_TIM_PERIOD - 1) / 255(led.c);读取时则做反向换算并做 255 上限钳制(led.c)。
另外需要说明:PWM 能力不是 pyboard 独占的。这是 led.c 中一段"半通用"代码(见 led.c 的注释),支持 TIM1/TIM2/TIM3 及通道 1-4。只要板级配置定义 MICROPY_HW_LEDx_PWM 宏即可启用。例如 ports/stm32/boards/PYBV3/mpconfigboard.h 中 LED1/LED2 也配了 PWM,ports/stm32/boards/NUCLEO_F412ZG/mpconfigboard.h 则用 TIM1/TIM4/TIM12 驱动三颗 LED。若板卡未定义任何 MICROPY_HW_LEDx_PWM 宏,LED_PWM_ENABLED 编译为 0,intensity() 便退化为纯开关语义。
实测验证:官方测试用例
仓库自带硬件测试脚本 tests/ports/stm32/led.py,它在真实 pyboard 上逐项验证了上述语义,可作为理解各方法行为的权威参考:
import os, pyb
machine = os.uname().machine
if "PYBv1." in machine or "PYBLITEv1." in machine:
leds = [pyb.LED(i) for i in range(1, 5)]
pwm_leds = leds[2:] # LED(3)、LED(4) 支持 PWM
elif "PYBD" in machine:
leds = [pyb.LED(i) for i in range(1, 4)]
pwm_leds = []
else:
print("SKIP")
raise SystemExit
# test printing
for i in range(3):
print(leds[i])
# test on and off
for l in leds:
l.on()
assert l.intensity() == 255 # on() 后亮度必为 255
pyb.delay(100)
l.off()
assert l.intensity() == 0 # off() 后亮度必为 0
pyb.delay(100)
# test toggle
for l in 2 * leds:
l.toggle()
assert l.intensity() in (0, 255)
pyb.delay(100)
# test intensity
for l in pwm_leds:
for i in range(256):
l.intensity(i)
assert l.intensity() == i # 亮度读写必须严格一致
pyb.delay(1)
for i in range(255, -1, -1):
l.intensity(i)
assert l.intensity() == i
pyb.delay(1)
该测试揭示了几条重要的可验证事实:
on()后intensity()必然返回 255,off()后必然返回 0,与"on 为最大亮度"的文档语义一致;toggle()后亮度必为 0 或 255,说明 toggle 不会产生中间亮度;- 支持 PWM 的 LED 其
intensity()读写必须严格往返一致(intensity(i)后intensity()必须等于i),这正是 PWM 亮度平滑性的直接证据; - 打印 LED 对象的输出为
LED(1)、LED(2)、LED(3)(对应期望文件 tests/ports/stm32/led.py.exp),由 led.c 的led_obj_print实现。
此外,PYBD 系列只有 3 颗 LED 且无 PWM(pwm_leds = []),说明 LED 数量与 PWM 支持完全取决于板级硬件配置。
实战示例
1. 基本开关与闪烁
from pyb import LED
import pyb
red = LED(1) # 红灯
red.on()
pyb.delay(500)
red.off()
# 闪 5 次
for _ in range(5):
red.toggle()
pyb.delay(200)
2. 平滑呼吸灯(仅限 LED(3)/LED(4))
from pyb import LED
import pyb
yellow = LED(3) # 黄色,支持 PWM
while True:
for i in range(256): # 渐亮
yellow.intensity(i)
pyb.delay(5)
for i in range(255, -1, -1): # 渐灭
yellow.intensity(i)
pyb.delay(5)
这段代码与官方测试的亮度扫描逻辑一致,intensity(i) 在 1~254 区间内会动态配置 Timer(2) 的 PWM 输出。
3. 读取当前亮度
from pyb import LED
led = LED(4)
led.intensity(128) # 设置为半亮
print(led.intensity()) # 输出 128
4. 与中断回调联动
在 docs/pyboard/quickref.rst 中还能看到 LED 与 pyb.Switch、pyb.Timer 回调组合的惯用写法:
sw = pyb.Switch()
sw.callback(lambda: pyb.LED(1).toggle()) # 按用户键翻转红灯
tim = pyb.Timer(4, freq=2)
tim.callback(lambda t: pyb.LED(1).toggle()) # 以 2Hz 定时翻转红灯
由于 toggle() 直接操作 ODR 寄存器、开销极小,非常适合放在回调上下文(包括中断上下文)中使用。
使用注意事项
LED(id)的id必须是 1~4 之间的整数,且不能超过板卡实际 LED 数量,否则抛ValueError: LED(x) doesn't exist;- 只有配置了 PWM 宏的 LED 才能平滑调光。标准 pyboard 上是 LED(3)、LED(4)(分别占用 Timer(2)、Timer(3)),其它板卡请查阅各自 ports/stm32/boards 下的
mpconfigboard.h; - 定时器是按需配置的:亮度设为 1~254 时占用定时器,
on()/off()/toggle()或亮度设为 0/255 后会释放定时器,可放心与pyb.Timer复用; intensity()设置亮度时返回None,只有无参数调用才返回亮度值;- 本对象为
pyb模块专有,仅适用于 STM32/pyboard 移植版;其它移植板请使用各自的machine.Pin方案(如 rp2、esp32 等端口没有pyb.LED)。
总结
pyb.LED 是一个设计精巧的板级外设对象:对象静态预分配、开关操作直达寄存器、PWM 亮度按需启用定时器、关闭即释放外设资源。通过本文对照 docs/library/pyb.LED.rst 文档、ports/stm32/led.c 实现与 tests/ports/stm32/led.py 测试,你既能熟练使用 on/off/toggle/intensity 完成 LED 控制,也能理解其底层 GPIO 与定时器 PWM 的协作机制,进而能够为自定义 STM32 板卡在 mpconfigboard.h 中配置 LED 引脚与 PWM 定时器通道,扩展出属于自己的亮度控制能力。