Ahmad Gul Zadran

Get a UGREEN US3000 UPS reporting properly on TrueNAS SCALE

Make a UGREEN US3000 UPS show charge, battery voltage and load on TrueNAS, and keep it working after updates.

intermediate30 minupdated 2026-10-13nuttruenasugreenupsDownload script.sh

Before you start

  • TrueNAS SCALE, with the UPS connected by USB
  • A UGREEN US3000 (vendor 2b89, product ffff)
  • Shell access as an administrator. A few checks need root.
  • A ZFS pool where you can put the driver, so it survives updates

Your values

Fill these in and every command below updates to match. Nothing is sent anywhere.

Run this at your own risk. These steps worked on my hardware; yours may differ. Take a backup first, read each command before running it, and see the disclaimer.

The UGREEN US3000 uses its own USB (HID) protocol, not the standard one for power devices. NUT's built-in usbhid-ups driver can see that the UPS exists, but not much more. You only get on-line or on-battery. No charge percentage, no cell voltages, no load.

This guide installs a community driver. It reads the raw data from the UPS directly and gives it to NUT in the right form.

The steps follow the installation guide of the driver project. The output below comes from a working install on a DXP4800 Plus. Check the output after each step, instead of running everything at once and hoping it works.

Check the UPS is actually visible

Before you install anything, check that the system sees the UPS. The US3000 shows up with vendor ID 2b89 and product ID ffff.

bash
lsusb | grep -i 2b89
expected output
Bus 001 Device 004: ID 2b89:ffff UGREEN UPS

If nothing comes back, stop here. No driver helps until the USB cable is connected and the system detects the device. Try the other USB port and another cable before you assume the UPS is broken.

Understand why the built-in driver is not enough

It is good to know why you install a custom driver instead of the one that comes with the system, because it matters when TrueNAS updates.

NUT added proper US3000 support in its Arduino HID subdriver, but only in NUT 2.8.4. TrueNAS SCALE still comes with an older NUT, so you do not have this fix yet. When TrueNAS includes a newer NUT, you no longer need this driver and can remove it.

Also good to know: newer TrueNAS SCALE versions no longer have the UPS widget on the dashboard. If it is missing, your setup is not broken, so do not waste time looking for it.

Choose a location that survives updates

This is the step where people make mistakes.

The TrueNAS root filesystem is read-only, and /tmp is mounted noexec, so programs cannot run from it. You cannot install into either one. Also, a system update deletes anything that is not on a pool.

So the driver goes on a pool, under a path you choose:

bash
mkdir -p /mnt/tank/apps/ugreen-ups-driver
cd /mnt/tank/apps/ugreen-ups-driver

Fetch the driver

If your TrueNAS has git:

bash
cd /mnt/tank/apps/ugreen-ups-driver
git clone https://github.com/meestaben/ugreen-ups-driver.git .

TrueNAS does not always include git. If the command is not found, download the archive instead. The result is the same:

bash
cd /mnt/tank/apps/ugreen-ups-driver
curl -L -o ugreen-ups.zip https://github.com/meestaben/ugreen-ups-driver/archive/refs/heads/main.zip
unzip ugreen-ups.zip
mv ugreen-ups-driver-main/* .
rm -rf ugreen-ups-driver-main ugreen-ups.zip

Run the installer

The installer copies the driver into place and creates a systemd service. It adds the driver to NUT's driver list and sets up the TrueNAS UPS service through the TrueNAS API, not by editing files. It also adds a post-init script.

The last part is important. A TrueNAS update removes changes to the system filesystem, and the post-init script puts them back after each start.

bash
cd /mnt/tank/apps/ugreen-ups-driver
chmod +x install-ugreen-ups.sh
./install-ugreen-ups.sh install /mnt/tank/apps/ugreen-ups-driver

Check the service is running

bash
systemctl status ugreen-ups-driver --no-pager
expected output
* ugreen-ups-driver.service - UGREEN US3000 UPS NUT Driver
     Loaded: loaded (/etc/systemd/system/ugreen-ups-driver.service; enabled; preset: enabled)
     Active: active (running) since Fri 2026-09-04 10:02:28 CEST; 1 week 1 day ago
   Main PID: 3040 (python3)
      Tasks: 3 (limit: 37555)
     Memory: 8.1M
     CGroup: /system.slice/ugreen-ups-driver.service
             `-3040 /usr/bin/python3 /mnt/tank/apps/ugreen-ups-driver/ugreen_ups_driver.py --port 3494

Look for two things. enabled means it starts again after a reboot. And the command line shows that the driver runs from your pool, not from the system filesystem. That is why it survives updates.

A warning about permissions for journal files is normal when you are not root. It does not mean something is wrong.

Read live values from the UPS

This is the real test. upsc asks NUT for every value the driver provides.

bash
upsc ugreen@localhost:3494
expected output
battery.capacity: 43
battery.cell.1.voltage: 4.096
battery.cell.2.voltage: 4.093
battery.cell.3.voltage: 4.091
battery.cell.4.voltage: 4.091
battery.charge: 98
battery.charge.low: 20
battery.voltage: 16.350
battery.voltage.nominal: 14
device.mfr: UGREEN
device.model: US3000
device.type: ups
driver.name: ugreen-hid-py
driver.version: 0.1
input.current: 2.370
input.voltage: 18.765
output.voltage.nominal: 12
ups.load: 0
ups.mfr: UGREEN
ups.model: US3000
ups.status: OL

Your numbers will be different. What matters: the fields have values and do not say unknown, and ups.status is OL (on mains power).

Do not expect mains voltage here. The US3000 sits between a DC power adapter and the NAS. So input.voltage is the DC input (about 19 V), and output.voltage.nominal is what it gives to the NAS (12 V). 18 V instead of 230 V is correct, not an error.

There is also no battery.runtime field. Estimate the remaining time from battery.charge and battery.capacity instead.

To watch it live while you unplug the power and plug it in again:

bash
journalctl -u ugreen-ups-driver -f

About the NUT configuration

The installer sets up NUT for you through the TrueNAS API, so usually you do not need to edit anything by hand.

Only root can read those files. A normal admin account gets Permission denied on /etc/nut/ups.conf. That is expected, not a problem.

This setup has two steps on purpose. The Python driver talks to the UPS and provides the values on its own port. NUT reads from that port. This way it works without changing NUT itself.

The UPS service in TrueNAS once the installer has run
The UPS service in TrueNAS once the installer has run

Reboot and check it comes back

Do not skip this. A UPS driver that stops working after the next reboot is worse than no driver, because you think you are protected when you are not.

Reboot the way you normally do: from the TrueNAS web interface, or from a shell:

bash
sudo reboot

After it comes back up:

bash
systemctl status ugreen-ups-driver --no-pager
upsc ugreen@localhost:3494 ups.status

Removing it later

When TrueNAS comes with NUT 2.8.4 or newer, the built-in usbhid-ups driver should support this UPS, and you can remove the custom driver.

bash
Destructive command. Read it before running it. This can delete data or interrupt service.
cd /mnt/tank/apps/ugreen-ups-driver
./install-ugreen-ups.sh uninstall /mnt/tank/apps/ugreen-ups-driver

A note on other models in the range

If you run a second UPS on a second NAS, each one is its own NUT master. They are not master and slave, and they do not need to know about each other.

Other UGREEN UPS models may send their data in a different format than the US3000. Then the positions this driver reads may not fit. If you try another model, expect to map them yourself.