GATT Human Interface Device (HID) Service

This module implements the Human Interface Device Service with the corresponding set of characteristics. When initialized, it adds the HID Service and a set of characteristics, according to the HID Service specification and to the user requirements, to the Zephyr Bluetooth stack database.

If enabled, notification of Input Report characteristics is performed when the application calls the corresponding bt_gatt_hids_inp_rep_send() function.

You can register dedicated event handlers for most of the HIDS characteristics to be notified about changes in their values.

The HIDS module must be notified about the incoming connect and disconnect events using the dedicated API. This is done to synchronize the connection state of HIDS with the top module that uses it.

The HID Service is used in the following samples:

Service Changed support

You can change the structure of the HID Service dynamically, even during an ongoing connection, by using the Service Changed feature that is supported by the Zephyr Bluetooth stack. To do it, you must uninitialize the currently used HIDS instance, prepare a new description of the service structure, and initialize a new instance. In such case, the Bluetooth stack automatically notifies connected peers about the changed service.

Multiclient support

The HIDS module is able to handle multiple connected peers at the same time. The server allocates context data for each connected client. The context data is then used to store the values of HIDS characteristics. These values are unique for each connected peer. While sending notifications, the user can also target a specific client by providing the connection instance that is associated with it.

Report masking

The HIDS module can consist of reports that are used to transmit differential data. One example of such a report type is a mouse report. In a mouse report, mouse movement data represents the position change along the X or Y axis and should only be interpreted once by the HID host. After receiving a notification from the HID device, the client should not be able to get any non-zero value from the differential data part of the report by using the GATT Read Request on its characteristic. This is achieved by report masking. You can configure a relevant mask for a report to specify which part of the report is not to be stored as a characteristic value.

API documentation

Header file: include/hids.h
Source file: subsys/bluetooth/services/hids.c
group bt_gatt_hids

API for the BLE GATT Human Interface Device (HID) Service.

Defines

CONFIG_BT_GATT_HIDS_INPUT_REP_MAX
CONFIG_BT_GATT_HIDS_OUTPUT_REP_MAX
CONFIG_BT_GATT_HIDS_FEATURE_REP_MAX
BT_GATT_HIDS_BOOT_MOUSE_REP_LEN

Length of the Boot Mouse Input Report.

BT_GATT_HIDS_BOOT_KB_INPUT_REP_LEN

Length of the Boot Keyboard Input Report.

BT_GATT_HIDS_BOOT_KB_OUTPUT_REP_LEN

Length of the Boot Keyboard Output Report.

BT_GATT_HIDS_INFORMATION_LEN

Length of encoded HID Information.

BT_GATT_HIDS_DEF(_name, ...)

Declare a HIDS instance.

Parameters
  • _name: Name of the HIDS instance.
  • ...: Lengths of HIDS reports

Typedefs

typedef void (*bt_gatt_hids_notif_handler_t)(enum bt_gatt_hids_notif_evt evt)

HID notification event handler.

Parameters
  • evt: Notification event.

typedef void (*bt_gatt_hids_rep_handler_t)(struct bt_gatt_hids_rep *rep, struct bt_conn *conn, bool write)

HID Report event handler.

Parameters
  • rep: Pointer to the report descriptor.
  • conn: Pointer to Connection Object.
  • write: true if handler is called for report write.

typedef void (*bt_gatt_hids_pm_evt_handler_t)(enum bt_gatt_hids_pm_evt evt, struct bt_conn *conn)

HID Protocol Mode event handler.

Parameters
  • evt: Protocol Mode event (see bt_gatt_hids_pm_evt).
  • conn: Pointer to Connection Object.

typedef void (*bt_gatt_hids_cp_evt_handler_t)(enum bt_gatt_hids_cp_evt evt)

HID Control Point event handler.

Parameters
  • evt: Event indicating that the Control Point value has changed. (see bt_gatt_hids_cp_evt).

Enums

enum bt_gatt_hids_pm

Possible values for the Protocol Mode Characteristic value.

Values:

BT_GATT_HIDS_PM_BOOT = 0x00

Boot protocol.

BT_GATT_HIDS_PM_REPORT = 0x01

Report protocol.

enum bt_gatt_hids_report_type

Report types as defined in the Report Reference Characteristic descriptor.

Values:

BT_GATT_HIDS_REPORT_TYPE_RESERVED = 0x00

Reserved value.

BT_GATT_HIDS_REPORT_TYPE_INPUT = 0x01

Input Report.

BT_GATT_HIDS_REPORT_TYPE_OUTPUT = 0x02

Output report.

BT_GATT_HIDS_REPORT_TYPE_FEATURE = 0x03

Feature Report.

enum bt_gatt_hids_flags

HID Service information flags.

Values:

BT_GATT_HIDS_REMOTE_WAKE = BIT(0)

Device is capable of sending a wake-signal to a host.

BT_GATT_HIDS_NORMALLY_CONNECTABLE = BIT(1)

Device advertises when bonded but not connected.

enum bt_gatt_hids_control_point

HID Control Point settings.

Values:

BT_GATT_HIDS_CONTROL_POINT_SUSPEND = 0x00

Suspend value for Control Point.

BT_GATT_HIDS_CONTROL_POINT_EXIT_SUSPEND = 0x01

Exit suspend value for Control Point.

enum bt_gatt_hids_pm_evt

HID Service Protocol Mode events.

Values:

BT_GATT_HIDS_PM_EVT_BOOT_MODE_ENTERED

Boot mode entered.

BT_GATT_HIDS_PM_EVT_REPORT_MODE_ENTERED

Report mode entered.

enum bt_gatt_hids_cp_evt

HID Service Control Point events.

Values:

BT_GATT_HIDS_CP_EVT_HOST_SUSP

Suspend command received.

BT_GATT_HIDS_CP_EVT_HOST_EXIT_SUSP

Exit suspend command received.

enum bt_gatt_hids_notif_evt

HID notification events.

Values:

BT_GATT_HIDS_CCCD_EVT_NOTIF_ENABLED

Notification enabled event.

BT_GATT_HIDS_CCCD_EVT_NOTIF_DISABLED

Notification disabled event.

Functions

int bt_gatt_hids_init(struct bt_gatt_hids *hids_obj, const struct bt_gatt_hids_init_param *init_param)

Initialize the HIDS instance.

Return
0 If the operation was successful. Otherwise, a (negative) error code is returned.
Parameters
  • hids_obj: Pointer to HIDS instance.
  • init_param: HIDS initialization descriptor.

int bt_gatt_hids_uninit(struct bt_gatt_hids *hids_obj)

Uninitialize a HIDS instance.

Return
0 If the operation was successful. Otherwise, a (negative) error code is returned.
Parameters
  • hids_obj: Pointer to HIDS instance.

int bt_gatt_hids_notify_connected(struct bt_gatt_hids *hids_obj, struct bt_conn *conn)

Function for notification HID service about connection to the device This function should be used in main application.

Return
0 If the operation was successful. Otherwise, a (negative) error code is returned.
Parameters
  • hids_obj: Pointer to HIDS instance.
  • conn: Pointer to Connection Object.

int bt_gatt_hids_notify_disconnected(struct bt_gatt_hids *hids_obj, struct bt_conn *conn)

Function for notification HID service about disconnection from the device. This function should be used in main application.

Return
0 If the operation was successful. Otherwise, a (negative) error code is returned.
Parameters
  • hids_obj: Pointer to HIDS instance.
  • conn: Pointer to Connection Object.

int bt_gatt_hids_inp_rep_send(struct bt_gatt_hids *hids_obj, struct bt_conn *conn, u8_t rep_index, u8_t const *rep, u8_t len, bt_gatt_complete_func_t cb)

Send Input Report.

Warning
The function is not thread safe. It can not be called from multiple threads at the same time.
Return
0 If the operation was successful. Otherwise, a (negative) error code is returned.
Parameters
  • hids_obj: Pointer to HIDS instance.
  • conn: Pointer to Connection Object.
  • rep_index: Index of report descriptor.
  • rep: Pointer to the report data.
  • len: Length of report data.
  • cb: Notification complete callback (can be NULL).

int bt_gatt_hids_boot_mouse_inp_rep_send(struct bt_gatt_hids *hids_obj, struct bt_conn *conn, const u8_t *buttons, s8_t x_delta, s8_t y_delta, bt_gatt_complete_func_t cb)

Send Boot Mouse Input Report.

Warning
The function is not thread safe. It can not be called from multiple threads at the same time.
Return
0 If the operation was successful. Otherwise, a (negative) error code is returned.
Parameters
  • hids_obj: Pointer to HIDS instance.
  • conn: Pointer to Connection Object.
  • buttons: Pointer to the state of the mouse buttons - if null, buttons are set to the previously passed value.
  • x_delta: Horizontal movement.
  • y_delta: Vertical movement.
  • cb: Notification complete callback (can be NULL).

int bt_gatt_hids_boot_kb_inp_rep_send(struct bt_gatt_hids *hids_obj, struct bt_conn *conn, u8_t const *rep, u16_t len, bt_gatt_complete_func_t cb)

Send Boot Keyboard Input Report.

Warning
The function is not thread safe. It can not be called from multiple threads at the same time.
Return
0 If the operation was successful. Otherwise, a (negative) error code is returned.
Parameters
  • hids_obj: Pointer to HIDS instance.
  • conn: Pointer to Connection Object.
  • rep: Pointer to the report data.
  • len: Length of report data.
  • cb: Notification complete callback (can be NULL).

struct bt_gatt_hids_info
#include <hids.h>

HID Service information.

Public Members

u16_t bcd_hid

Version of the base USB HID specification.

u8_t b_country_code

Country ID code. HID device hardware localization. Most hardware is not localized (value 0x00).

u8_t flags

Information flags (see bt_gatt_hids_flags).

struct bt_gatt_hids_rep
#include <hids.h>

Report data.

Public Members

u8_t *data

Pointer to the report data.

u8_t size

Size of the report.

struct bt_gatt_hids_inp_rep
#include <hids.h>

Input Report.

Public Members

struct _bt_gatt_ccc ccc

CCC descriptor.

u8_t id

Report ID defined in the HIDS Report Map.

u8_t idx

Index in Input Report Array.

u8_t att_ind

Index in the service attribute array.

u8_t size

Size of report.

u8_t offset

Report data offset.

u8_t perm

Report permissions

Use GATT attribute permission bit field values here. As input report can only be read only 3 flags are used:

  • BT_GATT_PERM_READ
  • BT_GATT_PERM_READ_ENCRYPT
  • BT_GATT_PERM_READ_AUTHEN

If no attribute is chosen, the configured default is used.

The CCC register would have set the proper permissions for read and write, based on the read permissions for the whole report.

const u8_t *rep_mask

Pointer to report mask. The least significant bit corresponds to the least significant byte of the report value. If this bit is set to 1 then the first byte of report is stored. For example, report is 16 byte length to mask this the 2 byte is needed, so if first byte is 0b11111111 then the first 8 byte of report is stored, if second byte is 0b00001111 the only next 4 bytes so first 12 byte of report is stored. The user must provide a mask of the appropriate length to mask all bytes of the report. If rep_mask is NULL then whole report is stored.

bt_gatt_hids_notif_handler_t handler

Callback with the notification event.

struct bt_gatt_hids_outp_feat_rep
#include <hids.h>

Output or Feature Report.

Public Members

u8_t id

Report ID defined in the HIDS Report Map.

u8_t idx

Index in Output/Feature Report Array.

u8_t size

Size of report.

u8_t offset

Report data offset.

u8_t att_ind

Index in the service attribute array.

u8_t perm

Report permissions

Use GATT attribute permission bit field values here. Different permissions may be used for write and read:

  • BT_GATT_PERM_READ
  • BT_GATT_PERM_READ_ENCRYPT
  • BT_GATT_PERM_READ_AUTHEN
  • BT_GATT_PERM_WRITE
  • BT_GATT_PERM_WRITE_ENCRYPT
  • BT_GATT_PERM_WRITE_AUTHEN

If no attribute is chosen, the configured default is used.

bt_gatt_hids_rep_handler_t handler

Callback with updated report data.

struct bt_gatt_hids_boot_mouse_inp_rep
#include <hids.h>

Boot Mouse Input Report.

Public Members

struct _bt_gatt_ccc ccc

CCC descriptor.

u8_t att_ind

Index in the service attribute array.

bt_gatt_hids_notif_handler_t handler

Callback with the notification event.

struct bt_gatt_hids_boot_kb_inp_rep
#include <hids.h>

Boot Keyboard Input Report.

Public Members

struct _bt_gatt_ccc ccc

CCC descriptor.

u8_t att_ind

Index in the service attribute array.

bt_gatt_hids_notif_handler_t handler

Callback with the notification event.

struct bt_gatt_hids_boot_kb_outp_rep
#include <hids.h>

Boot Keyboard Output Report.

Public Members

u8_t att_ind

Index in the service attribute array.

bt_gatt_hids_rep_handler_t handler

Callback with updated report data.

struct bt_gatt_hids_inp_rep_group
#include <hids.h>

Collection of all input reports.

Public Members

struct bt_gatt_hids_inp_rep reports[0]

Pointer to the report collection.

u8_t cnt

Total number of reports.

struct bt_gatt_hids_outp_rep_group
#include <hids.h>

Collection of all output reports.

Public Members

struct bt_gatt_hids_outp_feat_rep reports[0]

Pointer to the report collection.

u8_t cnt

Total number of reports.

struct bt_gatt_hids_feat_rep_group
#include <hids.h>

Collection of all feature reports.

Public Members

struct bt_gatt_hids_outp_feat_rep reports[0]

Pointer to the report collection.

u8_t cnt

Total number of reports.

struct bt_gatt_hids_rep_map
#include <hids.h>

Report Map.

Public Members

u8_t const *data

Pointer to the map.

u8_t size

Size of the map.

struct bt_gatt_hids_pm_data
#include <hids.h>

Protocol Mode.

Public Members

bt_gatt_hids_pm_evt_handler_t evt_handler

Callback with new Protocol Mode.

struct bt_gatt_hids_cp
#include <hids.h>

Control Point.

Public Members

u8_t value

Current value of the Control Point.

bt_gatt_hids_cp_evt_handler_t evt_handler

Callback with new Control Point state.

struct bt_gatt_hids_init_param
#include <hids.h>

HID initialization.

Public Members

struct bt_gatt_hids_info info

HIDS Information.

struct bt_gatt_hids_inp_rep_group inp_rep_group_init

Input Report collection.

struct bt_gatt_hids_outp_rep_group outp_rep_group_init

Output Report collection.

struct bt_gatt_hids_feat_rep_group feat_rep_group_init

Feature Report collection.

struct bt_gatt_hids_rep_map rep_map

Report Map.

bt_gatt_hids_pm_evt_handler_t pm_evt_handler

Callback for Protocol Mode characteristic.

bt_gatt_hids_cp_evt_handler_t cp_evt_handler

Callback for Control Point characteristic.

bt_gatt_hids_notif_handler_t boot_mouse_notif_handler

Callback for Boot Mouse Input Report.

bt_gatt_hids_notif_handler_t boot_kb_notif_handler

Callback for Boot Keyboard Input Report.

bt_gatt_hids_rep_handler_t boot_kb_outp_rep_handler

Callback for Boot Keyboard Output Report.

bool is_mouse

Flag indicating that the device has mouse capabilities.

bool is_kb

Flag indicating that the device has keyboard capabilities.

struct bt_gatt_hids
#include <hids.h>

HID Service structure.

Public Members

struct bt_gatt_pool gp

Descriptor of the service attribute array.

struct bt_gatt_hids_inp_rep_group inp_rep_group

Input Report collection.

struct bt_gatt_hids_outp_rep_group outp_rep_group

Output Report collection.

struct bt_gatt_hids_feat_rep_group feat_rep_group

Feature Report collection.

struct bt_gatt_hids_boot_mouse_inp_rep boot_mouse_inp_rep

Boot Mouse Input Report.

struct bt_gatt_hids_boot_kb_inp_rep boot_kb_inp_rep

Boot Keyboard Input Report.

struct bt_gatt_hids_boot_kb_outp_rep boot_kb_outp_rep

Boot Keyboard Output Report.

struct bt_gatt_hids_rep_map rep_map

Report Map.

struct bt_gatt_hids_pm_data pm

Protocol Mode.

struct bt_gatt_hids_cp cp

Control Point.

u8_t info[4]

Buffer with encoded HID Information.

bool is_mouse

Flag indicating that the device has mouse capabilities.

bool is_kb

Flag indicating that the device has keyboard capabilities.

struct bt_conn_ctx_lib *conn_ctx

Bluetooth connection contexts.

struct bt_gatt_hids_conn_data
#include <hids.h>

HID Connection context data structure.

Public Members

u8_t pm_ctx_value

Protocol Mode context data.

u8_t hids_boot_mouse_inp_rep_ctx[8]

HIDS Boot Mouse Input Report Context.

u8_t hids_boot_kb_inp_rep_ctx[8]

HIDS Boot Keyboard Input Report Context.

u8_t hids_boot_kb_outp_rep_ctx[1]

HIDS Boot Keyboard Output Report Context.

u8_t *inp_rep_ctx

Pointer to Input Reports Context data.

u8_t *outp_rep_ctx

Pointer to Output Reports Context data.

u8_t *feat_rep_ctx

Pointer to Feature Reports Context data.