Bluetooth HID Device

Bluetooth HID Device. More...

Data Structures
struct	bt_hid_device_cb
	Callbacks supplied by the HID application. More...

Functions
int	bt_hid_device_register (const struct bt_hid_device_cb *cb)
	Register HID device callbacks.
int	bt_hid_device_unregister (void)
	Unregister HID device callbacks and disable HID services.
int	bt_hid_device_connect (struct bt_conn *conn, struct bt_hid_device **hid)
	Initiate an outgoing HID association on the given connection.
int	bt_hid_device_disconnect (struct bt_hid_device *hid)
	Disconnect a previously connected HID association.
struct net_buf *	bt_hid_device_create_pdu (struct net_buf_pool *pool)
	Allocate/create a PDU buffer suitable for HID over L2CAP.
int	bt_hid_device_input_report (struct bt_hid_device *hid, struct net_buf *buf)
	Send a HID interrupt input report to the HID host.
int	bt_hid_device_virtual_cable_unplug (struct bt_hid_device *hid)
	Trigger a virtual cable unplug procedure for the given HID association.
struct bt_conn *	bt_hid_device_get_conn (struct bt_hid_device *hid)
	Obtain the ACL connection associated with a HID device.

HID protocol mode values
These values indicate which HID protocol the host requests the device to use. BOOT_MODE is the legacy boot protocol; REPORT_MODE indicates normal report protocol operation.
#define	BT_HID_PROTOCOL_BOOT_MODE   0x00
	Boot protocol mode (legacy).
#define	BT_HID_PROTOCOL_REPORT_MODE   0x01
	Report protocol mode (default).

HID report types used for Get/Set/Data operations
These map to report type fields in HID messages. INPUT reports are typically device->host, OUTPUT are host->device, and FEATURE are device-specific feature reports.
#define	BT_HID_REPORT_TYPE_INPUT   0x01
	Report type for input reports (1) - device->host.
#define	BT_HID_REPORT_TYPE_OUTPUT   0x02
	Report type for output reports (2) - host->device.
#define	BT_HID_REPORT_TYPE_FEATURE   0x03
	Report type for feature reports (3) - device-specific.

Detailed Description

Bluetooth HID Device.

Macro Definition Documentation

BT_HID_PROTOCOL_BOOT_MODE

#define BT_HID_PROTOCOL_BOOT_MODE   0x00

#include <hid_device.h>

Boot protocol mode (legacy).

BT_HID_PROTOCOL_REPORT_MODE

#define BT_HID_PROTOCOL_REPORT_MODE   0x01

#include <hid_device.h>

Report protocol mode (default).

BT_HID_REPORT_TYPE_FEATURE

#define BT_HID_REPORT_TYPE_FEATURE   0x03

#include <hid_device.h>

Report type for feature reports (3) - device-specific.

BT_HID_REPORT_TYPE_INPUT

#define BT_HID_REPORT_TYPE_INPUT   0x01

#include <hid_device.h>

Report type for input reports (1) - device->host.

BT_HID_REPORT_TYPE_OUTPUT

#define BT_HID_REPORT_TYPE_OUTPUT   0x02

#include <hid_device.h>

Report type for output reports (2) - host->device.

Function Documentation

bt_hid_device_connect()

int bt_hid_device_connect	(	struct bt_conn *	conn,
		struct bt_hid_device **	hid )

#include <hid_device.h>

Initiate an outgoing HID association on the given connection.

On success the bt_hid_device instance is stored in hid. The caller must not free this object.

Parameters

conn	Bluetooth connection to use for the association.
hid	Pointer to store the HID device instance on success.

Returns

0 on success or a negative errno on failure.

bt_hid_device_create_pdu()

struct net_buf * bt_hid_device_create_pdu

(

struct net_buf_pool *

pool

)

#include <hid_device.h>

Allocate/create a PDU buffer suitable for HID over L2CAP.

If pool is NULL a default pool may be used by the implementation.

Note

Callers should use net_buf_add_*() to append report payload to the returned buffer.

Parameters

pool	Buffer pool to allocate from, or NULL to use the default connection TX pool.

Returns

A new net_buf instance or NULL on failure.

bt_hid_device_disconnect()

int bt_hid_device_disconnect

(

struct bt_hid_device *

hid

)

#include <hid_device.h>

Disconnect a previously connected HID association.

The disconnect is asynchronous. Callers should not free the hid instance until the disconnected callback is invoked.

Parameters

hid	HID device instance to disconnect.

Returns

0 on success or a negative errno on failure.

bt_hid_device_get_conn()

struct bt_conn * bt_hid_device_get_conn

(

struct bt_hid_device *

hid

)

#include <hid_device.h>

Obtain the ACL connection associated with a HID device.

Useful from callbacks that only receive the HID device object (for example bt_hid_device_cb::vc_unplug) but need the peer identity, e.g. to clear bonding information.

Parameters

hid	HID device object.

Returns

Connection object associated with the HID device, or NULL if the device is not connected. The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.

bt_hid_device_input_report()

int bt_hid_device_input_report	(	struct bt_hid_device *	hid,
		struct net_buf *	buf )

#include <hid_device.h>

Send a HID interrupt input report to the HID host.

The buffer should contain the full report payload including the Report ID byte if the descriptor declares Report IDs (HID spec v1.1.2 Section 3.1.2.8).

The HID device can transmit interrupt channel messages to the host at any time.

Note

The buffer must be allocated with bt_hid_device_create_pdu() to ensure sufficient headroom for the HID and L2CAP headers.

Parameters

hid	HID device instance to send data on.
buf	Buffer containing the report payload (consumed on success).

Returns

0 on success or a negative errno on failure.

bt_hid_device_register()

int bt_hid_device_register

(

const struct bt_hid_device_cb *

cb

)

#include <hid_device.h>

Register HID device callbacks.

The callback pointer must remain valid until bt_hid_device_unregister() is called. A second registration without an intervening unregister is rejected with -EALREADY; the callbacks are not replaced.

Parameters

cb	Callbacks to register. Must not be NULL, and the mandatory bt_hid_device_cb::get_report and bt_hid_device_cb::set_report callbacks must be provided.

Return values

0	on success.
-EINVAL	if cb is NULL or a mandatory callback is missing.
-EALREADY	if a callback set is already registered.

bt_hid_device_unregister()

int bt_hid_device_unregister

(

void

)

#include <hid_device.h>

Unregister HID device callbacks and disable HID services.

This clears the callbacks and unregisters the L2CAP servers. The caller must disconnect any active HID session before calling this function; otherwise -EBUSY is returned and no action is taken.

Return values

0	on success.
-EBUSY	if an HID session is still active.

bt_hid_device_virtual_cable_unplug()

int bt_hid_device_virtual_cable_unplug

(

struct bt_hid_device *

hid

)

#include <hid_device.h>

Trigger a virtual cable unplug procedure for the given HID association.

This will request the remote host to treat the device as unplugged.

Parameters

hid	HID device instance to unplug.

Returns

0 on success or a negative errno on failure.