[Nut-upsdev] Question about "HB" flag and a "battery.charge.high" name

[Greg Troxel]

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.