灯光控制(WS2812 / neopixel)
独角仙S1 的灯带数据线固定在 GPIO13,固件里给了两条驱动路径:ws2812(C 模块,走 RMT 硬件,带亮度参数,光绘 App 用的就是它)和 neopixel(MicroPython 内置,写法最简洁)。两者控制的是同一根线,选一个用就行。
ws2812 一次发一整条灯带、顺手能调亮度;neopixel 一行就能点亮一颗。
引脚固定在固件里(引到 XT30 的信号脚),软件不可改。
neopixel 没有亮度参数,要自己把 RGB 按比例缩小。
硬件与接线
| 项目 | 值 |
|---|---|
| 数据线 | GPIO13(固定,不可改) |
| 驱动方式 | ws2812 → RMT 通道 0(常驻);neopixel → 内置位流(每次 write() 临时占用一个通道) |
| 线上数据格式 | 每颗灯 24 位,按 G → R → B 顺序发送 |
| 单次可发灯数 | 最多 480 颗(与光绘 App 的 MAX_RESOLUTION 一致) |
| 供电 | XT30 输出口直出 3S 锂电电压(约 9–12.6V) |
灯带怎么选、怎么接 XT30,见 兼容灯带与接线。
灯珠数量由配置决定
S1 的 App 有一个通用约定:灯珠数 = /sd/apps/config.json 里的 light_stick_length(段数)× 48。默认 3 → 144 颗。
import ujson
try:
with open('/sd/apps/config.json') as f:
n = ujson.load(f).get('light_stick_length', 3) * 48
except (OSError, ValueError):
n = 144 # 读不到就用默认值
这样用户改配置里的段数,你的灯效长度就跟着变,不用改代码。
快速开始
用 ws2812(整条灯带,推荐)
import ws2812
ws2812.init() # 安装 RMT,一个程序只调一次
N = 144 # 144 颗灯
buf = bytearray(N * 3) # 每颗灯 3 字节,顺序是「蓝、绿、红」
for i in range(N):
buf[i * 3 + 2] = 255 # 写到「红」那一格 → 整条变红
ws2812.play_rgb_buffer(buf, len(buf), 0.5) # 参数:缓冲区、字节数、亮度(0.0~1.0)
运行现象:整条灯带以 50% 亮度亮起红色。亮度是乘法,所以 255 × 0.5 ≈ 128。
用 neopixel(写法最短)
import neopixel
from machine import Pin
np = neopixel.NeoPixel(Pin(13), 144) # 144 颗灯
np[0] = (255, 0, 0) # 第 1 颗设红(顺序是「红、绿、蓝」)
np[10] = (0, 0, 255) # 第 11 颗设蓝
np.write() # 不调 write() 灯带不会有任何变化
运行现象:第 1 颗红灯、第 11 颗蓝灯,其余保持原状(上电时通常是灭的)。
两条路怎么选
ws2812(C 模块) | neopixel(内置) | |
|---|---|---|
| 一次发多少 | 一整条灯带(bytearray + 字节数) | 一整条灯带(逐颗赋值后 write()) |
| 亮度参数 | 有,play_rgb_buffer() 第 3 个参数 | 无,要自己缩 RGB |
| 缓冲区颜色顺序 | 蓝、绿、红(BGR) | 元组是 红、绿、蓝(RGB) |
| 刷新开销 | 常驻 RMT 通道,适合高频刷新 | 每次 write() 都要装/卸一次 RMT 通道 |
| 典型用途 | 光绘逐行播放、整条灯带动画 | 少量灯珠、简单状态指示 |
光绘 App 之所以用 ws2812,正是因为它常驻通道、高频刷新更稳——一帧一行,要跟得上拍摄节奏。
API 参考
ws2812(C 模块)
ws2812.init()
ws2812.init()
无参数、无返回值。它在 GPIO13 上配置 RMT 通道 0 并安装驱动。
- 一个程序里只调一次:同一个 RMT 通道只能安装一次,第二次调用会报错。
- 必须先
init()再用play_rgb_buffer(),否则通道没装好,发送会失败。
ws2812.play_rgb_buffer(buffer, length, brightness)
ws2812.play_rgb_buffer(buffer, length, brightness)
| 参数 | 类型 | 说明 |
|---|---|---|
buffer | bytearray / bytes | RGB 数据,每颗灯 3 字节,顺序是 蓝、绿、红 |
length | int | 要发送的字节数(不是灯珠数),一般传 len(buffer) |
brightness | float | 亮度系数,0.0–1.0;0 = 全灭,1.0 = 原色 |
无返回值。函数会阻塞到发送完成,所以它同时也就是"这一帧已经发出去了"的信号。
length大于buffer的实际长度 →ValueError: Buffer length mismatch。brightness不在0.0–1.0→ValueError: Brightness must be between 0.0 and 1.0。- 灯珠数 =
length // 3,末尾不足一颗灯的字节会被忽略。 - 颜色换算:先取
buffer[+2]当红、[+1]当绿、[+0]当蓝,再按 G→R→B 串出去——正好是 WS2812 / WS2815 要的顺序。
ws2812.calculate_percentage(numerator, denominator, seconds)
text = ws2812.calculate_percentage(row, total_rows, elapsed_seconds)
# 例如返回 "45% 3s"
返回一个字符串 "百分比% 秒数s"。它只是个格式化小工具(光绘 App 用它把进度打到屏幕上),和灯带本身无关。
denominator为0→ValueError: Denominator cannot be zero。- 百分比按整数除法算,不会四舍五入。
ws2812.deinit()
ws2812.deinit()
无参数、无返回值。卸载 RMT 通道 0。
注意:卸载通道不等于熄灯——灯带会保持最后一次收到的颜色。想让它灭,先发一帧全 0 再 deinit():
ws2812.play_rgb_buffer(bytearray(144 * 3), 144 * 3, 0)
ws2812.deinit()
neopixel(MicroPython 内置)
neopixel.NeoPixel(pin, n[, bpp])
import neopixel
from machine import Pin
np = neopixel.NeoPixel(Pin(13), 144)
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
pin | Pin | — | 数据线;独角仙S1 上是 Pin(13) |
n | int | — | 灯珠数量 |
bpp | int | 3 | 每颗灯字节数;3 是一般 RGB 灯带,4 用于 RGBW 灯带 |
返回灯带对象。构造时不会发送任何数据。
np[i] = (r, g, b) 与 np.fill((r, g, b))
np[0] = (255, 0, 0) # 第 1 颗
np.fill((0, 0, 0)) # 一次设置整条
每项是 0–255 的整数,顺序是 红、绿、蓝。赋值只改内存,不改灯带。
np.write()
np.write()
把内存里的颜色真正发到灯带上。无参数、无返回值。
它每次调用都会安装再卸载一个 RMT 通道,所以别放在超高频循环里——需要逐行高速刷新时请用 ws2812.play_rgb_buffer()。
len(np)
len(np) # 灯珠数量
颜色与字节顺序(最容易踩的坑)
两个接口的参数顺序不一样,这是最常见的错误来源:
| 接口 | 你写进去的顺序 | 写法 |
|---|---|---|
ws2812.play_rgb_buffer | 蓝、绿、红(BGR) | buf[i*3+0]=蓝、+1=绿、+2=红 |
neopixel.NeoPixel | 红、绿、蓝(RGB) | np[i] = (红, 绿, 蓝) |
为什么 ws2812 用 BGR?因为 24 位 BMP 文件里像素本来就是按 B、G、R 存的——这样光绘 App 可以把 BMP 的一整行直接丢进去,不用做任何转换。
驱动最终按 GRB 顺序往线上发(WS2812 / WS2815 的要求)。如果你的灯带红绿是反的:
- 把
/sd/apps/config.json里的"red_green_swap"改成true(App 会自己交换缓冲区里的绿、红两格),或者 - 自己写缓冲区时把绿、红两格对调。
常见坑点
| 现象 | 原因 / 处理 |
|---|---|
| 灯带整条不亮 | neopixel 忘了 write();或 ws2812 忘了 init();或灯带没供电 |
| 红绿颠倒 | 灯带色序与驱动不同 → red_green_swap: true |
| 颜色整体不对(像是蓝红互换) | 缓冲区顺序写错:ws2812 要 BGR,neopixel 要 RGB |
| 只有前几颗亮、后面乱闪 | length 传成了灯珠数(应该传字节数) |
ValueError: Buffer length mismatch | length 大于 buffer 的实际长度 |
| 调了亮度没反应 | 用的是 neopixel(它没有亮度参数)→ 换 ws2812 或自己缩 RGB |
第二次 ws2812.init() 报错 | RMT 通道 0 只能安装一次 → 全程只 init 一次 |
deinit() 之后灯不灭 | 卸载通道 ≠ 熄灯 → 先发一帧全 0 |
| 帧率上不去、闪烁 | 用了 neopixel.write() 逐帧刷 → 换 ws2812.play_rgb_buffer() |
更多配方
彩虹渐变
import ws2812
import time
N = 144
buf = bytearray(N * 3)
offset = 0
def wheel(pos):
"""0-255 的位置 -> (红, 绿, 蓝)"""
pos = pos % 255
if pos < 85:
return (pos * 3, 255 - pos * 3, 0)
if pos < 170:
pos -= 85
return (255 - pos * 3, 0, pos * 3)
pos -= 170
return (0, pos * 3, 255 - pos * 3)
ws2812.init()
try:
while True:
for i in range(N):
r, g, b = wheel(i * 256 // N + offset)
buf[i * 3 + 0] = b # 蓝
buf[i * 3 + 1] = g # 绿
buf[i * 3 + 2] = r # 红
ws2812.play_rgb_buffer(buf, len(buf), 0.4)
offset = (offset + 4) % 255
time.sleep(0.02) # ≈50 fps
finally:
ws2812.play_rgb_buffer(bytearray(N * 3), N * 3, 0)
ws2812.deinit()
呼吸灯(直接用 ws2812 的亮度)
import ws2812
import math
import time
N = 144
buf = bytearray(N * 3)
for i in range(N):
buf[i * 3 + 0] = 255 # 蓝
ws2812.init()
try:
step = 0
while True:
level = (math.sin(step / 12) + 1) / 2 # 0.0 ~ 1.0
ws2812.play_rgb_buffer(buf, len(buf), level)
step += 1
time.sleep(0.03)
finally:
ws2812.play_rgb_buffer(buf, len(buf), 0)
ws2812.deinit()
neopixel 没有亮度参数,同样的效果要自己乘:np[i] = (int(r * level), int(g * level), int(b * level))。
用 neopixel 做几颗状态指示灯
import neopixel
from machine import Pin
np = neopixel.NeoPixel(Pin(13), 3) # 只用前 3 颗当指示灯
def status(state):
np.fill((0, 0, 0))
if state == 'ok':
np[0] = (0, 255, 0)
elif state == 'busy':
np[1] = (255, 160, 0)
else:
np[2] = (255, 0, 0)
np.write()
完整示例
放在 SD 卡的 /sd/apps/led-demo/boot.py,开机跑一段彩虹,上/下键调亮度,长按中键退出:
import ws2812
import time
from button import Button
N = 144
buf = bytearray(N * 3)
brightness = 0.4
offset = 0
running = True
def wheel(pos):
pos = pos % 255
if pos < 85:
return (pos * 3, 255 - pos * 3, 0)
if pos < 170:
pos -= 85
return (255 - pos * 3, 0, pos * 3)
pos -= 170
return (0, pos * 3, 255 - pos * 3)
def on_up():
global brightness
brightness = min(1.0, round(brightness + 0.1, 2))
def on_down():
global brightness
brightness = max(0.0, round(brightness - 0.1, 2))
def on_exit():
global running
running = False
ws2812.init()
buttons = Button()
buttons.register_callback('up', 'short', on_up)
buttons.register_callback('down', 'short', on_down)
buttons.register_callback('center', 'long', on_exit)
try:
while running:
for i in range(N):
r, g, b = wheel(i * 256 // N + offset)
buf[i * 3 + 0] = b # 蓝
buf[i * 3 + 1] = g # 绿
buf[i * 3 + 2] = r # 红
ws2812.play_rgb_buffer(buf, len(buf), brightness)
offset = (offset + 4) % 255
time.sleep(0.03)
finally:
ws2812.play_rgb_buffer(bytearray(N * 3), N * 3, 0) # 先熄灭
buttons.deinit()
ws2812.deinit()
这里有个细节值得注意:play_rgb_buffer() 是阻塞式的,一帧发完才返回,所以主循环里不需要额外的同步措施。
排错
| 现象 | 原因 / 处理 |
|---|---|
| 完全没反应 | 先确认灯带供电(XT30 直出 3S 电压,5V 灯带需要 12V→5V 模块),再确认调了 init() / write() |
| 只有一小段亮 | length 与实际灯珠数不符 → 改成 len(buf) |
| 颜色随机跳 | 数据线和时钟线接反了,或者灯带 DIN 接到了错误的一端(多数灯带有方向) |
| 首颗灯乱闪 | 数据线太长/无屏蔽、灯带与主控没有共地 → 缩短线材并确保共地 |
| 亮度很低 | brightness 传小了;或灯带自身供电不足(长灯带要单独供电) |
ValueError: Brightness must be between 0.0 and 1.0 | 亮度传成了 0–255 之类的整数 → 改成 0.0–1.0 的小数 |
| 程序运行一会儿就报内存错误 | ws2812 每次发送都会临时申请 灯珠数 × 24 个 RMT 项的缓冲 → 降低灯珠数或降低刷新频率 |
| 和光绘功能一起用时灯带花屏 | 两处代码都在写 GPIO13 → 同一时间只保留一个驱动实例,互斥使用 |
相关模块:按键控制(button) · 蜂鸣器(beep) · 显示屏(ST7789)
AI 用法(即将上线)
以后你不用自己算 BGR 顺序、也不用纠结彩虹算法:用自然语言描述你想要的灯光效果,Agent 会照着本文档里的 API,直接生成能在独角仙S1 上运行的完整程序。
比如直接对它说:
开机让灯带跑一个彩虹,上键调亮、下键调暗,长按中键退出,退出前把灯带熄灭。
它就会把 ws2812、config.json 里的灯珠数和 button 的回调组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。
入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。