跳到主要内容

灯光控制(WS2812 / neopixel)

独角仙S1 的灯带数据线固定在 GPIO13,固件里给了两条驱动路径:ws2812(C 模块,走 RMT 硬件,带亮度参数,光绘 App 用的就是它)和 neopixel(MicroPython 内置,写法最简洁)。两者控制的是同一根线,选一个用就行。

两条路都能点灯

ws2812 一次发一整条灯带、顺手能调亮度;neopixel 一行就能点亮一颗。

数据线写死在 GPIO13

引脚固定在固件里(引到 XT30 的信号脚),软件不可改。

亮度只有 ws2812 有

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)
参数类型说明
bufferbytearray / bytesRGB 数据,每颗灯 3 字节,顺序是 蓝、绿、红
lengthint要发送的字节数(不是灯珠数),一般传 len(buffer)
brightnessfloat亮度系数,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)
参数类型默认说明
pinPin—数据线;独角仙S1 上是 Pin(13)
nint—灯珠数量
bppint3每颗灯字节数;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 mismatchlength 大于 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/。

Agent 入口(即将上线)

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