This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

HCI Drivers

API Reference

group bt_hci_driver

HCI drivers.

Defines

IS_BT_QUIRK_NO_AUTO_DLE(bt_dev)

Enums

enum [anonymous]

Values:

enumerator BT_QUIRK_NO_RESET = BIT(0)
enumerator BT_QUIRK_NO_AUTO_DLE = BIT(1)
enum bt_hci_driver_bus

Possible values for the ‘bus’ member of the bt_hci_driver struct.

Values:

enumerator BT_HCI_DRIVER_BUS_VIRTUAL = 0
enumerator BT_HCI_DRIVER_BUS_USB = 1
enumerator BT_HCI_DRIVER_BUS_PCCARD = 2
enumerator BT_HCI_DRIVER_BUS_UART = 3
enumerator BT_HCI_DRIVER_BUS_RS232 = 4
enumerator BT_HCI_DRIVER_BUS_PCI = 5
enumerator BT_HCI_DRIVER_BUS_SDIO = 6
enumerator BT_HCI_DRIVER_BUS_SPI = 7
enumerator BT_HCI_DRIVER_BUS_I2C = 8
enumerator BT_HCI_DRIVER_BUS_IPM = 9

Functions

int bt_recv(struct net_buf *buf)

Receive data from the controller/HCI driver.

This is the main function through which the HCI driver provides the host with data from the controller. The buffer needs to have its type set with the help of bt_buf_set_type() before calling this API.

Parameters:

  • buf – Network buffer containing data from the controller.

Returns:

0 on success or negative error number on failure.

uint8_t bt_read_static_addr(struct bt_hci_vs_static_addr addrs[], uint8_t size)

Read static addresses from the controller.

Parameters:

  • addrs – Random static address and Identity Root (IR) array.

  • size – Size of array.

Returns:

Number of addresses read.

int bt_hci_driver_register(const struct bt_hci_driver *drv)

Register a new HCI driver to the Bluetooth stack.

This needs to be called before any application code runs. The bt_enable() API will fail if there is no driver registered.

Parameters:
Returns:

0 on success or negative error number on failure.

int bt_hci_transport_setup(const struct device *dev)

Setup the HCI transport, which usually means to reset the Bluetooth IC.

Note

A weak version of this function is included in the H4 driver, so defining it is optional per board.

Parameters:

  • dev – The device structure for the bus connecting to the IC

Returns:

0 on success, negative error value on failure

int bt_hci_transport_teardown(const struct device *dev)

Teardown the HCI transport.

Note

A weak version of this function is included in the IPC driver, so defining it is optional. NRF5340 includes support to put network core in reset state.

Parameters:

  • dev – The device structure for the bus connecting to the IC

Returns:

0 on success, negative error value on faulure

struct net_buf *bt_hci_evt_create(uint8_t evt, uint8_t len)

Allocate an HCI event buffer.

This function allocates a new buffer for an HCI event. It is given the event code and the total length of the parameters. Upon successful return the buffer is ready to have the parameters encoded into it.

Parameters:

  • evt – Event OpCode.

  • len – Length of event parameters.

Returns:

Newly allocated buffer.

struct net_buf *bt_hci_cmd_complete_create(uint16_t op, uint8_t plen)

Allocate an HCI Command Complete event buffer.

This function allocates a new buffer for HCI Command Complete event. 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:

  • op – Command OpCode.

  • plen – Length of command parameters.

Returns:

Newly allocated buffer.

struct net_buf *bt_hci_cmd_status_create(uint16_t op, uint8_t status)

Allocate an HCI Command Status event buffer.

This function allocates a new buffer for HCI Command Status event. It is given the OpCode (encoded e.g. using the BT_OP macro) and the status code. Upon successful return the buffer is ready to have the parameters encoded into it.

Parameters:

  • op – Command OpCode.

  • status – Status code.

Returns:

Newly allocated buffer.

struct bt_hci_setup_params
#include <hci_driver.h>

Public Members

bt_addr_t public_addr

The public identity address to give to the controller.

This field is used when the driver selects CONFIG_BT_HCI_SET_PUBLIC_ADDR to indicate that it supports setting the controller’s public address.

struct bt_hci_driver
#include <hci_driver.h>

Abstraction which represents the HCI transport to the controller.

This struct is used to represent the HCI transport to the Bluetooth controller.

Public Members

const char *name

Name of the driver.

enum bt_hci_driver_bus bus

Bus of the transport (BT_HCI_DRIVER_BUS_*)

uint32_t quirks

Specific controller quirks.

These are set by the HCI driver and acted upon by the host. They can either be statically set at buildtime, or set at runtime before the HCI driver’s open() callback returns.

int (*open)(void)

Open the HCI transport.

Opens the HCI transport for operation. This function must not return until the transport is ready for operation, meaning it is safe to start calling the send() handler.

Return:

0 on success or negative error number on failure.

int (*close)(void)

Close the HCI transport.

Closes the HCI transport. This function must not return until the transport is closed.

Return:

0 on success or negative error number on failure.

int (*send)(struct net_buf *buf)

Send HCI buffer to controller.

Send an HCI command or ACL data to the controller. The exact type of the data can be checked with the help of bt_buf_get_type().

Note

This function must only be called from a cooperative thread.

Param buf:

Buffer containing data to be sent to the controller.

Return:

0 on success or negative error number on failure.

int (*setup)(const struct bt_hci_setup_params *params)

HCI vendor-specific setup.

Executes vendor-specific commands sequence to initialize BT Controller before BT Host executes Reset sequence.

Note

CONFIG_BT_HCI_SETUP must be selected for this field to be available.

Return:

0 on success or negative error number on failure.