Nut upsdev - Nov 2023 - What is the arduino sub-driver intended to be used for?

Kelly Byrd <kbyrd at memcpy.com> writes:
> Making progress on this PR. I have question about storing and checking
> state in a subdriver
> HID Power Devices can a "UPS.PowerSummary.CapacityMode" value.
According to
> the spec, the values are:
> 0: maH
> 1: mwH
> 2: percent (%)
> 3: Boolean support only (OK or failed)
>
> Grep'ing the source, nothing makes use of this now (some subdrivers
have it
> mapped to unmapped.ups.powersummary.capacitymode or something similar) and
> many of the HID UPS drivers assume CapacityMode 2 (they interpret
> RemainingCapacity, WarningCapacityLimit, RemainingCapacityLimit as
> percent). My application (and the original sample sketch for the Arduino
> project also does this, so I'm fine with that.
>
> But, I was wondering if anyone could point out the right way in a NUT
> subdriver to have a function that handles RemainingCapacity do different
> things based on CapacityMode. I think I understand how to write my own
> function to handle values in arduino-hid.c, but I don't know how to
check
> the state of a previously parsed value, especially one that doesn't
have a
> place to be stored in the normal nut names variable hierarchy.
>
> Or maybe this is too much trouble and I'll just assume CapacityMode =
2.
I am really unclear on all of this, but it sounds like the USB interface
has the device define CapacityMode and then provide a value.   So some
devices might report in mWh and some in %.  I guess some might even be
switchable but I would expect each one is how it is.

When mapping to nut, my view is that the point is to provide a common
abstraction while at the same time providing full access -- and these
two goals are not entirely compatible.

I would say that nut probably should have different variables  for the
different modes, and read the mode field, and then write the content of
RemainingCapacity into RemainingCapacityPercent if mode is 2.

Just writing without checking risks some other UPS having its mAh
remaining value put in a field that data consumers think is %.

I could be way off, but if so hopefully that's obvious!

You have the device side right. Devices have
"UPS.PowerSummary.CapacityMode" (are the next three in %, mAh, or mWh?
"UPS.PowerSummary.FullChargeCapacity"
"UPS.PowerSummary.RemainingCapacity"
"UPS.PowerSummary.RemainingCapacityLimit"
"UPS.PowerSummary.WarningCapacityLimit"


According to nut-names.txt, NUT has:
battery.charge             | Battery charge (percent)            | 100.0
battery.charge.low       | Remaining battery level when  UPS switches to LB
(percent)
battery.charge.restart    | Minimum battery level for UPS restart after
power-off
battery.charge.warning    | Battery level when UPS switches

and also

battery.capacity          | Battery capacity (Ah)               | 7.2
battery.capacity.nominal    | Nominal battery capacity (Ah)

So, it feels to me like this is the right logic:
if CapacityMode == 2 (capacity units are percent) then
  battery.charge = RemainingCapacity
  battery.charge.low, restart =  RemainingCapacityLimit
  battery.charge.warning =  WarningCapacityLimit

if CapacityMode == 0 (units are in mAh) then
  battery.capacity = RemainingCapacity
  battery.capacity.nominal = FullChargeCapacity (or DesignCapacity)

Note that in each case some things are left out. I didn't see a
battery.capacity.low or warning, which is probably ok because the time
remaining HID objects should give a similar set of behavior?

Looking at the existing drivers, it feels like most people use capacity as
a percent. It makes me wonder if either Windows or MacOS expects percent so
vendors just had to do that. I didn't find variables currently in  NUT for
milliwatt-hours.

I still have my original question, what is the right way to check this
CapacityMode while parsing RemainingCapacity and its friends? Although the
more I look into this, the more I think I won't bother and submit the PR
with comments that CapacityMode is assumed to be 2 and maybe a log message
if it isn't?

On Wed, Nov 15, 2023 at 7:50?AM Greg Troxel <gdt at lexort.com> wrote:
> Kelly Byrd <kbyrd at memcpy.com> writes:
>
> > Making progress on this PR. I have question about storing and checking
> > state in a subdriver
> > HID Power Devices can a "UPS.PowerSummary.CapacityMode"
value. According
> to
> > the spec, the values are:
> > 0: maH
> > 1: mwH
> > 2: percent (%)
> > 3: Boolean support only (OK or failed)
> >
> > Grep'ing the source, nothing makes use of this now (some
subdrivers have
> it
> > mapped to unmapped.ups.powersummary.capacitymode or something similar)
> and
> > many of the HID UPS drivers assume CapacityMode 2 (they interpret
> > RemainingCapacity, WarningCapacityLimit, RemainingCapacityLimit as
> > percent). My application (and the original sample sketch for the
Arduino
> > project also does this, so I'm fine with that.
> >
> > But, I was wondering if anyone could point out the right way in a NUT
> > subdriver to have a function that handles RemainingCapacity do
different
> > things based on CapacityMode. I think I understand how to write my own
> > function to handle values in arduino-hid.c, but I don't know how
to check
> > the state of a previously parsed value, especially one that
doesn't have
> a
> > place to be stored in the normal nut names variable hierarchy.
> >
> > Or maybe this is too much trouble and I'll just assume
CapacityMode = 2.
>
> I am really unclear on all of this, but it sounds like the USB interface
> has the device define CapacityMode and then provide a value.   So some
> devices might report in mWh and some in %.  I guess some might even be
> switchable but I would expect each one is how it is.
>
> When mapping to nut, my view is that the point is to provide a common
> abstraction while at the same time providing full access -- and these
> two goals are not entirely compatible.
>
> I would say that nut probably should have different variables  for the
> different modes, and read the mode field, and then write the content of
> RemainingCapacity into RemainingCapacityPercent if mode is 2.
>
> Just writing without checking risks some other UPS having its mAh
> remaining value put in a field that data consumers think is %.
>
> I could be way off, but if so hopefully that's obvious!
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://alioth-lists.debian.net/pipermail/nut-upsdev/attachments/20231115/005b8322/attachment-0001.htm>