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

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>

Jim Klimov <jimklimov+nut at gmail.com> writes:
>> "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).
I would suggest deferring until there is a need and an articulated use.

Hover charging is a new word for me, but I understand it to mean
declining to charge a battery which is mostly charged.

Part of the difficulty is this is about "state of charge" which has a
messy relationship to "battery voltage".
> 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?"
well, if that's how it is, I don't think it should be suppressed.  I
find it odd though, to be discharging, vs simply saying "battery at 93%
- good enough - don't fully charge it -- because it's better long term
to be nice to it compared to the value of the 7% if the power fails in
an hour".  But maybe I'm confused.
> 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.
Configuring what, for what purpose?  If this is about setting charge
thresholds, we should have a few models' interface on the table to see
what's common.
> 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.
And that is two different things.  There is "battery adequately
charged", where that might mean 75% or 85%.  there is an alarm condition
of excess voltage which indicates a charging circuit failure.    I would
not in English call a battery which is "mostly charged"  as
"high".
> 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.
I would view HB as a bug to be fixed unless we can find that a lot of
devices define that (the devices, not our drivers!).

As for HOVER, not sure what that means either.  There's a binary flag
"this device is known to not charge fully, and it is configured to do
so".  After that, there is just

   LOW BATTERY: it's so low that the UPS will not power a load for very
   long (longstanding)

   FULL BATTERY: the battery is either fully charged, in all senses, or
   is charged enough that the hover rules say don't charge any more.

and perhap FULL is split into FULL and MOSTLYFULL.
> 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):
I still find hover unclear.  We have to start with an unambiguous
description of the semantics, and not hope that people will infer the
same semantics from a word.
> * 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)
Is that what things really do?   I have seen devices simply decline to
charge above about 90%, but not discharge and recharge.

I typed in hover charging to DDG and got lots of information about how
to charge my hoverboard.  Then I got results about vacuums, and about EV
charging in the Birmingham-Hoover metro area.

So I submit that "hover charging" is not a thing worthy of us using
the
name.