[Jordi-14]

Problem

On the tested CyberPower OLS2000ERT2UA, standard HID monitoring does not expose the actual output watts, apparent power or output current available through PowerPanel.

USB captures show that these readings use a HID-framed version of the existing PowerPanel text protocol.

Changes

Extend the existing powerpanel driver with an optional libusb-1.0 transport and reuse its text subdriver.

Decode the additional status fields:

• Q: output.current, in amperes.
• J: ups.realpower, in watts.
• E: ups.power, in VA.

Serial operation remains the default. USB can be selected explicitly with transport = usb, or through port = auto when no transport is specified.

Example ups.conf section:

[myups]
    driver = powerpanel
    port = auto
    transport = usb
    protocol = text

The initial implementation requires exactly one device with USB ID 0764:0601 and checks that its product string identifies it as OLS2000ERT2UA. This USB ID is shared with other models, so the ID alone is insufficient to select this transport.

The patch also updates the manual, compatibility list, release notes and USB-information generator, and adds parser and mocked USB transport regression tests.

Protocol evidence

• Interrupt OUT endpoint 0x02: 64-byte frames containing report 0x29, a payload length, CR-terminated text and zero padding.
• Interrupt IN endpoint 0x81: report 0x28, a payload length and response fragments.
• Responses can span frames, including splitting numeric fields.
• Feature reports 0x25 and 0x27 perform the observed communication setup.
• Observed vendor C* commands are excluded from the transport's query allowlist.

Four captured status replies are included as regression cases without device identifiers. The 149 W / 191 VA / 0.7 A case matched the vendor application's simultaneous readings.

Validation

Tested on Linux with a CyberPower OLS2000ERT2UA, firmware OS02RV15.

• USB-enabled driver build: passed.
• USB-disabled serial build: passed.
• Parser and mocked USB transport regression tests: passed.
• Documentation spellcheck: passed.
• make distcheck-light: passed, including 17 regression tests and the NUT-Monitor application test.
• Final native hardware test: returned 188 W, 256 VA and 1.0 A, along with firmware and the existing status readings.

The hardware test used a bounded, isolated runtime with approximately 5.5 MiB peak container memory and no OOM events. Original TrueNAS UPS monitoring was restored afterwards with its configuration unchanged.

Distribution validation used:

make -j1 distcheck-light DISTCHECK_LIGHT_FLAGS='--with-all=auto --with-drivers=powerpanel --with-ssl=auto --with-doc=auto --enable-docs-man-for-progs-built-only=no --with-pynut=app --with-nut_monitor=force'

Limitations

This is an initial query-only implementation.

• USB mode does not register writable settings or instant commands.
• Shutdown and electrical-output commands are not implemented.
• Unverified battery-topology fields and software-default shutdown delays are omitted in USB mode.
• Fault-code and NCL-bank decoding remain future work.
• No per-socket metering is claimed.
• Other UPS models, serial hardware and other operating systems have not been hardware-tested.
• Normal-operation hardware tests do not validate every alarm or status transition.
• Rendered manual pages were not validated by the light distribution check.

This patch adds the verified transport and measurements. It does not claim complete telemetry parity with the existing HID driver and PowerPanel.

Development assistance

OpenAI Codex assisted with protocol analysis.

Contribution checklist

• Described the protocol, tested hardware, implementation and limitations.
• Reused the existing PowerPanel driver and text subdriver.
• Bumped the driver and text-subdriver versions.
• Documented the shared USB ID and restricted initial support to the tested model.
• Used existing NUT variable names for the additional measurements.
• Updated data/driver.list.in.
• Updated the relevant Makefile.am files for new sources and tests.
• Updated NEWS.adoc and the driver manual.
• Passed documentation spellcheck and updated docs/nut.dict.
• Passed make distcheck-light.
• Disclosed coding-helper assistance.
• Completed personal review of the code, documentation, portability and licence requirements.
• Added the contributor's DCO sign-off to the commit.
• Passed full make distcheck.
• Reviewed upstream CI results and addressed any failures.

The USB ID is already covered by the existing UPower hardware database. No new UPower device ID is introduced.

A separate NUT DDL contribution and additional hardware/platform validation can follow this initial implementation.

[github-actions]

Preparing a ZIP file with standard source tarball and another tarball with pre-built docs for commit a5a66e0 ...

[AppVeyorBot]

❌ Build nut 2.8.5.5907-master failed (commit cdd77429b7 by @Jordi-14)

• artifacts (if any)

[AppVeyorBot]

❌ Build nut 2.8.5.5907-master failed (commit cdd77429b7 by @Jordi-14)

[Jordi-14]

I checked the AppVeyor failure. powerpanel.exe compiled successfully, and both new PowerPanel regression tests passed.

The log stops during NIT daemon cleanup after repeated “fork: Resource temporarily unavailable” errors, and the build ended at the one-hour mark.

Could this AppVeyor job please be rerun to check whether the failure is transient?

[jimklimov]

Thanks for the heads-up (and the PR), Appveyor rebuild queued.

[AppVeyorBot]

✅ Build nut 2.8.5.5908-master completed (commit cdd77429b7 by @Jordi-14)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.5908-master.7z
• ccache: 398 of 415 compilations were cache hits (95.9%); cache size 749 of 750 MiB after cleanup

[AppVeyorBot]

✅ Build nut 2.8.5.5908-master completed (commit cdd77429b7 by @Jordi-14)