• AVR Freaks

Deciphering HID Report Descriptor

Author
rusttree
Super Member
  • Total Posts : 910
  • Reward points : 0
  • Joined: 2010/06/14 14:10:14
  • Location: Phoenix, AZ
  • Status: offline
2012/10/11 12:26:41 (permalink)
0

Deciphering HID Report Descriptor

I'm having a little difficulty understanding the HID report descriptor of a USB keyboard.  I lifted it straight out of a Microchip example.  I'm hoping someone can kind of step me through the items that are confusing me.  Here's the whole descriptor:

0x05, 0x01,                    // USAGE_PAGE (Generic Desktop)
0x09, 0x06,                    // USAGE (Keyboard)
0xa1, 0x01,                    // COLLECTION (Application)
0x05, 0x07,                    //   USAGE_PAGE (Keyboard)
0x19, 0xe0,                    //   USAGE_MINIMUM (Keyboard LeftControl)
0x29, 0xe7,                    //   USAGE_MAXIMUM (Keyboard Right GUI)
0x15, 0x00,                    //   LOGICAL_MINIMUM (0)
0x25, 0x01,                    //   LOGICAL_MAXIMUM (1)
0x75, 0x01,                    //   REPORT_SIZE (1)
0x95, 0x08,                    //   REPORT_COUNT (8)
0x81, 0x02,                    //   INPUT (Data,Var,Abs)
0x95, 0x01,                    //   REPORT_COUNT (1)
0x75, 0x08,                    //   REPORT_SIZE (8)
0x81, 0x03,                    //   INPUT (Cnst,Var,Abs)
0x95, 0x05,                    //   REPORT_COUNT (5)
0x75, 0x01,                    //   REPORT_SIZE (1)
0x05, 0x08,                    //   USAGE_PAGE (LEDs)
0x19, 0x01,                    //   USAGE_MINIMUM (Num Lock)
0x29, 0x05,                    //   USAGE_MAXIMUM (Kana)
0x91, 0x02,                    //   OUTPUT (Data,Var,Abs)
0x95, 0x01,                    //   REPORT_COUNT (1)
0x75, 0x03,                    //   REPORT_SIZE (3)
0x91, 0x03,                    //   OUTPUT (Cnst,Var,Abs)
0x95, 0x06,                    //   REPORT_COUNT (6)
0x75, 0x08,                    //   REPORT_SIZE (8)
0x15, 0x00,                    //   LOGICAL_MINIMUM (0)
0x25, 0x65,                    //   LOGICAL_MAXIMUM (101)
0x05, 0x07,                    //   USAGE_PAGE (Keyboard)
0x19, 0x00,                    //   USAGE_MINIMUM (Reserved (no event indicated))
0x29, 0x65,                    //   USAGE_MAXIMUM (Keyboard Application)
0x81, 0x00,                    //   INPUT (Data,Ary,Abs)
0xc0                           // End Collection

I follow the first couple of lines that are telling the host that this a regular keyboard.  Next it uses the USAGE_MINIMUM and MAXIMUM to describe the eight adjustment keys (ctrl/shift/alt/GUI left and right) will be on or off (LOGICAL_MINIMUM/MAXIMUM) and will use one bit each in an 8-bit field (REPORT_SIZE and REPORT_COUNT).
 
After that, I start to get lost.  I'll enumerate my questions:
1. What does "(Data,Var,Abs)" and "(Cnst,Var,Abs)" mean exactly on the INPUT lines?
2. What are the subsequent REPORT_COUNTs and REPORT_SIZEs referring to?
3. I assume the last couple of lines are setting up the regular keys on the keyboard (a-z, 0-9, etc).  Is the LOGICAL_MAXIMUM of 101 mean there are exactly 101 unique keys?
4. What does "Reserved (no event indicated)" and "Keyboard Application" mean in the last USAGE_MINIMUM and MAXIMUM?
 
Thanks!
#1

5 Replies Related Threads

    rusttree
    Super Member
    • Total Posts : 910
    • Reward points : 0
    • Joined: 2010/06/14 14:10:14
    • Location: Phoenix, AZ
    • Status: offline
    Re:Deciphering HID Report Descriptor 2012/10/11 14:51:00 (permalink)
    0
    Ok, I think I've worked my way mostly through it.  It looks like it's creating an input format that looks like (in hex):
    XX00YY00 00000000
    Where XX is a value corresponding to an adjustment key (crtl, shift, etc), and YY is a regular keystroke elsewhere on the keyboard.  The rest of the zeros are for padding (that's what the "Cnst" flag is for in the INPUT lines).
     
    I understand the desire to add padding so the total message falls on an 8-byte boundary, but why add padding between XX and YY?  Just for ease of viewing for the developer?
    #2
    chinzei
    Super Member
    • Total Posts : 2250
    • Reward points : 0
    • Joined: 2003/11/07 12:39:02
    • Location: Tokyo, Japan
    • Status: offline
    Re:Deciphering HID Report Descriptor 2012/10/11 16:11:24 (permalink)
    0
    1. What does "(Data,Var,Abs)" and "(Cnst,Var,Abs)" mean exactly on the INPUT lines?


    nput, Output and Feature tag take one byte (or more) item data
    The bitmap of the item data is common to these tags.

    Bit 0 {Data (0) | Constant (1)}
    Bit 1 {Array (0) | Variable (1)}
    Bit 2 {Absolute (0) | Relative (1)}
    ...

    To make these bits readable, we use the expression like INPUT (Data,Var,Abs)

    2. What are the subsequent REPORT_COUNTs and REPORT_SIZEs referring to?


    See these posts

    Global and Local items
    http://www.cygnal.org/ubb/Forum9/HTML/002068.html
    - posted July 07, 2010 10:18 PM

    Simplify report descriptor
    http://www.microchip.com/forums/fb.aspx?m=479147

    3. I assume the last couple of lines are setting up the regular keys on the keyboard (a-z, 0-9, etc).  Is the LOGICAL_MAXIMUM of 101 mean there are exactly 101 unique keys?


    Yes.

    The key codes (Usages) are defined in "10 Keyboard/Keypad Page (0x07) section of HUT (HID Usage Table)

    HID Usage Table
    http://www.usb.org/develo...ass_docs/Hut1_12v2.pdf

    4. What does "Reserved (no event indicated)" and "Keyboard Application" mean in the last USAGE_MINIMUM and MAXIMUM?


    "Reserved (no event indicated)" - no key is pushed down
    "Keyboard Application" - a key of Windows specific keyboard

    but why add padding between XX and YY?


    It's a practice of HID keyboard.
    Maybe, reserved for future extension of the modifier keys (SHIFT/CTRL, etc)


    You may have interest on these posts, too.

    Report ID
    http://www.microchip.com/forums/fb.aspx?m=493604

    Simple report descriptor for vendor-specific HID
    http://www.microchip.com/forums/fb.ashx?m=565164

    HID keyboard explanation
    http://www.cygnal.org/ubb/Forum9/HTML/001381.html

    Tsuneo
    #3
    rusttree
    Super Member
    • Total Posts : 910
    • Reward points : 0
    • Joined: 2010/06/14 14:10:14
    • Location: Phoenix, AZ
    • Status: offline
    Re:Deciphering HID Report Descriptor 2012/10/12 08:26:22 (permalink)
    0
    Thanks Tsuneo.  This is making a lot more sense now.
    #4
    rusttree
    Super Member
    • Total Posts : 910
    • Reward points : 0
    • Joined: 2010/06/14 14:10:14
    • Location: Phoenix, AZ
    • Status: offline
    Re:Deciphering HID Report Descriptor 2012/10/12 18:57:13 (permalink)
    0
    Tsuneo,
    I'm working on an application that needs to act like a keyboard, but only needs to ever send a single keystroke.  A spacebar in this case.  I don't need any OUT data from the host, so I created a report descriptor that looks like this:
    0x05, 0x01,                    // USAGE_PAGE (Generic Desktop)
    0x09, 0x06,                    // USAGE (Keyboard)
        0xa1, 0x01,                    // COLLECTION (Application)
        0x05, 0x07,                    //   USAGE_PAGE (Keyboard)
        0x19, 0x2C,                    //   USAGE_MINIMUM (Keyboard Spacebar)
        0x29, 0x2C,                    //   USAGE_MAXIMUM (Keyboard Spacebar)
        0x15, 0x00,                    //   LOGICAL_MINIMUM (0)
        0x25, 0x01,                    //   LOGICAL_MAXIMUM (1)
        0x75, 0x01,                    //   REPORT_SIZE (1)
        0x95, 0x01,                    //   REPORT_COUNT(1)
        0x81, 0x02,                    //   INPUT (Data,Var,Abs)
        0x75, 0x07,                    //   REPORT_SIZE (7)
        0x95, 0x01,                    //   REPORT_COUNT(1)
        0x81, 0x03,                    //   INPUT (Cnst,Var,Abs)
    0xC0                           // End Collection
     
    Can only send a single bit that is or is not a spacebar keystroke.  I added 7 bits of padding to form one full byte.  Do you see any issues with this descriptor for this very simple case?
    #5
    chinzei
    Super Member
    • Total Posts : 2250
    • Reward points : 0
    • Joined: 2003/11/07 12:39:02
    • Location: Tokyo, Japan
    • Status: offline
    Re:Deciphering HID Report Descriptor 2012/10/13 06:18:01 (permalink)
    0
    In the HID Usage Table, Keycode is defined as "Selectors" type.

    10 Keyboard/Keypad Page (0x07)
    "The usage type of all key codes is Selectors (Sel), except for the modifier keys"

    It means keycode should be used with an array
    The report descriptor looks like this one.

     
    char ReportDescriptor[23] = {
        0x05, 0x01,                    // USAGE_PAGE (Generic Desktop)
        0x09, 0x06,                    // USAGE (Keyboard)
        0xa1, 0x01,                    // COLLECTION (Application)
        0x15, 0x00,                    //   LOGICAL_MINIMUM (0)         // array index, 0 or 1
        0x25, 0x01,                    //   LOGICAL_MAXIMUM (1)

        0x75, 0x08,                    //   REPORT_SIZE (8)             // one byte report
        0x95, 0x01,                    //   REPORT_COUNT (1)

        0x05, 0x07,                    //   USAGE_PAGE (Key code)       // list up two array members
        0x09, 0x00,                    //   USAGE (0 - no key pushed)    //  index 0
        0x09, 0x2c,                    //   USAGE (Keyboard Spacebar)    //  index 1

        0x81, 0x00,                    //   INPUT (Data,Ary,Abs)        // array-type input report
        0xc0                           // END_COLLECTION
    };


    In the one byte input report, your firmware sends array index, 0: no key, 1: space bar, instead of keycode. Two input reports are send, one for key push (1), another for key release (0).

    Tsuneo
    post edited by chinzei - 2012/10/13 06:28:06
    #6
    Jump to:
    © 2020 APG vNext Commercial Version 4.5