Keyboard HID report

Question

In some github projects I have seen that for HID keyboard report it is used a python structure like the following:

        self.state = [ 
               0xA1, # This is an input report
               0x01, # Usage report = Keyboard
               # Bit array for Modifier keys (D7 being the first element, D0 being last)
               [0,   # Right GUI - (usually the Windows key) 
                0,   # Right ALT
                0,   # Right Shift
                0,   # Right Control
                0,   # Left GUI - (again, usually the Windows key)
                0,   # Left ALT
                0,   # Left Shift
                0],  # Left Control
               0x00, # Vendor reserved
               0x00, # Rest is space for 6 keys 
               0x00,
               0x00,
               0x00,
               0x00,
               0x00 ]

I have some doubts regarding the first two bytes that appears in the structure, 0xA1 and 0x01, because the data with the keyboard information is really the rest.

Do HID reports start always with 0xA1?

If the value (0x01) of the second byte means "report usage = keyboard", what value correspond to a gamepad?

Thank for your help.

Answer 1

Seems this code was borrowed from here.

In this case Bluetooth HID Profile is used with so called "Boot Protocol" for Keyboard device (Report ID = 0x1).

From the spec "3.3.2 Bluetooth HID device Boot Protocol Requirements":

Bluetooth HID devices support three report types: Input, Output, and Feature. Input and Output reports typically contain low latency information. Input reports are generated by the Bluetooth HID device and sent to the Bluetooth HID Host. Output reports are generated by the Bluetooth HID Host and sent to the Bluetooth HID device. Feature reports are bi-directional, and typically contain information that is not intended to be seen or generated by the user, and hence is not time-critical. A Bluetooth HID device shall contain at least one report type in its report descriptor. Two logical channels are created between the Bluetooth HID device and Bluetooth HID Host: the Control channel and the Interrupt Channel. Reports may be carried on either the Interrupt channel or the Control channel. Report data carried on the Interrupt channel is sent without a request and is not acknowledged and these transfers are referred to as “asynchronous reports”. Report data transferred on the Control channel is always initiated by a SET_REPORT or GET_REPORT request (see sections 3.1.2.3 and 3.1.2.4) and these transfers are referred to as “synchronous reports”

Bluetooth HID Boot Protocol devices require a 1-octet Report ID prepended to the standard HID Boot Protocol report. Bluetooth HID Boot Protocol keyboard reports are 9 octets (1-octet Report ID + standard 8-octet keyboard boot report), and mouse boot reports are 4 octets (1-octet Report ID + standard 3-octet mouse boot report). The USB standard boot report portion of each of these Bluetooth boot reports shall conform to the format defined by the respective Boot Report descriptor in the USB HID Specification, Appendix B in order for the data to be correctly interpreted. The keyboard usages and pointing device button and XY axis usages shall conform to the assignments in the USB HID specification.

In Boot Protocol Mode, there is no report descriptor, but the reports do have Report IDs as defined in Section 3.3.2 and thus do require the ReportID field of the GET_REPORT Request octet.

0xA1 - is a 10100001 in binary, it seems that its in HIDP-Hdr format. Not sure why it is here:

Bits specifying characteristics of request.
7..4 HIDP Message Type
  4 = GET_REPORT
3 Size
  0 = The host has allocated a buffer equal to the size of the report.
  1 = A 2-octet BufferSize field follows the Report ID. This field indicates the size of the buffer allocated by the host. A device limits the returned payload size to BufferSize. Note that the BufferSize is increased by 1-octet for Boot Protocol Mode reports to include the Report ID imposed by the Bluetooth HID. See §3.3.2 more information on Boot Protocol Mode.
2 Reserved (0)
1..0 Report Type
  0 = Reserved
  1 = Input
  2 = Output
  3 = Feature

Conclusion: You cannot emulate gamepad via Bluetooth HID boot protocol because it is not supported. If you want to emulate HID gamepad - you need to provide full HID report descriptor prior to sending any data to host so it could be parsed by host driver.