drivers: add experimental APC Microlink serial driver#3406
Open
libschmudie-so wants to merge 13 commits intonetworkupstools:masterfrom
Open
drivers: add experimental APC Microlink serial driver#3406libschmudie-so wants to merge 13 commits intonetworkupstools:masterfrom
libschmudie-so wants to merge 13 commits intonetworkupstools:masterfrom
Conversation
|
A ZIP file with standard source tarball and another tarball with pre-built docs for commit 1952ef3 is temporarily available: NUT-tarballs-PR-3406.zip. |
|
❌ Build nut 2.8.5.4533-master failed (commit 25f28b85db by @libschmudie-so) |
Member
|
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. |
Implement a new apcmicrolink driver for APC Smart-UPS units that expose the Microlink serial protocol. The driver establishes a Microlink session over the serial link, reads the device descriptor blob, and uses that runtime descriptor map to publish standard NUT variables, writable settings, status bits, alarms, and supported instant commands. Add labeled Microlink command masks for battery tests, calibration, UPS control, and outlet-group power control; wire APC-style load and shutdown commands through the static command map; publish input.transfer.reason from UPS status change cause; and stop folding simple-signaling status bits into ups.status. Also hook upsdrv_shutdown() up to the Microlink shutdown request, document the driver, and clean up initial upstream review issues such as missing file headers, whitespace, and format-string warnings. Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
…etworkupstools#3406] Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
…#3406] Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
jimklimov
added
serial port
AI
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| } | ||
|
|
||
| memcpy(descriptor_blob + usage->data_offset, payload, usage->size); | ||
| if (page < 256U) { |
Member
There was a problem hiding this comment.
@libschmudie-so : if there is potential for arch-dependent numeric type sizing, check other NUT code for use of pragmas to quiesce the warnings on specific-sized builds. Maybe a symbolic and type-specific max constraint like page <= UCHAR_MAX would be better than a number.
| return microlink_send_descriptor_write(path, payload, usage->size); | ||
| } | ||
|
|
||
| static int microlink_send_descriptor_typed_value(const microlink_desc_value_map_t *entry, |
| return pos; | ||
| } | ||
|
|
||
| static size_t microlink_parse_descriptor_block(const unsigned char *blob, size_t blob_len, |
Comment on lines
+1028
to
+1223
| switch (entry->type) { | ||
| case MLINK_DESC_STRING: | ||
| memset(payload, 0, usage->size); | ||
| for (i = 0; i < usage->size && val[i] != '\0'; i++) { | ||
| payload[i] = (unsigned char)val[i]; | ||
| } | ||
| return microlink_send_descriptor_write(path, payload, usage->size); | ||
|
|
||
| case MLINK_DESC_FIXED_POINT: | ||
| { | ||
| char *endptr = NULL; | ||
| int64_t raw; | ||
|
|
||
| if (usage->size == 0 || usage->size > 8) { | ||
| return 0; | ||
| } | ||
|
|
||
| if (entry->bin_point == 0U) { | ||
| /* strict integer parsing */ | ||
| long long parsed = strtoll(val, &endptr, 10); | ||
|
|
||
| if (endptr == val || *endptr != '\0') { | ||
| return 0; | ||
| } | ||
|
|
||
| raw = (int64_t)parsed; | ||
| } else { | ||
| /* fixed-point parsing */ | ||
| double numeric = strtod(val, &endptr); | ||
| double scaled; | ||
|
|
||
| if (endptr == val || *endptr != '\0') { | ||
| return 0; | ||
| } | ||
|
|
||
| scaled = numeric * (double)(1U << entry->bin_point); | ||
| raw = (int64_t)((scaled >= 0.0) ? (scaled + 0.5) : (scaled - 0.5)); | ||
| } | ||
|
|
||
| /* shared range + packing logic */ | ||
|
|
||
| { | ||
| int64_t min_raw, max_raw; | ||
|
|
||
| if (entry->sign == MLINK_DESC_SIGNED) { | ||
| max_raw = ((int64_t)1 << ((usage->size * 8U) - 1U)) - 1; | ||
| min_raw = -((int64_t)1 << ((usage->size * 8U) - 1U)); | ||
| } else { | ||
| min_raw = 0; | ||
| max_raw = ((int64_t)1 << (usage->size * 8U)) - 1; | ||
| } | ||
|
|
||
| if (raw < min_raw || raw > max_raw) { | ||
| return 0; | ||
| } | ||
| } | ||
|
|
||
| memset(payload, 0, usage->size); | ||
| for (i = 0; i < usage->size; i++) { | ||
| size_t shift = (usage->size - 1U - i) * 8U; | ||
| payload[i] = (unsigned char)(((uint64_t)raw >> shift) & 0xFFU); | ||
| } | ||
|
|
||
| return microlink_send_descriptor_write(path, payload, usage->size); | ||
| } | ||
|
|
||
| case MLINK_DESC_DATE: | ||
| { | ||
| int year; | ||
| int check_year; | ||
| unsigned int month, day; | ||
| unsigned int check_month, check_day; | ||
| int64_t raw; | ||
|
|
||
| if (usage->size == 0 || usage->size > 8) { | ||
| return 0; | ||
| } | ||
|
|
||
| if (sscanf(val, "%d-%u-%u", &year, &month, &day) != 3) { | ||
| return 0; | ||
| } | ||
|
|
||
| if (month < 1U || month > 12U || day < 1U || day > 31U) { | ||
| return 0; | ||
| } | ||
|
|
||
| raw = microlink_days_from_civil(year, month, day); | ||
| if (raw < 0 || (uint64_t)raw > microlink_max_unsigned_for_size(usage->size)) { | ||
| return 0; | ||
| } | ||
|
|
||
| microlink_civil_from_days(raw, &check_year, &check_month, &check_day); | ||
| if (check_year != year || check_month != month || check_day != day) { | ||
| return 0; | ||
| } | ||
|
|
||
| memset(payload, 0, usage->size); | ||
| for (i = 0; i < usage->size; i++) { | ||
| size_t shift = (usage->size - 1U - i) * 8U; | ||
| payload[i] = (unsigned char)(((uint64_t)raw >> shift) & 0xFFU); | ||
| } | ||
|
|
||
| return microlink_send_descriptor_write(path, payload, usage->size); | ||
| } | ||
|
|
||
| case MLINK_DESC_TIME: | ||
| { | ||
| unsigned int hours, minutes, seconds; | ||
| uint64_t raw; | ||
|
|
||
| if (usage->size == 0 || usage->size > 8) { | ||
| return 0; | ||
| } | ||
|
|
||
| if (sscanf(val, "%u:%u:%u", &hours, &minutes, &seconds) != 3) { | ||
| return 0; | ||
| } | ||
|
|
||
| if (minutes > 59U || seconds > 59U) { | ||
| return 0; | ||
| } | ||
|
|
||
| raw = ((uint64_t)hours * 3600U) + ((uint64_t)minutes * 60U) + (uint64_t)seconds; | ||
| if (raw > microlink_max_unsigned_for_size(usage->size)) { | ||
| return 0; | ||
| } | ||
|
|
||
| memset(payload, 0, usage->size); | ||
| for (i = 0; i < usage->size; i++) { | ||
| size_t shift = (usage->size - 1U - i) * 8U; | ||
| payload[i] = (unsigned char)((raw >> shift) & 0xFFU); | ||
| } | ||
|
|
||
| return microlink_send_descriptor_write(path, payload, usage->size); | ||
| } | ||
|
|
||
| case MLINK_DESC_ENUM_MAP: | ||
| case MLINK_DESC_BITFIELD_MAP: | ||
| { | ||
| char *endptr = NULL; | ||
| int64_t raw = 0; | ||
| size_t j; | ||
|
|
||
| if (usage->size == 0 || usage->size > 8) { | ||
| return 0; | ||
| } | ||
|
|
||
| if (entry->map != NULL) { | ||
| for (j = 0; entry->map[j].text != NULL; j++) { | ||
| if (!strcasecmp(entry->map[j].text, val)) { | ||
| raw = entry->map[j].value; | ||
| break; | ||
| } | ||
| } | ||
|
|
||
| if (entry->map[j].text == NULL) { | ||
| if (entry->type == MLINK_DESC_ENUM_MAP) { | ||
| raw = (int64_t)strtoll(val, &endptr, 0); | ||
| } else { | ||
| raw = (int64_t)strtoull(val, &endptr, 0); | ||
| } | ||
|
|
||
| if (endptr == val || *endptr != '\0') { | ||
| return 0; | ||
| } | ||
| } | ||
| } | ||
|
|
||
| { | ||
| int64_t min_raw, max_raw; | ||
|
|
||
| if (entry->type == MLINK_DESC_ENUM_MAP && entry->sign == MLINK_DESC_SIGNED) { | ||
| max_raw = ((int64_t)1 << ((usage->size * 8U) - 1U)) - 1; | ||
| min_raw = -((int64_t)1 << ((usage->size * 8U) - 1U)); | ||
| } else { | ||
| min_raw = 0; | ||
| max_raw = ((int64_t)1 << (usage->size * 8U)) - 1; | ||
| } | ||
|
|
||
| if (raw < min_raw || raw > max_raw) { | ||
| return 0; | ||
| } | ||
| } | ||
|
|
||
| memset(payload, 0, usage->size); | ||
| for (i = 0; i < usage->size; i++) { | ||
| size_t shift = (usage->size - 1U - i) * 8U; | ||
| payload[i] = (unsigned char)(((uint64_t)raw >> shift) & 0xFFU); | ||
| } | ||
|
|
||
| return microlink_send_descriptor_write(path, payload, usage->size); | ||
| } | ||
|
|
||
| default: | ||
| return 0; | ||
| } |
Comment on lines
+1399
to
+1490
| switch (token) { | ||
| case 0xF4: | ||
| pos = microlink_parse_descriptor_block(blob, blob_len, pos, data_offset, path); | ||
| if (pos == 0) { | ||
| return 0; | ||
| } | ||
| break; | ||
| case 0xF5: | ||
| skip_next = 1; | ||
| break; | ||
| case 0xF6: | ||
| case 0xFF: | ||
| return pos; | ||
| case 0xF7: | ||
| break; | ||
| case 0xF8: | ||
| { | ||
| char child[64]; | ||
| if (pos >= blob_len) { | ||
| return 0; | ||
| } | ||
| if (!microlink_build_child_path(child, sizeof(child), "", blob[pos++], ":")) { | ||
| return 0; | ||
| } | ||
| pos = microlink_parse_descriptor_block(blob, blob_len, pos, data_offset, child); | ||
| if (pos == 0) { | ||
| return 0; | ||
| } | ||
| break; | ||
| } | ||
| case 0xFE: | ||
| { | ||
| char child[64]; | ||
| if (pos >= blob_len) { | ||
| return 0; | ||
| } | ||
| if (!microlink_build_child_path(child, sizeof(child), path, blob[pos++], ".")) { | ||
| return 0; | ||
| } | ||
| pos = microlink_parse_descriptor_block(blob, blob_len, pos, data_offset, child); | ||
| if (pos == 0) { | ||
| return 0; | ||
| } | ||
| break; | ||
| } | ||
| case 0xFD: | ||
| { | ||
| unsigned char collection_id; | ||
| unsigned char count; | ||
| size_t block_start; | ||
| size_t block_end = 0; | ||
| unsigned int idx; | ||
|
|
||
| if (pos + 1 >= blob_len) { | ||
| return 0; | ||
| } | ||
|
|
||
| collection_id = blob[pos++]; | ||
| count = blob[pos++]; | ||
| block_start = pos; | ||
|
|
||
| for (idx = 0; idx < count; idx++) { | ||
| char child[64]; | ||
| size_t sub_pos; | ||
|
|
||
| if (!microlink_build_collection_path(child, sizeof(child), path, | ||
| collection_id, idx)) { | ||
| return 0; | ||
| } | ||
| sub_pos = microlink_parse_descriptor_block(blob, blob_len, block_start, data_offset, child); | ||
| if (sub_pos == 0) { | ||
| return 0; | ||
| } | ||
| block_end = sub_pos; | ||
| } | ||
|
|
||
| pos = block_end; | ||
| break; | ||
| } | ||
| default: | ||
| if (token == 0x00 || microlink_is_descriptor_operator(token) || token > 0xDF) { | ||
| return 0; | ||
| } | ||
|
|
||
| pos = microlink_parse_descriptor_usage(blob, blob_len, pos, data_offset, path, | ||
| token, skip_next); | ||
| if (pos == 0) { | ||
| return 0; | ||
| } | ||
| skip_next = 0; | ||
| break; | ||
| } |
Member
|
@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 |
Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
docs/man/Makefile.am: provide apsmicrolink.html also [networkupstools#3406]
drivers/Makefile.am: EXTRA_DIST apcmicrolink-maps.h apcmicrolink.h [networkupstools#3406]
NEWS.adoc: introduce apcmicrolink driver [networkupstools#3406]
|
❌ Build nut 2.8.5.4537-master failed (commit a65d9792c4 by @libschmudie-so) |
Member
|
Yeah, now it is sad about spelling checks. Do you have |
Member
|
There are also compiler complaints from static analysis, like: 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 For the formatting string, see |
Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
Author
|
How should I go about this? fmt comes from the functions arguments and is always fixed like
|
Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
Member
|
See connent above, the part about |
Author
|
So i should just pass fmt twice into the _dynamic version? That semt counter-intuitive to me, that's why I am checking |
|
✅ Build nut 2.8.5.4548-master completed (commit 17bc6789c6 by @libschmudie-so)
|
|
✅ Build nut 2.8.5.4549-master completed (commit 85cb70d261 by @libschmudie-so)
|
Member
|
Yes, it is usually that the first "real" format is a sentence with a few percent-values, maybe dynamically constructed in a buffer or taken from some array/map, and the other is a string just with those percents, static the way compiler checks like. |
| return 1; | ||
| } | ||
|
|
||
| static void microlink_publish_descriptor_exports(void) |
Contributor
|
Might be interesting if we could combine some things with the Example output for 2 of my UPS: |
Member
Portability trouble. For the |
Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
Author
|
@EchterAgo I've had a look and it seems microlink has more bits (or maybe they are just not documented for modbus). Do you think that maybe the CMD defines could be used as a common point between microlink and modbus? I'll definitely have a go at changing my info names to match yours. |
…mmands and values Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
|
✅ Build nut 2.8.5.4577-master completed (commit 540502e992 by @libschmudie-so)
|
|
✅ Build nut 2.8.5.4579-master completed (commit 4b9a1d92cf by @libschmudie-so)
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 othercase.
Did not extend obsoleted drivers with new hardware support features
(notably
blazerand other single-device family drivers for Qx protocols,except the new
nutdrv_qxwhich should cover them all).For updated existing device drivers, bumped the
DRIVER_VERSIONmacroor 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.hwdbfileProposed NUT data mapping is aligned with existing
docs/nut-names.txtfile. If the device exposes useful data points not listed in the file, the
experimental.*namespace can be used as documented there, and discussionshould be raised on the NUT Developers mailing list to standardize the new
concept.
Updated
data/driver.list.inif 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
intwherelanguage or libraries dictate the use of
size_t(orssize_tsometimes).Progress and errors are handled with
upsdebugx(),upslogx(),fatalx()and related methods, not with directprintf()orexit().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.txtfile.For newly added files, the
Makefile.amrecipes were updated and themake distchecktarget passes.General documentation updates
Added a bullet point into
NEWS.adoc, possibly alsoUPGRADING.adocif 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/*.txtfilesand corresponding recipe lists in
docs/man/Makefile.amfor new pagesPassed
make spellcheck, updated spell-checking dictionary in thedocs/nut.dictfile if needed (did not remove any words -- themakerule 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.