WS2812 LED 控制(neopixel)
萤火虫T1 通过顶部 5P-PIN 拓展接口驱动 WS2812 / WS2812B 炫彩灯带:数据线接 PIN5(GPIO13),5V 电由 PIN1 提供、靠 GPIO43 控制一个 P-MOS 开关。固件里同时提供了两套驱动——通用的 neopixel 库,以及内置的 ws2812 C 模块(官方光绘应用用的就是后者)。
对应顶部 5P-PIN 的 PIN5,直连 MCU,不需要额外器件。
pm.VCC_OUTPUT + GPIO43 拉低 + 数据线接好,缺一个灯带就是全黑。
neopixel 简单通用;ws2812 走 RMT,刷整条/整帧更快。
硬件与引脚
| 项目 | 值 |
|---|---|
| 灯珠类型 | WS2812 / WS2812B(5V 供电,单线 800 kHz 时序) |
| 数据引脚 | GPIO13(顶部 5P-PIN 的 PIN5) |
| 电源控制 | GPIO43 驱动 P-MOS:value(0) 低电平接通,value(1) 高阻态关断 |
| 5V 来源 | 顶部 5P-PIN 的 PIN1,输出电压由 电源管理(pm) 的 VCC 决定 |
| 灯珠数量 | 官方应用按 480 颗预留上限 |
| 数据排列 | 灯珠时序是 GRB;ws2812 的缓冲区按 B、G、R 排列 |
| 可用驱动 | neopixel(标准库,已冻结进固件)、ws2812(内置 C 模块,固定 GPIO13 + RMT 通道 0) |
接线与接口定义详见 拓展接口。
快速开始
灯带要亮,供电和数据必须同时到位:
import pm
pm.init()
pm.set_power_state(pm.VCC_OUTPUT) # 让 VCC 输出 5V(启动器的 poll 线程会在一秒内生效)
from machine import Pin
enable_pin = Pin(43, Pin.OPEN_DRAIN)
enable_pin.value(0) # 低电平导通 P-MOS,5V 出现在 PIN1 上
import neopixel
np = neopixel.NeoPixel(Pin(13), 60) # 数据脚 GPIO13,60 颗灯珠
np[0] = (255, 0, 0) # 第 0 颗:红
np[1] = (0, 255, 0) # 第 1 颗:绿
np[2] = (0, 0, 255) # 第 2 颗:蓝
np.write() # 必须调用,颜色才会真正发出去
运行现象:前 3 颗灯珠分别亮红、绿、蓝,其余保持熄灭。如果不调用 np.write(),灯珠不会有任何反应——改颜色只是改了内存里的缓冲区。
独立运行(自己写的 main.py,或直接在 REPL 里跑)时,还要周期性调用 pm.poll(),否则 set_power_state() 不生效,详见 电源管理(pm)。
两套驱动怎么选
neopixel | ws2812(固件内置) | |
|---|---|---|
| 实现方式 | 标准 MicroPython 驱动,纯 Python + machine.bitstream | C 模块,走 ESP32 的 RMT 外设 |
| 数据引脚 | 自己传,如 Pin(13) | 固定 GPIO13,不用传 |
| 设置颜色 | np[i] = (R, G, B) 元组 | 自己维护 bytearray,按 B、G、R 排列 |
| 自带亮度 | 无,要自己缩放 RGB | play_rgb_buffer() 有 brightness 参数 |
| 更新方式 | 可以只改一颗灯珠再 write() | 只能整段刷新(一次发 length 字节) |
| 适合场景 | 少量灯珠、逐颗改色、代码最简单 | 大量灯珠、整体刷帧(官方光绘应用每秒刷一整幅图) |
| 生命周期 | 构造出来就能用 | 需要 init() / deinit() 配对 |
建议:先用 neopixel 把效果跑通;等灯珠数量多、帧率不够时,再换成 ws2812。
API 参考
neopixel
构造 NeoPixel()
np = neopixel.NeoPixel(pin, n, bpp=3, timing=1)
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
pin | Pin | 必填 | 数据脚,用 Pin(13) |
n | int | 必填 | 灯珠数量 |
bpp | int | 3 | 每颗灯珠字节数,WS2812 固定为 3 |
timing | int | 1 | 1 = 800 kHz(WS2812B 标准),0 = 400 kHz |
构造时会立刻把该引脚设为输出,并分配 n × bpp 字节的缓冲区。n 填得和实际灯珠数一致最稳妥:填少了,后面没被覆盖的灯珠会保持上一次的颜色;填多一个上限值(如官方应用的 480)也不会出错,只是末尾那段数据白发了。
设置颜色 np[i]
np[0] = (255, 0, 0)
| 项 | 类型 | 取值 |
|---|---|---|
下标 i | int | 0 ~ len(np) - 1,越界抛 IndexError |
| 值 | tuple / list | (R, G, B),每个分量 0 ~ 255 |
np[i] 也能读回来,返回的就是你写进去的 (R, G, B) 元组。
批量填充 np.fill()
np.fill((255, 0, 0)) # 整条灯带设成同一个颜色
只接受一个元组参数。写成 np.fill(255, 0, 0) 会抛 TypeError。
输出 np.write()
np.write()
把缓冲区按 800 kHz 时序发到灯带,阻塞到发完为止。每颗灯珠约 30 微秒,60 颗约 1.8 毫秒、480 颗约 14 毫秒。
灯珠数量 len(np)
for i in range(len(np)):
np[i] = ...
ws2812(固件内置)
只提供「整段刷新」的接口,配合 RMT 硬件,适合刷整条灯带或整帧画面。
初始化 ws2812.init()
ws2812.init()
无参数。固定使用 GPIO13 与 RMT 通道 0,并把 GPIO13 配置为 RMT 输出。
一次程序里只调用一次。 未 deinit() 时重复调用会因 RMT 通道已被占用触发断言、设备重启。
发送 RGB888 数据 ws2812.play_rgb_buffer()
ws2812.play_rgb_buffer(buffer, length, brightness)
| 参数 | 类型 | 说明 |
|---|---|---|
buffer | bytearray | RGB888 数据,每颗灯珠 3 字节,按 B、G、R 排列 |
length | int | 本次发送的字节数,应为 3 的倍数;超过 buffer 长度抛 ValueError: Buffer length mismatch |
brightness | float | 0.0 ~ 1.0;超出范围抛 ValueError: Brightness must be between 0.0 and 1.0 |
无返回值。它会做三件事:
- 把每个分量乘以
brightness做整体调暗(brightness=0即全黑); - 重排成灯珠需要的 GRB 顺序,按 800 kHz 时序发出;
- 阻塞到全部发完(每颗灯珠约 30 微秒,480 颗约 14 毫秒)。
不传引脚、也不传灯珠数——灯珠数由 length ÷ 3 决定,所以同一个缓冲区可以只发前面一段,官方光绘应用正是按图片的每一行逐步发送的。
进度字符串 ws2812.calculate_percentage()
text = ws2812.calculate_percentage(20, 48, 13) # → "41% 13s"
三个 int(分子、分母、秒数),返回 "百分比% 秒数s" 形式的字符串。这是官方应用用来在屏幕上显示进度的小工具;denominator 为 0 时抛 ValueError。
释放资源 ws2812.deinit()
ws2812.deinit()
释放 RMT 通道。退出应用前调用,否则下次 init() 会重启设备。
颜色与字节顺序
两套驱动的颜色顺序不一样,这是换驱动时最容易踩的坑:
| 想要的颜色 | neopixel(元组,R/G/B) | ws2812 的缓冲区(字节,B/G/R) |
|---|---|---|
| 红 | np[i] = (255, 0, 0) | bytearray([0, 0, 255]) |
| 绿 | np[i] = (0, 255, 0) | bytearray([0, 255, 0]) |
| 蓝 | np[i] = (0, 0, 255) | bytearray([255, 0, 0]) |
| 白 | np[i] = (255, 255, 255) | bytearray([255, 255, 255]) |
neopixel用直觉顺序(R, G, B),驱动内部会帮你换成灯珠要的 GRB。ws2812的缓冲区是B、G、R,和 BMP 图片文件的字节排列一致——所以官方应用才能把 BMP 数据直接读进缓冲区发出去。写成 R、G、B 的典型症状就是红蓝对调。
常见坑点
- 忘了
np.write()。 改颜色只是改内存缓冲区,不调用write()灯珠不会有任何变化。 - 灯不亮先查供电三件事:
pm.set_power_state(pm.VCC_OUTPUT)、enable_pin.value(0)、数据线接在 PIN5(GPIO13)。 GPIO43的两种状态容易记反:value(0)才是接通(低电平导通 P-MOS),value(1)是高阻态、关断。启动器浏览应用列表时就处于关断状态。ws2812的缓冲区顺序是 B、G、R,不是 R、G、B。- RGB 分量必须在
0~255之间,写256会抛ValueError;下标越界抛IndexError。 np.fill()只接受一个元组:np.fill((255, 0, 0))。ws2812.init()与ws2812.deinit()必须配对。init()内部是ESP_ERROR_CHECK断言,重复初始化会直接重启设备。write()与play_rgb_buffer()都是阻塞的。 灯珠越多耗时越长(每颗约 30 微秒),灯珠数量别盲目往大里填。
更多配方
彩虹渐变
import neopixel
from machine import Pin
import time
NUM_LEDS = 60
np = neopixel.NeoPixel(Pin(13), NUM_LEDS)
def wheel(pos):
"""把 0~255 映射成彩虹色,返回 (R, G, B)。"""
pos = pos & 255
if pos < 85:
return (255 - pos * 3, pos * 3, 0)
elif pos < 170:
pos -= 85
return (0, 255 - pos * 3, pos * 3)
else:
pos -= 170
return (pos * 3, 0, 255 - pos * 3)
offset = 0
while True:
for i in range(NUM_LEDS):
np[i] = wheel(i * 256 // NUM_LEDS + offset)
np.write()
offset = (offset + 4) & 255
time.sleep_ms(20)
整体调暗(neopixel 没有亮度参数)
等比缩放每个分量即可:
BRIGHT = 0.25 # 0.0 ~ 1.0
def dim(color):
return tuple(int(c * BRIGHT) for c in color)
np.fill(dim((255, 0, 0))) # 暗红
np.write()
灯珠多、电源吃紧时,把亮度压到 0.2 ~ 0.3 能显著降低电流。
用 ws2812 做呼吸灯(自带 brightness)
import ws2812
import math
import time
NUM_LEDS = 30
ws2812.init()
buf = bytearray([0, 0, 255] * NUM_LEDS) # 纯红:B=0、G=0、R=255
step = 0
while True:
level = (math.sin(step / 20.0) + 1) / 2 # 0.0 ~ 1.0
ws2812.play_rgb_buffer(buf, len(buf), level)
step += 1
time.sleep_ms(30)
完整示例
萤火虫T1 的应用放在 SD 卡的 /sd/apps/<应用目录>/ 下,入口是 boot.py。下面这段放进 /sd/apps/my-light-app/boot.py:上 / 下短按切换颜色,中键短按切换亮度,中键长按退出并熄灭灯带。
import pm
import neopixel
import time
from machine import Pin
from button import Button
NUM_LEDS = 60
COLORS = [(255, 0, 0), (0, 255, 0), (0, 0, 255)] # 红 / 绿 / 蓝
NAMES = ['红', '绿', '蓝']
index = 0
brightness = 0.5
running = True
dirty = True
# 供电三件事:VCC 输出 + 导通 P-MOS + 数据线接 PIN5(GPIO13)
pm.init()
pm.set_power_state(pm.VCC_OUTPUT) # 启动器的 poll 线程会在一秒内让输出生效
enable_pin = Pin(43, Pin.OPEN_DRAIN)
enable_pin.value(0) # 低电平导通 P-MOS,5V 出现在 PIN1
np = neopixel.NeoPixel(Pin(13), NUM_LEDS)
buttons = Button()
def on_up():
global index, dirty
index = (index - 1) % len(COLORS)
dirty = True
def on_down():
global index, dirty
index = (index + 1) % len(COLORS)
dirty = True
def on_center_short():
global brightness, dirty
brightness = 0.2 if brightness > 0.5 else 0.9 # 两档亮度切换
dirty = True
def on_center_long():
global running
running = False
buttons.register_callback('up', 'short', on_up)
buttons.register_callback('down', 'short', on_down)
buttons.register_callback('center', 'short', on_center_short)
buttons.register_callback('center', 'long', on_center_long)
while running:
if dirty: # 只在有变化时刷新,省时间
dirty = False
np.fill(tuple(int(c * brightness) for c in COLORS[index]))
np.write()
print("{} 亮度 {}".format(NAMES[index], brightness))
time.sleep(0.05)
np.fill((0, 0, 0)) # 退出前熄灭灯带
np.write()
enable_pin.value(1) # 高阻态,关断 5V 输出(与启动器一致)
buttons.deinit()
相关模块见 五向按键(button)、电源管理(pm) 与 麦克风(mic)。
排错
| 现象 | 原因 / 处理 |
|---|---|
| 灯带全黑 | 供电三件事少了一件 → 检查 pm.VCC_OUTPUT、enable_pin.value(0)、数据线是否接在 PIN5(GPIO13) |
改了 np[i] 但灯没反应 | 忘了 np.write() → 所有修改都要 write() 后才生效 |
| 红蓝对调 | 用 ws2812.play_rgb_buffer() 时缓冲区写成了 R、G、B → 改成 B、G、R |
| 只有前几颗亮,后面不亮 | NeoPixel(Pin(13), n) 的 n 填少了 → 与实际灯珠数一致,或填一个上限值 |
抛 IndexError | np[i] 的 i 越界 → 范围是 0 ~ len(np) - 1 |
抛 ValueError: byte must be in range(0, 256) | RGB 分量超过 255 → 限制在 0 ~ 255 |
np.fill() 抛 TypeError | 写成了 np.fill(255, 0, 0) → 要传一个元组 np.fill((255, 0, 0)) |
抛 ValueError: Brightness must be between 0.0 and 1.0 | brightness 用了 0~255 → 改成 0.0 ~ 1.0 的小数 |
一调用 ws2812.init() 设备就重启 | 上次没 ws2812.deinit(),RMT 通道被占用 → 先 deinit() 再 init() |
| 颜色发白、末端闪烁 | 5V 供电能力不足或数据线过长 → 就近供电、缩短数据线,或把亮度调低 |
AI 用法(即将上线)
以后你不用自己理清 GPIO43 的两种状态、也不用记 BGR 顺序:用自然语言描述你想要的灯效,Agent 会照着本文档里的 API,直接生成能在萤火虫T1 上运行的完整程序。
比如直接对它说:
灯带 60 颗,开机时从中间往两边展开一段彩虹,然后保持常亮;中键短按切换亮度,长按退出并熄灭。
它就会把 neopixel、pm、Button 组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。
入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。