HID Host Classic

Source Code: hid_host_demo.c

This example implements a HID Host. For now, it connects to a fixed device. It will connect in Report protocol mode if this mode is supported by the HID Device, otherwise it will fall back to BOOT protocol mode.

Main application configuration

In the application configuration, L2CAP and HID host are initialized, and the link policies are set to allow sniff mode and role change.

static void packet_handler (uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size);

static void hid_host_setup(void){

  // Initialize L2CAP
  <a href="https://github.com/bluekitchen/btstack/blob/develop/src/l2cap.h#L477">l2cap_init</a>();

#ifdef ENABLE_BLE
  // Initialize LE Security Manager. Needed for cross-transport key derivation
  <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L68">sm_init</a>();
#endif

  // Initialize HID Host
  <a href="https://github.com/bluekitchen/btstack/blob/develop/src/classic/hid_host.h#L144">hid_host_init</a>(hid_descriptor_storage, sizeof(hid_descriptor_storage));
  <a href="https://github.com/bluekitchen/btstack/blob/develop/src/classic/hid_host.h#L152">hid_host_register_packet_handler</a>(packet_handler);

  // Allow sniff mode requests by HID device and support role switch
  <a href="https://github.com/bluekitchen/btstack/blob/develop/src/gap.h#L439">gap_set_default_link_policy_settings</a>(LM_LINK_POLICY_ENABLE_SNIFF_MODE | LM_LINK_POLICY_ENABLE_ROLE_SWITCH);

  // try to become master on incoming connections
  <a href="https://github.com/bluekitchen/btstack/blob/develop/src/hci.h#L1725">hci_set_master_slave_policy</a>(HCI_ROLE_MASTER);

  // register for HCI events
  hci_event_callback_registration.callback = &amp;packet_handler;
  <a href="https://github.com/bluekitchen/btstack/blob/develop/src/hci.h#L1580">hci_add_event_handler</a>(&amp;hci_event_callback_registration);

  // make discoverable to allow HID device to initiate connection
  <a href="https://github.com/bluekitchen/btstack/blob/develop/src/gap.h#L1256">gap_discoverable_control</a>(1);

  // Disable stdout buffering
  setvbuf(stdin, NULL, _IONBF, 0);
}

HID Report Handler

Use BTstack's compact HID Parser to process incoming HID Report in Report protocol mode. Iterate over all fields and process fields with usage page = 0x07 / Keyboard Check if SHIFT is down and process first character (don't handle multiple key presses)

Packet Handler

The packet handler responds to various HID events.

static void packet_handler (uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size)
{
...
  switch (packet_type) {
        case HCI_EVENT_PACKET:
      event = hci_event_packet_get_type(packet);

      switch (event) {      
#ifndef HAVE_BTSTACK_STDIN
        case BTSTACK_EVENT_STATE:
          if (btstack_event_state_get_state(packet) == HCI_STATE_WORKING){
            status = <a href="https://github.com/bluekitchen/btstack/blob/develop/src/classic/hid_host.h#L170">hid_host_connect</a>(remote_addr, hid_host_report_mode, &amp;hid_host_cid);
            if (status != ERROR_CODE_SUCCESS){
              printf("HID host connect failed, status 0x%02x.\n", status);
            }
          }
          break;
#endif
...
        case HCI_EVENT_HID_META:
          switch (hci_event_hid_meta_get_subevent_code(packet)){

            case HID_SUBEVENT_INCOMING_CONNECTION:
              // There is an incoming connection: we can accept it or decline it

              // If there are no resources to handle the connection,
              // the status will be ERROR_CODE_MEMORY_CAPACITY_EXCEEDED

              // The hid_host_report_mode in the <a href="https://github.com/bluekitchen/btstack/blob/develop/src/classic/hid_host.h#L179">hid_host_accept_connection</a> function
              // allows the application to request a protocol mode.

              // For available protocol modes, see hid_protocol_mode_t in btstack_hid.h file.
              if (hid_subevent_incoming_connection_get_status(packet) == ERROR_CODE_SUCCESS) {
                <a href="https://github.com/bluekitchen/btstack/blob/develop/src/classic/hid_host.h#L179">hid_host_accept_connection</a>(hid_subevent_incoming_connection_get_hid_cid(packet), hid_host_report_mode);
              }
              break;

            case HID_SUBEVENT_CONNECTION_OPENED:
              // The status field of this event indicates if the control and interrupt
              // connections were opened successfully.
              status = hid_subevent_connection_opened_get_status(packet);
              if (status != ERROR_CODE_SUCCESS) {
                printf("Connection failed, status 0x%02x\n", status);
                app_state = APP_IDLE;
                hid_host_cid = 0;
                return;
              }
              app_state = APP_CONNECTED;
              hid_host_descriptor_available = false;
              hid_host_cid = hid_subevent_connection_opened_get_hid_cid(packet);
              hid_host_caps_lock = false;
              hid_host_led_report_len = 0;
              printf("HID Host connected.\n");
              break;

            case HID_SUBEVENT_DESCRIPTOR_AVAILABLE:
              // This event will follows HID_SUBEVENT_CONNECTION_OPENED event. 
              // For incoming connections, i.e. HID Device initiating the connection,
              // the HID_SUBEVENT_DESCRIPTOR_AVAILABLE is delayed, and some HID  
              // reports may be received via HID_SUBEVENT_REPORT event. It is up to 
              // the application if these reports should be buffered or ignored until 
              // the HID descriptor is available.
              status = hid_subevent_descriptor_available_get_status(packet);
              if (status == ERROR_CODE_SUCCESS){
                hid_host_descriptor_available = true;
                printf("HID Descriptor available, please start typing.\n");
                hid_host_demo_lookup_caps_lock_led();
              } else {
                printf("Cannot handle input report, HID Descriptor is not available, status 0x%02x\n", status);
              }
              break;

            case HID_SUBEVENT_REPORT:
              // Handle input report.
              if (hid_host_descriptor_available){
                hid_host_handle_interrupt_report(hid_subevent_report_get_report(packet), hid_subevent_report_get_report_len(packet));
              } else {
                <a href="https://github.com/bluekitchen/btstack/blob/develop/src/btstack_util.h#L249">printf_hexdump</a>(hid_subevent_report_get_report(packet), hid_subevent_report_get_report_len(packet));
              }
              break;

            case HID_SUBEVENT_SET_PROTOCOL_RESPONSE:
              // For incoming connections, the library will set the protocol mode of the
              // HID Device as requested in the call to <a href="https://github.com/bluekitchen/btstack/blob/develop/src/classic/hid_host.h#L179">hid_host_accept_connection</a>. The event 
              // reports the result. For connections initiated by calling <a href="https://github.com/bluekitchen/btstack/blob/develop/src/classic/hid_host.h#L170">hid_host_connect</a>, 
              // this event will occur only if the established report mode is boot mode.
              status = hid_subevent_set_protocol_response_get_handshake_status(packet);
              if (status != HID_HANDSHAKE_PARAM_TYPE_SUCCESSFUL){
                printf("Error set protocol, status 0x%02x\n", status);
                break;
              }
              switch ((hid_protocol_mode_t)hid_subevent_set_protocol_response_get_protocol_mode(packet)){
                case HID_PROTOCOL_MODE_BOOT:
                  printf("Protocol mode set: BOOT.\n");
                  break;  
                case HID_PROTOCOL_MODE_REPORT:
                  printf("Protocol mode set: REPORT.\n");
                  break;
                default:
                  printf("Unknown protocol mode.\n");
                  break; 
              }
              break;

            case HID_SUBEVENT_CONNECTION_CLOSED:
              // The connection was closed.
              hid_host_cid = 0;
              hid_host_descriptor_available = false;
              printf("HID Host disconnected.\n");
              break;

            default:
              break;
          }
          break;
        default:
          break;
      }
      break;
    default:
      break;
  }
}

When BTSTACK_EVENT_STATE with state HCI_STATE_WORKING is received and the example is started in client mode, the remote SDP HID query is started.