Nut upsdev - Feb 2007 - Some questions on driver implementation and variable names

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.

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?

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

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?

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

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?

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

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?

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

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

The text for the "OB" status says "inverter is powering the
load".
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?

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?

Thanks for your help.

> 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

On 2/25/07, Edgar Fu? <ef@math.uni-bonn.de> wrote:
> 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?
Well, there's no need to limit the output to values directly obtained
from the UPS. The driver can calculate some stuff, like the battery
runtime, the battery charge (percentage) and so on. Basically, the
driver should calculate values that may be useful for the user, as
long at they're somewhat dependent on the particular UPS it is
driving.

Basically, a driver should calculate stuff so that the hardware looks
fancier than it actually is, but it should not implement features that
are better off in some layer above the driver.

-- 
Carlos Rodrigues

Hi Edgar,

did you check if your device is already supported by the
newhidups/usbhid_ups driver? This driver supports all USB HID devices,
and even if your device is not supported "out of the box", it is
usually a question of adding a few lines of code to support a new
device. You can run the newhidups/usbhid_ups driver with the "-x
explore" option to print enough debugging information to determine if
the device is supportable. 

On the other hand, if it is not a HID device, then it is most likely a
serial-over-USB protocol, which is not be supported by the
newhidups/usbhid_ups driver, but might be supportable by one of the
existing serial-over-USB drivers (megatec_usb, tripplite_usb, etc).

An entirely new driver would only be warranted if it's a genuinely new
protocol.

If you post your driver here, someone can probably tell you if the
protocol resembles a known one. 

-- Peter

Edgar Fuss wrote:
> 
> 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.
> 
> 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?
> 
> There are variables for minimum and maximum observed input voltage,  
> but not for frequencies. Is it OK to set input.frequency. 
> {minimum,maximum}?
> 
> 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?
> 
> Same for temeratures: We have ambient.temperature.alarm.{min,max} 
> imum, but nothing nike it for ups internal temperatures.
> 
> 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?
> 
> When running a battery test, apart from running until empty, I can  
> set a time. Anything like ups.test.duration?
> 
> 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?
> 
> If I accept a setvar(), do I have to dstate_setinfo() the variable or  
> does some generic routine do so for me?
> 
> Does "calibrate" mean to run on battery until exhausted or
seomething
> else?
> 
> The text for the "OB" status says "inverter is powering the
load".
> 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?
> 
> 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?
> 
> Thanks for your help.

> Can you post the driver here, even if it is not completely ready?
I can post what I've got so far for review purposes, sure. I was not  
in a mood of testing shutdown commands and the like from home (the  
UPS is installed at work). I will incorporate changes based on your  
comments before I post. Also, I'll have to ask a few more questions  
at the incredibly helpful technicians at Masterguard tomorrow.
> My personal opinion is, don't bother with it.
As this seems to make for a lot of debate, I'll probably go for  
#ifdef INFER.
> If these are not read from the UPS, don't make them up.
So drivers should also not make up for minimum and maximum observed  
input voltage? I saw several drivers doing so.
> Yes, input.frequency.low/high. See 'docs/new-names.txt'.
I guess my version of that file is out-dated (it's from 2.0.4).
> Please use the battery temperature for that.
Hm? I don't see min/max values there either. Besides, I don't know  
the battery temperature with the external packs of an A3000-19.
> Generally speaking, you'd need dstate_setinfo() to propagate  
> changes to
> the server (and ultimately the clients) too.
I meant the following: If the generic code calls my setvar() routine  
and I return STAT_SET_HANDLED, then the generic code could set deduce  
that the variable has changed to the value given. Instead, I  
additionally call dstate_setinfo() to propagate the value?
> That depends on the driver, but if you have the choice, I would opt  
> for
> the time until "LB" (Low Battery) is signalled.
OK, so "calibrate" means "try to run on battery as long as
possible now"
> These delay values are always good for a lot of confusion.
Ah. Thanks a lot for your explanation.
I've no influence on the behaviour when power returns. The UPS will  
simply turn on immediately.