bjonnh / cyberpower-usb-watcher

A tiny python script to watch CyberPower UPS directly from USB (no proprietary software involved)

This is a simple script that allows to watch a CyberPower UPS by USB (without using the proprietary software from the vendor).

I use it to export my UPS status into Prometheus:

• You can use it without root (careful, some of these can be turned off by USB, so giving access to non-root would also give them the right to do so)
• You can use it on non x86 platforms.
• You can use it because it is Free.

One of the problem I found is that there is no serial number in these units, or at least not accessible by USB meaning you cannot recognize which unit is which just by using USB. In my case, the firmware is giving two different versions so I use that to distinguish them (maybe they are serial after all).

For now, it only manages the PR3000LCDRTXL2U model, but it should be trivial to support others that use the same HID approach.

Use with prometheus

You need to have libhidapi-libusb installed (the libhidapi-hidraw version will not work as the devices will not get listed).

On Ubuntu, the package is named **libhidapi-libusb0**.

virtualenv --python=python3 venv
source venv/bin/activate
pip install -r requirements.txt
./server.py

the metrics will be available on http://127.0.0.1:9500/metrics

Useful docs

There was no need to reverse engineer, the device is using a standardized HID protocol.

https://usb.org/sites/default/files/pdcv10.pdf : The official HID tables for Power devices.

Example of output as json (default for usb.py)

{'load': 9, 'vin': 114, 'vout': 114, 'test': 0, 'capacity': 3000, 'batterytype': 'PbAcid', 'manufacturer': 'CyberPower Systems', 'firmware': 'PTEEU2000XYZ', 'product': 'PR3000LCDRTXL2U     ', 'ac': True, 'charge': True, 'belowcap': False, 'full': True, 'overtimelimit': True, 'runtime': 58, 'battery': 100}
{'load': 20, 'vin': 113, 'vout': 113, 'test': 0, 'capacity': 3000, 'batterytype': 'PbAcid', 'manufacturer': 'CyberPower Systems', 'firmware': 'PTEEU2000ZYX', 'product': 'PR3000LCDRTXL2U     ', 'ac': True, 'charge': True, 'belowcap': False, 'full': True, 'overtimelimit': True, 'runtime': 19, 'battery': 100}

What to do if you use a different model

In the code, change VENDOR_ID and PRODUCT_ID to match your product.

What to do if you require complex features

Have a look at Network UPS Tools.