////////
This file is included into other man pages, where appropriate,
by their choice of markup and sectioning (usually lands into
"USB INTERFACE ONLY" for serial/usb or "EXTRA ARGUMENTS").

Keep in sync with nut_usb_addvars() method provided by
* drivers/libusb0.c
* drivers/libusb1.c
* drivers/usb-common.h

and matching code in tools/nut-scanner/scan_usb.c
////////

*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
linkmanext: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 linkmanext: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 linkmanext: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 linkmanext: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 linkman: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 linkman: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/
* link:https://libusb.sourceforge.io/api-1.0/group\__libusb\__lib.html[https://libusb.sourceforge.io/api-1.0/group\__libusb__lib.html]

///////////////////
// EDITOR NOTE: There are no backslashes in the URL above, just that
// asciidoc sees them as "emphasis" markup, they had to be escaped.
// If a link from this asciidoc source file is needed, please visit:
// https://libusb.sourceforge.io/api-1.0/group__libusb__lib.html
///////////////////
