Add debug HID Report Descriptor as a build env 'BLE_GAMEPAD_DEBUG'

[LeeNX]

Add a build env BLE_GAMEPAD_DEBUG to dump the HID Report Descriptor, to make easy HID debugging.

[LeeNX]

Example of serial output

[BLEGamepad][INFO] HID Report Descriptor size: 106 bytes

000: 05 01 09 05 A1 01 85 05 05 09 15 00 25 01 75 01 
016: 19 01 29 06 95 06 81 02 75 01 95 02 81 03 05 01 
032: 16 00 00 26 FF 7F 75 10 95 08 A1 00 09 30 09 31 
048: 09 32 09 35 09 33 09 34 09 36 09 36 81 02 C0 A1 
064: 00 05 01 09 39 15 01 25 08 35 00 46 3B 01 65 12 
080: 75 08 95 01 81 42 C0 06 00 FF 09 01 09 01 15 00 
096: 26 FF 00 75 08 95 80 91 02 C0 
[BLEGamepad][INFO] End of HID Report Descriptor

Using something like https://eleccelerator.com/usbdescreqparser
The detail dump would look like

0x05, 0x01,        // Usage Page (Generic Desktop Ctrls)
0x09, 0x05,        // Usage (Game Pad)
0xA1, 0x01,        // Collection (Application)
0x85, 0x05,        //   Report ID (5)
0x05, 0x09,        //   Usage Page (Button)
0x15, 0x00,        //   Logical Minimum (0)
0x25, 0x01,        //   Logical Maximum (1)
0x75, 0x01,        //   Report Size (1)
0x19, 0x01,        //   Usage Minimum (0x01)
0x29, 0x06,        //   Usage Maximum (0x06)
0x95, 0x06,        //   Report Count (6)
0x81, 0x02,        //   Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x75, 0x01,        //   Report Size (1)
0x95, 0x02,        //   Report Count (2)
0x81, 0x03,        //   Input (Const,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x05, 0x01,        //   Usage Page (Generic Desktop Ctrls)
0x16, 0x00, 0x00,  //   Logical Minimum (0)
0x26, 0xFF, 0x7F,  //   Logical Maximum (32767)
0x75, 0x10,        //   Report Size (16)
0x95, 0x08,        //   Report Count (8)
0xA1, 0x00,        //   Collection (Physical)
0x09, 0x30,        //     Usage (X)
0x09, 0x31,        //     Usage (Y)
0x09, 0x32,        //     Usage (Z)
0x09, 0x35,        //     Usage (Rz)
0x09, 0x33,        //     Usage (Rx)
0x09, 0x34,        //     Usage (Ry)
0x09, 0x36,        //     Usage (Slider)
0x09, 0x36,        //     Usage (Slider)
0x81, 0x02,        //     Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
0xC0,              //   End Collection
0xA1, 0x00,        //   Collection (Physical)
0x05, 0x01,        //     Usage Page (Generic Desktop Ctrls)
0x09, 0x39,        //     Usage (Hat switch)
0x15, 0x01,        //     Logical Minimum (1)
0x25, 0x08,        //     Logical Maximum (8)
0x35, 0x00,        //     Physical Minimum (0)
0x46, 0x3B, 0x01,  //     Physical Maximum (315)
0x65, 0x12,        //     Unit (System: SI Rotation, Length: Centimeter)
0x75, 0x08,        //     Report Size (8)
0x95, 0x01,        //     Report Count (1)
0x81, 0x42,        //     Input (Data,Var,Abs,No Wrap,Linear,Preferred State,Null State)
0xC0,              //   End Collection
0x06, 0x00, 0xFF,  //   Usage Page (Vendor Defined 0xFF00)
0x09, 0x01,        //   Usage (0x01)
0x09, 0x01,        //   Usage (0x01)
0x15, 0x00,        //   Logical Minimum (0)
0x26, 0xFF, 0x00,  //   Logical Maximum (255)
0x75, 0x08,        //   Report Size (8)
0x95, 0x80,        //   Report Count (-128)
0x91, 0x02,        //   Output (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
0xC0,              // End Collection

// 106 bytes

@lemmingDev is there anything else you would like added?

[lemmingDev]

Nice functionality

Perhaps provide a link to https://eleccelerator.com/usbdescreqparser/ in the serial output

Also, the line beginnings such as 000: , 016: and 032: seem to need to be removed before pasting them into the parser

Maybe provide another output under it without them as well if that is the case, though I may be wrong

Something like below?

#if BLE_GAMEPAD_DEBUG
static void dumpHidReportDescriptor(const uint8_t* desc, size_t size) {
    if (!Serial) {
        // Serial not initialized yet, avoid printing
        return;
    }

    if (desc == nullptr || size == 0) {
        Serial.println("[BLEGamepad][ERROR] HID Report Descriptor is null or empty!");
        return;
    }

    Serial.printf("[BLEGamepad][INFO] HID Report Descriptor size: %u bytes\n", (unsigned)size);

    for (size_t i = 0; i < size; i++) {
        if (i % 16 == 0) {
            Serial.printf("\n%03u: ", (unsigned)i);
        }
        Serial.printf("%02X ", desc[i]);
    }
    Serial.println("\n[BLEGamepad][INFO] End of HID Report Descriptor");

    Serial.printf("\n\nCopy start under here\n");

    for (size_t i = 0; i < size; i++) {
        if (i % 16 == 0) {
            Serial.printf("\n");
        }
        Serial.printf("%02X ", desc[i]);
    }
    Serial.println("\nCopy end above here ");
    Serial.println("\n\nCopy and paste the output above and use a parser such as at https://eleccelerator.com/usbdescreqparser to create a readable HID Report Descriptor\n\n");
}
#endif

[LeeNX]

Thanks, first column is byte offset for the row.

Updated as suggested. Would be nice to find a HidReportDescriptor analyser.

[LeeNX]

Updates to include HID Report dumper. CI caught that I did not test the DEBUG env correctly. Noice.

@lemmingDev feedback welcome. I was not sure about the forward reference for the dumpHIDReport, feel like there should be a better way.

[LeeNX]

Extended the PR to include some updated CI, including platformIO builds using the debug option, to make sure extra code is compiling at least.

Credit for the PlatformIO basics should be webmonkey from https://github.com/webmonkey/ESP32-NIMBLE-Keyboard

[lemmingDev]

Thanks!