Nut upsdev - Aug 2007 - [nut-commits] svn commit r1043 - in trunk: . docs drivers

Arjen de Korte wrote:
> 
> + * drivers/apc-hid.c:
> +   - Commented out the 'fullycharged' status. If anyone can
explain the
> +     use of this, please step forward.
This flag is defined on p.36 of the "Universal Serial Bus Usage Tables
for HID Power Devices", Release 1.0 November 1, 1997, a USB standards
document available on the web.

The document defines this flag to mean "Fully Charged". I assume that
this means that the battery is fully charged, which would presumably
happen after charging has finished, and before discharging begins. Its
meaning should be similar to a battery.charge of 100%, except that it
is a boolean flag, and that for whatever reason, some UPS might
consider itself fully charged at less than 100%.

FullyCharged is not precisely an "alarm", as it is not a condition to
be worried about. It is a kind of status. The standard actually
defines four related codes defined: "Charging",
"Discharging",
"FullyCharged", and "FullyDischarged". Although some UPS
simply
pretend to be "charging" all the time, this is often confusing to
users, who expect that their battery must be full at some point.
It would make sense to me to map all four related codes to status
flags. In fact, precisely one of the four should be true at any given
time for any given connected battery, although the standard does not
specify this. 

-- Peter

Hi Arjen,

I think the following three lines are typos, should be alarm_set():

     status_set("Replace battery!");
     status_set("Awaiting power!");
     status_set("Emergency stop!");

I thought ups.status was supposed to be a space-separated list of
tokens, so allowing multi-word tokens would perhaps not be a good
idea.

Also, the documentation (docs/new-drivers.txt) speaks of alarm "words"
not "phrases", and lists OVERHEAT as an example (docs/new-names.txt). 
Will allowing multi-word alarms have any negative consequences?

I am happy, by the way, that you are working on the usbhid-ups driver,
which badly needs it. My child-care duties don't allow any time for
programming at the moment, so I had been hoping that someone might
step in if I sat on the sidelines long enough :)

-- Peter

Arjen de Korte wrote:
> 
> Author: adkorte-guest
> Date: Sat Aug 11 19:31:11 2007
> New Revision: 1043
> 
> Log:
> Reworked the 'ups.status' processing of usbhid-ups. Most
'illegally' added status words are now reported as 'ups.alarm'.
See the ChangeLog for a more detailed description of what has changed.

>> + * drivers/apc-hid.c:
>> +   - Commented out the 'fullycharged' status. If anyone can
explain the
>> +     use of this, please step forward.
>
> This flag is defined on p.36 of the "Universal Serial Bus Usage Tables
> for HID Power Devices", Release 1.0 November 1, 1997, a USB standards
> document available on the web.
I have that document, which is nice source for information regarding the
use of parameters that can be read from/written to the UPS.
> The document defines this flag to mean "Fully Charged". I assume
that
> this means that the battery is fully charged, which would presumably
> happen after charging has finished, and before discharging begins. Its
> meaning should be similar to a battery.charge of 100%, except that it
> is a boolean flag, and that for whatever reason, some UPS might
> consider itself fully charged at less than 100%.
That is also what I expected here. But then, why does a client/user need
to know that? What action could possibly be triggered by seeing that the
batteries are fully charged?
> FullyCharged is not precisely an "alarm", as it is not a
condition to
> be worried about. It is a kind of status. The standard actually
> defines four related codes defined: "Charging",
"Discharging",
> "FullyCharged", and "FullyDischarged". Although some
UPS simply
> pretend to be "charging" all the time, this is often confusing to
> users, who expect that their battery must be full at some point.
*sigh!*

People who have no clue about how batteries work, should not worry about
this. Unfortunately, that's not under our control, so I agree we'd
better
work around these 'bugs'. :-)
> It would make sense to me to map all four related codes to status
> flags. In fact, precisely one of the four should be true at any given
> time for any given connected battery, although the standard does not
> specify this.
I'm very reluctant to add all sorts of status flags to 'ups.status'
(in
fact, I still doubt if we should have CHRG and DISCHRG in there). Where
would we stop? I propose that we map 'FullyCharged=1' to '!chrg'
and
'FullyDischarged=1' to '!dischrg'. By putting these at the end
of the list
of 'ups.status' info elements, they would clear the Charging and
Discharging status, without setting these. So 'FullyCharged=0' would not
mean the UPS is charging, nor would 'FullyDischarged=0' mean that it is
discharging.

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

(still trying triaging my mail stack)

2007/8/11, Arjen de Korte <adkorte-guest at
alioth.debian.org>:
> Author: adkorte-guest
> Date: Sat Aug 11 19:31:11 2007
> New Revision: 1043
>
> Log:
> Reworked the 'ups.status' processing of usbhid-ups. Most
'illegally' added status words are now reported as 'ups.alarm'.
See the ChangeLog for a more detailed description of what has changed.
> ...
=============================================================================>
--- trunk/ChangeLog     (original)
> +++ trunk/ChangeLog     Sat Aug 11 19:31:11 2007
> @@ -1,3 +1,37 @@
> +   - 'shutdownimm' and 'timelimitexp' no longer map to the
LB status
> +     (this was never a good idea, you need OB LB to have an effect).
the ShutdownImminent must be kept as mapped on LB!
it's a complement to BelowRemainingCapacityLimit, and is generally
triggered when OB (linked to ACPresent=0). Other cases are handled by
the hardware through the BYPASS (overload), the RB (replace battery or
internal failure). It has also saved some users life by "launching"
the shutdown sequence. I've even thought about allowing the FSD
setting (or an equivalence) by the driver to force emergency stop.

Since we (MGE) don't use the RemainingTimeLimitExpired nor
FullyDischarged, I can't tell for these ones. But in theory, the
FullyDischarged flag should also trigger LB. If we're OB, then FSD
will come up. Otherwise, there is no real problem...

Arnaud
-- 
Free Software Developer - http://arnaud.quette.free.fr/
Debian Developer - http://people.debian.org/~aquette/
Network UPS Tools (NUT) Project Leader - http://www.networkupstools.org/
Ubuntu Media Center (UMC) Project Leader - https://launchpad.net/~umc-team