名称： wled
描述： 通过 HTTP API 控制 WLED LED 控制器。当用户要求控制 WLED 灯具、LED 灯带或基于 ESP 的 LED 控制器时使用。支持开关、亮度、颜色（RGB）、特效、调色板、预设和设备状态查询。

WLED 控制

通过 HTTP JSON API 控制 WLED LED 灯带和矩阵。

要求

• WLED 设备位于同一网络
• 设备 IP 地址或主机名
• Python 3（无需外部依赖）

使用方法

所有命令都需要通过 --host（或 -H）指定 WLED 设备的 IP 或主机名。

电源控制

python3 scripts/wled.py -H <ip> power          # 获取电源状态
python3 scripts/wled.py -H <ip> power on       # 开启
python3 scripts/wled.py -H <ip> power off      # 关闭

亮度控制

python3 scripts/wled.py -H <ip> brightness          # 获取当前亮度
python3 scripts/wled.py -H <ip> brightness 255      # 最大亮度
python3 scripts/wled.py -H <ip> brightness 128      # 50% 亮度

颜色设置

python3 scripts/wled.py -H <ip> color 255 0 0       # 红色
python3 scripts/wled.py -H <ip> color 0 255 0       # 绿色
python3 scripts/wled.py -H <ip> color 0 0 255       # 蓝色
python3 scripts/wled.py -H <ip> color 255 255 255   # 白色

特效控制

python3 scripts/wled.py -H <ip> effects             # 列出所有特效及其 ID
python3 scripts/wled.py -H <ip> effect 0            # 纯色模式
python3 scripts/wled.py -H <ip> effect 9            # 彩虹特效
python3 scripts/wled.py -H <ip> effect 9 -s 200     # 彩虹特效，快速模式
python3 scripts/wled.py -H <ip> effect 9 -i 128     # 彩虹特效，中等强度

调色板设置

python3 scripts/wled.py -H <ip> palettes            # 列出所有调色板及其 ID
python3 scripts/wled.py -H <ip> palette 6           # 设置派对调色板

预设管理

python3 scripts/wled.py -H <ip> presets             # 列出已保存的预设
python3 scripts/wled.py -H <ip> preset 1            # 加载预设 #1

设备状态

python3 scripts/wled.py -H <ip> status              # 获取完整设备状态

参考文档

完整 API 文档请参阅 references/api.md。

配置

为避免每次输入 --host，可在 ~/.wled/config.json 创建配置文件：

{
  "bedroom": "192.168.1.100",
  "kitchen": "192.168.1.101",
  "living_room": "wled-abc123.local"
}

之后即可使用别名：

python3 scripts/wled.py -H bedroom brightness 255
python3 scripts/wled.py -H kitchen color 255 0 0

或设置 WLED_HOST 环境变量：

export WLED_HOST=192.168.1.100
python3 scripts/wled.py brightness 255

查找 WLED 设备

通常可通过以下方式找到 WLED 设备：
- 路由器管理界面（查找 ESP 设备）
- mDNS/Bonjour：wled-<mac>.local
- WLED 应用设备发现功能

静态 IP 设置建议

IP 地址可能随时间变化。为避免频繁更新配置，建议为 WLED 设备设置静态 IP：

方案一：通过路由器设置（最简单）
1. 打开路由器管理界面
2. 通过 MAC 地址找到 WLED 设备
3. 为其保留/分配静态 IP

方案二：在设备上设置
1. 通过 http://<当前IP> 访问 WLED Web 界面
2. 进入“设置” → “WiFi 设置”
3. 手动设置静态 IP
4. 保存并重启设备

使用 mDNS 主机名（如 wled-abc123.local）也可避免 IP 变动问题——路由器会自动解析这些名称。