Nut upsdev - May 2024 - Question about "HB" flag and a "battery.charge.high" name

Jim Klimov via Nut-upsdev <nut-upsdev at alioth-lists.debian.net> writes:
>   During discussion at
> https://github.com/networkupstools/nut/pull/2430#discussion_r1592317940 I
> found that while `nut-names.txt` documents the `battery.charge.low` as the
> "Remaining battery level when UPS switches to LB (percent)",
there is no
> counterpart as `battery.charge.high`. First I thought one could be just
> added... but for that matter, what could one logically mean - an overcharge
> (as in, "possibly harmful to the chemistry of the cells")? Or an
> euphemism(*) for being "well charged" (maybe not 100% if the
device hovers
> at some 85%-95% to extend battery life)?
I don't think we should use .high, unless a significant number of
units/protoocls issue a "battery charge is high" state with a
consistent
meaning.  So no.

If this is about having variables with thresholds that control devices
or cause synthetic setting of some variable (like turning on LB if
charge% is < battery.charge.low), then it makes sense.   If there is no
such 'binary sensor' to use HA language, then it doesn't make sense.

I personally have set up a threshold sensor in HA, intended to be
  >= 27.2 is ok, <=26.4 is alarm
so that it goes into alarm at 26.4 and recovers at 27.2.  The point is
to switch to alarm state when the UPS transfers to battery and not
return until the battery is recharged and it has been stable, to reduce
falsing.  But I don't think this concept exists within nut.
>   In the same discussion, there is a mention of the "HB" flag
(apparently
> "High battery" per e.g. docs/new-drivers.txt), but there are too
few hits
> in the code base to make up an opinion about its physical meaning. Does
> anyone here remember the history or intent behind it?
I do not, but "battery voltage is unreasonably high" is a reasonable
concept.  I would say that > 14V for a 12V system is probably fair,
although it really needs to be temperature compensated.  That's an alert
for charging system failure, though.

I would not call it HB, though because that makes it sound parallel to
LB, which is about believed remaining capacity, not detection of
overcharging failure.  It is not parallel.

the long name is

  charging system failure - overcharging

and I am reluctant to abbreviate it.

Thanks for the insights, especially these:
> If this is about having variables with thresholds that control devices or
cause synthetic setting of some variable (like turning on LB if charge% is
< battery.charge.low), then it makes sense.
> "battery voltage is unreasonably high" is a reasonable concept.
<...> I
would not call it HB, though because that makes it sound parallel to LB,
which is about believed remaining capacity, not detection of overcharging
failure.

Well, given that a "battery.charge.high" is not a name yet defined or
used,
hands are untied - and it does seem like a sufficiently high-level concept
to me even if no devices would emit that information and only some users
set it for synthetic logic. Namely, I'm thinking about hover-charging which
some devices do - as noted earlier. This may become more popular with LiIon
batteries hitting the UPS market (laptops and phones already do often
hover).

Currently the concept in NUT was somewhat addressed by a
`onlinedischarge_log_throttle_hovercharge` setting introduced (in
https://github.com/networkupstools/nut/pull/2216 and being revised now in
https://github.com/networkupstools/nut/pull/2428) with the intention to
hush log messages to the tune of "we are both online and discharging, what
is happening?"

Telling users to configure something like a
"default.battery.charge.high"
instead of that contrived name seems better streamlined and can eventually
make way into other drivers (or `main.c` core) where applicable.

It seems that we still do not fully know what a "HB High Battery" NUT
flag
can mean physically, and if the few existing drivers that use it do so
consistently with *some* single definition; I looked at precedents of `git
grep -w HB` in the codebase, there are a few `setval()` hits, namely:

* adelsystem_cbi.c: "BVAL_HIALRM_I",
* al175.c: "BATTERY VOLTAGE STATUS",
* asem.c: "charge_percentage >= hb_threshold (default 75)",
* generic_modbus.c: "usually ... charging state > 85%",
* pijuice.c: "battery_charge_level > HIGH_BATTERY_THRESHOLD (macro
75)"
* similarly in hwmon_ina219.c added by PR
https://github.com/networkupstools/nut/pull/2430 that started this
discussion

The first one seems to be about an alarm, the second - not sure, and the
rest are about passing a threshold with no apparent implications of what
that means and why we care. MAYBE there are further NUT clients that would
react to the flag somehow, but they are not in the core codebase.

So maybe it is better to leave "HB" be, and define another
`ups.status`
flag - e.g. for this particular situation a new "HOVER" state makes
sense
and is unambiguous, and easier to set/check in driver code too. If we find
ways how devices report the state directly or just as the numeric threshold
(e.g. some new USB HID or SNMP OID endpoint(s)) - pass the direct flag
value through if available; otherwise synthesize it if the device or user
provided a setting and it is under 100% -- either way, we
`getval(somename)` and go from there if not NULL.

For that matter, a  name like `battery.charge.hover` might also be "less
ambiguous" than `battery.charge.high` but I'm not sure if some better
wording than just `...hover` is possible (suggestions welcome):

* not too long and cumbersome
* reflect that it is a lower limit/threshold/watermark of the battery
charge level, which the UPS would deflate to before it begins charging
again to reach some high watermark (maybe not 100% - and this is in fact
what `battery.charge.high` might mean more reasonably)

I guess I'll hold off on any decisions and activity here until summer, to
allow some time for community discussion and decision :)

Further insights welcome,
Jim Klimov


On Tue, May 7, 2024 at 2:46?PM Greg Troxel via Nut-upsdev <
nut-upsdev at alioth-lists.debian.net> wrote:
> Jim Klimov via Nut-upsdev <nut-upsdev at alioth-lists.debian.net>
writes:
>
> >   During discussion at
> >
https://github.com/networkupstools/nut/pull/2430#discussion_r1592317940
> I
> > found that while `nut-names.txt` documents the `battery.charge.low` as
> the
> > "Remaining battery level when UPS switches to LB (percent)",
there is no
> > counterpart as `battery.charge.high`. First I thought one could be
just
> > added... but for that matter, what could one logically mean - an
> overcharge
> > (as in, "possibly harmful to the chemistry of the cells")?
Or an
> > euphemism(*) for being "well charged" (maybe not 100% if the
device
> hovers
> > at some 85%-95% to extend battery life)?
>
> I don't think we should use .high, unless a significant number of
> units/protoocls issue a "battery charge is high" state with a
consistent
> meaning.  So no.
>
> If this is about having variables with thresholds that control devices
> or cause synthetic setting of some variable (like turning on LB if
> charge% is < battery.charge.low), then it makes sense.   If there is no
> such 'binary sensor' to use HA language, then it doesn't make
sense.
>
> I personally have set up a threshold sensor in HA, intended to be
>   >= 27.2 is ok, <=26.4 is alarm
> so that it goes into alarm at 26.4 and recovers at 27.2.  The point is
> to switch to alarm state when the UPS transfers to battery and not
> return until the battery is recharged and it has been stable, to reduce
> falsing.  But I don't think this concept exists within nut.
>
> >   In the same discussion, there is a mention of the "HB"
flag (apparently
> > "High battery" per e.g. docs/new-drivers.txt), but there are
too few hits
> > in the code base to make up an opinion about its physical meaning.
Does
> > anyone here remember the history or intent behind it?
>
> I do not, but "battery voltage is unreasonably high" is a
reasonable
> concept.  I would say that > 14V for a 12V system is probably fair,
> although it really needs to be temperature compensated.  That's an
alert
> for charging system failure, though.
>
> I would not call it HB, though because that makes it sound parallel to
> LB, which is about believed remaining capacity, not detection of
> overcharging failure.  It is not parallel.
>
> the long name is
>
>   charging system failure - overcharging
>
> and I am reluctant to abbreviate it.
>
>
> _______________________________________________
> Nut-upsdev mailing list
> Nut-upsdev at alioth-lists.debian.net
> https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/nut-upsdev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://alioth-lists.debian.net/pipermail/nut-upsdev/attachments/20240510/a74b42a4/attachment.htm>