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_gatt_hids_c_ready_cb function is called. Otherwise, bt_gatt_hids_c_prep_fail_cb is called.

Configuration

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

CONFIG_BT_GATT_HIDS_C_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_gatt_hids_c 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_gatt_hids_c_assign_check()

Checks if bt_gatt_hids_c_handles_assign() was already called and the post discovery process has been started.

bt_gatt_hids_c_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_gatt_hids_c_ready_cb function is called.

Reading the report map

To read the report map, call bt_gatt_hids_c_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_gatt_hids_c_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_gatt_hids_c_rep_next() function. This function iterates through all detected reports (excluding boot reports). To find a specific report, use bt_gatt_hids_c_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_gatt_hids_c_rep_next().

Switching between boot and report mode

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

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

Note

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

Suspending and resuming

To suspend the connected device, call bt_gatt_hids_c_suspend().

To resume, call bt_gatt_hids_c_exit_suspend().

API documentation

Header file: include/hids_c.h
Source file: subsys/bluetooth/services/hids_c.c
group bt_gatt_hids_c

API for the BLE GATT HID Service (HIDS) Client.

Typedefs

typedef u8_t (*bt_gatt_hids_c_read_cb)(struct bt_gatt_hids_c *hids_c, struct bt_gatt_hids_c_rep_info *rep, u8_t err, const u8_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_gatt_hids_c_rep_info::size field.

Parameters
  • hids_c: HIDS client object.

  • rep: Report object.

  • err: ATT error code.

  • data: Pointer to the received data.

Return Value
  • BT_GATT_ITER_STOP: Stop notification.

  • BT_GATT_ITER_CONTINUE: Continue notification.

typedef void (*bt_gatt_hids_c_write_cb)(struct bt_gatt_hids_c *hids_c, struct bt_gatt_hids_c_rep_info *rep, u8_t err)

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

Parameters
  • hids_c: HIDS client object.

  • rep: Report object.

  • err: ATT error code.

typedef void (*bt_gatt_hids_c_ready_cb)(struct bt_gatt_hids_c *hids_c)

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

When the bt_gatt_hids_c_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_gatt_hids_c_assign_error_cb

Parameters
  • hids_c: HIDS client object.

typedef void (*bt_gatt_hids_c_prep_fail_cb)(struct bt_gatt_hids_c *hids_c, int err)

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

When the bt_gatt_hids_c_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_gatt_hids_c_ready_cb

Parameters
  • hids_c: HIDS client object.

  • err: Negative internal error code or positive ATT error code.

typedef void (*bt_gatt_hids_c_map_cb)(struct bt_gatt_hids_c *hids_c, u8_t err, const u8_t *data, size_t size, size_t offset)

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

Parameters
  • hids_c: HIDS client 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_gatt_hids_c_pm_update_cb)(struct bt_gatt_hids_c *hids_c)

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

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

Parameters
  • hids_c: HIDS client object.

Functions

void bt_gatt_hids_c_init(struct bt_gatt_hids_c *hids_c, const struct bt_gatt_hids_c_init_params *params)

Initialize the HIDS client instance.

You must call this function on the HIDS client 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
  • hids_c: HIDS client object.

  • params: Initialization parameters.

int bt_gatt_hids_c_handles_assign(struct bt_gatt_dm *dm, struct bt_gatt_hids_c *hids_c)

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_gatt_hids_c_init_params before using the HIDS object.

Parameters
  • dm: Discovery object.

  • hids_c: HIDS client object.

Return Value
  • 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_gatt_hids_c_release(struct bt_gatt_hids_c *hids_c)

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_gatt_hids_c_init). After the instance is initialized, it is safe to call this function multiple times.

Parameters
  • hids_c: HIDS client object.

void bt_gatt_hids_c_abort_all(struct bt_gatt_hids_c *hids_c)

Abort all pending transfers.

Call this function only when the server is disconnected. Otherwise, if any read or write transfers are pending, the HIDS client 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 BLE stack.

Parameters
  • hids_c: HIDS client object.

bool bt_gatt_hids_c_assign_check(const struct bt_gatt_hids_c *hids_c)

Check if the assignment function was called.

Parameters
  • hids_c: HIDS client object.

Return Value
  • true: If the HIDS client has handlers assigned already.

  • false: If the HIDS client is released.

bool bt_gatt_hids_c_ready_check(const struct bt_gatt_hids_c *hids_c)

Check if the HIDS client is ready to work.

Note

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

Parameters
  • hids_c: HIDS client object.

Return Value
  • true: If the HIDS client is ready to work.

  • false: If the HIDS client is not ready.

int bt_gatt_hids_c_rep_read(struct bt_gatt_hids_c *hids_c, struct bt_gatt_hids_c_rep_info *rep, bt_gatt_hids_c_read_cb func)

Send a read request addressing the report value descriptor.

This function can be used on any type of report.

Parameters
  • hids_c: HIDS client object.

  • rep: Report object.

  • func: Function to be called to process the response.

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

int bt_gatt_hids_c_rep_write(struct bt_gatt_hids_c *hids_c, struct bt_gatt_hids_c_rep_info *rep, bt_gatt_hids_c_write_cb func, const void *data, u8_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
  • hids_c: HIDS client object.

  • rep: Report object.

  • func: Function to be called to process the response.

  • data: Data to be sent.

  • length: Data size.

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

int bt_gatt_hids_c_rep_write_wo_rsp(struct bt_gatt_hids_c *hids_c, struct bt_gatt_hids_c_rep_info *rep, const void *data, u8_t length)

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
  • hids_c: HIDS client object.

  • rep: Report object.

  • data: Data to be sent.

  • length: Data size.

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

int bt_gatt_hids_c_rep_subscribe(struct bt_gatt_hids_c *hids_c, struct bt_gatt_hids_c_rep_info *rep, bt_gatt_hids_c_read_cb func)

Subscribe to report notifications.

This function may be called only on Input type reports.

Parameters
  • hids_c: HIDS client object.

  • rep: Report object.

  • func: Function to be called to handle the notificated value.

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

int bt_gatt_hids_c_rep_unsubscribe(struct bt_gatt_hids_c *hids_c, struct bt_gatt_hids_c_rep_info *rep)

Remove the subscription for a selected report.

Parameters
  • hids_c: HIDS client object.

  • rep: Report object.

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

int bt_gatt_hids_c_map_read(struct bt_gatt_hids_c *hids_c, bt_gatt_hids_c_map_cb func, size_t offset, s32_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
  • hids_c: HIDS client 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 Value
  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int bt_gatt_hids_c_pm_update(struct bt_gatt_hids_c *hids_c, s32_t timeout)

Read the current protocol mode from the server.

The callback is called when a read response is received.

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 HIDS client object. This object may be used by other functions and is protected by semaphore.

See

bt_gatt_hids_c_pm_get

Parameters
  • hids_c: HIDS client object.

  • timeout: Time-out for the common read structure usage.

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

enum bt_gatt_hids_pm bt_gatt_hids_c_pm_get(const struct bt_gatt_hids_c *hids_c)

Get the current protocol mode.

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

Return

Current protocol mode.

Parameters
  • hids_c: HIDS client object.

int bt_gatt_hids_c_pm_write(struct bt_gatt_hids_c *hids_c, enum bt_gatt_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
  • hids_c: HIDS client object.

  • pm: Protocol mode to select.

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

int bt_gatt_hids_c_suspend(struct bt_gatt_hids_c *hids_c)

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
  • hids_c: HIDS client object.

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

int bt_gatt_hids_c_exit_suspend(struct bt_gatt_hids_c *hids_c)

Exit suspend and resume.

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

Parameters
  • hids_c: HIDS client object.

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

struct bt_conn *bt_gatt_hids_c_conn(const struct bt_gatt_hids_c *hids_c)

Get the connection object from the HIDS client.

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

Return

Connection object.

Parameters
  • hids_c: HIDS client object.

const struct bt_gatt_hids_info *bt_gatt_hids_c_conn_info_val(const struct bt_gatt_hids_c *hids_c)

Access the HID information value.

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

Return

Pointer to the decoded HID information structure.

Parameters
  • hids_c: HIDS client object.

struct bt_gatt_hids_c_rep_info *bt_gatt_hids_c_rep_boot_kbd_in(struct bt_gatt_hids_c *hids_c)

Access boot keyboard input report.

Return

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

Parameters
  • hids_c: HIDS client object.

struct bt_gatt_hids_c_rep_info *bt_gatt_hids_c_rep_boot_kbd_out(struct bt_gatt_hids_c *hids_c)

Access boot keyboard output report.

Return

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

Parameters
  • hids_c: HIDS client object.

struct bt_gatt_hids_c_rep_info *bt_gatt_hids_c_rep_boot_mouse_in(struct bt_gatt_hids_c *hids_c)

Access boot mouse input report.

Return

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

Parameters
  • hids_c: HIDS client object.

size_t bt_gatt_hids_c_rep_cnt(const struct bt_gatt_hids_c *hids_c)

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.

Return

The number of records.

Parameters
  • hids_c: HIDS client object.

struct bt_gatt_hids_c_rep_info *bt_gatt_hids_c_rep_next(struct bt_gatt_hids_c *hids_c, const struct bt_gatt_hids_c_rep_info *rep)

Get the next report in the HIDS client object.

Return

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

Parameters
  • hids_c: HIDS client object.

  • rep: The record before the one to access, or NULL to access the first record.

struct bt_gatt_hids_c_rep_info *bt_gatt_hids_c_rep_find(struct bt_gatt_hids_c *hids_c, enum bt_gatt_hids_report_type type, u8_t id)

Find a report.

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

Return

The report that was found, or NULL.

Parameters
  • hids_c: HIDS client 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.

void bt_gatt_hids_c_rep_user_data_set(struct bt_gatt_hids_c_rep_info *rep, void *data)

Set user data in report.

Parameters
  • rep: Report object.

  • data: User data pointer to set.

void *bt_gatt_hids_c_rep_user_data(const struct bt_gatt_hids_c_rep_info *rep)

Get user data from report.

Return

User data pointer.

Parameters
  • rep: Report object.

u8_t bt_gatt_hids_c_rep_id(const struct bt_gatt_hids_c_rep_info *rep)

Get report identifier.

Return

Report identifier.

Parameters
  • rep: Report object.

enum bt_gatt_hids_report_type bt_gatt_hids_c_rep_type(const struct bt_gatt_hids_c_rep_info *rep)

Get report type.

Return

Report type.

Parameters
  • rep: Report object.

size_t bt_gatt_hids_c_rep_size(const struct bt_gatt_hids_c_rep_info *rep)

Get report size.

Return

The size of the report.

Parameters
  • rep: Report object.

struct bt_gatt_hids_c_init_params
#include <hids_c.h>

HIDS client parameters for the initialization function.

Public Members

bt_gatt_hids_c_ready_cb ready_cb

Function to call when the HID client is ready.

bt_gatt_hids_c_prep_fail_cb prep_error_cb

Function to call if HID preparation fails.

bt_gatt_hids_c_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_gatt_hids_c
#include <hids_c.h>

HIDS client 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_gatt_hids_info info_val

HIDS client information.

bt_gatt_hids_c_ready_cb ready_cb

Callback for HIDS client ready (see bt_gatt_hids_c_ready_cb).

bt_gatt_hids_c_prep_fail_cb prep_error_cb

Callback for HIDS client preparation failed.

bt_gatt_hids_c_pm_update_cb pm_update_cb

Callback for protocol mode updated.

bt_gatt_hids_c_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_gatt_hids_c::read_params_sem

struct k_sem read_params_sem

The semaphore for common read parameters protection.

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

u8_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_gatt_hids_c_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_gatt_hids_c_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_gatt_hids_c_rep_info *mouse_inp

Mouse input boot report.

struct bt_gatt_hids_c_rep_info **rep_info

Array of report information structures.

u8_t rep_cnt

Number of records.

bool ready

Current state.

bt_gatt_hids_pm pm

Current protocol mode.

struct bt_gatt_hids_c_handlers
#include <hids_c.h>

Handlers for descriptors

Public Members

u16_t pm

Protocol Mode Characteristic value handle.

u16_t rep_map

Report Map descriptor handle.

u16_t info

HID Information Characteristic handle.

u16_t cp

HID Control Point Characteristic handle.