feat(server): EcoFlow UPS graceful shutdown via NUT on the home server

[ulises-c]

Goal

Connect the EcoFlow UPS to the Ubuntu Server home server over USB and have NUT (Network UPS Tools) shut the server down gracefully on power loss — without depending on EcoFlow's Synology-only "Power Manager NUT" package.

Findings (from unpacking PowerManagerNUT-x86_64-1.0.3-SynologyDS923+.spk)

The Synology .spk is a plain tar archive. Inside, EcoFlow's "Power Manager" is a generic x86-64 Linux build of NUT 2.8.2 with a thin DSM UI wrapper. Nothing about the actual UPS handling is Synology-specific:

• The bundled usbhid-ups binary contains a custom "ECOFLOW HID 0.1" subdriver — the only real EcoFlow-specific code. The UPS enumerates as USB VID 3746 (products 0001 / ffff), which stock NUT ≤ 2.8.2 does not recognize.
• This subdriver has since been upstreamed: NUT 2.8.4 ships a native ecoflow-hid subdriver (see networkupstools/nut#2735, confirmed working with River 3 Plus / Delta 3 Plus). Ubuntu 24.04 packages NUT 2.8.1 — too old.
• Their driver config (ups.conf) is the part worth carrying over verbatim:

  [ecoflow]
      driver = usbhid-ups
      port = auto
      pollfreq = 1
      usb_hid_ep_in = 1
      usb_hid_ep_out = 1
      ignorelb
      override.battery.runtime.low = -1

• udev rule granting access to VID 3746 (0001 and ffff), MODE/GROUP adjusted for the nut user instead of their world-writable 666.
• upsd on port 3496 only exists to dodge Synology's built-in NUT on 3493 — use the standard 3493 on Ubuntu.
• upsd.users ships hardcoded Ecoflow/Ecoflow credentials — replace.
• Their shutdown hook (eco_shutdown.sh) re-checks ups.status, gracefully stops libvirt VMs via virsh (10s timeout, then virsh destroy), then shutdown -h +0. Worth adapting if the server runs VMs; otherwise plain SHUTDOWNCMD "/sbin/shutdown -h +0" suffices.
• Binary compatibility is a non-issue either way: max glibc requirement is 2.17, ldd resolves fully on Ubuntu (bundled libusb-1.0.so.0), and usbhid-ups -h runs successfully on an Ubuntu desktop. The bundle even includes stock systemd units (with the developer's build prefix /home/efsz/proj/ps-003/ef-nut/… baked in, needs sed).

Plan

Preferred: upstream NUT ≥ 2.8.4, built from source (Ubuntu 24.04's 2.8.1 lacks the ecoflow-hid subdriver):

1. Build/install NUT 2.8.4 on the server (or pick up a backport if one exists by then).
2. Deploy config: ups.conf stanza above, upsd.conf (LISTEN localhost 3493), upsd.users (own creds), upsmon.conf (MONITOR ecoflow@localhost 1 <user> <pass> primary, SHUTDOWNCMD).
3. Install udev rule for VID 3746, group nut.
4. Enable nut-server / nut-monitor / nut-driver@ systemd units.
5. Test: upsc ecoflow@localhost, then a live pull-the-plug test to verify OB → LB/timer → clean shutdown.

Quick validation path (optional, before committing to a source build): run EcoFlow's own bundle from /opt — copy tree, fix unit paths, standard port. Useful only to confirm the specific UPS model talks to usbhid-ups.

Repo integration (this repo):

• Decide placement: linux-server/nut/ with configs (secrets via .env per repo policy — no real creds committed) + an install script, wired as a custom entry in packages.json gated to the server platform.
• verify.sh probe: upsc reachable and reporting OL.
• Doc page covering the pull-the-plug test procedure.

Open questions

• Exact EcoFlow model on the server (affects nothing in the plan, but worth recording once confirmed against 2.8.4's supported list).
• Does the server run libvirt VMs? If yes, adapt the virsh drain logic from eco_shutdown.sh into SHUTDOWNCMD.
• Source build vs. waiting for a distro/PPA package of NUT ≥ 2.8.4.