ich777/ugreen_dx4600_leds_controller
1
0
Fork 0
mirror of https://github.com/miskcoo/ugreen_dx4600_leds_controller.git synced 2025-07-23 20:30:46 +02:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

README: Update & Small improvements (#32)
Some checks failed
Build kernel module for TrueNAS / build-and-run (push) Has been cancelled
Details

Browse Source 
* repo rename

* layout and wording

* wording
This commit is contained in:
tooomm
2024-10-21 19:11:45 +02:00
committed by GitHub
parent c1386fc251
commit 241ff6bfa2
1 changed files with 94 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
README.md
View File

@@ -1,32 +1,39 @@
LED Controller of UGREEN's DX4600 Pro NAS LED Controller for UGREEN's DX/DXP NAS Series
== ==
UGREEN's DX4600 Pro is a four-bay NAS with a built-in system based on OpenWRT called `UGOS`. It can install Debian or other open-source NAS systems, but the issue is that the installed non-UGOS system does not have drivers for the six LED lights on the front panel (indicating power, network card, and four hard drives). By default, only the power indicator light blinks, and other indicator lights are off. UGREEN's DX/DXP NAS Series covers 2 to 8 bay NAS devices with a built-in system based on OpenWRT called `UGOS`.
Debian Linux or dedicated NAS operating systems and appliances are compatible with the hardware, but do not have drivers for the LED lights on the front panel to indicate power, network and hard drive activity.
Instead, when using a 3rd party OS with DX 4600 Pro, only the power indicator light blinks, and the other LEDs are off by default.
This repository describes the control logic of UGOS for these LED lights and provides a command-line tool and a kernel module to control them. For the process of understanding this control logic, please refer to [my blog (in Chinese)](https://blog.miskcoo.com/2024/05/ugreen-dx4600-pro-led-controller). This repository
- describes the control logic of UGOS for these LED lights
- provides a command-line tool and a kernel module to control them
**WARNING:** Only tested on the following devices. For other devices, please follow the [Preparation](#Preparation) section to check if the protocol is compatible, and run `./ugreen_leds_cli all` to see which LEDs are supported by this tool. For the process of understanding this control logic, please refer to [my blog (in Chinese)](https://blog.miskcoo.com/2024/05/ugreen-dx4600-pro-led-controller).
- [x] UGREEN DX4600 Pro > [!NOTE]
- [x] UGREEN DX4700+ > Only tested on the following devices:
- [x] UGREEN DXP2800 (reported in [#19](https://github.com/miskcoo/ugreen_dx4600_leds_controller/issues/19)) > - [x] UGREEN DX4600 Pro
- [x] UGREEN DXP4800 Plus (reported [here](https://gist.github.com/Kerryliu/c380bb6b3b69be5671105fc23e19b7e8)) > - [x] UGREEN DX4700+
- [x] UGREEN DXP6800 Pro (reported in [#7](https://github.com/miskcoo/ugreen_dx4600_leds_controller/issues/7)) > - [x] UGREEN DXP2800 (reported in [#19](https://github.com/miskcoo/ugreen_leds_controller/issues/19))
- [x] UGREEN DXP8800 Plus (see [this repo](https://github.com/meyergru/ugreen_dxp8800_leds_controller) and [#1](https://github.com/miskcoo/ugreen_dx4600_leds_controller/issues/1)) > - [x] UGREEN DXP4800 Plus (reported [here](https://gist.github.com/Kerryliu/c380bb6b3b69be5671105fc23e19b7e8))
- [ ] UGREEN DXP480T Plus (**NO**, but the protocol has been understood, see [#6](https://github.com/miskcoo/ugreen_dx4600_leds_controller/issues/6#issuecomment-2156807225)) > - [x] UGREEN DXP6800 Pro (reported in [#7](https://github.com/miskcoo/ugreen_leds_controller/issues/7))
> - [x] UGREEN DXP8800 Plus (see [this repo](https://github.com/meyergru/ugreen_dxp8800_leds_controller) and [#1](https://github.com/miskcoo/ugreen_leds_controller/issues/1))
> - [ ] UGREEN DXP480T Plus (**Not yet**, but the protocol has been understood, see [#6](https://github.com/miskcoo/ugreen_leds_controller/issues/6#issuecomment-2156807225))
>
>**I am not sure whether this is compatible with other devices.
>If you have tested it with different devices, please feel free to update the list above!**
>
> Please follow the [Preparation](#Preparation) section to check if the protocol is compatible, and run `./ugreen_leds_cli all` to see which LEDs are supported by this tool.
**I am not sure whether this is compatible with other devices. If you have tested it in other devices, please feel free to update the list above.** For third-party systems, I am using Debian 12 "Bookworm", but you can find some manuals for other systems:
- **DSM**: see [#8](https://github.com/miskcoo/ugreen_leds_controller/issues/8)
For third-party systems, I am using Debian 12, but you can find some manuals for other systems: - **TrueNAS**: see [#13](https://github.com/miskcoo/ugreen_leds_controller/issues/13) (and maybe [here](https://github.com/miskcoo/ugreen_leds_controller/tree/truenas-build/build-scripts/truenas)) for how to build the module, and [here](https://gist.github.com/Kerryliu/c380bb6b3b69be5671105fc23e19b7e8) for a script using the cli tool; [here](https://github.com/miskcoo/ugreen_leds_controller/tree/gh-actions/build-scripts/truenas/build) for pre-build drivers
- **unRAID**: there is a [plugin](https://forums.unraid.net/topic/168423-ugreen-nas-led-control/); see also [this repo](https://github.com/ich777/unraid-ugreenleds-driver/tree/master/source/usr/bin)
- DSM: see [#8](https://github.com/miskcoo/ugreen_dx4600_leds_controller/issues/8) - **Proxmox**: you need to use the cli tool in Proxmox, not in a VM
- TrueNAS: see [#13](https://github.com/miskcoo/ugreen_dx4600_leds_controller/issues/13) (and maybe [here](https://github.com/miskcoo/ugreen_dx4600_leds_controller/tree/truenas-build/build-scripts/truenas)) for how to build the module, and [here](https://gist.github.com/Kerryliu/c380bb6b3b69be5671105fc23e19b7e8) for a script using the cli tool; [here](https://github.com/miskcoo/ugreen_dx4600_leds_controller/tree/gh-actions/build-scripts/truenas/build) for pre-build drivers - **Debian**: see [the section below](#start-at-boot-for-debian-12)
- unRAID: there is a [plugin](https://forums.unraid.net/topic/168423-ugreen-nas-led-control/); see also [this repo](https://github.com/ich777/unraid-ugreenleds-driver/tree/master/source/usr/bin)
- Proxmox: you need to use the cli tool in Proxmox, not in a VM
- Debian: see [the section below](https://github.com/miskcoo/ugreen_dx4600_leds_controller#start-at-boot-for-debian-12)
Below is an example:
Below is an example:
![](https://blog.miskcoo.com/assets/images/dx4600-pro-leds.gif) ![](https://blog.miskcoo.com/assets/images/dx4600-pro-leds.gif)
It can be achieved by the following commands: It can be achieved by the following commands:
@@ -76,7 +83,9 @@ $ i2cdetect -y 1
## Build & Usage ## Build & Usage
**Note**: The kernel module and the command-line tool are conflict. To use the command-line tool, you must unload the `led_ugreen` module. > [!IMPORTANT]
> The command-line tool and the kernel module do conflict.
> To use the command-line tool, you must unload the `led_ugreen` module.
### The Command-line Tool ### The Command-line Tool
@@ -130,7 +139,7 @@ There are three methods to install the module:
dkms build -m led-ugreen -v 0.1 && dkms install -m led-ugreen -v 0.1 dkms build -m led-ugreen -v 0.1 && dkms install -m led-ugreen -v 0.1
``` ```
- You can also directly install the package [here](https://github.com/miskcoo/ugreen_dx4600_leds_controller/releases). - You can also directly install the package [here](https://github.com/miskcoo/ugreen_leds_controller/releases).
After loading the `led-ugreen` module, you need to run `scripts/ugreen-probe-leds`, and you can see LEDs in `/sys/class/leds`. After loading the `led-ugreen` module, you need to run `scripts/ugreen-probe-leds`, and you can see LEDs in `/sys/class/leds`.
@@ -155,56 +164,60 @@ echo 1 > /sys/class/leds/$led/rx
echo 100 > /sys/class/leds/$led/interval echo 100 > /sys/class/leds/$led/interval
``` ```
To blink the `disk` LED when a block device is active, you can use the `ledtrig-oneshot` module and monitor the changes of`/sys/block/sda/stat` (see `scripts/ugreen-diskiomon` for an example). If you are using zfs, you can combine this script with that provided in [#1](https://github.com/miskcoo/ugreen_dx4600_leds_controller/issues/1) to change the LED's color when a disk drive failure occurs. To see how to map the disk LEDs to correct disk slots, please read the [Disk Mapping](#disk-mapping) section. To blink the `disk` LED when a block device is active, you can use the `ledtrig-oneshot` module and monitor the changes of`/sys/block/sda/stat` (see `scripts/ugreen-diskiomon` for an example). If you are using zfs, you can combine this script with that provided in [#1](https://github.com/miskcoo/ugreen_leds_controller/issues/1) to change the LED's color when a disk drive failure occurs.
To see how to map the disk LEDs to correct disk slots, please read the [Disk Mapping](#disk-mapping) section.
#### Start at Boot (for Debian 12) #### Start at Boot (for Debian 12)
The configure file of `ugreen-diskiomon` and `ugreen-netdevmon` is `/etc/ugreen-led.conf`. Please see `scripts/ugreen-leds.conf` for an example. The configure file of `ugreen-diskiomon` and `ugreen-netdevmon` is `/etc/ugreen-led.conf`.
Please see `scripts/ugreen-leds.conf` for an example.
- Edit `/etc/modules-load.d/ugreen-led.conf` and add the following lines: - Edit `/etc/modules-load.d/ugreen-led.conf` and add the following lines:
``` ```
i2c-dev i2c-dev
led-ugreen led-ugreen
ledtrig-oneshot ledtrig-oneshot
ledtrig-netdev ledtrig-netdev
``` ```
- Install the `smartctl` tool: `apt install smartmontools` - Install the `smartctl` tool: `apt install smartmontools`
- Install the kernel module by one of the three methods mentioned above. For example, directly install [the deb package](https://github.com/miskcoo/ugreen_dx4600_leds_controller/releases). - Install the kernel module by one of the three methods mentioned above. For example, directly install [the deb package](https://github.com/miskcoo/ugreen_leds_controller/releases).
- Copy files in the `scripts` directory: - Copy files in the `scripts` directory:
```bash ```bash
# copy the scripts # copy the scripts
scripts=(ugreen-diskiomon ugreen-netdevmon ugreen-probe-leds) scripts=(ugreen-diskiomon ugreen-netdevmon ugreen-probe-leds)
for f in ${scripts[@]}; do for f in ${scripts[@]}; do
chmod +x "scripts/$f" chmod +x "scripts/$f"
cp "scripts/$f" /usr/bin cp "scripts/$f" /usr/bin
done done
# copy the configuration file, you can change it if needed # copy the configuration file, you can change it if needed
cp scripts/ugreen-leds.conf /etc/ugreen-leds.conf cp scripts/ugreen-leds.conf /etc/ugreen-leds.conf
# copy the systemd services # copy the systemd services
cp scripts/*.service /etc/systemd/system/ cp scripts/*.service /etc/systemd/system/
systemctl daemon-reload systemctl daemon-reload
# change enp2s0 to the network device you want to monitor # change enp2s0 to the network device you want to monitor
systemctl start ugreen-netdevmon@enp2s0 systemctl start ugreen-netdevmon@enp2s0
systemctl start ugreen-diskiomon systemctl start ugreen-diskiomon
# if you confirm that everything works well, # if you confirm that everything works well,
# run the command below to make the service start at boot # run the command below to make the service start at boot
systemctl enable ugreen-netdevmon@enp2s0 systemctl enable ugreen-netdevmon@enp2s0
systemctl enable ugreen-diskiomon systemctl enable ugreen-diskiomon
``` ```
## Disk Mapping ## Disk Mapping
To make the disk LEDs useful, we should map the disk LEDs to correct disk slots. First of all, we should highlight that using `/dev/sdX` is never a smart idea, as it may change at every boot. In the script `ugreen-diskiomon` we provide three mapping methods: **by ATA**, **by HCTL** and **by serial**. To make the disk LEDs useful, we should map the disk LEDs to correct disk slots. First of all, we should highlight that using `/dev/sdX` is never a smart idea, as it may change at every boot.
In the script `ugreen-diskiomon` we provide three mapping methods: **by ATA**, **by HCTL** and **by serial**.
The best mapping method is using serial numbers, but it needs to record them manually and fill the `DISK_SERIAL` array in `/etc/ugreen-leds.conf`. We use ATA mapping by default, and find that UGOS also uses a similar mapping method (see [#15](https://github.com/miskcoo/ugreen_dx4600_leds_controller/pull/15)). See the comments in `scripts/ugreen-leds.conf` for more details. The best mapping method is using serial numbers, but it needs to record them manually and fill the `DISK_SERIAL` array in `/etc/ugreen-leds.conf`. We use ATA mapping by default, and find that UGOS also uses a similar mapping method (see [#15](https://github.com/miskcoo/ugreen_leds_controller/pull/15)).
See the comments in `scripts/ugreen-leds.conf` for more details.
The HCTL mapping depends on how the SATA controllers are connected to the PCIe bus and the disk slots. To check the HCTL order, you can run the following command, and check the serial of your disks: The HCTL mapping depends on how the SATA controllers are connected to the PCIe bus and the disk slots. To check the HCTL order, you can run the following command, and check the serial of your disks:
@@ -220,18 +233,25 @@ sdf 5:0:0:0 XXGT2ZXX
sdg 6:0:0:0 XXKH3SXX sdg 6:0:0:0 XXKH3SXX
sdh 7:0:0:0 XXJDB1XX sdh 7:0:0:0 XXJDB1XX
``` ```
> [!NOTE]
As far as we know, the mapping between HCTL and the disk serial are stable at each boot (see [#4](https://github.com/miskcoo/ugreen_dx4600_leds_controller/pull/4) and [#9](https://github.com/miskcoo/ugreen_dx4600_leds_controller/issues/9)). However, it has been reported that the exact order is model-dependent (see [#9](https://github.com/miskcoo/ugreen_dx4600_leds_controller/issues/9)). In DX4600 Pro and DXP8800 Plus, the mapping is `X:0:0:0 -> diskX`, but in DXP6800 Pro, `0:0:0:0` and `1:0:0:0` are mapped to `disk5` and `disk6`, and `2:0:0:0` to `6:0:0:0` are mapped to `disk1` to `disk4`. The script will use `dmidecode` to detect the device model, but I suggest to check the mapping outputed by the script manually. > As far as we know, the mapping between HCTL and the disk serial are stable at each boot (see [#4](https://github.com/miskcoo/ugreen_leds_controller/pull/4) and [#9](https://github.com/miskcoo/ugreen_leds_controller/issues/9)).
> However, it has been reported that the exact order is model-dependent (see [#9](https://github.com/miskcoo/ugreen_leds_controller/issues/9)).
> - For DX4600 Pro and DXP8800 Plus, the mapping is `X:0:0:0 -> diskX`.
> - For DXP6800 Pro, `0:0:0:0` and `1:0:0:0` are mapped to `disk5` and `disk6`, and `2:0:0:0` to `6:0:0:0` are mapped to `disk1` to `disk4`.
>
> The script will use `dmidecode` to detect the device model, but I suggest to check the mapping outputed by the script manually.
## Communication Protocols ## Communication Protocols
The IDs for the six LED lights on the front panel of the chassis are as follows: The IDs for the six LED lights on the front panel of the DX4600 Pro chassis are as follows:
- power indicator light = 0; | ID | LED |
- network device indicator light = 1; |------|--------------------------------|
- four hard drive indicator lights = 2 - 5. | 0 | power indicator |
| 1 | network device indicator |
| 2-5 | hard drive indicator 1-4 |
### Query status ### Query Status
Reading 11 bytes from the address `0x81 + LED_ID` allows us to obtain the current status of the corresponding LED. The meaning of these 11 bytes is as follows: Reading 11 bytes from the address `0x81 + LED_ID` allows us to obtain the current status of the corresponding LED. The meaning of these 11 bytes is as follows:
@@ -254,11 +274,10 @@ The checksum is a 16-bit value obtained by summing all the data at the correspon
We can directly use `i2cget` to read from the relevant registers. For example, below is the status of the power indicator light (purple, blinking once per second, lit for 40% of the time, with a brightness of 180/256): We can directly use `i2cget` to read from the relevant registers. For example, below is the status of the power indicator light (purple, blinking once per second, lit for 40% of the time, with a brightness of 180/256):
``` ```
$ i2cget -y 0x01 0x3a 0x81 i 0x0b $ i2cget -y 0x01 0x3a 0x81 i 0x0b 0x02 0xb4 0xff 0x00 0xff 0x03 0xe8 0x01 0x90 0x04 0x30
0x02 0xb4 0xff 0x00 0xff 0x03 0xe8 0x01 0x90 0x04 0x30
``` ```
### Change status ### Change Status
By writing 12 bytes to the address `0x00 + LED_ID`, we can modify the current status of the corresponding LED. The meaning of these 12 bytes is as follows: By writing 12 bytes to the address `0x00 + LED_ID`, we can modify the current status of the corresponding LED. The meaning of these 12 bytes is as follows:
@@ -287,8 +306,11 @@ For the four different modification types at address 0x05:
Below is an example for turning off and on the power indicator light using `i2cset`: Below is an example for turning off and on the power indicator light using `i2cset`:
``` ```
$ i2cset -y 0x01 0x3a 0x00 0x00 0xa0 0x01 0x00 0x00 0x03 0x01 0x00 0x00 0x00 0x00 0xa5 i # turn off power LED # turn off power LED
$ i2cset -y 0x01 0x3a 0x00 0x00 0xa0 0x01 0x00 0x00 0x03 0x00 0x00 0x00 0x00 0x00 0xa4 i # turn on power LED $ i2cset -y 0x01 0x3a 0x00 0x00 0xa0 0x01 0x00 0x00 0x03 0x01 0x00 0x00 0x00 0x00 0xa5 i
# turn on power LED
$ i2cset -y 0x01 0x3a 0x00 0x00 0xa0 0x01 0x00 0x00 0x03 0x00 0x00 0x00 0x00 0x00 0xa4 i
``` ```
## Acknowledgement ## Acknowledgement