BLE HCI Components

[中文]

The BLE HCI component is used to directly operate the BLE Controller via the VHCI interface to achieve functionalities like broadcasting and scanning. Compared to initiating broadcasting and scanning through the Nimble or Bluedroid protocol stacks, using this component offers the following advantages:

  • Lower memory usage

  • Smaller firmware size

  • Faster initialization process

How to Use BLE HCI

For Broadcasting Applications: 1.Initialize BLE HCI: Use ble_hci_init() function to initialize. 2.Set Local Random Address (Optional): If you need to use a random address for broadcasting, set it using the ble_hci_set_random_address() function. 3.Configure Broadcast Parameters: Use ble_hci_set_adv_param() function to configure broadcast parameters. 4.Set Broadcast Data: Use ble_hci_set_adv_data() function to specify the data to be broadcast. 5.Start Broadcasting: Use ble_hci_set_adv_enable() function.

For Scanning Applications: 1.Initialize BLE HCI: Use ble_hci_init() function to initialize. 2.Configure Scanning Parameters: Use ble_hci_set_scan_param() function to configure scanning parameters. 3.Enable Meta Event: Use ble_hci_enable_meta_event() function to enable interrupt events. 4.Register Scanning Event Function: Use ble_hci_set_register_scan_callback() function to register the interrupt event. 5.Start Scanning: Use the ble_hci_set_scan_enable() function.

API Reference

Header File

Functions

esp_err_t ble_hci_init(void)

BLE HCI initialization.

Returns

esp_err_t

  • ESP_OK: succeed

  • others: fail

esp_err_t ble_hci_deinit(void)

BLE HCI de-initialization.

Returns

esp_err_t

  • ESP_OK: succeed

  • others: fail

esp_err_t ble_hci_reset(void)

BLE HCI reset controller.

Returns

esp_err_t

  • ESP_OK: succeed

  • others: fail

esp_err_t ble_hci_enable_meta_event(void)

Enable BLE HCI meta event.

Returns

esp_err_t

esp_err_t ble_hci_set_adv_param(ble_hci_adv_param_t *param)

Set BLE HCI advertising parameters.

Parameters

param – : advertising parameters

Returns

esp_err_t

  • ESP_OK: succeed

  • others: fail

esp_err_t ble_hci_set_adv_data(uint8_t len, uint8_t *data)

Set BLE HCI advertising data.

Parameters

  • len – : advertising data length

  • data – : advertising data

Returns

esp_err_t

  • ESP_OK: succeed

  • others: fail

esp_err_t ble_hci_set_adv_enable(bool enable)

Set BLE HCI advertising enable.

Parameters

enable – : true for enable advertising

Returns

esp_err_t

  • ESP_OK: succeed

  • others: fail

esp_err_t ble_hci_set_scan_param(ble_hci_scan_param_t *param)

Set BLE HCI scan parameters.

Parameters

param – : scan parameters

Returns

esp_err_t

  • ESP_OK: succeed

  • others: fail

esp_err_t ble_hci_set_scan_enable(bool enable, bool filter_duplicates)

Set BLE HCI scan enable.

Parameters

  • enable – : enable or disable scan

  • filter_duplicates – : filter duplicates or not

Returns

esp_err_t

  • ESP_OK: succeed

  • others: fail

esp_err_t ble_hci_set_register_scan_callback(ble_hci_scan_cb_t cb)

Set BLE HCI scan callback.

Parameters

cb – : scan callback function pointer

Returns

esp_err_t

  • ESP_OK: succeed

  • others: fail

esp_err_t ble_hci_add_to_accept_list(ble_hci_addr_t addr, ble_hci_addr_type_t addr_type)

Add BLE white list.

Parameters

  • addr – : address to be added to white list

  • addr_type – : address type to be added to white list

Returns

esp_err_t

  • ESP_OK: succeed

  • others: fail

esp_err_t ble_hci_clear_accept_list(void)

Clear BLE white list.

Returns

esp_err_t

  • ESP_OK: succeed

  • others: fail

esp_err_t ble_hci_set_random_address(ble_hci_addr_t addr)

Set BLE owner address.

Parameters

addr – : owner address

Returns

  • ESP_OK: succeed

  • others: fail

Structures

struct ble_hci_scan_result_t

BLE scan result struct.

Public Members

ble_hci_search_evt_t search_evt

Search event type

ble_hci_dev_type_t dev_type

Device type

ble_hci_addr_t bda

Bluetooth device address which has been searched

ble_hci_addr_type_t ble_addr_type

Ble device address type

uint8_t ble_adv[ESP_BLE_ADV_DATA_LEN_MAX + ESP_BLE_SCAN_RSP_DATA_LEN_MAX]

Received EIR

uint8_t adv_data_len

Adv data length

uint8_t scan_rsp_len

Scan response length

int rssi

Searched device’s RSSI

struct ble_hci_adv_param_t

Ble adv parameters.

Public Members

uint16_t adv_int_min

Time = N × 0.625 ms Range: 0x0020 to 0x4000

uint16_t adv_int_max

Time = N × 0.625 ms Range: 0x0020 to 0x4000

ble_hci_adv_type_t adv_type

Advertising Type

ble_hci_addr_type_t own_addr_type

Own Address Type

ble_hci_addr_t peer_addr

Peer device bluetooth device address

ble_hci_addr_type_t peer_addr_type

Peer device bluetooth device address type, only support public address type and random address type

ble_hci_adv_channel_t channel_map

Advertising channel map

ble_hci_adv_filter_t adv_filter_policy

Advertising Filter Policy:

struct ble_hci_scan_param_t

Ble sccan parameters.

Public Members

ble_hci_scan_type_t scan_type

Scan Type

uint16_t scan_interval

Time = N × 0.625 ms Range: 0x0004 to 0x4000

uint16_t scan_window

Time = N × 0.625 ms Range: 0x0004 to 0x4000

ble_hci_addr_type_t own_addr_type

Own Address Type

ble_hci_adv_filter_t filter_policy

Scanning Filter Policy

Macros

ESP_BLE_ADV_DATA_LEN_MAX

Advertising data maximum length.

ESP_BLE_SCAN_RSP_DATA_LEN_MAX

Scan response data maximum length.

BLE_HCI_ADDR_LEN

BLE Address Length.

Type Definitions

typedef uint8_t ble_hci_addr_t[BLE_HCI_ADDR_LEN]

Bluetooth device address.

typedef void (*ble_hci_scan_cb_t)(ble_hci_scan_result_t *scan_result, uint16_t result_len)

BLE HCI scan callback function type.

Param scan_result

: ble advertisement scan result

Param result_len

: length of scan result

Enumerations

enum ble_hci_search_evt_t

Sub Event of BLE_HCI_BLE_SCAN_RESULT_EVT.

Values:

enumerator BLE_HCI_SEARCH_INQ_RES_EVT

Inquiry result for a peer device.

enumerator BLE_HCI_SEARCH_INQ_CMPL_EVT

Inquiry complete.

enumerator BLE_HCI_SEARCH_DISC_RES_EVT

Discovery result for a peer device.

enumerator BLE_HCI_SEARCH_DISC_BLE_RES_EVT

Discovery result for BLE GATT based service on a peer device.

enumerator BLE_HCI_SEARCH_DISC_CMPL_EVT

Discovery complete.

enumerator BLE_HCI_SEARCH_DI_DISC_CMPL_EVT

Discovery complete.

enumerator BLE_HCI_SEARCH_SEARCH_CANCEL_CMPL_EVT

Search cancelled

enumerator BLE_HCI_SEARCH_INQ_DISCARD_NUM_EVT

The number of pkt discarded by flow control

enum ble_hci_addr_type_t

BLE address type.

Values:

enumerator BLE_ADDR_TYPE_PUBLIC

Public Device Address

enumerator BLE_ADDR_TYPE_RANDOM

Random Device Address.

enumerator BLE_ADDR_TYPE_RPA_PUBLIC

Resolvable Private Address (RPA) with public identity address

enumerator BLE_ADDR_TYPE_RPA_RANDOM

Resolvable Private Address (RPA) with random identity address.

enum ble_hci_dev_type_t

Bluetooth device type.

Values:

enumerator BLE_HCI_DEVICE_TYPE_BREDR
enumerator BLE_HCI_DEVICE_TYPE_BLE
enumerator BLE_HCI_DEVICE_TYPE_DUMO
enum ble_hci_adv_type_t

BLE advertising type.

Values:

enumerator ADV_TYPE_IND
enumerator ADV_TYPE_DIRECT_IND_HIGH
enumerator ADV_TYPE_SCAN_IND
enumerator ADV_TYPE_NONCONN_IND
enumerator ADV_TYPE_DIRECT_IND_LOW
enum ble_hci_adv_channel_t

Advertising channel mask.

Values:

enumerator ADV_CHNL_37
enumerator ADV_CHNL_38
enumerator ADV_CHNL_39
enumerator ADV_CHNL_ALL
enum ble_hci_scan_type_t

Ble scan type.

Values:

enumerator BLE_SCAN_TYPE_PASSIVE

Passive scan

enumerator BLE_SCAN_TYPE_ACTIVE

Active scan

enum ble_hci_adv_filter_t

Ble adv filteer type.

Values:

enumerator ADV_FILTER_ALLOW_SCAN_ANY_CON_ANY

Allow both scan and connection requests from anyone.

enumerator ADV_FILTER_ALLOW_SCAN_WLST_CON_ANY

Allow both scan req from White List devices only and connection req from anyone.

enumerator ADV_FILTER_ALLOW_SCAN_ANY_CON_WLST

Allow both scan req from anyone and connection req from White List devices only.

enumerator ADV_FILTER_ALLOW_SCAN_WLST_CON_WLST

Allow scan and connection requests from White List devices only.

Provide feedback about this document