Bluetooth HID Service (HIDS)

Bluetooth HID Service (HIDS). More...

Data Structures
struct	bt_hids_cb
	HID Service callbacks. More...
struct	bt_hids_register_param
	HID Service registration parameters. More...

Macros
#define	BT_HIDS_REPORT_MAP_MAX_LEN   512U
	Maximum Report Map length of one HID Service.

Enumerations
enum	bt_hids_report_type { BT_HIDS_REPORT_TYPE_INPUT = 0x01U , BT_HIDS_REPORT_TYPE_OUTPUT = 0x02U , BT_HIDS_REPORT_TYPE_FEATURE = 0x03U }
	HID Report Type values. More...
enum	bt_hids_info_flags { BT_HIDS_INFO_FLAG_REMOTE_WAKE = BIT(0) , BT_HIDS_INFO_FLAG_NORMALLY_CONNECTABLE = BIT(1) }
	HID Information flags. More...
enum	bt_hids_ctrl_point { BT_HIDS_CTRL_SUSPEND = 0x00U , BT_HIDS_CTRL_EXIT_SUSPEND = 0x01U }
	HID Control Point commands. More...

Functions
int	bt_hids_register (const struct bt_hids_register_param *param)
	Register the HID Service.
int	bt_hids_unregister (void)
	Unregister the HID Service.
int	bt_hids_report_set (enum bt_hids_report_type report_type, uint8_t report_id, const uint8_t *data, uint16_t len)
	Set the value a Host reads from a Report characteristic.
int	bt_hids_report_get (enum bt_hids_report_type report_type, uint8_t report_id, uint8_t *data, uint16_t *len)
	Read back the value of a Report characteristic.
int	bt_hids_send_report (struct bt_conn *conn, uint8_t report_id, const uint8_t *data, uint16_t len, bt_gatt_complete_func_t func, void *user_data)
	Send an Input Report to a Host.

Detailed Description

Bluetooth HID Service (HIDS).

Since

4.6

Version

0.1.0

Server side implementation of the HID Service. The GATT attribute table is static; the number of Report characteristics of each type is a build time configuration and the application supplies the Report IDs when it registers the service.

The HID Service sets no security requirements of its own. The security required to access the characteristics is a build time configuration, see CONFIG_BT_HIDS_SECURITY_NONE, CONFIG_BT_HIDS_SECURITY_ENCRYPT and CONFIG_BT_HIDS_SECURITY_AUTHEN.

The API can be called from any thread, but not from an interrupt. The service serializes it with the Host accesses to the characteristics, and calls the callbacks without holding any lock of its own, so a callback can call the API.

Not supported yet: Boot Protocol Mode, that is the Protocol Mode characteristic and the Boot Keyboard and Boot Mouse Report characteristics, which the HID Service makes mandatory for a keyboard and for a mouse; multiple HID Service instances; and the "Include" of external services whose characteristics are described in the Report Map together with the External Report Reference descriptor.

Macro Definition Documentation

BT_HIDS_REPORT_MAP_MAX_LEN

#define BT_HIDS_REPORT_MAP_MAX_LEN   512U

#include <zephyr/bluetooth/services/hids.h>

Maximum Report Map length of one HID Service.

A composite HID Device that needs more octets than this to describe its functions uses several HID Service instances, which is not supported.

Enumeration Type Documentation

bt_hids_ctrl_point

enum bt_hids_ctrl_point

#include <zephyr/bluetooth/services/hids.h>

HID Control Point commands.

Defined by the HID Service, HID Control Point characteristic. The characteristic has four further commands for the HID SCI feature, which this service does not implement and rejects.

Enumerator
BT_HIDS_CTRL_SUSPEND	The Host is entering Suspend Mode.
BT_HIDS_CTRL_EXIT_SUSPEND	The Host is exiting Suspend Mode.

bt_hids_info_flags

enum bt_hids_info_flags

#include <zephyr/bluetooth/services/hids.h>

HID Information flags.

Defined by the HID Service, HID Information characteristic. The characteristic has two further flags for the HID SCI feature, which this service does not implement, and bt_hids_register() rejects them.

Enumerator
BT_HIDS_INFO_FLAG_REMOTE_WAKE	Device supports remote wake.
BT_HIDS_INFO_FLAG_NORMALLY_CONNECTABLE	Device is normally connectable.

bt_hids_report_type

enum bt_hids_report_type

#include <zephyr/bluetooth/services/hids.h>

HID Report Type values.

Defined by the HID Service, Report Reference characteristic descriptor.

Enumerator
BT_HIDS_REPORT_TYPE_INPUT	Input Report.
BT_HIDS_REPORT_TYPE_OUTPUT	Output Report.
BT_HIDS_REPORT_TYPE_FEATURE	Feature Report.

Function Documentation

bt_hids_register()

int bt_hids_register

(

const struct bt_hids_register_param *

param

)

#include <zephyr/bluetooth/services/hids.h>

Register the HID Service.

Registers the GATT HID Service and assigns the given Report IDs to its Report characteristics. Only one service instance is supported.

Parameters

[in]

param

Registration parameters.

Return values

0	Success.
-EALREADY	Already registered.
-EINVAL	Invalid parameters, including a Report Map longer than BT_HIDS_REPORT_MAP_MAX_LEN, a bcd_hid that is not binary coded decimal, a HID Information flag outside bt_hids_info_flags, duplicate Report IDs within one Report Type, and a Report ID of 0 when the Report Type has more than one Report characteristic.

bt_hids_report_get()

int bt_hids_report_get	(	enum bt_hids_report_type	report_type,
		uint8_t	report_id,
		uint8_t *	data,
		uint16_t *	len )

#include <zephyr/bluetooth/services/hids.h>

Read back the value of a Report characteristic.

Returns what a Host reads from the Report, which is the value the application last set with bt_hids_report_set() or a Host last wrote with SET_REPORT.

Parameters

[in]	report_type	HID Report Type, see bt_hids_report_type.
[in]	report_id	HID Report ID.
[out]	data	Destination for the payload. A buffer of CONFIG_BT_HIDS_MAX_REPORT_LEN octets always fits, since neither the application nor a Host can store a longer value.
[in,out]	len	Size of data on entry, the payload length on return.

Return values

0	Success.
-EINVAL	data or len is NULL.
-ENOMEM	data is too small for the value.
-ESRCH	Service not registered.
-ENOENT	No Report characteristic with this Report ID and Report Type.

bt_hids_report_set()

int bt_hids_report_set	(	enum bt_hids_report_type	report_type,
		uint8_t	report_id,
		const uint8_t *	data,
		uint16_t	len )

#include <zephyr/bluetooth/services/hids.h>

Set the value a Host reads from a Report characteristic.

The HID Service holds the value of every Report and answers a Host read from it, so the application sets the value whenever the state it describes changes. This is the arrangement the Report Map already uses, and the one the other GATT services use for values a Host can read: every fragment of a read comes from that one value, rather than from a per-read copy that could go stale, so an ATT Read Blob Request is consistent with the read it continues.

The fragments are read from the value as it is at that moment, so an application that calls this function while a Host is reading a Report longer than the ATT MTU can have the Host assemble octets of two different values. Set the value between reads, or keep Reports that a Host reads within one ATT_MTU-3 octets.

A Host write to a writable Report replaces the value as well, so a read that follows a SET_REPORT returns what the Host wrote.

The value survives disconnection; bt_hids_unregister() clears it. Until it is set for the first time a Host reads an empty value.

Parameters

[in]	report_type	HID Report Type, see bt_hids_report_type.
[in]	report_id	HID Report ID.
[in]	data	Report payload, excluding the Report ID byte.
[in]	len	Payload length.

Return values

0	Success.
-EINVAL	data is NULL, len is 0, or len is greater than CONFIG_BT_HIDS_MAX_REPORT_LEN.
-ESRCH	Service not registered.
-ENOENT	No Report characteristic with this Report ID and Report Type.

bt_hids_send_report()

int bt_hids_send_report	(	struct bt_conn *	conn,
		uint8_t	report_id,
		const uint8_t *	data,
		uint16_t	len,
		bt_gatt_complete_func_t	func,
		void *	user_data )

#include <zephyr/bluetooth/services/hids.h>

Send an Input Report to a Host.

Uses a GATT notification. If conn is NULL, all subscribed Hosts are notified, and the return value is that of the last Host notified.

Every error value is listed below, whether the HID Service or the GATT notification returns it.

Parameters

[in]	conn	Target connection, or NULL for all subscribed Hosts.
[in]	report_id	HID Report ID.
[in]	data	Report payload (excluding the Report ID byte).
[in]	len	Payload length.
[in]	func	Optional completion callback, NULL if not needed.
[in]	user_data	User data passed to the completion callback.

Return values

0	Success.
-EINVAL	data is NULL, len is 0 or greater than CONFIG_BT_HIDS_MAX_REPORT_LEN, or the Host is not subscribed to the Input Report. The subscription is only enforced when CONFIG_BT_GATT_ENFORCE_SUBSCRIPTION is enabled, which it is by default.
-ESRCH	Service not registered.
-ENOENT	Report ID not found.
-ENOTCONN	The Host is not connected, or no Host is subscribed when conn is NULL.
-EPERM	The link does not have the security level the characteristics require.
-EAGAIN	Bluetooth is not ready, or the Host is not change-aware.
-ENOMEM	No buffer is available for the notification, or len is greater than the ATT_MTU of the Host minus 3.

bt_hids_unregister()

int bt_hids_unregister

(

void

)

#include <zephyr/bluetooth/services/hids.h>

Unregister the HID Service.

Unregisters the GATT service and drops the HID state of every Host. Connected Hosts stay connected and are notified through the Service Changed characteristic.

Must not be called while another thread is in bt_hids_send_report(): the notification is sent without the service lock, so the application serializes unregistering with sending Input Reports.

Must not be called while settings_load() runs if a settings handler of the application calls a bt_hids_*() function: for a bonded Host that is not connected, unregistering stores the CCC values with the service lock held, which takes the settings lock that settings_load() holds while it runs the handlers.

Returns

0 on success, or a negative errno from bt_gatt_service_unregister() on failure.

Return values

-EALREADY

Not registered.