[Nut-upsdev] Masterguard/Phoenixtec driver

[Edgar Fuß]

> Any hints/documentation pointers welcome.
So I just wrote it according to my understanding of the documentation and it seems to work quite well.

Output of upsc/upscmd/upsrw attached; comments welcome.

What's the preferred way of sharing my work?

However, I still have a bunch of questions.


General/Q* related:

instcmd() gets an "extradata" parameter which the Q* framework passes to the handler function (in value). Where does that data come from? Is there any documentation on it?
Looking at example code, test.battery seems to use that data, while shutdown.{reboot,stayoff} use ups.delay.{shutdown,start} instead. Is that simply for historical reasons?

I need to issue a command to the UPS in order to learn the supported values for output.voltage.nominal. In the Q* framework, is there a way to simply ignore the result (after it has been digested in a preprocess function to set the corresponding info_rw_t enum, of course)? I currently use a custom var "output_voltages" for it.

On certain commands, the UPS doesn't report an answer. Not an empty one, just nothing. Is there a saner way to handle that than the USB subdriver knowing these commands and skipping the result-reading part of the function for them?

In case a variable can be modified by an instcmd (e.g. ups.beeper.status by beeper.enable), how do I express that in the qx2nut table?
In case modifiyng one variable (output.voltage.nominal) is going to modify another one (output.voltage.current), how am I supposed to express that?

Given the Q* framework, how can I report battery.charger.status? It depends on several command's output.


Translating my UPS's values to NUT:

The UPS reports the battery's running time (not in the battery.runtime sense, the time since last replacement). How do I report that (I'm using ups.uptime now, which doesn't really seem correct)?

The UPS has a (fixed-size) fault log (and a command to retieve it, of course). I'm now using custom variables for it? Better ideas?

The UPS reports the nominal hold time at both 50% and 100% load. Is there a way to report this in NUT variables?


Variable/Command intended semantics:

Am I supposed to report ups.model/.mfr when I report device.*?

What's the difference between the load.off.delay and shutdown.stayoff commands?

What different from test.battery is test.failure.start supposed to do? Deploy the battery and then turn off the load?

What's calibrate.start different from test.battery.start.deep?

What's the difference between ambient.temperature.high ambient.temperature.high.critical?

Am I supposed to report both ups.temperature and ambient.0.temperature?

The documentation of the ups.shutdown variable says "Enable or disable UPS shutdown ability (poweroff)" and the mge-hid driver is the only one to use it. Is this a safeguard against accidently issuing the shutdown commands?


For reference, my current vartable:

series: Series (A/E)
slave_address: Slave address (UPS id) to match
input_fault_voltage: Input fault voltage (whatever that means)
number_of_battery_cells: Number of battery cells in series
nominal_cell_voltage: Nominal battery cell voltage
runtime_half: Nominal battery run time at 50% load (seconds)
runtime_full: Nominal battery run time at 100% load (seconds)
recharge_time: Nominal battery recharge time to 95% capacity (seconds)
output_voltages: Possible output voltages (volts)
fault_1: Fault record 1 (newest)
fault_2: Fault record 2
fault_3: Fault record 3
fault_4: Fault record 4
fault_5: Fault record 5 (oldest)


Thanks for any suggestions.
-------------- next part --------------
ambient.0.temperature: 23.4
ambient.0.temperature.high: 40
ambient.0.temperature.low: 10
battery.charge: 100
battery.packs: 0
battery.runtime: 1023
battery.type: PbAc
battery.voltage: 27.24
battery.voltage.nominal: 27.60
device.mfr: Masterguard
device.model: A700-19
device.part: 6A1212
device.serial: 2782
device.type: ups
device.uptime: 163021157
driver.name: nutdrv_qx_usb
driver.parameter.bus: 000
driver.parameter.device: 002
driver.parameter.pollfreq: 30
driver.parameter.pollinterval: 2
driver.parameter.port: auto
driver.parameter.productid: 0002
driver.parameter.protocol: masterguard
driver.parameter.slave_address: 03
driver.parameter.subdriver: phoenixtec
driver.parameter.synchronous: no
driver.parameter.vendorid: 06da
driver.version: 2.7.4
driver.version.data: Masterguard 0.01
driver.version.internal: 0.28
input.frequency: 49.9
input.frequency.high: 53.00
input.frequency.low: 47.00
input.frequency.nominal: 50.00
input.voltage: 225.0
input.voltage.high.critical: 276
input.voltage.low.critical: 160
input.voltage.nominal: 230
load.high: 140
output.current: 1.32
output.current.nominal: 3.05
output.voltage: 229.3
output.voltage.nominal: 230
ups.beeper.status: enabled
ups.delay.shutdown: 30
ups.delay.start: 180
ups.firmware: 10.06
ups.firmware.aux: 03.09
ups.id: 03
ups.load: 43
ups.power: 302
ups.power.nominal: 700
ups.productid: 0002
ups.status: OL
ups.temperature: 23.4
ups.test.result: OK
ups.type: online
ups.vendorid: 06da
-------------- next part --------------
Instant commands supported on UPS [mueritz]:

beeper.disable - Disable the UPS beeper
beeper.enable - Enable the UPS beeper
bypass.start - Put the UPS in bypass mode
bypass.stop - Take the UPS out of bypass mode
shutdown.return - Turn off the load and return when power is back
shutdown.stayoff - Turn off the load and remain off
shutdown.stop - Stop a shutdown in progress
test.battery.start - Start a battery test
test.battery.start.deep - Start a deep battery test
test.battery.start.quick - Start a quick battery test
test.battery.stop - Stop the battery test
-------------- next part --------------
[battery.packs]
Number of battery packs
Type: RANGE
Option: "0-0" SELECTED

[device.uptime]
Description unavailable
Type: NUMBER

[output.voltage.nominal]
Nominal output voltage (V)
Type: ENUM
Option: "220"
Option: "230" SELECTED
Option: "240"

[ups.delay.shutdown]
Interval to wait after shutdown with delay command (seconds)
Type: RANGE
Option: "0-5940" SELECTED

[ups.delay.start]
Interval to wait before (re)starting the load (seconds)
Type: RANGE
Option: "0-599940" SELECTED

[ups.id]
UPS system identifier
Type: RANGE
Option: "0-99" SELECTED