跳到主要内容

WS2812 LED 控制(neopixel)

萤火虫T1 通过顶部 5P-PIN 拓展接口驱动 WS2812 / WS2812B 炫彩灯带:数据线接 PIN5(GPIO13),5V 电由 PIN1 提供、靠 GPIO43 控制一个 P-MOS 开关。固件里同时提供了两套驱动——通用的 neopixel 库,以及内置的 ws2812 C 模块(官方光绘应用用的就是后者)。

数据线 GPIO13

对应顶部 5P-PIN 的 PIN5,直连 MCU,不需要额外器件。

5V 要三件事一起做

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)。

两套驱动怎么选​

neopixelws2812(固件内置)
实现方式标准 MicroPython 驱动,纯 Python + machine.bitstreamC 模块,走 ESP32 的 RMT 外设
数据引脚自己传,如 Pin(13)固定 GPIO13,不用传
设置颜色np[i] = (R, G, B) 元组自己维护 bytearray,按 B、G、R 排列
自带亮度无,要自己缩放 RGBplay_rgb_buffer() 有 brightness 参数
更新方式可以只改一颗灯珠再 write()只能整段刷新(一次发 length 字节)
适合场景少量灯珠、逐颗改色、代码最简单大量灯珠、整体刷帧(官方光绘应用每秒刷一整幅图)
生命周期构造出来就能用需要 init() / deinit() 配对

建议:先用 neopixel 把效果跑通;等灯珠数量多、帧率不够时,再换成 ws2812。

API 参考​

neopixel​

构造 NeoPixel()​

np = neopixel.NeoPixel(pin, n, bpp=3, timing=1)
参数类型默认值说明
pinPin必填数据脚,用 Pin(13)
nint必填灯珠数量
bppint3每颗灯珠字节数,WS2812 固定为 3
timingint11 = 800 kHz(WS2812B 标准),0 = 400 kHz

构造时会立刻把该引脚设为输出,并分配 n × bpp 字节的缓冲区。n 填得和实际灯珠数一致最稳妥:填少了,后面没被覆盖的灯珠会保持上一次的颜色;填多一个上限值(如官方应用的 480)也不会出错,只是末尾那段数据白发了。

设置颜色 np[i]​

np[0] = (255, 0, 0)
项类型取值
下标 iint0 ~ 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)
参数类型说明
bufferbytearrayRGB888 数据,每颗灯珠 3 字节,按 B、G、R 排列
lengthint本次发送的字节数,应为 3 的倍数;超过 buffer 长度抛 ValueError: Buffer length mismatch
brightnessfloat0.0 ~ 1.0;超出范围抛 ValueError: Brightness must be between 0.0 and 1.0

无返回值。它会做三件事:

  1. 把每个分量乘以 brightness 做整体调暗(brightness=0 即全黑);
  2. 重排成灯珠需要的 GRB 顺序,按 800 kHz 时序发出;
  3. 阻塞到全部发完(每颗灯珠约 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 的典型症状就是红蓝对调。

常见坑点​

  1. 忘了 np.write()。 改颜色只是改内存缓冲区,不调用 write() 灯珠不会有任何变化。
  2. 灯不亮先查供电三件事:pm.set_power_state(pm.VCC_OUTPUT)、enable_pin.value(0)、数据线接在 PIN5(GPIO13)。
  3. GPIO43 的两种状态容易记反:value(0) 才是接通(低电平导通 P-MOS),value(1) 是高阻态、关断。启动器浏览应用列表时就处于关断状态。
  4. ws2812 的缓冲区顺序是 B、G、R,不是 R、G、B。
  5. RGB 分量必须在 0 ~ 255 之间,写 256 会抛 ValueError;下标越界抛 IndexError。
  6. np.fill() 只接受一个元组:np.fill((255, 0, 0))。
  7. ws2812.init() 与 ws2812.deinit() 必须配对。 init() 内部是 ESP_ERROR_CHECK 断言,重复初始化会直接重启设备。
  8. 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 填少了 → 与实际灯珠数一致,或填一个上限值
抛 IndexErrornp[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.0brightness 用了 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/。

Agent 入口(即将上线)

入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。