apc_modbus: Add support for commands

[EchterAgo]

This is for after merging #2063 .

We need to add support for UPS commands. This is what we can add:

• UPSCommand_BF

  • RestoreFactorySettings

• OutletCommand_BF

  • Cancel

  • OutputOn

  • OutputOff

  • OutputShutdown

  • OutputReboot

  • args:

    • ColdBootAllowed
    • UseOnDelay
    • UseOffDelay

  • target:

    • UnswitchedOutletGroup
    • SwitchedOutletGroup0
    • SwitchedOutletGroup1
    • SwitchedOutletGroup2

• SimpleSignalingCommand_BF

  • RequestShutdown
  • RemoteOff
  • RemoteOn

• ReplaceBatteryTestCommand_BF (incorrectly named UPSStatus_BF in docs)

  • start test

• RunTimeCalibrationCommand_BF

  • start calibration

• UserInterfaceCommand_BF

  • mute
  • cancel mute
  • acknowledge battery alarm

[EchterAgo]

There are also quite a few values that can not only be read but also set. Things like the shutdown delay.

[EchterAgo]

We also should add a SIZEOF_ARRAY helper macro to simplify the sizeof(x)/sizeof(x[0]) situation, see #2063

UPDATE: #2124 for this one

[jimklimov]

@EchterAgo : do you expect to proceed with this immediately/soon? As in, should we delay NUT v2.8.1 release in anticipation of this addition (so as to publish it with a fully functional apc_modbus driver, at least to the extent that systems shutdown and load off/cycling can be set up)?

[EchterAgo]

Sorry, but it will have to wait a bit, I currently have some other things I need to get sorted out first, but I expect to have this working sometime in November.

[EchterAgo]

Although maybe if you can tell me what you'd consider the minimum amount of support and which commands that would be, I might be able to do a quick implementation of these. I'm really new to actually using commands / writing values in nut, I have only used it for monitoring so far.

I'm not sure how I'd actually do system shutdown from the UPS, do you mean just turning the output off? Load off / cycling is something that APC supports for what it calls outlet groups.

[EchterAgo]

Implementing the commands should actually be just a simple register write. I think for power on/off/reboot we just need to write the right registers. We might need only OutletCommand_BF and SimpleSignalingCommand_BF. The documentation for these are here if anyone wants to check: https://download.schneider-electric.com/files?p_enDocType=Application+Notes&p_File_Name=MPAO-98KJ7F_R1_EN.pdf&p_Doc_Ref=SPD_MPAO-98KJ7F_EN

I'd need some advice what to write for which command, then I think I could do an implementation quickly.

[EchterAgo]

I just checked and for example modbus_write_register(modbus_ctx, 1541, 1); (ReplaceBatteryTestCommand_BF) works to start a battery test. I just need to know when to call which function, implement some error handling and maybe things also need some status polling (for example RunTimeCalibrationCommand_BF has a RunTimeCalibrationStatus_BF).

[jimklimov]

Well, modeling after other NUT drivers that map commands and data points to protocol/media specific information (e.g. "1541" and "1" in your post above), it would make sense to eventually use those in a mapping table and just have a loop that converts from layman text items to whatever the device likes.

I wonder if the recent several modbus drivers have accumulated some lessons-learned sufficient to make a single driver with shared code for modbus and subdrivers for specific devices/vendors (like usbhid-ups, snmp-ups or nutdrv_qx) or at least gauge if there are sufficient similaritites that such driver would be beneficial? :)

[jimklimov]

As for the "bare minimum" - well, monitoring the device to the point that we know it is discharging and in a low-battery state is already quite a lot :)

Actual shutdown routines usually end with a command to the device to turn off the load or completely the UPS (or ideally - power-cycle if the wall power came back while we were shutting down, possibly turn on after getting recharged to a safe level that ensures another graceful shutdown if needed). These relate to several commands and variables about "load." and "shutdown." (see docs/nut-names.txt) , further depending on what this or that hardware/firmware actually allows to do.

Numerous other things like setting delays for these power operations, starting calibration, managing separate outlet groups, popularly the beeper state, etc. are useful cherries on the cake - welcome generally but might wait if not a low-hanging fruit.

[EchterAgo]

Thanks for the information Jim. I'll try to look into this tomorrow (23rd, it is the 22nd already here). @PrplHaze4, do you mind also sharing what commands you consider most important and how you'd expect them to work?