[Nut-upsdev] Developing the UPS side of the UPS-NUT equation (via usbhid)

[Charles Lepple]

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