drivers/snmp-ups: add "voltronic" subdriver for enterprise 43943 UPSes - #3570
drivers/snmp-ups: add "voltronic" subdriver for enterprise 43943 UPSes#3570chrisallen wants to merge 2 commits into
Conversation
|
A ZIP file with standard source tarball and another tarball with pre-built docs for commit 487f190 is temporarily available: NUT-tarballs-PR-3570.zip. |
Add support for Voltronic enterprise 43943 SNMP cards, tested with a PowerShield Centurion RT 1000VA and PSSNMPV4 card. The private MIB gives better resolution for most readings, so use it first and keep RFC1628 as a fallback. Direct GETs showed that the private line tables use index 0 while the RFC1628 tables use index 1, despite the MIB declarations not making that difference clear. Map identity, topology, status, battery data, input, output, bypass, ratings, load and measured real power. Publish the canonical aggregate power names alongside the useful output aliases. The card returns zero for apparent power, power factor and the generic transfer limits even when the UPS is carrying load. Leave those values out instead of presenting them as measurements or trying to calculate them from load. Leave the optional PSEMD branch out as well because no connected sensor was available to verify it. Delayed shutdown, startup and beeper controls follow the vendor MIB and firmware definitions. They have not been tested on live hardware, and no control command was sent during development. Add the subdriver to the build, document its limits, and add the tested PowerShield model to the compatibility list. Signed-off-by: Chris Allen <203867+chrisallen@users.noreply.github.com>
3ff92f3 to
15ce8fa
Compare
|
❌ Build nut 2.8.5.5055-master failed (commit e1288d05ad by @chrisallen) |
|
I'll fix up the issues reported by the build farm tomorrow. |
|
✅ Build nut 2.8.5.5056-master completed (commit ace2c3e6d0 by @chrisallen)
|
|
✅ Build nut 2.8.5.5056-master completed (commit ace2c3e6d0 by @chrisallen) |
…mp `snmp-ups` version [networkupstools#3570] Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
jimklimov
added
SNMP
Voltronic
AI
|
✅ Build nut 2.8.5.5059-master completed (commit d081651e56 by @jimklimov)
|
|
Thank you @jimklimov for adding the remaining parts to this PR. Here is the evidence output from this driver running on my Unraid system. https://gist.github.com/chrisallen/ed6cf59a1ae2ec86dfb9bacac0b47206 Note: This new Voltronic subdriver detected the native device as XIIHVT1K0. Standard NUT identity overrides were used to show the identity as PowerShield Centurion RT 1000VA. No PowerShield branding or model-specific ratings are compiled into the subdriver. |
3 participants
Closes #3478.
Summary
This adds a
voltronicsubdriver tosnmp-upsfor UPS cards using Voltronic'senterprise 43943 MIBs. I developed it against a PowerShield Centurion RT
1000VA (PSCERT1000) with a PSSNMPV4 card running firmware 1.1.8.C.
Although the UPS I tested is sold by PowerShield, the same protocol is used by
several OEM brands mentioned in #3478. I have therefore kept the subdriver
generic instead of building PowerShield branding into it. Friendly identity
overrides can still be set in
ups.confwhere needed.How I worked through the driver
I started with the three MIBs supplied with #3478:
RFC1628.mib.txtUPS_20250508.MIB.txtUPSmib.mib.txtI also unpacked
PSSNMPv4MIBfiles.zipand statically inspected the cardfirmware in
upgrade1_1_8_C_20220310.tar.gz.zip. The firmware was useful forchecking the enterprise identity, defaults, table indexing, scaling and
special values used when a reading or environmental sensor is unavailable.
The mapping was then compared with NUT's SNMP driver documentation,
docs/nut-names.txt, and existing subdrivers such asietf-mib.candxppc-mib.c. This was written from those findings rather than generated fromthe MIB files.
Some details could not safely be decided from the MIB declarations alone. The
main example was the table index: direct GET requests showed that the private
input, output and bypass tables use
.0, while the corresponding RFC1628tables use
.1. I tested both instances for the ambiguous objects and usedthe live results in the mapping.
The private MIB usually gives the more precise value, so it is preferred where
verified. RFC1628 remains as a fallback where useful, with
SU_FLAG_UNIQUEpreventing a lower-precision fallback from replacing a valid private value.
What is mapped
The subdriver covers identity, firmware, topology, NUT status, alarms, battery
data, input, output, bypass, nominal ratings, load and measured real power. It
publishes the canonical
ups.power*andups.realpower*names along with theuseful
output.*compatibility aliases.The card reports real power with useful precision, but returns zero for
apparent power and power factor even while the UPS is carrying load. Those
values are treated as unsupported and left out. The driver does not invent
apparent power from rounded load or present the nominal W/VA ratio as a live
power factor. Generic RFC1628 transfer limits that return placeholder zeroes
are also omitted, while the valid non-zero bypass and ECO limits are kept.
I have left the optional PSEMD environmental branch out for now. The firmware
and read-only probes showed how a disconnected sensor is represented, but I
did not have a connected EMD to verify its scaling, presence changes, or the
smoke/contact channels. I thought leaving it unmapped was safer than guessing.
Delayed shutdown, startup and beeper controls follow the vendor MIB and NUT's
delayed-shutdown model. I did not run any of these commands against the live
UPS, so they should not yet be considered hardware-tested.
Testing
All testing against the UPS was read-only. I did not send an SNMP SET, invoke
a NUT instant command, start a battery test, or change the output state.
I used direct SNMPv2c GETs to check OIDs,
.0/.1table instances,enumerations, scaling, valid zero readings and unsupported-value sentinels. I
also ran a complete foreground polling cycle on Unraid 7.3.2. The driver was
detected as
voltronic 0.10and returned plausible online status, battery,voltage, frequency, current, load and real-power readings. Unsupported
apparent power, power factor, generic transfer limits, empty alarms and EMD
values were absent as intended.
For build and integration checks I:
snmp-upsfrom the current NUT default branch on x86_64 with-Wall -Wextra -Werror;make -C drivers checkandgit diff --check;NUT-unRAID plugin; and
against the target Unraid loader and libraries before live polling.
Development assistance
I used OpenAI Codex to help compare the MIBs and firmware with existing NUT
code, prepare the implementation and documentation, and organize the tests. I
reviewed the changes and validated them against the supplied files and live
hardware, and I take responsibility for the contribution.
Contributor checklist
General points
Add SNMP sub-driver for Voltronics/Powershield UPS (PEN 43943) #3478.
Signed-off-bytrailer.docs/developers.txt, thesurrounding source style and NUT's ASCII requirements.
Driver addition
snmp-upsdriver family.voltronic 0.10subdriver version.subdriver.
docs/nut-names.txt; vendor-specific mode informationuses the experimental namespace where needed.
data/driver.list.in.Code, build and documentation
conventions.
drivers/Makefile.amfor the new source and header.docs/man/snmp-ups.txtmanual page; no new manualpage recipe is needed.
make distcheckhas not been run locally.make spellcheckhas not been run locally.NEWS.adocwas not changed because this adds a subdriver without a newpackage, dependency or upgrade requirement.
docs/acknowledgements.txtwas not changed because this was not avendor-backed contribution.
Follow-up after posting
static analysis.