OPNSense, UPS, Nut, USBHID-Driver

[PerpetualNewbie]

How I setup OPNSense to use NUT to talk to my UPS over USB...

You may remember my string of posts showing an example setup for using Nut with the SNMP driver to talk either SNMPv1 or SNMPv3 through nut to a UPS which supports those, here:
https://forum.opnsense.org/index.php?topic=27776.0

Since I was unable to get Nut to communicate over AES encyrpted session with SNMPv3 (even though snmpwalk was able to talk AES to the UPS) I switched over to trying to have Nut connect over USB using the Nut "USBHID-Driver"

Getting Nut installed is the same:
In order to support SNMP-Driver, on OPNSense, login to the web interface.

System -> Firmware -> Plugins:

Now, right frame, choose to "+" install "os-nut":

Refresh web page after install, Scroll down to "Services" and check for:
Services -> Nut -> Configuration

In the right-frame, specify your Desired IP address for nut service, and name the UPS configuration to use.
To avoid problems, try using a name without any white-spaces, and limit the name to alpha-numerics with underscore, hyphen, and periods.

Enable Nut: X
Service Mode: NetClient
Name: NameForYourUPSWithoutSpaces
Listen Address: YOUR_IPv4_OR_IPv6_Address_For_NUT_Service_Here
[Apply] (choose apply)

To setup use for the Nut "USBHID-Driver" some information to help you:

Use your preferred OS of choice to connect to the USB port of your UPS, and try to identiy the 4 hexadecimal-digit code for "VendorID" along with the 4 hexadecimal-digit code for "ProductID".

Sometimes UPS have multiple USB ports, and each have different purposes. Make sure to check your product manual to determine which USB port is used for signalling status of the UPS and connect to it.

With many Linux distributions, you have "lsusb" as root to show you all of these.

An example of the format for output of these devices might be:
Bus [0-9]{3} Device [0-9]{3}: ID [0-9a-f]{4}:[0-9a-f]{4} SOME_DESCRIPTION_OF_ITEM_HERE

The 3 digit integer following "Bus" refers to which USB "Bus" identified where is is connected.
The 3 digit integer following "Device" refers to which USB "Slot" on a shared USB "Bus" is connected.
These tend to be unreliable if selected to identify your UPS, as they can change assignments each boot, or when BIOS/Firmware is upgraded, or features are enabled/disabled in BIOS/Setup.

The 2 groups of 4 hexadecimal-digits separated by a Colon ":" are the items of interest here.
The Second item of interest is the string that follows, which in this example is "SOME_DESCRIPTION_OF_ITEM_HERE"

You can probably identify your UPS using the "SOME_DESCRIPTION_OF_ITEM_HERE" string provided, but it can change with firmware upgrades, so isn't as reliable as using the "VendorID" and "ProcuctID" but it is better than trying to use the USB Device/Bus.

The 4 hexadecimal-digits to the left of the colon refer to "VendorID" while the 4 hexadecimal-digits to the right refer to a "ProductID" : The product ID can sometimes change when firmware is upgraded, but the VendorID tends to not change very much.

Another item you can use to try to help the Nut "USBHID-Driver" identify your UPS is your UPS's Serial Number, if it is presented over USB as an identifier.

From FreeBSD (like what OPNSense is using right now) you can try:
"usbconfig dump_all_desc | less"

Look through the list, and then if you can find your device described in a line which is left-justified with no spaces to the left something like:

ugen[0-9].[0-9]: <NAME_OR_DESCRIPTION_OF_UPS_OR_MODEL_OF_UPS> at usbus[0-9], cfg=[0-9] md=[.]* spd=FULL (12Mbps) pwr=ON (10mA)

Then look below that for these lines of data if present:
...
  idVendor = 0x[0-9a-f]{1,4}
...
  idProduct = 0x[0-9a-f]{1,4}
...
  iSerialNumber = 0x[0-9a-f]{1,4}  <SOME_SERIAL_NUMBER>
...

Copy the 4 hexadecimal values you see for your UPS "idVendor" after the "0x" somewhere.
 (Let's assume your devices vendorID is "abcd")
Copy the 4 hexadecimal values you see for your UPS "idProduct" after the "0x" somewhere.
 (Let's assume your devices productID is "0123")
Copy the sting for "iSerialNumber" contained within the "<" and ">" but not including the "<"or ">"
 (Let's assume your devices serial number is "0a1b2c3d4f-0000"

On OPNSense web interface, visit:
Services -> Nut -> Configuration

On the right, you should see "Services: Nut: Configuration" with the "General Settings" you filled out with your data above, and applied.

There should what looks like a "tab" to the right of "General Settings" called "UPS Type"
The "UPS Type" tab should have a down-triangle to the right.
Click on that down-triangle and you should see a drop-down menu with choices of drivers.
Visit each driver and make sure that any drivers other than the "UBSHID-driver" are NOT enabled. If they are enabled, disable and choose apply for each that is enabled.

Next, visit "UPS Type" down-triangle , drop-down menu: USBHID-Driver and add data:
Enable: X
Extra Arguments:

In this "Extra arguments" you will want to make some decisions on how to identify your USB Device:
 Use VendorID and ProductID (or)
 Use Serial Number (or)
 Use VendorID and ProductID and Serial Number

From above, we assumed
your device's vendorID was "abcd")
your device's productID was "0123")
Your device's serial number was "0a1b2c3d4f-0000"
(Your VendorID, ProductID and Serial number will almost certainly be different)

Add what you want to the Extra arguments like:
vendorid=abcd
productid=0123
serial=0a1b2c3d4f-0000

A required "extra argument" is "port" which for USB can be auto:
port=auto

An Optional Extra argument is a description for the UPS, and maybe choose a name/model of your UPS without spaces and add it:
desc=ModelX_UPS

Final list of extra arguments:
port=auto
desc=ModelX_UPS
vendorid=abcd
productid=0123
serial=0a1b2c3d4f-0000

(The values you would use would be different)

Then you choose to apply:
[Apply]

Is it working?

A word of warning: if this does not work, your web interface can become slow and sluggish, requiring you to try to resolve these changed from the command-line.
If you are confident that won't be a problem, visit:
Services -> Nut -> Diagnostics

If you are NOT feeling confident, then before you visit "Diagnostics" maybe see if your DeviceID and ProductID are claimed as supported with your install of nut and its USBHID-Driver. A good place to check?
/usr/local/etc/devd/nut-usb.conf
Review that file, and see if you can find any mention of you device with an entry that contains BOTH the VendorID and ProductID you found reported by your UPS when asking for it over USB.
If it is listed, that should raise your confidence.
If not listed, then it is a bit of a gamble.

When you visit the "Diagnostics" pages, if your device is supported, and the USB cable works, and the USB Interface on your UPS and system are working, and the device you specified matches your UPS, then within 3 seconds you should see information appear to the right once you visit the "Services -> Nut -> Diagnostics" page.

If you do not, you can try tests from the command line as root.
Recall the name you assigned your UPS on the "General Settings" screen under Services -> Nut -> Configuration

If you called it "NameForYourUPSWithoutSpaces" then that is the name to use here:
/usr/local/libexec/nut/usbhid-ups -DDDDDDDDDDDDDDD -a NameForYourUPSWithoutSpaces -u root

If that "works" you should see super-detailed information where your OPNSense Nut service "usbhid-driver" tries to talk to the USB device you identified in the "UPS Type" tab under the "USBHID-Driver" using the "Extra Arguments"

Errors and problems described when running this may help you to identify the problem.

Here is an example of bad news for you:
...
   0.015875     This VENDORNAME device (baad:f00d) is not (or perhaps not yet) supported by usbhid-ups. Please make sure you have an up-to-date version of NUT. If this does not fix the problem, try running the driver with the '-x productid=0004' option. Please report your results to the NUT user's mailing list <nut-upsuser@lists.alioth.debian.org>.
   0.015877     Device does not match - skipping
...

("baad:f00d" is an example of a 4-hexadecimal digit for "VendorID" with a colon then a 4-hexadecimal digit for "ProductID" which would be replaced with the VendorID and ProductID for your UPS.)

It probably means your device is not yet supported.

In one case, I found that upgrading the UPS Firmware and then *rebooting* the UPS (taking all outlets offline, unplugging UPS, then pressing power button to turn off UPS for moving, then plugging it back in, pressing the power button, then re-enabling all of the outlets) caused the "ProductID" to change, and suddenly be supported. This is an uncommon and should not be *expected* but it worth trying.

If you found problems with this procedure and have suggestions, please post replies to help other people have an easier time than you did.

Useful links:
 * https://networkupstools.org/docs/man/usbhid-ups.html : man page on web with mentions for supported hardware for this driver and descriptions for many "Extra Arguments" not used in this example.

I hope this helps you. Good luck!

[EdwinKM]

This seems a guide. Thanks for sharing. Maybe you can better post it at "Tutorials and FAQs"

[PerpetualNewbie]

That makes sense. Mods, feel free to move this thread with setting up Nut with USBHID to UPS and the other thread on setting up Nut with SNMPv1 or SNMPv3 to UPS to the other forum.

Thanks!