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_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.

Note

Some systems require security to use the HID service. To ensure interoperability, enable the CONFIG_BT_HIDS_DEFAULT_PERM_RW_ENCRYPT option.

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_hids

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

Defines

CONFIG_BT_HIDS_INPUT_REP_MAX
CONFIG_BT_HIDS_OUTPUT_REP_MAX
CONFIG_BT_HIDS_FEATURE_REP_MAX
BT_HIDS_BOOT_MOUSE_REP_LEN

Length of the Boot Mouse Input Report.

BT_HIDS_BOOT_KB_INPUT_REP_LEN

Length of the Boot Keyboard Input Report.

BT_HIDS_BOOT_KB_OUTPUT_REP_LEN

Length of the Boot Keyboard Output Report.

BT_HIDS_INFORMATION_LEN

Length of encoded HID Information.

BT_HIDS_DEF(_name, ...)

Declare a HIDS instance.

Parameters

  • _name – Name of the HIDS instance.

  • ... – Lengths of HIDS reports

Typedefs

typedef void (*bt_hids_notify_handler_t)(enum bt_hids_notify_evt evt)

HID notification event handler.

Param evt

Notification event.

typedef void (*bt_hids_rep_handler_t)(struct bt_hids_rep *rep, struct bt_conn *conn, bool write)

HID Report event handler.

Param rep

Pointer to the report descriptor.

Param conn

Pointer to Connection Object.

Param write

true if handler is called for report write.

typedef void (*bt_hids_pm_evt_handler_t)(enum bt_hids_pm_evt evt, struct bt_conn *conn)

HID Protocol Mode event handler.

Param evt

Protocol Mode event (see bt_hids_pm_evt).

Param conn

Pointer to Connection Object.

typedef void (*bt_hids_cp_evt_handler_t)(enum bt_hids_cp_evt evt)

HID Control Point event handler.

Param evt

Event indicating that the Control Point value has changed. (see bt_hids_cp_evt).

Enums

enum bt_hids_pm

Possible values for the Protocol Mode Characteristic value.

Values:

enumerator BT_HIDS_PM_BOOT

Boot protocol.

enumerator BT_HIDS_PM_REPORT

Report protocol.

enum bt_hids_report_type

Report types as defined in the Report Reference Characteristic descriptor.

Values:

enumerator BT_HIDS_REPORT_TYPE_RESERVED

Reserved value.

enumerator BT_HIDS_REPORT_TYPE_INPUT

Input Report.

enumerator BT_HIDS_REPORT_TYPE_OUTPUT

Output report.

enumerator BT_HIDS_REPORT_TYPE_FEATURE

Feature Report.

enum bt_hids_flags

HID Service information flags.

Values:

enumerator BT_HIDS_REMOTE_WAKE

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

enumerator BT_HIDS_NORMALLY_CONNECTABLE

Device advertises when bonded but not connected.

enum bt_hids_control_point

HID Control Point settings.

Values:

enumerator BT_HIDS_CONTROL_POINT_SUSPEND

Suspend value for Control Point.

enumerator BT_HIDS_CONTROL_POINT_EXIT_SUSPEND

Exit suspend value for Control Point.

enum bt_hids_pm_evt

HID Service Protocol Mode events.

Values:

enumerator BT_HIDS_PM_EVT_BOOT_MODE_ENTERED

Boot mode entered.

enumerator BT_HIDS_PM_EVT_REPORT_MODE_ENTERED

Report mode entered.

enum bt_hids_cp_evt

HID Service Control Point events.

Values:

enumerator BT_HIDS_CP_EVT_HOST_SUSP

Suspend command received.

enumerator BT_HIDS_CP_EVT_HOST_EXIT_SUSP

Exit suspend command received.

enum bt_hids_notify_evt

HID notification events.

Values:

enumerator BT_HIDS_CCCD_EVT_NOTIFY_ENABLED

Notification enabled event.

enumerator BT_HIDS_CCCD_EVT_NOTIFY_DISABLED

Notification disabled event.

Functions

int bt_hids_init(struct bt_hids *hids_obj, const struct bt_hids_init_param *init_param)

Initialize the HIDS instance.

Parameters

  • hids_obj – Pointer to HIDS instance.

  • init_param – HIDS initialization descriptor.

Returns

0 If the operation was successful. Otherwise, a (negative) error code is returned.

int bt_hids_uninit(struct bt_hids *hids_obj)

Uninitialize a HIDS instance.

Parameters

  • hids_obj – Pointer to HIDS instance.

Returns

0 If the operation was successful. Otherwise, a (negative) error code is returned.

int bt_hids_connected(struct bt_hids *hids_obj, struct bt_conn *conn)

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

Parameters

  • hids_obj – Pointer to HIDS instance.

  • conn – Pointer to Connection Object.

Returns

0 If the operation was successful. Otherwise, a (negative) error code is returned.

int bt_hids_disconnected(struct bt_hids *hids_obj, struct bt_conn *conn)

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

Parameters

  • hids_obj – Pointer to HIDS instance.

  • conn – Pointer to Connection Object.

Returns

0 If the operation was successful. Otherwise, a (negative) error code is returned.

int bt_hids_inp_rep_send(struct bt_hids *hids_obj, struct bt_conn *conn, uint8_t rep_index, uint8_t const *rep, uint8_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.

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).

Returns

0 If the operation was successful. Otherwise, a (negative) error code is returned.

int bt_hids_boot_mouse_inp_rep_send(struct bt_hids *hids_obj, struct bt_conn *conn, const uint8_t *buttons, int8_t x_delta, int8_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.

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).

Returns

0 If the operation was successful. Otherwise, a (negative) error code is returned.

int bt_hids_boot_kb_inp_rep_send(struct bt_hids *hids_obj, struct bt_conn *conn, uint8_t const *rep, uint16_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.

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).

Returns

0 If the operation was successful. Otherwise, a (negative) error code is returned.

struct bt_hids_info
#include <hids.h>

HID Service information.

Public Members

uint16_t bcd_hid

Version of the base USB HID specification.

uint8_t b_country_code

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

uint8_t flags

Information flags (see bt_hids_flags).

struct bt_hids_rep
#include <hids.h>

Report data.

Public Members

uint8_t *data

Pointer to the report data.

uint8_t size

Size of the report.

struct bt_hids_inp_rep
#include <hids.h>

Input Report.

Public Members

struct _bt_gatt_ccc ccc

CCC descriptor.

uint8_t id

Report ID defined in the HIDS Report Map.

uint8_t idx

Index in Input Report Array.

uint8_t att_ind

Index in the service attribute array.

uint8_t size

Size of report.

uint8_t offset

Report data offset.

uint8_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 uint8_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_hids_notify_handler_t handler

Callback with the notification event.

struct bt_hids_outp_feat_rep
#include <hids.h>

Output or Feature Report.

Public Members

uint8_t id

Report ID defined in the HIDS Report Map.

uint8_t idx

Index in Output/Feature Report Array.

uint8_t size

Size of report.

uint8_t offset

Report data offset.

uint8_t att_ind

Index in the service attribute array.

uint8_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_hids_rep_handler_t handler

Callback with updated report data.

struct bt_hids_boot_mouse_inp_rep
#include <hids.h>

Boot Mouse Input Report.

Public Members

struct _bt_gatt_ccc ccc

CCC descriptor.

uint8_t att_ind

Index in the service attribute array.

bt_hids_notify_handler_t handler

Callback with the notification event.

struct bt_hids_boot_kb_inp_rep
#include <hids.h>

Boot Keyboard Input Report.

Public Members

struct _bt_gatt_ccc ccc

CCC descriptor.

uint8_t att_ind

Index in the service attribute array.

bt_hids_notify_handler_t handler

Callback with the notification event.

struct bt_hids_boot_kb_outp_rep
#include <hids.h>

Boot Keyboard Output Report.

Public Members

uint8_t att_ind

Index in the service attribute array.

bt_hids_rep_handler_t handler

Callback with updated report data.

struct bt_hids_inp_rep_group
#include <hids.h>

Collection of all input reports.

Public Members

struct bt_hids_inp_rep reports[0]

Pointer to the report collection.

uint8_t cnt

Total number of reports.

struct bt_hids_outp_rep_group
#include <hids.h>

Collection of all output reports.

Public Members

struct bt_hids_outp_feat_rep reports[0]

Pointer to the report collection.

uint8_t cnt

Total number of reports.

struct bt_hids_feat_rep_group
#include <hids.h>

Collection of all feature reports.

Public Members

struct bt_hids_outp_feat_rep reports[0]

Pointer to the report collection.

uint8_t cnt

Total number of reports.

struct bt_hids_rep_map
#include <hids.h>

Report Map.

Public Members

uint8_t const *data

Pointer to the map.

uint8_t size

Size of the map.

struct bt_hids_pm_data
#include <hids.h>

Protocol Mode.

Public Members

bt_hids_pm_evt_handler_t evt_handler

Callback with new Protocol Mode.

struct bt_hids_cp
#include <hids.h>

Control Point.

Public Members

uint8_t value

Current value of the Control Point.

bt_hids_cp_evt_handler_t evt_handler

Callback with new Control Point state.

struct bt_hids_init_param
#include <hids.h>

HID initialization.

Public Members

struct bt_hids_info info

HIDS Information.

struct bt_hids_inp_rep_group inp_rep_group_init

Input Report collection.

struct bt_hids_outp_rep_group outp_rep_group_init

Output Report collection.

struct bt_hids_feat_rep_group feat_rep_group_init

Feature Report collection.

struct bt_hids_rep_map rep_map

Report Map.

bt_hids_pm_evt_handler_t pm_evt_handler

Callback for Protocol Mode characteristic.

bt_hids_cp_evt_handler_t cp_evt_handler

Callback for Control Point characteristic.

bt_hids_notify_handler_t boot_mouse_notif_handler

Callback for Boot Mouse Input Report.

bt_hids_notify_handler_t boot_kb_notif_handler

Callback for Boot Keyboard Input Report.

bt_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_hids
#include <hids.h>

HID Service structure.

Public Members

struct bt_gatt_pool gp

Descriptor of the service attribute array.

struct bt_hids_inp_rep_group inp_rep_group

Input Report collection.

struct bt_hids_outp_rep_group outp_rep_group

Output Report collection.

struct bt_hids_feat_rep_group feat_rep_group

Feature Report collection.

struct bt_hids_boot_mouse_inp_rep boot_mouse_inp_rep

Boot Mouse Input Report.

struct bt_hids_boot_kb_inp_rep boot_kb_inp_rep

Boot Keyboard Input Report.

struct bt_hids_boot_kb_outp_rep boot_kb_outp_rep

Boot Keyboard Output Report.

struct bt_hids_rep_map rep_map

Report Map.

struct bt_hids_pm_data pm

Protocol Mode.

struct bt_hids_cp cp

Control Point.

uint8_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_hids_conn_data
#include <hids.h>

HID Connection context data structure.

Public Members

uint8_t pm_ctx_value

Protocol Mode context data.

uint8_t hids_boot_mouse_inp_rep_ctx[8]

HIDS Boot Mouse Input Report Context.

uint8_t hids_boot_kb_inp_rep_ctx[8]

HIDS Boot Keyboard Input Report Context.

uint8_t hids_boot_kb_outp_rep_ctx[1]

HIDS Boot Keyboard Output Report Context.

uint8_t *inp_rep_ctx

Pointer to Input Reports Context data.

uint8_t *outp_rep_ctx

Pointer to Output Reports Context data.

uint8_t *feat_rep_ctx

Pointer to Feature Reports Context data.