# RIELLO_USB(8)

## NAME

riello_usb - Driver for Riello UPS Protocol UPS equipment via USB

## SYNOPSIS

riello_usb -h

riello_usb -a UPS_NAME [OPTIONS]

Note | This man page only documents the hardware-specific features of the riello_usb driver. For information about the core driver, see nutupsdrv(8).

## SUPPORTED HARDWARE

riello_usb supports all recent Riello UPS with USB.

Older Riello UPS products are not supported.

## EXTRA ARGUMENTS

port = string

  Required option for all NUT drivers. Some value must be set, typically auto for drivers that handle USB connections.

  Note | This could be a device filesystem path like `/dev/usb/hiddev0` but current use of libusb API precludes knowing and matching by such identifiers. They may also be inherently unreliable (dependent on re-plugging and enumeration order). At this time the actual value is ignored, but syntactically some port configuration must still be there.

It is possible to control multiple UPS units simultaneously by running several instances of this driver, provided they can be uniquely distinguished by setting some combination of the vendor, product, vendorid, productid, serial, bus and/or device options detailed below. For devices or operating systems that do not provide sufficient information, the allow_duplicates option can be of use (limited and risky!)

vendorid = regex
productid = regex
vendor = regex
product = regex
serial = regex

  Select a specific UPS, in case there is more than one connected via USB. Each option specifies an extended regular expression (see regex(7) for more information on regular expressions), which must match the UPS’s entire respective `vendor`/`product`/`serial` string values (minus any surrounding whitespace), or the whole 4-digit hexadecimal code for `vendorid` and `productid`.

  Try lsusb(8) or running this NUT driver with `-DD` command-line argument for finding out the strings to match.

  Examples:

  - `-x vendor="Foo.Corporation.*"`

  - `-x vendorid="051d*"` (APC)

  - `-x product=".*(Smart|Back)-?UPS.*"`

bus = regex

  OPTIONAL, NOT RECOMMENDED.

  Select a UPS on a specific USB bus or group of buses. The argument is a regular expression that must match the bus name where the UPS is connected (e.g. `bus="002"` or `bus="00[2-3]"`) as seen on Linux in `/sys/bus/usb/devices` or lsusb(8); including leading zeroes.

  Note | Bus numbers are not guaranteed by the OS to be stable across re-boots, kernel driver reloads or device re-plugging (e.g. changing visible population of USB hubs).

device = regex

  OPTIONAL, NOT RECOMMENDED.

  Select a UPS on a specific USB device or group of devices. The argument is a regular expression that must match the device name where the UPS is connected (e.g. `device="001"` or `device="00[1-2]"`) as seen on Linux in `/sys/bus/usb/devices` or lsusb(8); including leading zeroes.

  Note | Device numbers are not guaranteed by the OS to be stable across re-boots or device re-plugging.

busport = regex

  OPTIONAL, NOT RECOMMENDED.

  If supported by the hardware, OS and libusb on the particular deployment, this option should allow to specify physical port numbers on an USB hub, rather than logical `device` enumeration values, and in turn — this should be less volatile across reboots or re-plugging. The value may be seen in the USB topology output of `lsusb -tv` on systems with that tool, for example.

  Note | This option is not practically supported by some NUT builds (it should be ignored with a warning then), and not by all systems that NUT can run on.

allow_duplicates

  OPTIONAL, NOT RECOMMENDED.

  If you have several UPS devices which may not be uniquely identified by the options above (e.g. only VID:PID can be discovered there), this flag allows each driver instance where it is set to take the first match if available, or proceed to try another.

  Normally the driver initialization would abort at this point claiming "Resource busy" or similar error, assuming that the otherwise properly matched device is unique — and some other process already handles it.

  Warning | This feature is inherently non-deterministic! The association of driver instance name to actual device may vary between runs! If you only care to know that at least one of your no-name UPSes is online, this option can help. If you must really know which one, it will not!

usb_set_altinterface = bAlternateSetting

  Force redundant call to `usb_set_altinterface()`, especially if needed for devices serving multiple USB roles where the UPS is not represented by the interface number `0` (default).

usb_config_index
usb_hid_rep_index
usb_hid_desc_index
usb_hid_ep_in
usb_hid_ep_out

  Force use of specific interface, endpoint, descriptor index etc. numbers, rather than defaulting to 0 (rarely other values in certain drivers for some devices known to use non-zero numbers). Specified as a hexadecimal number.

  As a rule of thumb for `usb_hid_desc_index` discovery, you can see larger `wDescriptorLength` values (roughly 600+ bytes) in reports of `lsusb` or similar tools.

LIBUSB_DEBUG = INTEGER

  Run-time troubleshooting of USB-capable NUT drivers can involve not only raising the common NUT debug verbosity (e.g. using the `DEBUG_MIN` setting in ups.conf(5) or protocol commands to change the `driver.debug` value), but may also benefit from LibUSB specific debugging.

  For the latter, you can set the `LIBUSB_DEBUG` driver option; alternatively you can classically export the environment variable `LIBUSB_DEBUG` before starting a NUT driver program (may be set and "exported" in driver init script or service method, perhaps via nut.conf(5)), to a numeric value such as `4` ("All messages are emitted").

  For more details, including the currently supported values for your version of the library, see e.g.:

  - https://libusb.sourceforge.io/api-1.0/

  - https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html

You may need to tweak some settings, depending on the make and model of your UPS (see ups.conf(5)):

localcalculation

  When enabled, driver will calculate values of `battery.runtime` and `battery.charge` "locally" in the driver. This is for some Riello models (iPlug and iDialog series) which provide incorrect values in hardware readings, or none at all. This "local calculation" is done according to nominal battery capacity, nominal battery voltage, actual battery charge, maximum and actual UPS load.

  You may want to also configure default.battery.voltage.low and default.battery.voltage.high in case the built-in default range (from 10.7V to 12.9V) does not match your hardware, or give a shot to default.battery.voltage.nominal (e.g. 24) if your device does not serve that either.

  Note | Lead (PbAc) battery charge graph is not linear, so guesstimated charge value may not be perfectly accurate. However it should be good enough to determine battery actual status and roughly estimate the time it can still power the system.

  Warning | This keyword may be deprecated in future releases of the driver, in favor of `runtimecal` and other settings which it requires (as seen in nutdrv_qx(8), blazer_ser(8) and blazer_usb(8) drivers).

## AUTHOR

Massimo Zampieri

## SEE ALSO

### Related drivers

riello_ser(8)

### The core driver

nutupsdrv(8)

### Internet resources

The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.4/