Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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_bufbt_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
bufBuffer 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
handleThe 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
opcodeCommand OpCode.
param_lenLength 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
opcodeCommand OpCode.
bufCommand 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
opcodeCommand OpCode.
bufCommand buffer or NULL (if no parameters).
rspPlace 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
handleThe 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
advAdvertising set.
adv_handlePlace 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
syncPeriodic advertising sync set.
sync_handlePlace 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
connConnection object.
conn_handlePlace 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_versionThe 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
bufferBuffer to fill with random bytes.
lenLength 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
handleThe periodic sync set handle
Return values
Thecorresponding 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
cbCallback to be called when the stack receives a HCI Vendor-Specific Event.
Returns
0 on success or negative error value on failure.