drivers: add experimental APC Microlink serial driver#3406
drivers: add experimental APC Microlink serial driver#3406libschmudie-so wants to merge 13 commits into
Conversation
|
Preparing a ZIP file with standard source tarball and another tarball with pre-built docs for commit 9cdbc62 ... |
|
❌ Build nut 2.8.5.4533-master failed (commit 25f28b85db by @libschmudie-so) |
|
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. |
…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) { |
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, |
| 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; | ||
| } |
| 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; | ||
| } |
|
@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) |
|
Yeah, now it is sad about spelling checks. Do you have |
|
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 |
|
✅ Build nut 2.8.5.4579-master completed (commit 4b9a1d92cf by @libschmudie-so)
|
|
@libschmudie-so : PRs for Thanks @EchterAgo ! |
|
Cheers @libschmudie-so : is further work planned to complete this PR into a consistent and mergeable state, please? |
|
Hi @jimklimov, yes I do intend to get this into a mergeable state. I am still looking at signal-name parity between apc-modbus and this right now. |
|
@jimklimov If you wouldn't mind, could you maybe give me a quick refresher on what still needs to be done aside from the signal names? |
|
Can't quickly remember if there was anything else. A quick scroll up revealed #3406 (comment) but maybe that's it, OTOH. |
|
@jimklimov I'll have a look right now if there is something I can do to share some code between apcmicrolink and apc-modbus as there is a lot in common. I'll push the changes along with the missing/renamed signals and then I'll have another look regarding code issues |
|
@jimklimov is there a correct way for me to run the code checks locally? |
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>
…#3406] Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
…etworkupstools#3406] Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
…mmands and values Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
Change to allow flexible frame size (upto 256 bytes) by waiting for page0, as some devices with payload size != 35 were incompatible. Allow variable length serial number string during handshake (as some devices use 14 characters). Signed-off-by: Tom Eldon <tom@tomeldon.com>
|
❌ Build nut 2.8.5.4692-master failed (commit dd0896c5a0 by @libschmudie-so) |
|
Sorry for the delay, one easy way for local checks is to use |
|
❌ Build nut 2.8.5.4695-master failed (commit f186c46cd3 by @libschmudie-so) |
Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
… of command source Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
6 participants
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.