guillorrr/ups.md

Hikvision UPS 2000VA/3000VA + NUT on Ubuntu 24.04

Complete guide to configure a Hikvision UPS (2000VA or 3000VA, line-interactive) with Network UPS Tools (NUT) on Ubuntu 24.04. This UPS uses the Richcomm V2.0 USB chipset (0925:1234), which is not supported by the NUT version packaged in Ubuntu 24.04 (2.8.1).

The Problem

The Hikvision UPS uses a Richcomm V2.0 USB controller that identifies as:

Bus 005 Device 003: ID 0925:1234 Lakeview Research UPS USB Mon V2.0
Manufacturer: RICHCOMM
Product: UPS USB Mon V2.0

Despite being detected as a USB HID device (bInterfaceClass 3), none of the standard NUT 2.8.1 drivers work:

Driver	Result
`usbhid-ups`	`failed to match a subdriver to vendor and/or product ID`
`richcomm_usb`	`driver callback failed: Entity not found` (designed for V1.4, not V2.0)
`blazer_usb`	`Device does not match - skipping`
`nutdrv_qx` (2.8.1)	armac subdriver incomplete for this chipset
`apcupsd`	`STATUS: COMMLOST` — not APC protocol

The Solution

Compile NUT from git (>= 2.8.2) and use nutdrv_qx with subdriver=armac and protocol=megatec.

This solution was discovered via this gist by lvl47 and confirmed working on Ubuntu 24.04 with a Hikvision UPS 2000VA.

Compatible Devices

Any UPS using the Richcomm V2.0 chipset (USB ID 0925:1234) should work, including models from:

Hikvision (DS-UPS2000 / DS-UPS3000)
Accurat Flux 850
Vultech UPS1400VA-LFP, UPS2000VA-PRO
Armac R/2000I/PSW, PF1, Home 850E
ExeGate SpecialPro Smart
TED Electric 3100VA

Prerequisites

Ubuntu 24.04 (tested; should work on Debian Bookworm and derivatives)
UPS connected via USB
nut packages installed: sudo apt install nut nut-client nut-server

Step 1: Build the Driver

The build script from lvl47's gist automates this. Download and run:

cd /root
wget -O build_nut_driver.sh "https://gist.githubusercontent.com/lvl47/a280c7d1a0a8a489c084c83b8f28f054/raw/build_nut_driver.sh"
chmod +x build_nut_driver.sh
sudo ./build_nut_driver.sh

This clones the NUT git repo, compiles nutdrv_qx with the armac subdriver, and installs it as /lib/nut/nutdrv_qx_new. It also installs a matching upsdrvctl_new to avoid version mismatches with the system package.

Build prerequisites (installed automatically by the script)

git build-essential autoconf automake libtool pkg-config libusb-1.0-0-dev libssl-dev

Step 2: Create the Symlink

The compiled upsdrvctl_new looks for the driver in /usr/local/nut-dev/bin/. Create a symlink:

sudo mkdir -p /usr/local/nut-dev/bin
sudo ln -sf /lib/nut/nutdrv_qx_new /usr/local/nut-dev/bin/nutdrv_qx_new

Step 3: Configure NUT

`/etc/nut/nut.conf`

MODE=netserver

`/etc/nut/ups.conf`

For a 2000VA model (2× 12V batteries in series = 24V nominal):

[myups]
    driver = "nutdrv_qx_new"
    port = "auto"
    vendorid = "0925"
    productid = "1234"
    product = "UPS USB Mon V2.0"
    vendor = "RICHCOMM"
    subdriver = "armac"
    protocol = "megatec"
    desc = "Hikvision UPS 2000VA"
    pollinterval = 5

    # Battery charge thresholds (guesstimated from voltage)
    ignorelb
    override.battery.charge.low = 20
    override.battery.charge.warning = 40

    # Voltage thresholds for 24V battery bank (2× 12V in series)
    override.battery.voltage.high = 27.2
    override.battery.voltage.low = 20.8

    # Shutdown timing
    offdelay = 60
    ondelay = 120

Note for 3000VA model: The 3000VA uses 4× 12V batteries (2 series pairs in parallel, still 24V nominal). The voltage thresholds above should still be correct.

`/etc/nut/upsd.conf`

LISTEN 0.0.0.0 3493

`/etc/nut/upsd.users`

[upsmaster]
    password = YOUR_MASTER_PASSWORD
    actions = SET
    instcmds = ALL
    upsmon master

[upsclient]
    password = YOUR_CLIENT_PASSWORD
    upsmon slave

sudo chmod 640 /etc/nut/upsd.users
sudo chown root:nut /etc/nut/upsd.users

`/etc/nut/upsmon.conf`

MONITOR myups@localhost 1 upsmaster YOUR_MASTER_PASSWORD master

SHUTDOWNCMD "/sbin/shutdown -h +0"

POLLFREQ 5
POLLFREQALERT 2
DEADTIME 15
FINALDELAY 10

NOTIFYFLAG ONLINE     SYSLOG
NOTIFYFLAG ONBATT     SYSLOG+WALL
NOTIFYFLAG LOWBATT    SYSLOG+WALL
NOTIFYFLAG FSD        SYSLOG+WALL
NOTIFYFLAG SHUTDOWN   SYSLOG+WALL

RUN_AS_USER root

Important: Do NOT add CERTPATH or CERTVERIFY lines. On Ubuntu 24.04, the NUT 2.8.1 upsmon binary fails to initialize the SSL context with these settings, causing the service to crash in a restart loop.

Step 4: Systemd Override

Create a systemd override so the driver service uses the compiled upsdrvctl_new:

sudo mkdir -p /etc/systemd/system/nut-driver@myups.service.d
cat << 'EOF' | sudo tee /etc/systemd/system/nut-driver@myups.service.d/override.conf
[Service]
ExecStart=
ExecStart=/lib/nut/upsdrvctl_new start myups
ExecStop=
ExecStop=/lib/nut/upsdrvctl_new stop myups
EOF
sudo systemctl daemon-reload

Also ensure /run/nut persists across reboots:

cat << 'EOF' | sudo tee /etc/tmpfiles.d/nut-ups.conf
d /run/nut 0770 root nut -
EOF

And the config symlink:

sudo mkdir -p /usr/local/nut-dev/etc
sudo ln -sf /etc/nut /usr/local/nut-dev/etc/nut

Step 5: USB Permissions (udev rule)

cat << 'EOF' | sudo tee /etc/udev/rules.d/99-nut-ups.rules
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0925", ATTRS{idProduct}=="1234", MODE="0660", GROUP="nut"
EOF
sudo udevadm control --reload-rules
sudo udevadm trigger

Step 6: Start Services

sudo /lib/nut/upsdrvctl_new start myups
sudo systemctl restart nut-server
sleep 3
sudo systemctl restart nut-monitor
sudo systemctl enable nut-server nut-monitor

Step 7: Verify

upsc myups@localhost

Expected output:

battery.charge: 97
battery.voltage: 27.0
battery.voltage.high: 27.2
battery.voltage.low: 20.8
battery.voltage.nominal: 24.0
input.frequency: 50.0
input.voltage: 224.0
output.voltage: 224.0
ups.firmware: V3.65
ups.load: 13
ups.status: OL
ups.temperature: 20.8
ups.type: offline / line interactive

Verify persistence after reboot:

sudo reboot
# After reboot:
upsc myups@localhost 2>/dev/null | grep "ups.status"
# Should show: ups.status: OL

Shutdown Sequence

When a power outage occurs:

Power outage
  │
  ▼
UPS switches to battery (ups.status: OB)
  │
  ▼
Battery drains...
  │
  ▼
battery.charge drops below 20% (override.battery.charge.low)
  │
  ▼
NUT triggers Forced Shutdown (FSD)
  │
  ▼
System shuts down cleanly
  │
  ▼
UPS waits offdelay (60s), then cuts power
  │
  ═══════════ mains power returns ═══════════
  │
  ▼
UPS waits ondelay (120s), then restores power
  │
  ▼
System boots (requires BIOS "Restore on AC Power Loss" enabled)

Troubleshooting

Driver doesn't start: `Can't start nutdrv_qx_new: No such file or directory`

The compiled upsdrvctl_new looks for the driver in its build prefix. Fix:

sudo mkdir -p /usr/local/nut-dev/bin
sudo ln -sf /lib/nut/nutdrv_qx_new /usr/local/nut-dev/bin/nutdrv_qx_new

`nut-monitor` crash loop: `Can not initialize SSL context`

Remove SSL config from upsmon.conf:

sudo sed -i '/CERTPATH/d' /etc/nut/upsmon.conf
sudo sed -i '/CERTVERIFY/d' /etc/nut/upsmon.conf
sudo systemctl restart nut-monitor

`Resource busy` when testing USB communication

The kernel usbhid driver or a NUT process may be holding the device. Kill any existing NUT drivers before testing:

sudo killall -9 usbhid-ups richcomm_usb nutdrv_qx nutdrv_qx_new 2>/dev/null

`Init SSL without certificate database` warning

This is harmless and can be ignored. It comes from the system upsmon (2.8.1) not having SSL configured.

Environment

OS: Ubuntu 24.04 LTS
NUT (system package): 2.8.1
NUT (compiled driver): 2.8.5+ from git
UPS: Hikvision DS-UPS2000, 2000VA, 220V
USB ID: 0925:1234 (Lakeview Research / RICHCOMM UPS USB Mon V2.0)
Date tested: April 2026

References

NUT Issue #3132 — Hikvision UPS 2000VA (same device)
NUT Issue #2125 — RICHCOMM V2.0 driver question
NUT Issue #2219 — Vultech UPS1400VA (same chipset)
lvl47's gist — Accurat Flux 850 build scripts (the solution)
NUT nutdrv_qx man page

guillorrr/ups.md

Select an option

No results found

Select an option

No results found

Hikvision UPS 2000VA/3000VA + NUT on Ubuntu 24.04

The Problem

The Solution

Compatible Devices

Prerequisites

Step 1: Build the Driver

Build prerequisites (installed automatically by the script)

Step 2: Create the Symlink

Step 3: Configure NUT

`/etc/nut/nut.conf`

`/etc/nut/ups.conf`

`/etc/nut/upsd.conf`

`/etc/nut/upsd.users`

`/etc/nut/upsmon.conf`

Step 4: Systemd Override

Step 5: USB Permissions (udev rule)

Step 6: Start Services

Step 7: Verify

Shutdown Sequence

Troubleshooting

Driver doesn't start: `Can't start nutdrv_qx_new: No such file or directory`

`nut-monitor` crash loop: `Can not initialize SSL context`

`Resource busy` when testing USB communication

`Init SSL without certificate database` warning

Environment

References

guillorrr/ups.md

Hikvision UPS 2000VA/3000VA + NUT on Ubuntu 24.04

The Problem

The Solution

Compatible Devices

Prerequisites

Step 1: Build the Driver

Build prerequisites (installed automatically by the script)

Step 2: Create the Symlink

Step 3: Configure NUT

/etc/nut/nut.conf

/etc/nut/ups.conf

/etc/nut/upsd.conf

/etc/nut/upsd.users

/etc/nut/upsmon.conf

Step 4: Systemd Override

Step 5: USB Permissions (udev rule)

Step 6: Start Services

Step 7: Verify

Shutdown Sequence

Troubleshooting

Driver doesn't start: Can't start nutdrv_qx_new: No such file or directory

nut-monitor crash loop: Can not initialize SSL context

Resource busy when testing USB communication

Init SSL without certificate database warning

Environment

References

`/etc/nut/nut.conf`

`/etc/nut/ups.conf`

`/etc/nut/upsd.conf`

`/etc/nut/upsd.users`

`/etc/nut/upsmon.conf`

Driver doesn't start: `Can't start nutdrv_qx_new: No such file or directory`

`nut-monitor` crash loop: `Can not initialize SSL context`

`Resource busy` when testing USB communication

`Init SSL without certificate database` warning