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.
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¶
include/hids.h
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.
- Parameters
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.
- Parameters
rep – Pointer to the report descriptor.
conn – Pointer to Connection Object.
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.
- Parameters
evt – Protocol Mode event (see bt_hids_pm_evt).
conn – Pointer to Connection Object.
-
typedef void (*
bt_hids_cp_evt_handler_t
)(enum bt_hids_cp_evt evt)¶ HID Control Point event handler.
- Parameters
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.
-
enumerator
-
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.
-
enumerator
-
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.
-
enumerator
-
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.
-
enumerator
-
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.
-
enumerator
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).
-
uint16_t
-
struct
bt_hids_rep
¶ - #include <hids.h>
Report data.
-
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_gatt_ccc
-
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.
-
uint8_t
-
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_gatt_ccc
-
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_gatt_ccc
-
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.
-
uint8_t
-
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_inp_rep
-
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_outp_feat_rep
-
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_outp_feat_rep
-
struct
bt_hids_rep_map
¶ - #include <hids.h>
Report 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.
-
bt_hids_pm_evt_handler_t
-
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.
-
uint8_t
-
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_info
-
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_gatt_pool
-
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.
-
uint8_t
-