POWERVAR_CX_USB(8)

NAME
powervar_cx_usb - Driver for Powervar GTS and UPM Series UPS equipment with USB connection

SYNOPSIS

powervar_cx_usb -h

powervar_cx_usb -a UPS_NAME [OPTIONS]

    Note

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

SUPPORTED HARDWARE

This driver supports two Powervar UPS families with USB connections:

    • UPM (either USB or Serial)

    • GTS (USB only)

For serial connected UPM Series devices, see also powervar_cx_ser(8).

EXTRA ARGUMENTS

This driver supports the following optional settings in the ups.conf(5) file:

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

startdelay=num
    Change startup delay time from 1 second default.

offdelay=num
    Change shutdown delay time from 0 second default.

disptesttime=num
    Change display test time from the 10 second default (UPM only).

INSTANT COMMANDS

This driver supports the following Instant Commands (see upscmd(8)):

  All GTS and UPM UPS units

beeper.disable
    Disable the UPS beeper.

beeper.enable
    Enable the UPS beeper.

beeper.mute
    Temporarily mute the UPS beeper.

shutdown.return
    Turn off the load possibly after a delay and return when power is back.

shutdown.stop
    Stop a shutdown in progress.

shutdown.reboot
    Shut down the load briefly while rebooting the UPS.

shutdown.stayoff
    Turn off the load and remain off.

test.battery.start.deep
    Start a "deep" battery test. This test runs the UPS until the low battery point and then returns to the AC line.

test.battery.start.quick
    Start a "quick" battery test. The default time is 2 minutes. This time can be set in the ups.conf file. See testime above.

test.battery.stop
    Stops a battery test that is in progress.

test.failure.start
    Starts a simulation of an input power failure.

test.failure.stop
    Stops a simulation of an input power failure.

  All UPM UPS units

test.panel.start
    Start testing the UPS panel.

reset.input.minmax
    Reset minimum and maximum input voltage status.

WRITABLE VARIABLES

See upsrw(8) to see what variables are writable for the UPS.

AUTHORS

    • Bill Elliot <bill@wreassoc.com>

SEE ALSO

For serial connected UPM Series devices, see powervar_cx_ser(8).

  The core driver:

nutupsdrv(8)

  Internet resources:

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