MicroPython pyb.LED 类完全指南:从开关控制到 PWM 亮度调节的源码级解析

原创2026-09-19 16:10:521,395 阅读
文章标签:编程语言语言运行时解释器标准库编译器嵌入式物联网固件驱动开发内存管理

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)

该测试揭示了几条重要的可验证事实:

  1. on() 后 intensity() 必然返回 255,off() 后必然返回 0,与"on 为最大亮度"的文档语义一致;
  2. toggle() 后亮度必为 0 或 255,说明 toggle 不会产生中间亮度;
  3. 支持 PWM 的 LED 其 intensity() 读写必须严格往返一致(intensity(i) 后 intensity() 必须等于 i),这正是 PWM 亮度平滑性的直接证据;
  4. 打印 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 定时器通道,扩展出属于自己的亮度控制能力。

登录后查看全文
micropython