GATT Human Interface Device Service (HIDS) Client

The HIDS Client uses the GATT Discovery Manager to acquire all attribute handles that are required to interact with the HIDS server.

Overview 

Some additional data must be read from the discovered descriptors before the HIDS Client is ready. This process is started automatically just after the handles are assigned. If the process finishes successfully, the bt_hogp_ready_cb function is called. Otherwise, bt_hogp_prep_fail_cb is called.

Configuration 

Use the following Kconfig options to configure the library:

CONFIG_BT_HOGP - Enable the library in the application build.
CONFIG_BT_HOGP_REPORTS_MAX - Set the maximum number of total reports supported by the library.

The report memory is shared with all HIDS Client objects, so set this option to the maximum total number of reports supported by the application.
CONFIG_BT_HOGP_SCI - Enable HID Shorter Connection Intervals (SCI) support in the HIDS client. Requires CONFIG_BT_SHORTER_CONNECTION_INTERVALS.

Usage 

You can use the GATT HIDS Client library to interact with a connected HIDS server.

Retrieving the HIDS Client readiness state 

The following functions are available to retrieve the readiness state of the service client object:

bt_hogp_assign_check() - Check if bt_hogp_handles_assign() was called and the post-discovery process started.
bt_hogp_ready_check() - Check if the client object is ready to interact with the HIDS server. The ready flag is set just before the bt_hogp_ready_cb function is called.

Reading the report map 

To read the report map, call the bt_hogp_map_read() function. If the report map does not fit into a single PDU, call the function repeatedly with different offsets.

The HIDS report map interpretation implemented in the HIDS Client is not specifically supported.

Accessing the reports 

To read or write a report, use one of the following functions:

To manage input report notifications, use the following functions:

The report size is always updated before the callback function is called while reading or notifying. It can be obtained by calling bt_hogp_rep_size().

All report operations require a report info pointer as input. How to retrieve this pointer depends on whether you are processing a normal report or a boot report.

Call the bt_hogp_rep_next() function to retrieve the report info pointer. This function iterates through all detected reports (excluding boot reports).

Use the bt_hogp_rep_find() function to find a specific report. This function locates a report based on its type and ID.

If the connected device supports the boot protocol, it must have mouse or keyboard boot reports available. This means that:

For the mouse boot protocol, the function bt_hogp_rep_boot_mouse_in() returns a non-NULL value.
For the keyboard boot protocol, the two functions bt_hogp_rep_boot_kbd_in() and bt_hogp_rep_boot_kbd_out() return a non-NULL value.

All these functions return report pointers that may be used in the access functions. However, these pointers cannot be used as a previous record pointer in bt_hogp_rep_next().

Changing protocol mode 

To manage protocol modes, use the following functions:

bt_hogp_pm_write() - Switch between Boot Protocol Mode and Report Protocol Mode.

Every time the protocol mode is changed, the bt_hogp_pm_update_cb function is called.
bt_hogp_pm_get() - Retrieve the current protocol.

This function returns the internally cached version of the current protocol mode.
bt_hogp_pm_update() - Update the protocol mode value directly from the device.

Suspending and resuming 

To suspend or resume the connected device, call the following functions:

bt_hogp_suspend() - Suspend the connected device.
bt_hogp_exit_suspend() - Resume the connected device.

HID Shorter Connection Intervals (SCI)

When the CONFIG_BT_HOGP_SCI Kconfig option is enabled, the client discovers the HID SCI Information and HID SCI mode characteristics if the peer exposes them.

After the client is ready, use the bt_hogp_sci_supported() function to check whether the peer supports SCI. If the mandatory interval validation fails during SCI Information read, the client still becomes ready, but this function returns false.

This feature is in an experimental state.

The following functions are needed for host side SCI interaction:

bt_hogp_sci_mode_req() - Request the HID device to enter a specific SCI mode (writes the HID Control Point characteristic).
bt_hogp_sci_mode_read() - Read the current SCI mode from the HID device.
bt_hogp_sci_mode_subscribe() and bt_hogp_sci_mode_unsubscribe() - Enable or disable SCI mode change notifications.

Call the bt_hogp_sci_low_power_mode_supported() function before requesting Low Power mode using bt_hogp_sci_mode_req().