GATT Human Interface Device (HID) Service Client

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:

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 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:

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.

Parameters
  • hogp – HOGP object.

  • rep – Report object.

  • err – ATT error code.

  • data – Pointer to the received data.

Returns

  • BT_GATT_ITER_STOP – Stop notification.

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

Parameters
  • hogp – HOGP object.

  • rep – Report object.

  • 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

bt_hogp_assign_error_cb

Parameters
  • 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

bt_hogp_ready_cb

Parameters
  • hogp – HOGP object.

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

Parameters
  • hogp – HOGP object.

  • err – ATT error code.

  • data – Pointer to the data, or NULL if there is an error or no more data.

  • size – The size of the received data chunk.

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

Parameters
  • 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.

Returns

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

Returns

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

Returns

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

Returns

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.

Returns

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.

Returns

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.

Returns

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.

Returns

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.

Returns

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

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.

Returns

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.

Returns

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.

Returns

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.

Returns

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

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.