hci.h File Reference

#include <stdbool.h>
#include <stdint.h>
#include <zephyr/net/buf.h>
#include <zephyr/bluetooth/addr.h>
#include <zephyr/bluetooth/conn.h>
#include <zephyr/bluetooth/hci_types.h>

Go to the source code of this file.

Typedefs
typedef bool	bt_hci_vnd_evt_cb_t(struct net_buf_simple *buf)
	Callback type for vendor handling of HCI Vendor-Specific Events.

Functions
static const char *	bt_hci_err_to_str (uint8_t hci_err)
	Converts a HCI error to string.
struct net_buf *	bt_hci_cmd_create (uint16_t opcode, uint8_t param_len)
	Allocate a HCI command buffer.
int	bt_hci_cmd_send (uint16_t opcode, struct net_buf *buf)
	Send a HCI command asynchronously.
int	bt_hci_cmd_send_sync (uint16_t opcode, struct net_buf *buf, struct net_buf **rsp)
	Send a HCI command synchronously.
int	bt_hci_get_conn_handle (const struct bt_conn *conn, uint16_t *conn_handle)
	Get connection handle for a connection.
struct bt_conn *	bt_hci_conn_lookup_handle (uint16_t handle)
	Get connection given a connection handle.
int	bt_hci_get_adv_handle (const struct bt_le_ext_adv *adv, uint8_t *adv_handle)
	Get advertising handle for an advertising set.
struct bt_le_ext_adv *	bt_hci_adv_lookup_handle (uint8_t handle)
	Get advertising set given an advertising handle.
int	bt_hci_get_adv_sync_handle (const struct bt_le_per_adv_sync *sync, uint16_t *sync_handle)
	Get periodic advertising sync handle.
struct bt_le_per_adv_sync *	bt_hci_per_adv_sync_lookup_handle (uint16_t handle)
	Get periodic advertising sync given an periodic advertising sync handle.
const char *	bt_hci_get_ver_str (uint8_t core_version)
	Obtain the version string given a core version number.
int	bt_hci_register_vnd_evt_cb (bt_hci_vnd_evt_cb_t cb)
	Register user callback for HCI Vendor-Specific Events.
int	bt_hci_le_rand (void *buffer, size_t len)
	Get Random bytes from the LE Controller.

Typedef Documentation

bt_hci_vnd_evt_cb_t

bt_hci_vnd_evt_cb_t

Callback type for vendor handling of HCI Vendor-Specific Events.

A function of this type is registered with bt_hci_register_vnd_evt_cb() and will be called for any HCI Vendor-Specific Event.

Parameters

buf	Buffer containing event parameters.

Returns

true if the function handles the event or false to defer the handling of this event back to the stack.

Function Documentation

bt_hci_adv_lookup_handle()

struct bt_le_ext_adv * bt_hci_adv_lookup_handle

(

uint8_t

handle

)

Get advertising set given an advertising handle.

Parameters

handle

The advertising handle

Returns

The corresponding advertising set on success, NULL if it does not exist.

bt_hci_cmd_create()

struct net_buf * bt_hci_cmd_create	(	uint16_t	opcode,
		uint8_t	param_len
	)

Allocate a HCI command buffer.

This function allocates a new buffer for a HCI command. It is given the OpCode (encoded e.g. using the BT_OP macro) and the total length of the parameters. Upon successful return the buffer is ready to have the parameters encoded into it.

Parameters

opcode	Command OpCode.
param_len	Length of command parameters.

Returns

Newly allocated buffer.

bt_hci_cmd_send()

int bt_hci_cmd_send	(	uint16_t	opcode,
		struct net_buf *	buf
	)

Send a HCI command asynchronously.

This function is used for sending a HCI command asynchronously. It can either be called for a buffer created using bt_hci_cmd_create(), or if the command has no parameters a NULL can be passed instead. The sending of the command will happen asynchronously, i.e. upon successful return from this function the caller only knows that it was queued successfully.

If synchronous behavior, and retrieval of the Command Complete parameters is desired, the bt_hci_cmd_send_sync() API should be used instead.

Parameters

opcode	Command OpCode.
buf	Command buffer or NULL (if no parameters).

Returns

0 on success or negative error value on failure.

bt_hci_cmd_send_sync()

int bt_hci_cmd_send_sync	(	uint16_t	opcode,
		struct net_buf *	buf,
		struct net_buf **	rsp
	)

Send a HCI command synchronously.

This function is used for sending a HCI command synchronously. It can either be called for a buffer created using bt_hci_cmd_create(), or if the command has no parameters a NULL can be passed instead.

The function will block until a Command Status or a Command Complete event is returned. If either of these have a non-zero status the function will return a negative error code and the response reference will not be set. If the command completed successfully and a non-NULL rsp parameter was given, this parameter will be set to point to a buffer containing the response parameters.

Parameters

opcode	Command OpCode.
buf	Command buffer or NULL (if no parameters).
rsp	Place to store a reference to the command response. May be NULL if the caller is not interested in the response parameters. If non-NULL is passed the caller is responsible for calling net_buf_unref() on the buffer when done parsing it.

Returns

0 on success or negative error value on failure.

bt_hci_conn_lookup_handle()

struct bt_conn * bt_hci_conn_lookup_handle

(

uint16_t

handle

)

Get connection given a connection handle.

The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.

Parameters

handle

The connection handle

Returns

The corresponding connection object on success. NULL if it does not exist.

bt_hci_err_to_str()

static const char * bt_hci_err_to_str ( uint8_t  hci_err )

inlinestatic

Converts a HCI error to string.

The error codes are described in the Bluetooth Core specification, Vol 1, Part F, Section 2.

The HCI documentation found in Vol 4, Part E, describes when the different error codes are used.

See also the defined BT_HCI_ERR_* macros.

Returns

The string representation of the HCI error code. If CONFIG_BT_HCI_ERR_TO_STR is not enabled, this just returns the empty string

bt_hci_get_adv_handle()

int bt_hci_get_adv_handle	(	const struct bt_le_ext_adv *	adv,
		uint8_t *	adv_handle
	)

Get advertising handle for an advertising set.

Parameters

adv	Advertising set.
adv_handle	Place to store the advertising handle.

Returns

0 on success or negative error value on failure.

bt_hci_get_adv_sync_handle()

int bt_hci_get_adv_sync_handle	(	const struct bt_le_per_adv_sync *	sync,
		uint16_t *	sync_handle
	)

Get periodic advertising sync handle.

Parameters

sync	Periodic advertising sync set.
sync_handle	Place to store the periodic advertising sync handle.

Returns

0 on success or negative error value on failure.

bt_hci_get_conn_handle()

int bt_hci_get_conn_handle	(	const struct bt_conn *	conn,
		uint16_t *	conn_handle
	)

Get connection handle for a connection.

Parameters

conn	Connection object.
conn_handle	Place to store the Connection handle.

Returns

0 on success or negative error value on failure.

bt_hci_get_ver_str()

const char * bt_hci_get_ver_str

(

uint8_t

core_version

)

Obtain the version string given a core version number.

The core version of a controller can be obtained by issuing the HCI Read Local Version Information command.

See also the defines prefixed with BT_HCI_VERSION_.

Parameters

core_version

The core version.

Returns

Version string corresponding to the core version number.

bt_hci_le_rand()

int bt_hci_le_rand	(	void *	buffer,
		size_t	len
	)

Get Random bytes from the LE Controller.

Send the HCI_LE_Rand to the LE Controller as many times as required to fill the provided buffer.

Note

This function is provided as a helper to gather an arbitrary number of random bytes from an LE Controller using the HCI_LE_Rand command.

Parameters

buffer	Buffer to fill with random bytes.
len	Length of the buffer in bytes.

Returns

0 on success or negative error value on failure.

bt_hci_per_adv_sync_lookup_handle()

struct bt_le_per_adv_sync * bt_hci_per_adv_sync_lookup_handle

(

uint16_t

handle

)

Get periodic advertising sync given an periodic advertising sync handle.

Parameters

handle

The periodic sync set handle

Return values

The	corresponding periodic advertising sync set object on success, NULL if it does not exist.

bt_hci_register_vnd_evt_cb()

int bt_hci_register_vnd_evt_cb

(

bt_hci_vnd_evt_cb_t

cb

)

Register user callback for HCI Vendor-Specific Events.

Parameters

cb	Callback to be called when the stack receives a HCI Vendor-Specific Event.

Returns

0 on success or negative error value on failure.