GATT Human Interface Device (HID) Service Client

Configuration
Usage
API documentation

The HID Service Client module can be used to interact with a connected HID server. The server can, for example, be an instance of the GATT Human Interface Device (HID) Service.

The HID Service Client is used in the Bluetooth: Central HIDS sample.

The client uses the GATT Discovery Manager module to acquire all attribute handles that are required to interact with the HID server. Some additional data must be read from the discovered descriptors before the HID 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 

Apart from standard configuration parameters, there is one important setting:

CONFIG_BT_HOGP_REPORTS_MAX: Sets the maximum number of total reports supported by the library. The report memory is shared along all HIDS client objects, so this option should be set to the maximum total number of reports supported by the application.

Usage 

Note

Do not access any of the values in the bt_hogp object structure directly. All values that should be accessed have accessor functions. The reason that the structure is fully defined is to allow the application to allocate the memory for it.

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(): Checks if bt_hogp_handles_assign() was already called and the post discovery process has been started.
bt_hogp_ready_check(): Checks if the client object is fully ready to interact with the HID 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 bt_hogp_map_read(). If the report map does not fit into a single PDU, call the function repeatedly with different offsets.

There is no specific support for HID report map interpretation implemented in the HIDS client.

Accessing the reports 

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

bt_hogp_rep_read()
bt_hogp_rep_write()
bt_hogp_rep_write_wo_rsp()

To manage input report notifications, use the following functions:

bt_hogp_rep_subscribe()
bt_hogp_rep_unsubscribe()

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 if you are processing a normal report or a boot report.

Normal report:

The report info pointer for a normal report can be retrieved with the bt_hogp_rep_next() function. This function iterates through all detected reports (excluding boot reports). To find a specific report, use bt_hogp_rep_find(). This function locates a report based on its type and ID.

Boot report:

If the connected device supports the boot protocol, it must have mouse and/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. Note, however, that these pointers cannot be used as a previous record pointer in bt_hogp_rep_next().

Switching between boot and report mode 

To switch between Boot Protocol Mode and Report Protocol Mode, use bt_hogp_pm_write().

You can retrieve the current protocol with bt_hogp_pm_get(). This function returns the internally cached version of the current protocol mode. To update this value directly from the device, use bt_hogp_pm_update().

Note

Every time the protocol mode is changed, the bt_hogp_pm_update_cb function is called.

Suspending and resuming 

To suspend the connected device, call bt_hogp_suspend().

To resume, call bt_hogp_exit_suspend().

API documentation 

Header file: include/bluetooth/services/hogp.h

Source file: subsys/bluetooth/services/hogp.c

group bt_hogp

API for the Bluetooth LE GATT HID Service (HIDS) Client.

Typedefs

typedef uint8_t (*bt_hogp_read_cb)(struct bt_hogp *hogp, struct bt_hogp_rep_info *rep, uint8_t err, const uint8_t *data)

Callback function that is called when a notification or read response is received.

This function is called when new data related to the given report object appears. The data size can be obtained from the report object from the bt_hogp_rep_info::size field.

Param hogp: HOGP object.
Param rep: Report object.
Param err: ATT error code.
Param data: Pointer to the received data.
Retval BT_GATT_ITER_STOP: Stop notification.
Retval BT_GATT_ITER_CONTINUE: Continue notification.

typedef void (*bt_hogp_write_cb)(struct bt_hogp *hogp, struct bt_hogp_rep_info *rep, uint8_t err)

Callback function that is called when a write response is received.

Param hogp: HOGP object.
Param rep: Report object.
Param err: ATT error code.

typedef void (*bt_hogp_ready_cb)(struct bt_hogp *hogp)

Callback function that is called when the HIDS client is ready.

When the bt_hogp_handles_assign function is called, the module starts reading all additional information it needs to work. When this process is finished, this callback function is called.

See also

bt_hogp_assign_error_cb

Param hogp: HOGP object.

typedef void (*bt_hogp_prep_fail_cb)(struct bt_hogp *hogp, int err)

Callback function that is called when an error is detected during HIDS client preparation.

When the bt_hogp_handles_assign function is called, the module starts reading all additional information it needs to work. If an error is detected during this process, this callback function is called.

See also

bt_hogp_ready_cb

Param hogp: HOGP object.
Param err: Negative internal error code or positive ATT error code.

typedef void (*bt_hogp_map_cb)(struct bt_hogp *hogp, uint8_t err, const uint8_t *data, size_t size, size_t offset)

Callback function that is called when a chunk of a report map data is received.

Param hogp: HOGP object.
Param err: ATT error code.
Param data: Pointer to the data, or NULL if there is an error or no more data.
Param size: The size of the received data chunk.
Param offset: Current data chunk offset.

typedef void (*bt_hogp_pm_update_cb)(struct bt_hogp *hogp)

Callback function that is called when the protocol mode is updated.

This function is called when a protocol mode read or write finishes.

Param hogp: HOGP object.

Functions

void bt_hogp_init(struct bt_hogp *hogp, const struct bt_hogp_init_params *params)

Initialize the HIDS client instance.

You must call this function on the HOGP object before any other function.

Note

This function clears the whole memory occupied by the object. Do not call it on the object in use.

Parameters

hogp – HOGP object.
params – Initialization parameters.

int bt_hogp_handles_assign(struct bt_gatt_dm *dm, struct bt_hogp *hogp)

Assign handlers to the HIDS client instance.

This function should be called when a link with a peer has been established, to associate the link to this instance of the module. This makes it possible to handle several links and associate each link to a particular instance of this module. The GATT attribute handles are provided by the GATT Discovery Manager.

Note

This function starts the report discovery process. Wait for one of the functions in bt_hogp_init_params before using the HIDS object.

Parameters

dm – Discovery object.
hogp – HOGP object.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.
(-ENOTSUP) – Special error code used when the UUID of the service does not match the expected UUID.

void bt_hogp_release(struct bt_hogp *hogp)

Release the HIDS client instance.

This function releases all dynamic memory allocated by the HIDS client instance and clears all the instance data.

Note

Do not call this function on an instance that was not initialized (see bt_hogp_init). After the instance is initialized, it is safe to call this function multiple times.

Parameters

hogp – HOGP object.

void bt_hogp_abort_all(struct bt_hogp *hogp)

Abort all pending transfers.

Call this function only when the server is disconnected. Otherwise, if any read or write transfers are pending, the HOGP object might permanently return an EBUSY error on the following transfer attempts.

Note

This function disables transfers inside the HIDS client library. It does not abort any pending transfers in the Bluetooth LE stack.

Parameters

hogp – HOGP object.

bool bt_hogp_assign_check(const struct bt_hogp *hogp)

Check if the assignment function was called.

Parameters

hogp – HOGP object.

Return values

true – If the HIDS client has handlers assigned already.
false – If the HIDS client is released.

bool bt_hogp_ready_check(const struct bt_hogp *hogp)

Check if the HIDS client is ready to work.

Note

If bt_hogp_assign_check returns true while this function returns false, it means that initialization is in progress.

Parameters

hogp – HOGP object.

Return values

true – If the HIDS client is ready to work.
false – If the HIDS client is not ready.

int bt_hogp_rep_read(struct bt_hogp *hogp, struct bt_hogp_rep_info *rep, bt_hogp_read_cb func)

Send a read request addressing the report value descriptor.

This function can be used on any type of report.

Parameters

hogp – HOGP object.
rep – Report object.
func – Function to be called to process the response.

Return values

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

int bt_hogp_rep_write(struct bt_hogp *hogp, struct bt_hogp_rep_info *rep, bt_hogp_write_cb func, const void *data, uint8_t length)

Send a write request addressing the report value descriptor.

Note that In reports might not support this function. In this case, this function may succeed but pass an ATT error code to the callback function.

Parameters

hogp – HOGP object.
rep – Report object.
func – Function to be called to process the response.
data – Data to be sent.
length – Data size.

Return values

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

int bt_hogp_rep_write_wo_rsp(struct bt_hogp *hogp, struct bt_hogp_rep_info *rep, const void *data, uint8_t length, bt_hogp_write_cb func)

Send a write command addressing the report value descriptor.

Note that in case of an error, no error response from the server is received. If the server cannot execute the command, it is just ignored.

Parameters

hogp – HOGP object.
rep – Report object.
data – Data to be sent.
length – Data size.
func – Function to be called when operation is completed.

Return values

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

int bt_hogp_rep_subscribe(struct bt_hogp *hogp, struct bt_hogp_rep_info *rep, bt_hogp_read_cb func)

Subscribe to report notifications.

This function may be called only on Input type reports.

Parameters

hogp – HOGP object.
rep – Report object.
func – Function to be called to handle the notificated value.

Return values

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

int bt_hogp_rep_unsubscribe(struct bt_hogp *hogp, struct bt_hogp_rep_info *rep)

Remove the subscription for a selected report.

Parameters

hogp – HOGP object.
rep – Report object.

Return values

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

int bt_hogp_map_read(struct bt_hogp *hogp, bt_hogp_map_cb func, size_t offset, k_timeout_t timeout)

Read part of the report map.

This function sends a read request to the report map value. Depending on the offset, either read or read blob is sent.

The report map might not fit into a single PDU. To read the whole map, call this function repeatedly with a different offset.

Note

This function uses the common read parameters structure inside the HIDS client object. This object may be used by other functions and is protected by semaphore.

Parameters

hogp – HOGP object.
func – Function to be called to process the response.
offset – Byte offset where to start data read.
timeout – Time-out for the common read structure usage.

Return values

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

int bt_hogp_pm_update(struct bt_hogp *hogp, k_timeout_t timeout)

Read the current protocol mode from the server.

The callback is called when a read response is received.

See also

bt_hogp_pm_get

Note

Usually, the protocol mode value is read during HIDS client preparation, and its value is followed after that. This function may be used in an error recovery situation and should not be required in normal usage.
This function uses the common read parameters structure inside the HOGP object. This object may be used by other functions and is protected by semaphore.

Parameters

hogp – HOGP object.
timeout – Time-out for the common read structure usage.

Return values

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

enum bt_hids_pm bt_hogp_pm_get(const struct bt_hogp *hogp)

Get the current protocol mode.

This function returns the protocol mode stored in the HOGP object. It does not generate any traffic on the radio.

Parameters

hogp – HOGP object.

Returns

Current protocol mode.

int bt_hogp_pm_write(struct bt_hogp *hogp, enum bt_hids_pm pm)

Set the current protocol mode.

This function sends a write command to the Protocol Mode value.

Note

For the Protocol Mode value, only Write Without Response is used, so there is no control over the real Protocol Mode value if the write does not succeed.

Parameters

hogp – HOGP object.
pm – Protocol mode to select.

Return values

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

int bt_hogp_suspend(struct bt_hogp *hogp)

Suspend the device.

This function sends a SUSPEND command using the Control Point Characteristic. It should be called when the HOST enters SUSPEND state.

Parameters

hogp – HOGP object.

Return values

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

int bt_hogp_exit_suspend(struct bt_hogp *hogp)

Exit suspend and resume.

This function is used to inform the device that the HOST exits SUSPEND state.

Parameters

hogp – HOGP object.

Return values

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

struct bt_conn *bt_hogp_conn(const struct bt_hogp *hogp)

Get the connection object from the HIDS client.

This function gets the connection object that is used with a given HIDS client.

Parameters

hogp – HOGP object.

Returns

Connection object.

const struct bt_hids_info *bt_hogp_conn_info_val(const struct bt_hogp *hogp)

Access the HID information value.

This function accesses the structure with the decoded HID Information Characteristic value.

Parameters

hogp – HOGP object.

Returns

Pointer to the decoded HID information structure.

struct bt_hogp_rep_info *bt_hogp_rep_boot_kbd_in(struct bt_hogp *hogp)

Access boot keyboard input report.

Parameters

hogp – HOGP object.

Returns

The report pointer, or NULL if the device does not support boot keyboard protocol mode.

struct bt_hogp_rep_info *bt_hogp_rep_boot_kbd_out(struct bt_hogp *hogp)

Access boot keyboard output report.

Parameters

hogp – HOGP object.

Returns

The report pointer, or NULL if the device does not support boot keyboard protocol mode.

struct bt_hogp_rep_info *bt_hogp_rep_boot_mouse_in(struct bt_hogp *hogp)

Access boot mouse input report.

Parameters

hogp – HOGP object.

Returns

The report pointer, or NULL if the device does not support boot mouse protocol mode.

size_t bt_hogp_rep_count(const struct bt_hogp *hogp)

Get the number of HID reports in the device.

Note

This function does not take boot records into account. They can be accessed using separate functions.

Parameters

hogp – HOGP object.

Returns

The number of records.

struct bt_hogp_rep_info *bt_hogp_rep_next(struct bt_hogp *hogp, const struct bt_hogp_rep_info *rep)

Get the next report in the HOGP object.

Parameters

hogp – HOGP object.
rep – The record before the one to access, or NULL to access the first record.

Returns

The next report according to rep, or NULL if no more reports are available.

struct bt_hogp_rep_info *bt_hogp_rep_find(struct bt_hogp *hogp, enum bt_hids_report_type type, uint8_t id)

Find a report.

This function searches for a report with the given type and identifier.

Parameters

hogp – HOGP object.
type – The report type to find.
id – The identifier to find. Note that valid identifiers start from 1, but the value 0 may be used for devices that have one report of each type and there is no report ID inside the report map.

Returns

The report that was found, or NULL.

void bt_hogp_rep_user_data_set(struct bt_hogp_rep_info *rep, void *data)

Set user data in report.

Parameters

rep – Report object.
data – User data pointer to set.

void *bt_hogp_rep_user_data(const struct bt_hogp_rep_info *rep)

Get user data from report.

Parameters

rep – Report object.

Returns

User data pointer.

uint8_t bt_hogp_rep_id(const struct bt_hogp_rep_info *rep)

Get report identifier.

Parameters

rep – Report object.

Returns

Report identifier.

enum bt_hids_report_type bt_hogp_rep_type(const struct bt_hogp_rep_info *rep)

Get report type.

Parameters

rep – Report object.

Returns

Report type.

size_t bt_hogp_rep_size(const struct bt_hogp_rep_info *rep)

Get report size.

Note

You can rely on this function after completing the read procedure for your target HID report with the bt_hogp_rep_read API. The completion is reported by the appropriate callback. Alternatively, you can subscribe to your target report with bt_hogp_rep_subscribe API and start using the function below once you receive the first notification. In all other cases, the size information is not available.

Parameters

rep – Report object.

Returns

The size of the report or 0 if not available.

struct bt_hogp_init_params

#include <hogp.h>

HIDS client parameters for the initialization function.

Public Members

bt_hogp_ready_cb ready_cb: Function to call when the HID client is ready.

bt_hogp_prep_fail_cb prep_error_cb: Function to call if HID preparation fails.

bt_hogp_pm_update_cb pm_update_cb

Function to call when the protocol mode is updated.

This function is called every time the protocol mode is read or written. The old value is not checked.

struct bt_hogp

#include <hogp.h>

HOGP object.

Note

This structure is defined here to allow the user to allocate the memory for it in an application-dependent manner. Do not use any of the fields here directly, but use the accessor functions. There are accessors for every field you might need.

Public Members

struct bt_conn *conn: Connection object.

struct bt_hids_info info_val: HIDS client information.

bt_hogp_ready_cb ready_cb: Callback for HIDS client ready (see bt_hogp_ready_cb).

bt_hogp_prep_fail_cb prep_error_cb: Callback for HIDS client preparation failed.

bt_hogp_pm_update_cb pm_update_cb: Callback for protocol mode updated.

bt_hogp_map_cb map_cb: Callback for report map data chunk received.

struct bt_gatt_read_params read_params

Internal read parameters used when reading Protocol Mode or Report Map. This struct might also be used during initialization.

See also

bt_hogp::read_params_sem

struct k_sem read_params_sem

The semaphore for common read parameters protection.

This semaphore must be used when bt_hogp::read_params can be used.

uint8_t rep_idx: During the initialization process, all reports reference information is read. This structure helps tracking the current state of this process.

struct bt_hogp_rep_info *kbd_inp: Keyboard input boot report. Input and Output keyboard reports come in pairs. It is not valid that only one of the keyboard reports is present.

struct bt_hogp_rep_info *kbd_out: Keyboard output boot report. Input and Output keyboard reports come in pairs. It is not valid that only one of the keyboard reports is present.

struct bt_hogp_rep_info *mouse_inp: Mouse input boot report.

struct bt_hogp_rep_info **rep_info: Array of report information structures.

uint8_t rep_count: Number of records.

bool ready: Current state.

enum bt_hids_pm pm: Current protocol mode.

struct bt_hogp_handlers

#include <hogp.h>

Handlers for descriptors

Public Members

uint16_t pm: Protocol Mode Characteristic value handle.

uint16_t rep_map: Report Map descriptor handle.

uint16_t info: HID Information Characteristic handle.

uint16_t cp: HID Control Point Characteristic handle.