HOG - ATT DB / hids_device_t

[benjaminaigner]

Dear Matthias,

my last contact with BTStack is a long time ago, but I'm glad the RaspberryPi Foundation is using BTStack for the PicoW!
I would like to implement a flexible way to use either combination of Mouse, Keyboard and Joystick in Bluetooth as it is working
with USB-HID (TinyUSB), see earlephilhower/arduino-pico#1506 .
I've done this before with the ESP32 (https://github.com/asterics/esp32_mouse_keyboard), which was of course no fun, but it is working. The problem is: with Bluedroid one is much more flexible with the creation of the ATT DB, I'm currently thinking on how to do this with BTStack, without re-implementing most of the HID stuff.

Is your feature request related to a problem? Please describe.
Although HID would allow composite devices (e.g. keyboard+mouse+joystick),
BTStack is using a fixed ATT setup with 1 IN, 1 OUT & 1 FEATURE entry.

Describe the solution you'd like
Some flexibility what parts are in the hids_device struct and the possibility to get/set a handle to the hids_device_send_input_report function (at least more than 1 input entry)

Describe alternatives you've considered
Maybe a flexible list of input,output&feature entries, including the handles & values.

Additional context

Thank you very much,
greetings,
Benjamin

[mringwal]

Hi Benjamin. Nice you're still interested.

While trying to avoid complexity, we've limited HID over GATT a bit, that's correct. :)

Haven't used HID in a while. If I remember correctly, you can add as many usages into a single report. Is this not possible for LE?

Assuming you need more than one report per type:

• would it be possible to specify the number of reports per type at compile time?
• or do you need to setup the ATT DB at run time?

In the first case, we had the vague idea to provide params to included gatt service definitions.

Cheers
Matthias

[matsobdev]

Hi! Using just one report with hod_keyboard_demo.c and modified descriptor:

const uint8_t hid_descriptor_keyboard_boot_mode[] = {

    0x05, 0x01,                    // Usage Page (Generic Desktop)
    0x09, 0x06,                    // Usage (Keyboard)
    0xa1, 0x01,                    // Collection (Application)

    0x85,  0x01,                   // Report ID 1

    // Modifier byte

    0x75, 0x01,                    //   Report Size (1)
    0x95, 0x08,                    //   Report Count (8)
    0x05, 0x07,                    //   Usage Page (Key codes)
    0x19, 0xe0,                    //   Usage Minimum (Keyboard LeftControl)
    0x29, 0xe7,                    //   Usage Maxium (Keyboard Right GUI)
    0x15, 0x00,                    //   Logical Minimum (0)
    0x25, 0x01,                    //   Logical Maximum (1)
    0x81, 0x02,                    //   Input (Data, Variable, Absolute)

    // Reserved byte

    0x75, 0x01,                    //   Report Size (1)
    0x95, 0x08,                    //   Report Count (8)
    0x81, 0x03,                    //   Input (Constant, Variable, Absolute)

    // LED report + padding

    0x95, 0x05,                    //   Report Count (5)
    0x75, 0x01,                    //   Report Size (1)
    0x05, 0x08,                    //   Usage Page (LEDs)
    0x19, 0x01,                    //   Usage Minimum (Num Lock)
    0x29, 0x05,                    //   Usage Maxium (Kana)
    0x91, 0x02,                    //   Output (Data, Variable, Absolute)

    0x95, 0x01,                    //   Report Count (1)
    0x75, 0x03,                    //   Report Size (3)
    0x91, 0x03,                    //   Output (Constant, Variable, Absolute)

    // Keycodes

    0x95, 0x05,                    //   Report Count (5, was 6) 
    0x75, 0x08,                    //   Report Size (8)
    0x15, 0x00,                    //   Logical Minimum (0)
    0x25, 0xff,                    //   Logical Maximum (1)
    0x05, 0x07,                    //   Usage Page (Key codes)
    0x19, 0x00,                    //   Usage Minimum (Reserved (no event indicated))
    0x29, 0xff,                    //   Usage Maxium (Reserved)
    0x81, 0x00,                    //   Input (Data, Array)

    //0xc0,                        // End collection
	 
    0x05, 0x0C,		// usage page (consumer device) 
    //0x09, 0x01, 		// usage -- consumer control 
    //0xA1, 0x01, 		// collection (application) 
    //0x85, 0x02, 		// report id 

    0x15, 0x00, 		// logical minimum 
    0x25, 0xFF,     		// logical maximum (ff) 
    0x19, 0x00, 		// usage minimum (0) 
    0x29, 0xFF,    		// usage maximum (ff) 
    0x95, 0x01, 		// report count (1, was 8) 
    0x75, 0x08, 		// report size (8) 
    0x81, 0x00, 		// input 
    0xC0,	 			// end collection
    0x05, 0x01,                    // USAGE_PAGE (Generic Desktop)
    0x09, 0x02,                    // USAGE (Mouse)
    0xa1, 0x01,                    // COLLECTION (Application)

    // 0x85,  0x01,                   // Report ID 1
    0x09, 0x01,                    //   USAGE (Pointer)
    0xa1, 0x00,                    //   COLLECTION (Physical)

    0x05, 0x09,                    //     USAGE_PAGE (Button)
    0x19, 0x01,                    //     USAGE_MINIMUM (Button 1)
    0x29, 0x03,                    //     USAGE_MAXIMUM (Button 3)
    0x15, 0x00,                    //     LOGICAL_MINIMUM (0)
    0x25, 0x01,                    //     LOGICAL_MAXIMUM (1)
    0x95, 0x03,                    //     REPORT_COUNT (3)
    0x75, 0x01,                    //     REPORT_SIZE (1)
    0x81, 0x02,                    //     INPUT (Data,Var,Abs)
    0x95, 0x01,                    //     REPORT_COUNT (1)
    0x75, 0x05,                    //     REPORT_SIZE (5)
    0x81, 0x03,                    //     INPUT (Cnst,Var,Abs)

    0x05, 0x01,                    //     USAGE_PAGE (Generic Desktop)
    0x09, 0x30,                    //     USAGE (X)
    0x09, 0x31,                    //     USAGE (Y)
    0x15, 0x81,                    //     LOGICAL_MINIMUM (-127)
    0x25, 0x7f,                    //     LOGICAL_MAXIMUM (127)
    0x75, 0x08,                    //     REPORT_SIZE (8)
    0x95, 0x02,                    //     REPORT_COUNT (2)
    0x81, 0x06,                    //     INPUT (Data,Var,Rel)

    // 0xc0,                          //   END_COLLECTION
	 0xc0,                          //   END_COLLECTION
    0xc0                           // END_COLLECTION
};

send_report() looks like that:

static void send_report(uint8_t modifier, uint8_t keycode, uint8_t keycode_last, uint8_t button, int dx, int dy){
    uint8_t report[] = {modifier, 0, keycode, 0, 0, 0, 0, keycode_last, button, dx, dy};
    switch (protocol_mode){
        case 0:
            hids_device_send_boot_keyboard_input_report(con_handle, report, sizeof(report));
            break;
        case 1:
           hids_device_send_input_report(con_handle, report, sizeof(report));
           break;
        default:
            break;
    }
}

And finally some demo to show off its actions:

while(1) {		
		send_report(0x00, 0x00, 0x00, 0, -50, -50);
		send_report(0x00, 0x00, 0x00, 2, 0, 0);
		send_report(0x00, 0x00, 0x00, 0, 0, 0);
		sleep_ms(2500);
	 }

I feel sending separate reports for keyboard/mouse (and whatever input device) would be more natural for USB HID standard, although it works for me to USBfy and BLEfy Lenovo G505 keyboard with Pico W.

PS. Last (6th) keyboard keycode is changed to be multimedia key (consume control) here.
PS2. Tested only on Samsung S7 and it shows up as a keyboard. I don't know, it there are different icons for composite devices. Maybe first is on to go.
PS3. I would play with hids.gatt file and merge mouse and keyboard examples, since - according to Matthias keyboard and mouse would need its own characteristic to be report independent. This file has ORG_BLUETOOTH_CHARACTERISTIC_BOOT_KEYBOARD_INPUT_REPORT and ORG_BLUETOOTH_CHARACTERISTIC_BOOT_MOUSE_INPUT_REPORT under ORG_BLUETOOTH_SERVICE_HUMAN_INTERFACE_DEVICE service. At least some clue.
PS4. In HID over GATT https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=245141 there is no joystick or other device but keyboard and mouse. So maybe adding joystick will only be a matter of a merged descriptor shared with keyboard or mouse for that kind of an input device (and other as well).

[benjaminaigner]

Dear @mringwal, dear @matsobdev ,

regarding the single report, identified by the report ID: normally you are right, what else is the report id used for :-).
But we are working with USB defined protocols and an ugly mixup with BT&BLE standards...

@matsobdev I'm sure your report map works on an Android device, these are the most compatible ones (similar to Linux). If you want to use iOS (mandatory for us) and Windows, there is a BIG difference on how the report map is parsed.
As far as I understand you don't use report IDs at all in your setup, so the Samsung device identifies the report type by length (I think).

ad PS: I'm really not sure how this works on all platforms, but I like your creative solution!
ad PS2: You have to change the "GAP Appearance" for a different icon
ad PS3: thx for the hint, this is exactly what I need, more report characteristics
ad PS4: I have it working with the ESP32: https://github.com/asterics/esp32_mouse_keyboard

@mringwal

THX for the hint, it would be option 1, we know the number of reports at compile time.
I'm happy with suggestions to implement this!

Greetings,
Benjamin

[mringwal]

Hi @benjaminaigner
Thanks for sharing your experience. After my iOS extensions (Classic HID), I didn't use HID myself.

To use two or more reports per type, we'd need to a) extend the database, as well as make the service implementation more flexible. For the GATT Compiler, I can image adding a mechanism to repeat one or more lines in the .gatt file controlled by a (global-)variable or even parameters to the #include call.

We'll have some internal discussion and get back.

[matsobdev]

I just compared mouse and keyboard hog examples and was optimistic (possibly prematurely) when saw:

case	HIDS_SUBEVENT_BOOT_KEYBOARD_INPUT_REPORT_ENABLE:
		con_handle = hids_subevent_boot_keyboard_input_report_enable_get_con_handle(packet);
		printf("Boot Keyboard Characteristic Subscribed %u\n", hids_subevent_boot_keyboard_input_report_enable_get_enable(packet));
		break;
case	HIDS_SUBEVENT_BOOT_MOUSE_INPUT_REPORT_ENABLE:
		con_handle = hids_subevent_boot_mouse_input_report_enable_get_con_handle(packet);
		printf("Boot Mouse Characteristic Subscribed %u\n", hids_subevent_boot_mouse_input_report_enable_get_enable(packet));
		break;

in hog_mouse_demo.c. Does that mean that mouse example is already capable of doing keyboard (separate characteristics) with descriptor with separate report_id for mouse and keyboard? After I read what's above, you'll prove me wrong I guess.

[benjaminaigner]

Dear @matsobdev ,

this is a special mode for using the BLE mouse&keyboard before the OS is loaded. AFAIK it is a basic mode, where the input report has a specific format. No HID report descriptor is used in this case.

Personally, I've never saw any device using the boot mode. All major OS use the report mode (in your send_report example is the if statement which type is used).

[matsobdev]

I was aware of that mode and wasn't sure but had an idea how it would work. Was too optimistic and missed that boot word, thanks for clarification.

[matsobdev]

Victory!
I've put content of hog_device_test.gatt file into hids.gatt file - to get two HID devices and voila. What wasn't working before - consumer control under different report_id, now is working. Descriptor below:

    0x05, 0x01, // USAGE_PAGE (Generic Desktop)
    0x09, 0x06, // USAGE (Keyboard)
    0xa1, 0x01, // COLLECTION (Application)
	 0x85, 0x01,
    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, 0xFF, // LOGICAL_MAXIMUM (255)
    0x05, 0x07, // USAGE_PAGE (Keyboard)
    0x19, 0x00, // USAGE_MINIMUM (Reserved (no event indicated))
    0x29, 0xff, // USAGE_MAXIMUM (Keyboard Application)
    0x81, 0x00, // INPUT (Data,Ary,Abs)
    0xc0,        // END_COLLECTION
	 0x05, 0x0C,									/* usage page (consumer device) */
	0x09, 0x01, 								/* usage -- consumer control */
	0xA1, 0x01, 								/* collection (application) */
	0x85, 0x04, 		/* report id */
	/* 4 Media Keys */
	0x15, 0x00, 								/* logical minimum */
	0x25, 0xFF,     							/* logical maximum (3ff) */
	0x19, 0x00, 								/* usage minimum (0) */
	0x29, 0xFF,    							/* usage maximum (3ff) */
	0x95, 0x08, 								/* report count (4) */
	0x75, 0x08, 								/* report size (16) */
	0x81, 0x00, 								/* input */
	0xC0, /* end collection */

And send_report():

static void send_report(uint8_t report_id, uint8_t modifier, uint8_t keycode){
    uint8_t report[] = {report_id, modifier, 0, keycode, 0, 0, 0, 0, 0};
    switch (protocol_mode){
        case 0:
            hids_device_send_boot_keyboard_input_report(con_handle, report, sizeof(report));
            break;
        case 1:
           hids_device_send_input_report(con_handle, report, sizeof(report));
           break;
        default:
            break;
    }
}

And test code:

while(1) {
	send_report(0x04, 0x00, 0xEA); //Volume down
	send_report(0x04, 0x00, 0x00);
	sleep_ms(1500);
}

It is Android tho, but wasn't working before, so progress.
It might work with mouse the same way like consumer control - different report_id stuff in descriptor.

Sorry, too fast, only one is working... 0x01 rep id not.

[benjaminaigner]

Sorry, too fast, only one is working... 0x01 rep id not.

And which one is working?

I've put content of hog_device_test.gatt file into hids.gatt file

Nice, thanks for the hint, so an adaption of the .gatt file is necessary.
I think in addition, you need the correct handler to send the report to.
(see here in the esp-idf implementation: https://github.com/asterics/esp32_mouse_keyboard/blob/d4ac64ef02ff0f6199efd0a675f9caed09d9d780/main/hid_dev.c#L45)

[benjaminaigner]

BTW: I'm working with the RaspberryPi Pico W with Earle Philhower's arduino-core: https://github.com/earlephilhower/arduino-pico

[matsobdev]

Yes, I'm on Pico W as well. I'm not gonna call it a success, but successfully used hardcoded output report (not boot) inside hids.gatt file - that is called by project .gatt file by the way. Changing there:

CHARACTERISTIC, ORG_BLUETOOTH_CHARACTERISTIC_REPORT, DYNAMIC | READ | WRITE | NOTIFY | ENCRYPTION_KEY_SIZE_16,
// fixed report id = 2, type = Output (2)
REPORT_REFERENCE, READ, 2, 1 //last 2 to 1, to set it as an input - I guess this is how it works

So output report is now input report_id 2. And demo code for mousing and keyboarding:

 while(1) {		
	hids_device_send_input_report(con_handle, (uint8_t[]) {0, 0, 4, 0, 0, 0, 0, 0}, 8);
	sleep_ms(5);
	hids_device_send_input_report(con_handle, (uint8_t[]) {0, 0, 0, 0, 0, 0, 0, 0}, 8);
	sleep_ms(5);
	hids_device_send_output_report(con_handle, (uint8_t[]) {2, 10, 10, 0}, 4);
	hids_device_send_output_report(con_handle, (uint8_t[]) {0, 10, 10, 0}, 4);
	sleep_ms(1500);
 }

This time with proper combo descriptor:

    0x05, 0x01,                    // Usage Page (Generic Desktop)
    0x09, 0x06,                    // Usage (Keyboard)
    0xa1, 0x01,                    // Collection (Application)

    0x85,  0x01,                   // Report ID 1

    // Modifier byte

    0x75, 0x01,                    //   Report Size (1)
    0x95, 0x08,                    //   Report Count (8)
    0x05, 0x07,                    //   Usage Page (Key codes)
    0x19, 0xe0,                    //   Usage Minimum (Keyboard LeftControl)
    0x29, 0xe7,                    //   Usage Maxium (Keyboard Right GUI)
    0x15, 0x00,                    //   Logical Minimum (0)
    0x25, 0x01,                    //   Logical Maximum (1)
    0x81, 0x02,                    //   Input (Data, Variable, Absolute)

    // Reserved byte

    0x75, 0x01,                    //   Report Size (1)
    0x95, 0x08,                    //   Report Count (8)
    0x81, 0x03,                    //   Input (Constant, Variable, Absolute)

    // LED report + padding

    0x95, 0x05,                    //   Report Count (5)
    0x75, 0x01,                    //   Report Size (1)
    0x05, 0x08,                    //   Usage Page (LEDs)
    0x19, 0x01,                    //   Usage Minimum (Num Lock)
    0x29, 0x05,                    //   Usage Maxium (Kana)
    0x91, 0x02,                    //   Output (Data, Variable, Absolute)

    0x95, 0x01,                    //   Report Count (1)
    0x75, 0x03,                    //   Report Size (3)
    0x91, 0x03,                    //   Output (Constant, Variable, Absolute)

    // Keycodes

    0x95, 0x06,                    //   Report Count (6)
    0x75, 0x08,                    //   Report Size (8)
    0x15, 0x00,                    //   Logical Minimum (0)
    0x25, 0xff,                    //   Logical Maximum (1)
    0x05, 0x07,                    //   Usage Page (Key codes)
    0x19, 0x00,                    //   Usage Minimum (Reserved (no event indicated))
    0x29, 0xff,                    //   Usage Maxium (Reserved)
    0x81, 0x00,                    //   Input (Data, Array)

    0xc0,                          // End collection
	 
    0x05, 0x01,                    // USAGE_PAGE (Generic Desktop)
    0x09, 0x02,                    // USAGE (Mouse)
    0xa1, 0x01,                    // COLLECTION (Application)

    0x85,  0x02,                    // Report ID 1

    0x09, 0x01,                    //   USAGE (Pointer)

    0xa1, 0x00,                    //   COLLECTION (Physical)

    0x05, 0x09,                    //     USAGE_PAGE (Button)
    0x19, 0x01,                    //     USAGE_MINIMUM (Button 1)
    0x29, 0x03,                    //     USAGE_MAXIMUM (Button 3)
    0x15, 0x00,                    //     LOGICAL_MINIMUM (0)
    0x25, 0x01,                    //     LOGICAL_MAXIMUM (1)
    0x95, 0x03,                    //     REPORT_COUNT (3)
    0x75, 0x01,                    //     REPORT_SIZE (1)
    0x81, 0x02,                    //     INPUT (Data,Var,Abs)
    0x95, 0x01,                    //     REPORT_COUNT (1)
    0x75, 0x05,                    //     REPORT_SIZE (5)
    0x81, 0x03,                    //     INPUT (Cnst,Var,Abs)

    0x05, 0x01,                    //     USAGE_PAGE (Generic Desktop)
    0x09, 0x30,                    //     USAGE (X)
    0x09, 0x31,                    //     USAGE (Y)
    0x15, 0x81,                    //     LOGICAL_MINIMUM (-127)
    0x25, 0x7f,                    //     LOGICAL_MAXIMUM (127)
    0x75, 0x08,                    //     REPORT_SIZE (8)
    0x95, 0x02,                    //     REPORT_COUNT (2)
    0x81, 0x06,                    //     INPUT (Data,Var,Rel)

    0xc0,                          //   END_COLLECTION
    0xc0                           // END_COLLECTION

I was searching throughout BTStack, maybe hids_device.c if a key to make separate extra characteristic instead of borrowing output one (no problem to add one inside .gatt file, but to put data on it). Full project dir: hog_kbd_test.zip

And .uf2 file but without mouse clicking, only moving and capital A typing: hog_kbd.zip for quick compatibility test. And maybe the same as above, but with that last keyboard key as a consumer device (pressing volume down here) under the same report_id 1 as keyboard to prove if it will (or not) work under Windows/Mac with BLE: hog_kbd_mutimedia.zip

[mringwal]

THX for the hint, it would be option 1, we know the number of reports at compile time.
I'm happy with suggestions to implement this!

We did a first analysis of the requirements and sketched out changes to the gatt compiler and hids_device.c.
The GATT compiler needs to support parameters for #include to specify the number of reports per type, a way to have an array of { characteristic, report reference } tuples, and also some kind of counter to enumerate the report ids. The hids_device.c needs storage for the additional reports and an index field for all send function.

Did we miss anything here?

We'll try to make the changes to the hid_device.c first as you can manually copy & paste & modify the current hids_device.gatt file and adapt it to your needs.

[benjaminaigner]

We did a first analysis of the requirements and sketched out changes to the gatt compiler and hids_device.c.
The GATT compiler needs to support parameters for #include to specify the number of reports per type, a way to have an array of { characteristic, report reference } tuples, and also some kind of counter to enumerate the report ids. The hids_device.c needs storage for the additional reports and an index field for all send function.

That sounds exactly like what we need 👍

Did we miss anything here?

I don't think so.

We'll try to make the changes to the hid_device.c first as you can manually copy & paste & modify the current hids_device.gatt file and adapt it to your needs.

Thank you very much, I think as well that the hid_device changes are important, the GATT file can be adapted manually.

[benjaminaigner]

@matsobdev Thank you very much for the intensive experimenting!

@mringwal Do you know how long it would take from your implementation to be included in the pico-sdk :-)?

[matsobdev]

Couldn't it be the way it is now, like adding an extra input report_id 4 characteristic in the project .gatt file, that will be corresponding to combo descriptor report_id 4 (value of 0x85 byte in the descriptor)? When I switch feature report to be an input one, and change mouse descriptor byte:

0x85,  0x03,                    // Report ID 3

this:

hids_device_send_feature_report(con_handle, (uint8_t[]) {0, 100, 100, 0}, 4);

works as expected.