Add usb_resetter documentation for unreliable USB UPS interfaces (Linux, Python)

[deajan]

This PR adds documentation for a workaround solution for unreliable USB interfaces, as stated in #1688
I use this on a couple of UPS for months now, without any major issue.

General points

• Described the changes in the PR submission or a separate issue, e.g.
  known published or discovered protocols, applicable hardware (expected
  compatible and actually tested/developed against), limitations, etc.

• There may be multiple commits in the PR, aligned and commented with
  a functional change. Notably, coding style changes better belong in a
  separate PR, but certainly in a dedicated commit to simplify reviews
  of "real" changes in the other commits. Similarly for typo fixes in
  comments or text documents.

General documentation updates

• [N/A] Updated docs/acknowledgements.txt (for vendor-backed device support)

• [N/A] Added or updated manual page information in docs/man/*.txt files
  and corresponding recipe lists in docs/man/Makefile.am for new pages

• [N/A] Passed make spellcheck, updated spell-checking dictionary in the
  docs/nut.dict file if needed (did not remove any words -- the make
  rule printout in case of changes suggests how to maintain it).

[jimklimov]

Thanks for the contribution, much appreciated. I think it is worth noting (maybe in the document too) that nut-driver.service provided here is an example, and more so - tied to a particular VID:PID (even if one likely to need it often).

With current NUT releases (2.8.0+), this single service for all the drivers you have as one bundle should be no more. Instead, nut-driver@.service template is used (manually or e.g. by nut-driver-enumerator script or service) to run each driver in a dedicated instance. The call to usb_resetter can be a systemd drop-in file for the particular device, so it does not impact others (unless they use the same USB hub...)

Also, I suppose after the usb_resetter runs, the OS re-discovers the device, it gets owned by kernel, udev/upower/... hands it off to a NUT run-time account, and only then can it be opened by a driver. Does the script only exit when it is sure the device is usable, or should there be an artificial delay added?

[deajan]

I think it is worth noting (maybe in the document too) that nut-driver.service provided here is an example

Indeed, I'll have another PR for the README file

The call to usb_resetter can be a systemd drop-in file for the particular device

I have looked at drop-in files, but i don't know how to limit to one instance of a @.service file.
Care to point me to the right direction ?

Does the script only exit when it is sure the device is usable, or should there be an artificial delay added?

No, the script's task is only to reset devices / controllers.
Nevertheless, I did not have to set any arbitrary wait time to make use of my USB UPSes with NUT.

[jimklimov]

don't know how to limit to one instance of a @.service file

Just name its directory for the expected instance (NDE with NUT v2.8.0+ will create some drop-ins), e.g.

/etc/systemd/system/nut-driver@myups.service.d/dropin.conf

[jimklimov]

As a curious data point, similar issue (and also with Innotech chips) was addressed for Solaris/illumos earlier, see https://github.com/networkupstools/nut/blob/master/docs/solaris-usb.txt#L233 and https://github.com/networkupstools/nut/blob/master/scripts/Solaris/reset-ups-usb-solaris.sh.sample

[jimklimov]

Thanks!