WS2812B 256-LED 矩阵

项目介绍

概述

本示例基于 WS63 开发板驱动一块 256 颗 WS2812B 灯珠的 RGB 点阵屏，使用 SPI 模拟单线协议（每颗灯珠的 1 个 bit 编码为 1 个 SPI 字节），由 SPI 硬件时钟输出时序，CPU 只做缓冲填充，稳定不卡顿。

配合上位机（ws2812b_host.py），可通过串口逐颗点亮灯珠：色盘选色、16×16 点阵上点击或拖拽上色，灯珠实时同步。

主要特点：

SPI 硬件时序驱动，CPU 无需位级忙等，稳定不卡死
串口命令控制（P / C / F / A），板端回 OK 确认
Python 上位机：色盘 + 16×16 像素格 + 拖拽连续涂色
256 颗灯珠，16×16 点阵，每行从左到右寻址

项目结构

code

ws2812b_256/
├── src/
│   ├── ws2812b_256_demo.c    # 板端主程序（SPI 驱动 + 串口命令解析）
│   ├── Kconfig               # 引脚 / SPI / 行列参数
│   └── CMakeLists.txt        # 编译配置
├── ws2812b_host.py           # 上位机脚本（Python）
└── README.md                 # 本文档

硬件连接

WS63 引脚	SPI 功能	接到灯板
GPIO9	SPI0 MOSI（S_MGPIO9）	DI（数据输入，必需）
GPIO7	SPI0 SCK	可不接（SPI 内部时序）
GPIO11	SPI0 MISO	可不接
GND	-	灯板 GND（必须共地）
电源	-	灯板 VCC（独立供电）

说明：灯板只需接一根数据线（GPIO9 接到 DI）。SCK / MISO 是开发板内部的 SPI 引脚，灯板用不到。

⚠️ 供电：256 颗灯珠全亮白时电流可达 数安培~十几安培，必须用独立电源（5V 适配器）给灯板供电，不能靠开发板 USB。

SDK 配置说明

步骤 0：复制 Demo 代码到 SDK

将 ws2812b_256 文件夹复制到 SDK 的 application/samples/peripheral/ 目录下：

code

application/samples/peripheral/
├── ws2812b_256/             <-- 复制到这里
│   ├── src/                 (或把 src 下的 3 个文件直接放这里)
│   │   ├── ws2812b_256_demo.c
│   │   ├── CMakeLists.txt
│   │   └── Kconfig
├── gpio/
├── i2c/
├── ...

步骤 1：注册 Demo 到构建系统

在 application/samples/peripheral/ 的 Kconfig 和 CMakeLists.txt 中注册本 Demo。

1.1 修改 Kconfig

编辑 application/samples/peripheral/Kconfig，在末尾添加：

kconfig

config SAMPLE_SUPPORT_WS2812B_256
    bool
    prompt "Support WS2812B 256 Sample."
    default n
    depends on ENABLE_PERIPHERAL_SAMPLE
    help
        This option means support WS2812B 256-LED matrix Sample.
        Uses SPI to simulate the WS2812B single-wire protocol and
        controls individual LEDs via serial commands from a PC tool.

if SAMPLE_SUPPORT_WS2812B_256
menu "WS2812B 256 Sample Configuration"
    osource "application/samples/peripheral/ws2812b_256/Kconfig"
endmenu
endif

1.2 修改 CMakeLists.txt

编辑 application/samples/peripheral/CMakeLists.txt，添加：

cmake

if(DEFINED CONFIG_SAMPLE_SUPPORT_WS2812B_256)
    add_subdirectory_if_exist(ws2812b_256)
endif()

步骤 2：启用 Demo（menuconfig）

bash

python build.py ws63-liteos-app menuconfig

配置路径：

code

Application Configuration
  └─> Peripheral Sample Configuration
      └─> [*] Support WS2812B 256 Sample.

Demo 参数（引脚/SPI/行列）可在 WS2812B 256 Sample Configuration 下调整，也可以直接改 ws2812b_256/Kconfig 的默认值。

步骤 3：编译

bash

python build.py ws63-liteos-app

编译成功后生成烧录固件（如 output/ws63/fwpkg/ws63-liteos-app/ws63-liteos-app_all.fwpkg），用 HiSpark Studio 或烧录工具烧到开发板即可。

上位机使用

依赖：Python 3 + tkinter（内置于标准 Python）+ pyserial。

bash

pip install pyserial
python ws2812b_host.py

操作说明：

顶部选择串口（如 COM5），点击连接。
右侧色盘：调节 色相 / 饱和度 / 亮度 滑条，或用取色器、常用色板选色。
中间 16×16 像素格：
- 单击：给当前格子涂上当前颜色。
- 按住拖拽：连续涂色（自动补画中间格，快速拖动不断笔）。
工具栏按钮：
- 清空（C）：熄灭全部灯珠。
- 全亮当前色（F）：所有灯珠点亮为当前颜色。
- 恢复动画（A）：恢复板端默认动画。

串口命令协议

板端使用 UART0（波特率 115200，8N1），行分隔，收到合法命令回 OK：

命令	含义
`P <idx> <RRGGBB>`	点亮第 `idx` 颗灯（`idx`：0~255，物理链序号）
`C`	全部熄灭
`F <RRGGBB>`	全部点亮为指定颜色
`A`	恢复动画循环

收到 P / C / F 后板子进入主机控制模式（暂停动画）；发 A 恢复。

示例（可用任意串口助手发送）：

code

P 0 FF0000      # 点亮第 0 颗为红色
P 255 00FF00    # 点亮第 255 颗为绿色
F 0000FF        # 全部点亮为蓝色
C               # 全部熄灭
A               # 恢复动画

引脚寻址说明

本 Demo 默认 LED 映射为每行从左到右：

led_index(row, col) = row * 16 + col

如果你的灯板是蛇形（回字形）走线（奇数行从右到左），请修改 ws2812b_256_demo.c 中的 ws2812b_256_led_index()：

static uint16_t ws2812b_256_led_index(uint16_t row, uint16_t col)
{
    if ((row & 1) != 0) {
        return (uint16_t)(row * CONFIG_WS2812B_256_COLS + (CONFIG_WS2812B_256_COLS - 1 - col));
    }
    return (uint16_t)(row * CONFIG_WS2812B_256_COLS + col);
}

上位机脚本 ws2812b_host.py 中的 led_index() 也要同步修改。

注意事项

独立供电：256 颗灯珠功耗大，务必用独立电源给灯板供电。
共地：开发板 GND 必须与灯板 GND 相连。
串口占用：上位机 / 串口监视器会占用 UART0，同时只能运行一个工具。
AT 命令：Demo 接管了 UART0 的接收（原 AT 命令框架），故 AT 命令经 UART0 不可用；如需 AT，请改用其他 UART。
数据线与 SCK：只需接 DI（GPIO9），SCK/MISO 可不接。

0 条评论

还没有评论，来说两句。