外观
WLED
WLED 是 ESP 世界里最受欢迎的灯光固件之一：刷到 ESP32 上，接好 WS2812B 之类的可寻址灯带，手机连上 Wi-Fi 就能调颜色、选灯效、做 2D 矩阵动画。不用写代码，适合想做氛围灯、电视背光、节日灯的人。
项目概况
| 项目 | 内容 |
|---|---|
| 仓库 / 官网 | github.com/wled-dev/WLED（原 Aircoookie/WLED，旧地址会跳转），文档 kno.wled.ge |
| 作者 / 组织 | Christian Schwinne (Aircoookie) 创建，现由社区维护 |
| 开源协议 | EUPL v1.2（仓库 LICENSE 文件与 README 均如此标注）。注意：这是一个 copyleft 协议，旧资料里常见的 MIT 说法已过时，以仓库当前文件为准 |
| 支持芯片 | README 写的是 ESP32 全系（原版、S2、S3、C3）；ESP8266 在早期版本中受支持，新版本的支持范围请查文档 |
| 首次发布 | 仓库创建于 2016 年 12 月 20 日 |
| 最新稳定版 | v16.0.1（2026 年 7 月 7 日）；另有每日构建 (nightly) |
| 热度 | 约 1.9 万星（2026 年 10 月） |
它是怎么工作的
固件在 ESP32 上同时跑一个 Web 服务器和一个灯效引擎。灯效引擎按帧计算每颗 LED 的颜色，通过 RMT 或 I2S 外设按灯珠协议（单线时序）输出；Web 界面和手机 App 通过 HTTP / JSON API 修改状态。
主要概念：
- 分段 (Segments)：把一条灯带拆成多段，每段独立设置灯效、颜色和调色板。
- 预设 (Presets)：README 称最多 250 个，可以做成播放列表自动轮播。
- 灯效：200 多种内置效果，50 多种调色板，自带调色板编辑器。
- 声音反应 (AudioReactive)：用麦克风或线路输入，让灯跟着音乐跳。
- 2D 矩阵与 HUB75 面板：支持 LED 矩阵和 HUB75 面板（ESP32）。
- 多输出：ESP32 上最多 17 路 LED 输出（I2S + RMT 并行）。
联网与集成：JSON 与 HTTP API、MQTT（含 Home Assistant 自动发现）、E1.31 / Art-Net / DDP（专业舞台灯光协议）、ESP-NOW 设备间无路由同步、UDP 实时同步、Hue 同步、Alexa、Hyperion / Adalight 电脑氛围灯、红外遥控、NTP 定时。
需要的硬件
| 部件 | 说明 |
|---|---|
| 主控 | 任意常见 ESP32 开发板即可；追求多路输出和稳定性可用 QuinLED 之类的专用板 |
| 灯带 | WS2812B、WS2811、WS2815、SK6812、APA102、WS2801 等可寻址灯带；也支持 RGBW、RGB+CCT、纯白灯带 |
| 电源 | 灯带耗电大，每颗 WS2812B 满亮最高约 60 mA（RGB 全白），必须单独供电，不要从开发板 5V 引脚硬拉 |
| 电平 | ESP32 输出 3.3V，部分灯带需要电平转换，数据线最好串一个小电阻，电源端并联大电容 |
| 可选 | 麦克风 (I2S / 模拟)、红外接收头、按键、以太网 |
灯带供电不当可能烧灯珠或烧线，详见 灯光玩法。WLED 提供「自动亮度限制器」，设好电源可承受的电流，固件会自动降低亮度。
上手路径
- 打开 WLED 官网的在线安装器，用 Chrome / Edge 通过 USB 直接刷固件（原理见 烧录工具）。
- 设备启动后出现名为 WLED-AP 的热点，连上后配置家里 Wi-Fi。
- 在 Config 里设置 LED 数量、数据 GPIO 和灯带类型，电源限流值。
- 用网页或 Android / iOS 的 WLED App 控制。
- 在 Home Assistant 里添加 WLED 集成（自动发现）；见 智能家居。
生态与衍生
- 硬件：QuinLED 系列、Athom 等厂商出预刷 WLED 的控制器。
- 软件：WLED Native 手机 App、第三方控制工具；Hyperion、diyHue 用它做屏幕背光和 Hue 替代。
- 对比：同样做灯光，ESPHome 更偏向通用设备，WLED 的灯效库和灯带专用功能更全。
- 社区维护：README 现在要求 AI 辅助的贡献遵守 CONTRIBUTING.md，并为 AI 编码代理准备了 AGENTS.md。
局限与注意事项
- 灯效越多、灯珠越多，对 CPU 和内存压力越大；很多灯效在 ESP8266 上不可用或受限。
- Web 管理界面默认没有密码，OTA 可以设密码；不要把设备端口直接映射到公网。
- 版本号从 0.x 跳到 16.x（README 与 release 标注），大版本升级前先备份预设和配置文件。
- 2D 矩阵的接线映射（蛇形、行列顺序）需要自己按实物设置。
- 灯珠协议时序对 3.3V 电平比较敏感，数据线过长会出现闪烁，需要电平转换。