drivers: add experimental APC Microlink serial driver

[libschmudie-so]

Implement a new apcmicrolink driver for APC Smart-UPS units that expose the Microlink serial protocol over the RJ45 serial interface.

The driver establishes a Microlink session over the serial link, reads and parses the device descriptor blob at runtime, and uses that descriptor map to publish standard NUT variables, writable settings, alarms, and supported instant commands. It also adds labeled Microlink command masks for battery tests, runtime calibration, UPS control, and outlet-group power control, including APC-style load., shutdown., and outlet.group.N.* commands.

The driver now uses the Microlink UPS status word for ups.status, exposes input.transfer.reason from the UPS status change cause enum, and avoids folding simple-signaling bits into the synthesized NUT status. The patch also adds the driver to the build and hardware lists, documents configuration and current limitations, and cleans up initial upstream review issues such as missing file headers, whitespace, and format-string warnings.

Tested against:

APC Smart-UPS 750 (SMT750RMI2UC)

Coding helper disclosure: Codex

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.

• 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]

A ZIP file with standard source tarball and another tarball with pre-built docs for commit 1fdc538 is temporarily available: NUT-tarballs-PR-3406.zip.

[AppVeyorBot]

❌ Build nut 2.8.5.4533-master failed (commit 25f28b85db by @libschmudie-so)

• artifacts (if any)

[AppVeyorBot]

❌ Build nut 2.8.5.4533-master failed (commit 25f28b85db by @libschmudie-so)

[jimklimov]

This looks very solid, thanks!

CI disliked something about dist recipes though; while at it - the man page HTML rendering is not listed in the Makefile.am. I'm on a phone commuting now, so can't look deeper.

[AppVeyorBot]

❌ Build nut 2.8.5.4534-master failed (commit a16ec310aa by @libschmudie-so)

• artifacts (if any)

[AppVeyorBot]

❌ Build nut 2.8.5.4535-master failed (commit b9a755542f by @libschmudie-so)

• artifacts (if any)

[jimklimov]

@libschmudie-so : Cheers, your PR is made from your master branch and not with a toggle that I can edit it as a maintainer, so I posted a couple of recipe fixes as PRs into your fork. Hopefully they should get the CI builds passing.

Is this a personal or corporate-backed contribution? Feel free to add a note in acknowledgements.txt in the latter case.

[AppVeyorBot]

❌ Build nut 2.8.5.4537-master failed (commit a65d9792c4 by @libschmudie-so)

• artifacts (if any)

[AppVeyorBot]

❌ Build nut 2.8.5.4537-master failed (commit a65d9792c4 by @libschmudie-so)

[jimklimov]

Yeah, now it is sad about spelling checks. Do you have aspell? Run make spellcheck-interactive-quick and it should arrange an interface to add the new words. Alternately, edit docs/nut.dict to same effect (bumping the number of entries in the top line, in the end):

FAILED : Aspell reported errors here:
----- vvv
600:& apcmicrolink 2 32: apc microlink, apc-microlink
688:& RMI 18 29: RIM, REMI, MRI, EMI, RM, MI, RI, ROM, RUM, RAMIE, RAM, REM, RMS, RBI, RSI, RIME, RAMA, ROME
----- ^^^
make[5]: *** [/home/runner/work/nut/nut/nut-2.8.5.13.7/_build/sub/docs/Makefile:1875: ../NEWS.adoc-spellchecked] Error 1
=====================================================================
FAILED automatic spellcheck for the following sources (relative to /home/runner/work/nut/nut/nut-2.8.5.13.7/_build/sub/docs) using custom dictionary file 'nut.dict':  ../../../docs/../NEWS.adoc
=====================================================================
Please 'cd /home/runner/work/nut/nut/nut-2.8.5.13.7/_build/sub && make spellcheck-interactive'
to either fix document sources or update the dictionary of accepted
words and spellings listed in the 'nut.dict' file there.
Either way, please follow up by posting a pull request or a patch
to integrate your fixes into the common NUT codebase.
=====================================================================
make[4]: *** [Makefile:1955: spellcheck] Error 1
  SUBDIR-MAKE	FAILURE: 'make spellcheck' in docs
make[3]: *** [Makefile:2119: spellcheck/docs] Error 2
  ASPELL	Spell checking on /home/runner/work/nut/nut/nut-2.8.5.13.7/docs/man/apcmicrolink.txt
FAILED : Aspell reported errors here:
----- vvv
70:& APCMICROLINK 2 1: APC MICROLINK, APC-MICROLINK
127:& apcmicrolink 2 1: apc microlink, apc-microlink
205:& apcmicrolink 2 2: apc microlink, apc-microlink
258:& apcmicrolink 2 2: apc microlink, apc-microlink
340:& apcmicrolink 2 2: apc microlink, apc-microlink
420:& apcmicrolink 2 6: apc microlink, apc-microlink
767:& apcmicrolink 2 14: apc microlink, apc-microlink
857:& showinternals 32 2: show internals, show-internals, internals, internalise, swindlers, centennials, internalize, sentinels, swindler's, bicentennials, fontanels, centennial's, vintners, swindles, Shantung's, shantung's, sentinel's, vintner's, swindle's, windfalls, wantons, tercentennials, bicentennial's, fontanel's, wanton's, wantonly, windlass, Chinatown's, winding's, windfall's, tercentennial's, Wendell's
1324:& showunmapped 9 2: show unmapped, show-unmapped, unmapped, swamped, shrimped, chomped, shampooed, wimped, champed
1628:& testinterval 6 12: test interval, test-interval, distinctively, distantly, distasteful, distastefully
1842:& Lukas 55 3: Lucas, Lucks, Lurks, Leaks, Luke's, Likes, Luck's, Lugs, Lakes, Lug's, Luges, Licks, Lula's, Lags, Lucas's, Lick's, Like's, Luaus, Lurkers, Ukase, Las, Luisa, Lacks, Larks, Leeks, Locks, Looks, Leak's, Skuas, Luna's, Lax, Lux, Loki's, Lu's, Luca, Luis, Luke, Lack's, Lake's, Lark's, Leas, Leek's, Lock's, Look's, UK's, LG's, Flukes, Lac's, Lag's, La's, Lusaka's, Lanka's, Luau's, Lea's, Fluke's
2251:& Schmid 12 9: Schmidt, Sch mid, Sch-mid, Chmod, Schmo, Schmier, Schemed, Schmo's, Schist, Chimed, Shamed, Schizoid
----- ^^^
make[6]: *** [/home/runner/work/nut/nut/nut-2.8.5.13.7/_build/sub/docs/Makefile:1875: apcmicrolink.txt-spellchecked] Error 1

[jimklimov]

There are also compiler complaints from static analysis, like:

apcmicrolink.c:335:49: error: format string is not a string literal [-Werror,-Wformat-nonliteral]
  335 |         written = vsnprintf(buf + *pos, buflen - *pos, fmt, ap);
      |                                                        ^~~
apcmicrolink.c:453:25: error: format string is not a string literal [-Werror,-Wformat-nonliteral]
  453 |                 snprintf(out, outlen, templ, rendered_index);
      |                                       ^~~~~
apcmicrolink.c:1028:10: error: enumeration value 'MLINK_DESC_NONE' not explicitly handled in switch [-Werror,-Wswitch-enum]
 1028 |         switch (entry->type) {
      |                 ^~~~~~~~~~~
apcmicrolink.c:1280:12: error: enumeration value 'MLINK_DESC_NONE' not explicitly handled in switch [-Werror,-Wswitch-enum]
 1280 |                         switch (entry->type) {
      |                                 ^~~~~~~~~~~
apcmicrolink.c:1999:11: error: enumeration value 'MLINK_DESC_WRITE_NONE' not explicitly handled in switch [-Werror,-Wswitch-enum]
 1999 |                 switch (entry->write_type) {
      |                         ^~~~~~~~~~~~~~~~~
5 errors generated.

For the switch, they have two conflicting requirements ("must have a default", and "do not need a default when all possible enum values were listed"), so we use a copy-paste block of pragmas to quiesce that. So list all enum values where needed, and add a default: surrounded by those pragmas, many examples in code for that. Probably the case for value(s) you did not list yet go just above that default line :)

For the formatting string, see {v,}snprintf_dynamic() etc. which validate that the actual fmt_dynamic formatting string you used matches the percent-argument template (which to compiler corresponds to the varargs passed to this fmt_reference parameter as if it were the formatting string). OTOH, something like snprintf_dynamic(out, outlen, templ, "%i", rendered_index); would be the fix.

[AppVeyorBot]

❌ Build nut 2.8.5.4538-master failed (commit 78527bd045 by @libschmudie-so)

• artifacts (if any)

[AppVeyorBot]

❌ Build nut 2.8.5.4539-master failed (commit c4a020c47c by @libschmudie-so)

• artifacts (if any)

[AppVeyorBot]

❌ Build nut 2.8.5.4706-master failed (commit bb2a0f4e65 by @libschmudie-so)

• artifacts (if any)

[AppVeyorBot]

✅ Build nut 2.8.5.4713-master completed (commit 140fc68627 by @libschmudie-so)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.4713-master.7z

[AppVeyorBot]

✅ Build nut 2.8.5.4713-master completed (commit 140fc68627 by @libschmudie-so)

[libschmudie-so]

@jimklimov Stupid question, but can you tell me what I am missing regarding the issue in "GHA-01: Tarballs / Make Dist and Docs Tarballs, see workflow page for links". It works locally and with ci_build.sh at this point without errors...

[AppVeyorBot]

❌ Build nut 2.8.5.4714-master failed (commit 93b97962b5 by @libschmudie-so)

• artifacts (if any)

[AppVeyorBot]

❌ Build nut 2.8.5.4714-master failed (commit 93b97962b5 by @libschmudie-so)

[AppVeyorBot]

❌ Build nut 2.8.5.4715-master failed (commit 51bd68c936 by @libschmudie-so)

• artifacts (if any)

[AppVeyorBot]

✅ Build nut 2.8.5.4718-master completed (commit f9204fadbd by @libschmudie-so)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.4718-master.7z

[AppVeyorBot]

✅ Build nut 2.8.5.4718-master completed (commit f9204fadbd by @libschmudie-so)

[libschmudie-so]

@jimklimov Stupid question, but can you tell me what I am missing regarding the issue in "GHA-01: Tarballs / Make Dist and Docs Tarballs, see workflow page for links". It works locally and with ci_build.sh at this point without errors...

Nevermind I think i figured it out...

[AppVeyorBot]

✅ Build nut 2.8.5.4723-master completed (commit 6c64df88b0 by @libschmudie-so)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.4723-master.7z

[libschmudie-so]

@jimklimov I think I have every fixed up and am also using some stuff shared with apc_modbus now as it is indeed similar. Is there anything left from your side?

[AppVeyorBot]

✅ Build nut 2.8.5.4727-master completed (commit 5a3d7ef674 by @libschmudie-so)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.4727-master.7z

[jimklimov]

This is quite a significant body of work, now with refactoring/simplification that seems generally beneficial, but I would welcome a review from @EchterAgo as this change impacts the driver maintained by him, just to make sure I did not miss something critical.

As for the review, it seems there is one line that should be dropped to pass CI across the board (PR against source branch posted), and highlighted several spots where I think it would be more maintainable to write the code differently, but I am open to being convinced I misunderstood a greater scheme :) Otherwise LGTM upon at least a cursory reading.

[jimklimov]

Here and below, is there a particular reason to NOT use textual names defined in the header for same bit-shifted values (avoid possible discrepancies if only one of the explicit bit-shifts somehow gets edited later without concern for the other)?

[libschmudie-so]

As far as I know not all have a matching enum, but for those that do I can of course use the enum values. They pretty much just came straight out of apcmicrolink-maps without much changing, thats why it doesn't have the enums in there.

[jimklimov]

Rather a question of style and maintainability than a requirement to change: why was 10957 hard-coded here and not defined as a macro or static number? e.g. as dropped from apc_modbus.c:

static const time_t apc_date_start_offset = 946684800; /* 2000-01-01 00:00 */

Wondering if the specific numbers would differ as/when/if this code migrates to 64-bit time sooner or later.

[libschmudie-so]

I honestly haven't thought about it that much. The value from the UPS was in days so the 10957 in days made sense to me. I guess we could pull it out into a static or macro tho.

[jimklimov]

Same question as elsewhere about use of bit-shift values explicitly vs. enum value textual names, to avoid future surprises.

[jimklimov]

Just in case: is there some code (transplanted map contents) that would warrant adding Copyright © 2023 Axel Gembe <axel@gembe.net> here?

CC @EchterAgo

[libschmudie-so]

From what I recall the functions in here are what I had written, but they probably are inspired from the apc_modbus so I'll just add the copyright in there too.

[jimklimov]

Note to self: this could be useful in #2811 :)

[AppVeyorBot]

✅ Build nut 2.8.5.4741-master completed (commit a0e8bd7409 by @libschmudie-so)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.4741-master.7z

[AppVeyorBot]

✅ Build nut 2.8.5.4742-master completed (commit b1ae14653a by @libschmudie-so)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.4742-master.7z

[AppVeyorBot]

✅ Build nut 2.8.5.4743-master completed (commit fb8908dfda by @libschmudie-so)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.4743-master.7z