[reklrekl]

Adds a ugreen-hid subdriver for the Ugreen US2000 (72 W DC UPS,
2b89:ffff), which no subdriver claims today — usbhid-ups fails with
"Manufacturer or model not supported!" unless subdriver=Arduino is set
by hand. Problem statement and firmware evidence: #3779. Full
reverse-engineering write-up:
https://github.com/reklrekl/ugreen-ups-re

Why

The device's HID feature reports are partly hardcoded by its firmware:
ups.load is always 1, input.voltage is always 1, and
battery.runtime is 0xFFFF while on mains. The PresentStatus bits
behind LB have no code path at all, so LB cannot be raised from this
device. Its real measurements are pushed instead — as a 64-byte HID Input
report with ID 0x71 that nothing in the device's report descriptor
describes, and which hid2nut therefore cannot reach.

What

Standard PDC feature-report mappings are kept for the values that are
correct (battery.charge, battery.voltage, battery.runtime, the
PresentStatus flags, the delay timers). The 0x71 frame is decoded
for output.current, ups.load, input.voltage, output.voltage,
battery.current, battery.charger.status, battery.temperature and
battery.type. The VID:PID is registered in the upower hwdb.

LB is deliberately not synthesized: with battery.charge live, the core
ignorelb option plus battery.charge.low covers that case.

Shared VID:PID 2b89:ffff — please review

Siblings share these IDs but push a different telemetry layout (the US3000
pushes subtype 0x03 frames; see #2987). The subdriver therefore claims on
VID/PID alone, so a sibling attaches and keeps every standard PDC mapping
instead of falling through to "unsupported", and gates the vendor decoder
on the USB product string so a non-US2000 gets no values decoded at
another model's offsets.

Effect on existing setups: a sibling configured with subdriver=Arduino is
unaffected, because an explicit subdriver is resolved by name before the
claim() loop runs. In auto mode 2b89:ffff currently matches no
subdriver at all, so no working configuration is downgraded. -x explore
users would now get this subdriver instead of explore-hid. If the
maintainers prefer the claim be strict on the US2000 product string, that
is a one-line change.

Testing

US2000 on NUT 2.8.5 master, mains and on battery.

Not tested against the US3000 or any other sibling — no such hardware
available.

AI Disclosure

opencode (Muse Spark 1.3, DeepSeek V4.1 Flash) assisted with the
subdriver and the firmware analysis.

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.

• Use of coding helper tools and AI should be disclosed in the commit
  or PR comments (it is interesting to know which ones do a decent job).
  As with other contributions, a human is responsible and thanked for the
  quality and content of the change, and is presumed to have the right to
  post that code to be published further under the project's license terms.

• Especially with involvement of AI, including modern IDE coding aid,
  please be sure to revise that proposed code and documentation changes
  follow NUT code style guide -- this helps portability across the decades
  worth of supported systems. Notably, avoid Unicode characters where ASCII
  text is expected (C sources and headers, manual pages and other acsiidoc
  inputs). Particularly AI is keen on adding mdash characters instead of
  plain ASCII double-dash (which renders into the long dash where applicable).

• Please star NUT on GitHub, this helps with sponsorships! ;)

Frequent "underwater rocks" for driver addition/update PRs

• Revised existing driver families and added a sub-driver if applicable
  (nutdrv_qx, usbhid-ups...) or added a brand new driver in the other
  case.

• Did not extend obsoleted drivers with new hardware support features
  (notably blazer and other single-device family drivers for Qx protocols,
  except the new nutdrv_qx which should cover them all).

• For updated existing device drivers, bumped the DRIVER_VERSION macro
  or its equivalent.

• For USB devices (HID or not), revised that the driver uses unique
  VID/PID combinations, or raised discussions when this is not the case
  (several vendors do use same interface chips for unrelated protocols).

• For new USB devices, built and committed the changes for the
  scripts/upower/95-upower-hid.hwdb file

• Proposed NUT data mapping is aligned with existing docs/nut-names.txt
  file. If the device exposes useful data points not listed in the file, the
  experimental.* namespace can be used as documented there, and discussion
  should be raised on the NUT Developers mailing list to standardize the new
  concept.

• Updated data/driver.list.in if applicable (new tested device info)

Frequent "underwater rocks" for general C code PRs

• Did not "blindly assume" default integer type sizes and value ranges,
  structure layout and alignment in memory, endianness (layout of bytes and
  bits in memory for multi-byte numeric types), or use of generic int where
  language or libraries dictate the use of size_t (or ssize_t sometimes).

• Progress and errors are handled with upsdebugx(), upslogx(),
  fatalx() and related methods, not with direct printf() or exit().
  Similarly, NUT helpers are used for error-checked memory allocation and
  string operations (except where customized error handling is needed,
  such as unlocking device ports, etc.)

• Coding style (including whitespace for indentations) follows precedent
  in the code of the file, and examples/guide in docs/developers.txt file.

• For newly added files, the Makefile.am recipes were updated and the
  make distcheck target passes.

General documentation updates

• Added a bullet point into NEWS.adoc, possibly also UPGRADING.adoc
  if there is something packagers or custom-build users should take into
  account (new driver categories, configuration options, dependencies...)

• Updated docs/acknowledgements.txt (for vendor-backed device support)

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

• 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).

Additional work may be needed after posting this PR

• Propose a PR for NUT DDL with detailed device data dumps from tests
  against real hardware (the more models, the better).

• Address NUT CI farm build failures for the PR: testing on numerous
  platforms and toolkits can expose issues not seen on just one system.

• Revise suggestions from LGTM.COM analysis about "new issues" with
  the changed codebase.

[github-actions]

Preparing a ZIP file with standard source tarball and another tarball with pre-built docs for commit 6e4f62a ...

[AppVeyorBot]

✅ Build nut 2.8.5.5902-master completed (commit 82d1fb8917 by @reklrekl)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.5902-master.7z
• ccache: 400 of 411 compilations were cache hits (97.3%); cache size 750 of 750 MiB after cleanup