Nut upsdev - Mar 2014 - Developing the UPS side of the UPS-NUT equation (via usbhid)

The syntax is beginning (just beginning) to make sense to me now, so I'm
looking now to try and implement just a few items in the report descriptor, and
then I figured I can progress from there if all goes well.

The power HID docs seem to encourage drawing out your system first, and then
letting the report descriptor flow from there.  So, my very simplified system
goes like this:

[Battery]===DC Flow ==>[Power Summary]

All of the drawings seem to end in a power summary, and the doc seemed to stress
that it was essential to power management software being able to effectively use
it, so I'll include it.

I think I understand how the usages work now....they're basically like
establishing the namespace (like com.java.class, etc).  I had been confused
before when I would see multiple usage() statements all following each other,
but seeing it in the nut output as the path makes it more clear.

So, pretty much everything should be under the UPS usage.  Then I would define
things under the battery usage, then the flow usage, and then the power summary
usage...right?

Where I'm still foggy is two things....first collections.  I'm pretty
sure there's supposed to be an application collection, and then I usually
see a physical collection, but I'm still not completely understanding what
their purpose is.

The second thing I still don't understand is the minimum/maximum
descriptors.  Ok, Logical min/max I get...that's just the range of the
actual value in the report...basically a way to indicate if it is unsigned or
signed.  If you only have an 8 bit value specified, then I'd guess you
can't have a logical max greater than 255.  But physical min/max are a bit
confusing.  Is it just a means of scaling or offsetting the logical value?

So, for instance temperature.  Our UPS has a temperature monitor on it, but HID
temperature values are in Kelvin.  I could define an 8-bit temperature field,
with a logical min/max of 0/100, and a physical min/max of 273/373.  So if I
pass 50 as a value, then it gets read as 323 on the PC side?  And if the
physical range is much greater than the logical range, then it just scales it?

The other min/max I don't quite understand is usage min/max.  I'm
thinking they have something to do with the usages "OutputID",
"FlowID", etc.

Thank you for the help so far.  I really wish there were better learning docs
out there for the un-initiated.

Rob




-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.alioth.debian.org/pipermail/nut-upsdev/attachments/20140312/ec34e1b2/attachment.html>

Ok, using the tutorial at silabs
(https://www.silabs.com/Support%20Documents/TechnicalDocs/AN249.pdf),
collections make more sense to me now.  They are quite well explained:

? Application Collections group variables that carry out a common purpose. All
report items must be contained
inside an application collection.
? Logical Collections group variables of different types that form a composite
data structure. Think of logical
collections as a collection designator for ?struct? data types, such as a struct
that groups a buffer with index
variables for that buffer.
? Physical Collections group data describing a single data point. For instance,
a physical collection of data could
contain readings from a temperature sensor.

So, everything needs to go in an application collection, items grouped in a
report go in a logical collection?but I guess I still don?t quite understand why
or how you?d use a physical collection.  A single data point?ok, but isn?t that
true of your temperature data without it being in a ?collection??



From: Nut-upsdev [mailto:nut-upsdev-bounces+rgroner=rtd.com at
lists.alioth.debian.org] On Behalf Of Rob Groner
Sent: Wednesday, March 12, 2014 10:48 AM
To: nut-upsdev at lists.alioth.debian.org
Subject: Re: [Nut-upsdev] Developing the UPS side of the UPS-NUT equation (via
usbhid)

The syntax is beginning (just beginning) to make sense to me now, so I?m looking
now to try and implement just a few items in the report descriptor, and then I
figured I can progress from there if all goes well.

The power HID docs seem to encourage drawing out your system first, and then
letting the report descriptor flow from there.  So, my very simplified system
goes like this:

[Battery]===DC Flow ==>[Power Summary]

All of the drawings seem to end in a power summary, and the doc seemed to stress
that it was essential to power management software being able to effectively use
it, so I?ll include it.

I think I understand how the usages work now?.they?re basically like
establishing the namespace (like com.java.class, etc).  I had been confused
before when I would see multiple usage() statements all following each other,
but seeing it in the nut output as the path makes it more clear.

So, pretty much everything should be under the UPS usage.  Then I would define
things under the battery usage, then the flow usage, and then the power summary
usage?right?

Where I?m still foggy is two things?.first collections.  I?m pretty sure there?s
supposed to be an application collection, and then I usually see a physical
collection, but I?m still not completely understanding what their purpose is.

The second thing I still don?t understand is the minimum/maximum descriptors. 
Ok, Logical min/max I get?that?s just the range of the actual value in the
report?basically a way to indicate if it is unsigned or signed.  If you only
have an 8 bit value specified, then I?d guess you can?t have a logical max
greater than 255.  But physical min/max are a bit confusing.  Is it just a means
of scaling or offsetting the logical value?

So, for instance temperature.  Our UPS has a temperature monitor on it, but HID
temperature values are in Kelvin.  I could define an 8-bit temperature field,
with a logical min/max of 0/100, and a physical min/max of 273/373.  So if I
pass 50 as a value, then it gets read as 323 on the PC side?  And if the
physical range is much greater than the logical range, then it just scales it?

The other min/max I don?t quite understand is usage min/max.  I?m thinking they
have something to do with the usages ?OutputID?, ?FlowID?, etc.

Thank you for the help so far.  I really wish there were better learning docs
out there for the un-initiated.

Rob




-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.alioth.debian.org/pipermail/nut-upsdev/attachments/20140312/cce20df7/attachment-0001.html>

So, going with the proposed initial design, I created a report descriptor to
describe the battery.  I thought that I'd then see how NUT responded to it. 
The good news is that the descriptor showed up and all of the paths were
correct.  Unfortunately, after that, nothing happened...no reports were
requested, and it just kept timing out.  Is there some minimum amount of
functionality I need to provide in this report descriptor in order for NUT to
work correctly?  I assume it's not requesting reports because there is
nothing it wants to know about.

Here is what I have so far:

USAGE_PAGE (Power Device)
USAGE (UPS)
COLLECTION (Application)
  USAGE (BatterySystem)
  COLLECTION (Physical)
    REPORT_ID (1)
    USAGE (Voltage)
    REPORT_SIZE (8)
    REPORT_COUNT (1)
    UNIT (SI Lin:Volts)
    LOGICAL_MINIMUM (0)
   LOGICAL_MAXIMUM (255)
    FEATURE (Data,Var,Abs)
    REPORT_ID (2)
    USAGE (Temperature)
    REPORT_SIZE (8)
    REPORT_COUNT (1)
    LOGICAL_MINIMUM (0)
    LOGICAL_MAXIMUM (255)
    UNIT (SI Lin:Temperature)
    FEATURE (Data,Var,Abs)
    USAGE_PAGE (Battery System)
    REPORT_ID (3)
    USAGE (RemainingCapacity)
    REPORT_SIZE (8)
    REPORT_COUNT (1)
    LOGICAL_MINIMUM (0)
    LOGICAL_MAXIMUM (100)
    FEATURE (Data,Var,Abs)
  END_COLLECTION
END_COLLECTION

From: Nut-upsdev [mailto:nut-upsdev-bounces+rgroner=rtd.com at
lists.alioth.debian.org] On Behalf Of Rob Groner
Sent: Wednesday, March 12, 2014 10:48 AM
To: nut-upsdev at lists.alioth.debian.org
Subject: Re: [Nut-upsdev] Developing the UPS side of the UPS-NUT equation (via
usbhid)

The syntax is beginning (just beginning) to make sense to me now, so I'm
looking now to try and implement just a few items in the report descriptor, and
then I figured I can progress from there if all goes well.

The power HID docs seem to encourage drawing out your system first, and then
letting the report descriptor flow from there.  So, my very simplified system
goes like this:

[Battery]===DC Flow ==>[Power Summary]

All of the drawings seem to end in a power summary, and the doc seemed to stress
that it was essential to power management software being able to effectively use
it, so I'll include it.

I think I understand how the usages work now....they're basically like
establishing the namespace (like com.java.class, etc).  I had been confused
before when I would see multiple usage() statements all following each other,
but seeing it in the nut output as the path makes it more clear.

So, pretty much everything should be under the UPS usage.  Then I would define
things under the battery usage, then the flow usage, and then the power summary
usage...right?

Where I'm still foggy is two things....first collections.  I'm pretty
sure there's supposed to be an application collection, and then I usually
see a physical collection, but I'm still not completely understanding what
their purpose is.

The second thing I still don't understand is the minimum/maximum
descriptors.  Ok, Logical min/max I get...that's just the range of the
actual value in the report...basically a way to indicate if it is unsigned or
signed.  If you only have an 8 bit value specified, then I'd guess you
can't have a logical max greater than 255.  But physical min/max are a bit
confusing.  Is it just a means of scaling or offsetting the logical value?

So, for instance temperature.  Our UPS has a temperature monitor on it, but HID
temperature values are in Kelvin.  I could define an 8-bit temperature field,
with a logical min/max of 0/100, and a physical min/max of 273/373.  So if I
pass 50 as a value, then it gets read as 323 on the PC side?  And if the
physical range is much greater than the logical range, then it just scales it?

The other min/max I don't quite understand is usage min/max.  I'm
thinking they have something to do with the usages "OutputID",
"FlowID", etc.

Thank you for the help so far.  I really wish there were better learning docs
out there for the un-initiated.

Rob




-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.alioth.debian.org/pipermail/nut-upsdev/attachments/20140312/f157144e/attachment.html>

On Mar 12, 2014, at 10:48 AM, Rob Groner wrote:
> The syntax is beginning (just beginning) to make sense to me now, so I?m
looking now to try and implement just a few items in the report descriptor, and
then I figured I can progress from there if all goes well.
>  
> The power HID docs seem to encourage drawing out your system first, and
then letting the report descriptor flow from there.  So, my very simplified
system goes like this:
>  
> [Battery]===DC Flow ?[Power Summary]
>  
> All of the drawings seem to end in a power summary, and the doc seemed to
stress that it was essential to power management software being able to
effectively use it, so I?ll include it.
>  
> I think I understand how the usages work now?.they?re basically like
establishing the namespace (like com.java.class, etc).  I had been confused
before when I would see multiple usage() statements all following each other,
but seeing it in the nut output as the path makes it more clear.
Agreed, the path notation makes sense once you start working with deeper
collections than would be present on, say, a mouse or keyboard.
> So, pretty much everything should be under the UPS usage.  Then I would
define things under the battery usage, then the flow usage, and then the power
summary usage?right?
Right. NUT can be adapted to match, so it's really a question of whether you
need compatibility with other UPS monitoring software. Given that this tends to
be vendor-specific in other OSes, that is probably less of a concern than just
keeping it organized for your own sake.
 
> Where I?m still foggy is two things?.first collections.  I?m pretty sure
there?s supposed to be an application collection, and then I usually see a
physical collection, but I?m still not completely understanding what their
purpose is.
I think the application collections are the only important ones. Physical
collections are not as widely used, although they were designed to group values
with tags for their physical location (think of all the flaps and levers on a
flight simulator joystick).
> The second thing I still don?t understand is the minimum/maximum
descriptors.  Ok, Logical min/max I get?that?s just the range of the actual
value in the report?basically a way to indicate if it is unsigned or signed.  If
you only have an 8 bit value specified, then I?d guess you can?t have a logical
max greater than 255.  But physical min/max are a bit confusing.  Is it just a
means of scaling or offsetting the logical value?
 
Yes.
> So, for instance temperature.  Our UPS has a temperature monitor on it, but
HID temperature values are in Kelvin.  I could define an 8-bit temperature
field, with a logical min/max of 0/100, and a physical min/max of 273/373.  So
if I pass 50 as a value, then it gets read as 323 on the PC side?  And if the
physical range is much greater than the logical range, then it just scales it?
That sounds about right.
> The other min/max I don?t quite understand is usage min/max.  I?m thinking
they have something to do with the usages ?OutputID?, ?FlowID?, etc.
It's basically a more succinct way to represent a range of sequential Usage
IDs. I suspect you would see them more on keyboards, where you might not want to
list all of the scan codes.

I think the OutputID and FlowID are just Constant fields. I'd have to check
the spec, though.

It's not formatted well, but there is an example of an MGE HID descriptor
here:

http://anonscm.debian.org/viewvc/libhid/trunk/ref/lsusb-vvv/MGE_Pulsar_Evolution_500?revision=224&view=markup

(the other lsusb outputs from UPSes are not HID PDC.)

-- 
Charles Lepple
clepple at gmail

On Mar 12, 2014, at 5:18 PM, Rob Groner wrote:
> Is there some minimum amount of functionality I need to provide in this
report descriptor in order for NUT to work correctly?  I assume it?s not
requesting reports because there is nothing it wants to know about.
That sounds vaguely familiar, but I think NUT will still poll the interrupt pipe
if present. The requests over EP0 are probably only made if there are HID usage
paths mapped to NUT variable names.

-- 
Charles Lepple
clepple at gmail