ugreen_leds_controller 是一款针对绿联（UGREEN）DX/DXP 系列 NAS 的开源LED 控制器，通过 I2C 总线直接操控前面板的电源、网络与硬盘指示灯（颜色、亮度、闪烁、呼吸），让 DSM、TrueNAS、Debian 等第三方系统也能拥有 UGOS 般的灯光效果。如果你的机型不在官方支持列表里，本文教你30 秒自测兼容性，并拆解其 I2C 协议，带你完成从"能不能用"到"怎么扩展"的完整流程。

📌 支持的设备清单：先对号入座

项目目前确认工作的设备如下（来源：README.md）：

💡关键点：列表外 ≠ 不能用。只要你的机器通过下文的协议自测，绝大多数 DX/DXP 机型都可以直接驱动。

🔍 30秒快速检测：你的 NAS 是否兼容协议

LED 控制芯片挂在SMBus I801 adapter的 I2C 地址0x3a上。按下面三步即可判断：

# 1. 安装工具并加载 I2C 模块 apt install -y i2c-tools modprobe -v i2c-dev # 2. 找到 SMBus I801 适配器编号（示例中为 i2c-1） i2cdetect -l # i2c-1 smbus SMBus I801 adapter at efa0 SMBus adapter # 3. 扫描该总线的设备地址 i2cdetect -y 1

如果输出矩阵的30:行中出现3a（或3a UU），说明控制芯片已被识别，你的设备协议兼容概率极高：

30: 30 -- -- -- -- 35 UU UU -- -- 3a -- -- -- -- --

拿到命令行工具后（cd cli && make），再运行一条命令即可看到本机实际可用的全部 LED：

ugreen_leds_cli all

能输出各灯的status / brightness / color，就代表协议完全跑通 🎉。

⚙️ I2C 协议详解：读懂 LED 芯片的"语言"

前面板每颗灯都有一个固定 ID，这是所有通信的基础：

查询状态：从0x81 + LED_ID读 11 字节

以电源灯为例，i2cget -y 0x01 0x3a 0x81 i 0x0b会返回 11 字节，含义如下（完整定义见 README.md 的 Communication Protocols 章节）：

修改状态：向0x00 + LED_ID写 12 字节帧

帧结构是"固定头 + 指令 + 参数 + 校验"，理解它就理解了整个扩展点：

[LED_ID] [0xa0] [0x01] [0x00] [0x00] [CMD] [P1] [P2] [P3] [P4] [CK_H] [CK_L]

指令字节CMD决定操作类型（源码中对应ugreen_leds_t::_change_status，见 cli/ugreen_leds.cpp）：

写完还需读寄存器0x80确认芯片是否执行成功（返回1表示成功），这是 cli/ugreen_leds_cli.cpp 中重试机制的依据。

校验和机制：扩展时最容易踩的坑

校验算法极简——把参与校验的字节按无符号整数直接累加，取 16 位结果，高字节在前。命令行工具与内核模块实现完全一致：

• CLI 端：compute_checksum()/append_checksum()，见 cli/ugreen_leds.cpp
• 内核端：cksum = 0xa1 + command + param1..param4，见 kmod/led-ugreen.c

⚠️ 如果你要扩展新指令或修改帧结构，务必同步两处校验范围（CLI 对0x00~0x08求和；内核帧从固定头0xa0之后开始），否则芯片会静默拒收命令。

🛠️ 协议扩展实操：从源码到自定义驱动

仓库采用"双轨"架构，扩展时可按需选择：

[!IMPORTANT] 两者不能同时使用：启用命令行工具前必须rmmod led_ugreen，反之亦然。

扩展一个新机型的典型思路：

1. 先跑通 CLI：用i2cget/i2cset手工验证 ID、地址与帧结构是否与上文一致；
2. 差异定位：若个别灯无响应，多半是 LED ID 排布不同，只需调整 cli/ugreen_leds.h 中led_type_t枚举的 ID 映射；
3. 新指令类型：若芯片支持未知 CMD，按_change_status()的参数打包方式新增一条命令即可，重试与校验逻辑可直接复用；
4. 固化为内核驱动：验证稳定后，在 kmod/led-ugreen.c 中实现对应的i2c_smbus_write_i2c_block_data调用，并通过 DKMS 随内核自动重编译，配置见 kmod/dkms.conf 与 kmod/debian/。

加载内核模块后的注册流程可参考 scripts/ugreen-probe-leds（含 DKMS 回退构建逻辑）。

🎨 让 LED 真正有用：磁盘映射与颜色配置

灯能亮还不够，灯和盘位的对应关系才是灵魂。scripts/ugreen-diskiomon 提供三种映射方式，全部在 /etc/ugreen-leds.conf 中配置：

可用 scripts/ugreen-detect-disks 一键打印当前映射与序列号。

颜色语义也全部可配，例如硬盘健康/休眠/故障三色、网卡按协商速率变色（100M 绿 / 1G 蓝 / 10G 白）：

# /etc/ugreen-leds.conf 中的关键项 MAPPING_METHOD=ata COLOR_DISK_HEALTH="255 255 255" COLOR_DISK_STANDBY="0 0 255" COLOR_ZPOOL_FAIL="255 0 0" CHECK_LINK_SPEED_DYNAMIC=true # 按速率自动变色的开关

服务由 scripts/systemd/ 下的单元拉起：ugreen-netdevmon@<网卡>负责网络灯、ugreen-diskiomon负责硬盘灯、ugreen-power-led负责电源灯呼吸/常亮（配置项BLINK_TYPE_POWER）。

✅ 实测验证清单：确认适配成功的 3 步

1. 状态自检：ugreen_leds_cli all -status，所有灯均能读回状态而非unavailable；
2. 点亮测试：ugreen_leds_cli disk1 -on -color 255 0 0 -blink 400 600，观察对应盘位是否红光闪烁；
3. 负载联动：dd if=/dev/sdX of=/dev/null bs=1M count=100制造 I/O，确认该盘位 LED 随读写闪动（即ugreen-detect-disks脚本末尾的验证方法）。

💡 如果你的机型测试通过，欢迎把结果反馈给项目维护者更新支持列表——这正是 DX4800、DXP4800 等机型进入 ✅ 状态的方式，也是社区推动 iDX6011 Pro 等新机型适配的主要途径。

总结：ugreen_leds_controller 的核心壁垒不在驱动本身，而在对0x3a芯片12 字节帧 + 16 位加和校验协议的逆向分析。只要你的 NAS 能通过i2cdetect看到0x3a，大概率只需微调 LED ID 映射，就能把第三方系统的"死灯"变成与 UGOS 一样会"呼吸"的指示灯。