类: Strip (灯带驱动)

约 1685 字大约 6 分钟

2026-09-06

构建固件和导入到JS

在 C++ 里加入以下代码, 然后重新编译构建固件：

// 为了控制固件的尺寸，BeShell 的 module 是按需引入的。
beshell.use<be::driver::ws2812b::WS2812B>() ;

Strip 类由 ws2812b 模块提供：

import { Strip } from 'ws2812b'

简介

WS2812B LED 灯带驱动类

用于控制 WS2812B 全彩 LED 灯带，支持设置单个像素颜色、清空灯带和刷新显示。使用 RMT 硬件模块实现精确的时序控制。

示例：

import { Strip } from "ws2812b"

// 创建 Strip 实例（30个LED，回环）
const strip = new Strip()

// 初始化配置
strip.setup({
    pin: 18,    // 数据引脚
    length: 30, // LED 数量
    loop: true  // 首尾相接（可选，默认 false）
})

// 设置第一个 LED 为红色
strip.setPixel(0, 255, 0, 0)

// HSV 方式设置第二个 LED 为绿色
strip.setPixelHSV(1, 120, 1, 1)

// 刷新显示（将数据发送到灯带）
strip.flush()

// 清空灯带（所有 LED 熄灭）
strip.clear()
strip.flush()

类属性

属性 loop

类型: boolean

回环开关

读写 strip 是否首尾相接。回环模式下越界像素索引取模回卷。

类方法

方法 constructor

原型: constructor ()

构造函数

创建一个新的 Strip 实例。

返回值:

类型Strip

说明返回 Strip 实例

方法 setup

原型: setup (config:object)

初始化 WS2812B LED 灯带

配置 LED 灯带的数据引脚和 LED 数量。可重复调用（重复调用时先释放旧配置）。

配置参数说明：

pin: 连接 LED 灯带数据线的 GPIO 引脚号
length: LED 灯带上的 LED 数量（1-1024）
loop: 是否首尾相接（回环），默认 false

示例：

strip.setup({
    pin: 18,
    length: 30,
    loop: true
})

参数:

config

类型object (详见下方类型定义)

参数说明配置对象

config 类型定义：

{
    pin: number,           // 数据引脚 GPIO 号
    length: number,        // LED 数量（1-1024）
    loop?: boolean         // 是否回环，默认 false
}

异常:

LED 数量必须在 1-1024 范围内
LED 灯带初始化失败

返回值:

类型undefined

方法 setPixel

原型: setPixel (idx:number, red:number, green:number, blue:number)

设置单个像素的颜色

设置指定索引位置的 LED 颜色。颜色值使用 RGB 格式，每个通道范围为 0-255。注意：调用此方法后需要调用 flush() 才能将颜色数据发送到灯带。

示例：

strip.setPixel(0, 255, 0, 0)  // 第 0 个 LED 为红色
strip.flush()

参数:

idx
类型number
参数说明像素索引（从 0 开始；回环模式下越界索引取模回卷）
red
类型number
参数说明红色通道值（0-255）
green
类型number
参数说明绿色通道值（0-255）
blue
类型number
参数说明蓝色通道值（0-255）

异常:

请先调用 setup()
无效的像素索引（非回环模式）

返回值:

类型undefined

方法 setPixelHSV

原型: setPixelHSV (idx:number, h:number, s:number, v:number)

以 HSV 方式设置单个像素的颜色

HSV 到 RGB 的转换在 C++ 侧完成。h 自动取模回卷，s/v 自动截断到 0-1。注意：调用此方法后需要调用 flush() 才能将颜色数据发送到灯带。

示例：

strip.setPixelHSV(0, 0, 1, 1)     // 第 0 个 LED 为红色
strip.setPixelHSV(1, 120, 1, 1)   // 第 1 个 LED 为绿色
strip.flush()

参数:

idx
类型number
参数说明像素索引（从 0 开始；回环模式下越界索引取模回卷）
h
类型number
参数说明色相（0-360，自动回卷）
s
类型number
参数说明饱和度（0-1）
v
类型number
参数说明明度（0-1）

异常:

请先调用 setup()

返回值:

类型undefined

方法 clear

原型: clear ()

清空灯带

将所有 LED 的颜色设置为关闭（黑色）。注意：调用此方法后需要调用 flush() 才能将数据发送到灯带。

异常:

请先调用 setup()

返回值:

类型undefined

方法 flush

原型: flush ()

刷新显示

将设置的颜色数据发送到 LED 灯带。在调用 setPixel() 或 clear() 后，必须调用此方法才能将更改应用到实际的 LED 灯带上。

异常:

请先调用 setup()

返回值:

类型undefined

方法 exportConfig

原型: exportConfig ()

导出配置

导出当前驱动层配置 {pin, length, loop}，返回可 JSON 序列化的对象。

返回值:

类型object (详见下方类型定义)

说明配置对象

返回值类型定义：

{
    pin: number,      // 数据引脚 GPIO 号
    length: number,   // LED 数量
    loop: boolean     // 是否回环
}

方法 importConfig

原型: importConfig (config:object)

导入配置

从配置对象恢复驱动层设置（缺省字段保持当前值），并重建硬件。

参数:

config

类型object (详见下方类型定义)

参数说明配置对象（缺省字段保持当前值）

config 类型定义：

{
    pin?: number,     // 数据引脚 GPIO 号
    length?: number,  // LED 数量（1-1024）
    loop?: boolean    // 是否回环
}

返回值:

类型undefined

控件

类: Strip (灯带驱动)