[Nut-upsdev] Some questions on driver implementation and variable names

[Arjen de Korte]

> I've just written an NUT driver to manage a Masterguard UPS connected
> via USB, and some questions arose.
>
> Why I wrote a new driver? The servers in question only have two
> serial ports, so I want to use USB. I first wrote the low-level USB
> routines expecting to integrate them into the existing masterguard
> driver. However, that driver was so rudimentary I wrote my own one.
> It can be trivially extended to talk via a serial line.

Can you post the driver here, even if it is not completely ready?

> Now to my questions:
>
> In case there is some variable (like ups.power) the UPS does not
> directly exhibit, but which can be computed by other known values
> (nominal power, load); should I compute and set that variable or
> should I only set values directly obtained form the UPS?

My personal opinion is, don't bother with it. Many installations will only
look at 'ups.status' since this is all that upsmon uses. If values can be
calculated from other variables, there is not much value of doing that in
the driver (where it will be done all the time, even when not used) rather
than in a client, where it can be done when needed.

I would prefer that the CGI programs would calculate these values if they
are not set by the UPS in the web interface rather than in the driver
(this is a more general solution).

> There are variables for minimum and maximum observed input voltage,
> but not for frequencies. Is it OK to set input.frequency.
> {minimum,maximum}?

If these are not read from the UPS, don't make them up.

> We have input.transfer.low and the like, but this UPS also gives me a
> frequency range outside which it will go offline. Any variable names
> for that?

Yes, input.frequency.low/high. See 'docs/new-names.txt'.

> Same for temeratures: We have ambient.temperature.alarm.{min,max}
> imum, but nothing nike it for ups internal temperatures.

Please use the battery temperature for that.

> I assume battery.runtime shold give the estimated runtime under
> current load. I also have nominal on-battery runtime for 100% and 50%
> load. Any names for those?

As far as I know, no. We really need to think about the value of adding
these, since if no application can use this, the added value is minimal.
Estimated runtime at present load might be useful though.

> When running a battery test, apart from running until empty, I can
> set a time. Anything like ups.test.duration?

Not yet.

> In case my setvar routine knows the name, but the value is illegal, I
> suppose I have to return STAT_SET_UINKNOWN despite the name being
> known, right?

Yes. Generally speaking, a client should check the bounds before calling
setvar(), since many variables come with min,max values or enum lists. So
this should not happen.

> If I accept a setvar(), do I have to dstate_setinfo() the variable or
> does some generic routine do so for me?

Generally speaking, you'd need dstate_setinfo() to propagate changes to
the server (and ultimately the clients) too.

> Does "calibrate" mean to run on battery until exhausted or seomething
> else?

That depends on the driver, but if you have the choice, I would opt for
the time until "LB" (Low Battery) is signalled.

> The text for the "OB" status says "inverter is powering the load".

A rather unfortunate description... :-)

> Despite that, I assume that with an online UPS, I'm not supposed to
> always set that flag, but only when on battery, right? Am I right to
> believe that "OL" and "OB" are mutually exclusive?

Yes. "OB" is an acronym for On Battery. Although it is theoretically
possible that a UPS is drawing power from both the battery and the mains,
you should not display "OL" and "OB" then, but only "OB".

> Finally, I'm not sure I understand the different ups.delay.*
> variables correctly. When initiating a shutdown, there are two things
> I can set: The duration of the countdown (e.g. time from now to power-
> off) and the time from then until restarting the load (the UPS will
> always auto-power-on after a line failure). I guess the later is
> ups.delay.start and the former is ups.delay.reboot for
> shutdown.reboot.graceful, zero for shutdown.reboot and
> ups.delay.shutdown for shutdown.{return,stayoff}. Or am I getting it
> wrong?

These delay values are always good for a lot of confusion.

ups.delay.start - time to wait before switching on the load after the
power returns (shutdown.return only)
ups.delay.reboot - time to stay off when rebooting the UPS
(shutdown.reboot.* only)
ups.delay.shutdown - grace period before UPS is shutdown
(shutdown.reboot.graceful only)

Except for the shutdown.reboot.graceful command, there should be
essentially no delay after issuing a shutdown.* command, other than the
minimal delay required by the UPS itself.

Best regards, Arjen
-- 
Eindhoven - The Netherlands
Key fingerprint - 66 4E 03 2C 9D B5 CB 9B  7A FE 7E C1 EE 88 BC 57