ugreen_leds_controller drives the front panel LEDs on UGREEN DX and DXP NAS hardware

Third party operating systems lose the front panel LEDs

UGREEN's DX and DXP NAS series covers two to eight bay devices with a built-in system based on OpenWRT called UGOS, or Debian called UGOS-Pro. Debian Linux and dedicated NAS operating systems are compatible with the hardware, but they do not have drivers for the LED lights on the front panel that indicate power, network and hard drive activity.

The consequence is specific and visible. On a third party system with, for example, a DX 4600 Pro, only the power indicator light blinks and the other LEDs are off by default. On the DXP series, all the LEDs blink in a rolling sequence when a non-UGOS system is running. So the hardware is not broken and the LEDs are not dead, the driver that drives them is simply missing.

This project has two stated goals. It describes the control logic of UGOS for the LED lights on the device front, and it provides a command line tool and a kernel module to control them. The first part is a reverse engineering write-up, and the author points to a blog post in Chinese for the process of understanding the control logic.

It is worth being clear about who this is for. The user is somebody who bought the hardware, replaced the vendor operating system, and now has a NAS whose front panel looks half dead. The value is in restoring a small hardware feature that the vendor software provides and the open source alternatives do not.

The chip sits at 0x3a on the SMBus I801 adapter

The mechanism is I2C. The README states that the control chip of the LED is reached over I2C, corresponding to the device with address 0x3a on the SMBus I801 adapter. Before any of that works you need the i2c-dev kernel module loaded and the i2c-tools package installed:

$ apt install -y i2c-tools
$ modprobe -v i2c-dev

Then you can list the adapters and probe the bus to confirm the chip is there:

$ i2cdetect -l
i2c-0   i2c             Synopsys DesignWare I2C adapter         I2C adapter
i2c-1   smbus           SMBus I801 adapter at efa0              SMBus adapter
i2c-2   i2c             Synopsys DesignWare I2C adapter         I2C adapter

The probe output in the README shows the address 3a present in the 30 row of bus 1, alongside entries that are marked UU because they are already claimed by a driver, and a couple of other addresses such as 30, 35 and 44 that respond.

This check is the first thing to run on any new model, and the README asks you to run it before proceeding. The protocol is not guaranteed to be identical across the DX and DXP families, so seeing the chip at the expected address is necessary but not sufficient, which is why the project also asks you to run the CLI against your unit and see which LEDs it reports as supported.

The CLI and the kernel module cannot both own the LEDs

There is an important conflict, and the README marks it as important. The command line tool and the kernel module do conflict, and to use the command line tool you must unload the led_ugreen module.

That is the whole ownership model. The kernel module registers a driver that claims the chip and drives the LEDs continuously, which is what you want when the LEDs should reflect disk activity on its own. The command line tool talks to the same chip directly, which is what you want when you are scripting a specific colour or blink pattern. You pick one, and the other has to stand down.

The build for the tool is a plain make in the cli directory, and running the resulting binary requires root permissions.

The command line interface takes LED names followed by options. The usage text spells out the shape:

Usage: ugreen_leds_cli  [LED-NAME...] [-on] [-off] [-(blink|breath) T_ON T_OFF]
                    [-color R G B] [-brightness BRIGHTNESS] [-status]

The LED names are separated by white space and the possible values are power, netdev, disk[1-8] and all. The -on and -off flags turn the corresponding LEDs on or off, and -blink or -breath sets the LED to that mode, keeping it on for T_ON milliseconds and then off for T_OFF milliseconds, with both values in the range 0 to 65535. The -color option takes R, G and B in the range 0 to 255, and -brightness sets the brightness of the corresponding LEDs.

The naming is worth reading carefully. The tool calls the network activity indicator netdev and the drive indicators disk1 through disk8, which is a mapping you will have to work out for your own unit rather than assume.

A short script is all it takes to drive the whole panel

The example in the README shows the intended usage pattern, and it is worth reading as a template because it shows the argument order and the rhythm of the calls:

ugreen_leds_cli all -off -status
ugreen_leds_cli power  -color 255 0 255 -blink 400 600
sleep 0.1
ugreen_leds_cli netdev -color 255 0 0   -blink 400 600
sleep 0.1
ugreen_leds_cli disk1  -color 255 255 0 -blink 400 600
sleep 0.1
ugreen_leds_cli disk2  -color 0 255 0   -blink 400 600
sleep 0.1
ugreen_leds_cli disk3  -color 0 255 255 -blink 400 600
sleep 0.1
ugreen_leds_cli disk4  -color 0 0 255   -blink 400 600

The pattern is to turn everything off first with -off and -status, then set each LED in turn with its own colour and blink timing, with a tenth of a second between calls. The -status flag is what makes the first call useful, since it reports the current state of the LEDs rather than changing anything.

The colour values are plain RGB triples, and the blink timing is a pair of milliseconds for on and off. In the example the power light is magenta blinking at 400 on and 600 off, the network light is red with the same timing, and the four disk lights cycle through yellow, green, cyan and blue. That sequence is illustrative rather than a config format, since the tool takes its arguments on the command line and does not read a configuration file.

The blink and breath modes are alternatives rather than additions, and T_ON and T_OFF share the same 0 to 65535 range, so a breath mode is expressed by choosing an on and off duration that produces the effect you want.

One repository, many operating systems, and a compatibility caveat

The author develops on Debian 12 Bookworm for third party systems, and the README points to per system instructions elsewhere. Synology DSM has its own issue thread, Proxmox has the note that you need to use the CLI tool in Proxmox and not in a virtual machine, since the hardware is not passed through to the guest, and TrueNAS has issue threads plus a separate install repository and a build script branch. The TrueNAS build scripts are also published as pre-build drivers, and the README explains that the default directories are built from master while tag builds such as v0.3 and v0.4-beta live under a tags directory.

unRAID is covered by a plugin on the community forums with its own related repository. So the project is not a Debian-only tool with a mention of others; it has a maintained path per platform, and the differences between them are mostly about how you get the module and driver onto the box.

The compatibility caveat is the part to take seriously. The README marks the list of tested and working devices, and the entries are not uniform. The DX4600 Pro, DX4700+, DXP2800, DXP4800, DXP4800 Plus, DXP4800 Pro, DXP6800 Pro and DXP8800 Plus are listed as working. The DXP2800 V1.2, DXP4800 GT, and the iDX6011 and iDX6011 Pro are listed as experimental and available on the v0.4-beta release. The DXP480T Plus and the DXP2800 GT are marked as work in progress.

Underneath the list the author is blunt: I am not sure whether this module is compatible with other devices, and if you have tested it on other hardware, please feel free to update the list. That is an honest statement of the limits of reverse engineered hardware control, and it is why the project ships a SPECS/ directory and asks people to check the protocol themselves rather than assuming.

Releases track both hardware support and the base system

The release history shows two axes of change. v0.4-beta, published on 2026-07-07, is titled for experimental iDX6011 series support, and the README confirms that the experimental entries for the DXP2800 V1.2, the DXP4800 GT and the iDX6011 are available on that tag. v0.3, published on 2025-03-20, is titled Debian 12, and v0.2 from 2024-11-01 is also titled Debian 12, which suggests the earlier release covered a different Debian generation and the numbering tracked the base system rather than the hardware list.

That naming tells you something useful. A version tag here is not just a code version, it is a statement about which operating system and which devices that code was built against. The README makes the same point about the pre-build drivers, where the tag directory matters.

Maintenance is current. The last push was on 2026-09-27 and the repository is not archived. The topics list is minimal, just nas, but the release cadence and the presence of pre-built driver branches in the repository point to a project that is kept in step with the hardware rather than abandoned.

The licence is MIT, with a LICENSE file at the repository root, so you can take the build scripts and the driver and adapt them to a platform the upstream does not cover, which is exactly what the TrueNAS and unRAID integrations appear to have done. That is a licensing note rather than legal advice, and it says nothing about the trademark status of the devices themselves.

Editorial conclusion

Adopt this project if you run a UGREEN DX or DXP NAS on a third party operating system and want the power, network and disk activity indicators back, since the vendor OS is the only thing supplying those drivers. Do not adopt it if your device is not on the tested list, because the protocol differs between models and the author is explicit that compatibility with other hardware is unknown. Verify first by loading i2c-dev, installing i2c-tools and checking whether the control chip is visible at 0x3a on the SMBus I801 adapter, then run ugreen_leds_cli all to see which LEDs your unit supports before touching any drivers.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. miskcoo/ugreen_leds_controller on GitHub
4. README
5. Releases