ESP-BLE-ISO

ESP-BLE-ISO provides APIs for Bluetooth LE Isochronous Channels, enabling time-synchronized, connection-oriented (CIS) and connectionless (BIS) streaming. The implementation is built on the Bluetooth controller ISO support and is intended for use with the ESP-BLE-AUDIO component.

Channel types

Connected Isochronous Streams (CIS) — Bidirectional isochronous links between two devices; requires a prior ACL connection to be established. Used for time-synchronized unicast audio (e.g., LE Audio).
Broadcast Isochronous Streams (BIS) — Unidirectional isochronous streams from a Broadcaster to one or more Synchronized Receivers, without a prior connection. Used for broadcast audio and group listening.

With these APIs you can create or join Connected ISO Groups (CIG), create or synchronize to Broadcast ISO Groups (BIG), set up ISO data paths, and send or receive isochronous data (e.g., LC3 audio). For higher-level LE Audio profiles and codec APIs, see ESP-BLE-AUDIO.

警告

This is a preview release. The ESP-BLE-ISO APIs, data structures, and configuration parameters are subject to change in future releases. Breaking changes — such as renamed or restructured types, modified function signatures, or removed fields — may be introduced without prior notice.

Application Examples

BIG (Broadcast Isochronous Group) - bluetooth/esp_ble_iso/big_broadcaster demonstrates how to create a BIG and send isochronous data over BIS. - bluetooth/esp_ble_iso/big_receiver demonstrates how to synchronize to a BIG and receive isochronous data from BIS.
CIS (Connected Isochronous Stream) - bluetooth/esp_ble_iso/cis_central demonstrates how to act as a CIS Central that creates a CIG/CIS and sends isochronous data. - bluetooth/esp_ble_iso/cis_peripheral demonstrates how to act as a CIS Peripheral that accepts a CIS and receives isochronous data.

API Reference

ESP-BLE-ISO APIs are divided into the following parts:

ESP-BLE-ISO Common API

ESP-BLE-ISO Common API

This section contains macros, type definitions, and functions from esp_ble_iso_common_api.h: BIS index and data path macros, controller delay and interval limits, CIG/BIG parameters and structures, ISO server and channel operations, data path setup, BIG create/sync/terminate, and GAP event types and ISO common initialization.

Header File

components/bt/esp_ble_iso/api/include/esp_ble_iso_common_api.h
This header file can be included with:
#include "esp_ble_iso_common_api.h"
This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:
REQUIRES bt
or
PRIV_REQUIRES bt

Functions

esp_err_t esp_ble_iso_data_parse(const uint8_t ltv[], size_t size, bool (*func)(uint8_t type, const uint8_t *data, uint8_t data_len, void *user_data), void *user_data)

Helper for parsing length-type-value data.

参数:

ltv -- Length-type-value (LTV) encoded data.
size -- Size of the ltv data.
func -- Callback function which will be called for each element that's found in the data. The callback should return true to continue parsing, or false to stop parsing.
user_data -- User data to be passed to the callback.

返回:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_server_register(esp_ble_iso_server_t *server)

Register an ISO server.

参数:: server -- Pointer to the ISO server structure.
返回:: ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_server_unregister(esp_ble_iso_server_t *server)

Unregister an ISO server.

参数:: server -- Pointer to the ISO server structure.
返回:: ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_cig_create(esp_ble_iso_cig_param_t *param, esp_ble_iso_cig_t **out_cig)

Create a Connected ISO Group (CIG).

参数:

param -- Parameters for CIG creation.
out_cig -- Pointer to store created CIG.

返回:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_cig_reconfigure(esp_ble_iso_cig_t *cig, esp_ble_iso_cig_param_t *param)

Reconfigure a Connected ISO Group.

参数:

cig -- Pointer to the CIG to reconfigure.
param -- New parameters for the CIG.

返回:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_cig_terminate(esp_ble_iso_cig_t *cig)

Terminate a Connected ISO Group.

参数:: cig -- Pointer to the CIG to terminate.
返回:: ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_chan_connect(esp_ble_iso_connect_param_t *param, uint16_t conn_handle, size_t count)

Connect ISO channels.

参数:

param -- Connection parameters.
conn_handle -- Connection handle.
count -- Number of channels to connect.

返回:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_chan_disconnect(esp_ble_iso_chan_t *chan)

Disconnect an ISO channel.

参数:: chan -- Pointer to the ISO channel.
返回:: ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_setup_data_path(const esp_ble_iso_chan_t *chan, uint8_t dir, const esp_ble_iso_chan_path_t *path)

Set up the ISO data path for an ISO channel.

The channel must be associated with a BIS or CIS handle first which it is when the esp_ble_iso_chan_ops_t.connected() callback is called.

参数:

chan -- The channel to setup the ISO data path for.
dir -- The direction to setup, either ESP_BLE_ISO_DATA_PATH_DIR_INPUT or ESP_BLE_ISO_DATA_PATH_DIR_OUTPUT. For ISO broadcast channels this can only be ESP_BLE_ISO_DATA_PATH_DIR_INPUT, and for ISO sync receiver channels this can only be ESP_BLE_ISO_DATA_PATH_DIR_OUTPUT.
path -- The data path.

返回:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_remove_data_path(const esp_ble_iso_chan_t *chan, uint8_t dir)

Removes the ISO data path for an ISO channel.

Removes the ISO data path configured by esp_ble_iso_setup_data_path() for the provided dir.

The data paths of CIS for Peripherals are deleted by the controller, and thus it is not necessary (or possible) to remove data paths of CIS after they have disconnected for a Peripheral, as per Bluetooth Core specification 6.0, Vol 4, Part E, Section 7.7.5. The data paths for CIS for a Central remain valid, even after a disconnection, and thus a Central device should call bt_iso_remove_data_path() on disconnect if it no longer wants to use that CIS. All data paths created by a Central are removed when the CIG is removed with esp_ble_iso_cig_terminate().

Any data paths associated with an ISO Sync Receiver BIG are removed by the controller when the BIG sync is lost or terminated, and thus it is not necessary (or possible) to remove data paths of ISO channels associated with a BIG for a Sync Receiver, as per Bluetooth Core specification 6.0, Vol 4, Part E, Section 7.7.65.30.

All data paths associated with an ISO Broadcaster BIG are removed when the BIG is terminated by esp_ble_iso_big_terminate(), and thus it is not necessary (or possible) to remove data paths of ISO channels associated with a BIG for a Broadcaster, as per Bluetooth Core specification 6.0, Vol 4, Part E, Section 7.8.105.

参数:

chan -- The channel to setup the ISO data path for.
dir -- The direction to setup, either ESP_BLE_ISO_DATA_PATH_DIR_INPUT or ESP_BLE_ISO_DATA_PATH_DIR_OUTPUT. For ISO broadcast channels this can only be ESP_BLE_ISO_DATA_PATH_DIR_INPUT, and for ISO sync receiver channels this can only be ESP_BLE_ISO_DATA_PATH_DIR_OUTPUT.

返回:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_big_register_cb(esp_ble_iso_big_cb_t *cb)

Registers callbacks for Broadcast Sources.

参数:: cb -- Pointer to the callback structure.
返回:: ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_big_ext_adv_add(esp_ble_iso_ext_adv_info_t *info)

Add extended advertising for BIG.

参数:: info -- Extended advertising information.
返回:: ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_big_ext_adv_delete(esp_ble_iso_ext_adv_info_t *info)

Delete extended advertising for BIG.

参数:: info -- Extended advertising information.
返回:: ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_big_create(uint8_t adv_handle, esp_ble_iso_big_create_param_t *param, esp_ble_iso_big_t **out_big)

Create a Broadcast ISO Group (BIG).

参数:

adv_handle -- Advertising handle.
param -- Parameters for BIG creation.
out_big -- Pointer to store created BIG.

返回:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_big_sync(uint16_t sync_handle, esp_ble_iso_big_sync_param_t *param, esp_ble_iso_big_t **out_big)

Synchronize with a Broadcast ISO Group.

参数:

sync_handle -- Sync handle.
param -- Sync parameters.
out_big -- Pointer to store synchronized BIG.

返回:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_big_terminate(esp_ble_iso_big_t *big)

Terminate a Broadcast ISO Group.

参数:: big -- Pointer to the BIG to terminate.
返回:: ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_chan_get_info(esp_ble_iso_chan_t *chan, esp_ble_iso_info_t *info)

Get ISO channel information.

参数:

chan -- Pointer to the ISO channel.
info -- Pointer to store channel information.

返回:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_chan_get_tx_sync(esp_ble_iso_chan_t *chan, esp_ble_iso_tx_info_t *info)

Get TX sync information for an ISO channel.

参数:

chan -- Pointer to the ISO channel.
info -- Pointer to store TX sync information.

返回:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_chan_send(esp_ble_iso_chan_t *chan, const uint8_t *sdu, uint16_t sdu_len, uint16_t seq_num)

Send data over an ISO channel.

参数:

chan -- Pointer to the ISO channel.
sdu -- Pointer to the SDU data.
sdu_len -- Length of the SDU.
seq_num -- Sequence number.

返回:

ESP_OK on success, or an error code on failure.

esp_err_t esp_ble_iso_chan_send_ts(esp_ble_iso_chan_t *chan, const uint8_t *sdu, uint16_t sdu_len, uint16_t seq_num, uint32_t ts)

Send timestamped data over an ISO channel.

参数:

chan -- Pointer to the ISO channel.
sdu -- Pointer to the SDU data.
sdu_len -- Length of the SDU.
seq_num -- Sequence number.
ts -- Timestamp.

返回:

ESP_OK on success, or an error code on failure. ISO GAP Extended Scan Recv event

void esp_ble_iso_gap_app_post_event(uint8_t type, void *param)

Post an application-layer GAP event for ISO internal usage.

备注

This function is only needed while using NimBLE Host.

参数:

type -- Event type.
param -- Event parameters.

esp_err_t esp_ble_iso_common_init(esp_ble_iso_init_info_t *info)

Initialize ISO common functionality.

参数:: info -- Initialization information.
返回:: ESP_OK on success, or an error code on failure.

Structures

struct esp_ble_iso_ext_adv_info_t

Extended advertising information structure

Public Members

uint8_t adv_handle: Handle for the advertising set

struct esp_ble_iso_init_info_t

ISO initialization information structure

Public Members

bt_le_gap_app_cb gap_cb: GAP event callbacks

Macros

ESP_BLE_ISO_BIS_INDEX_BIT(x)

Convert BIS index to bit

The BIS indexes start from 0x01, so the lowest allowed bit is BIT(0) that represents index 0x01. To synchronize to e.g. BIS indexes 0x01 and 0x02, the bitfield value should be BIT(0) | BIT(1). As a general notation, to sync to BIS index N use BIT(N - 1).

参数:

x -- BIS index (1-based). The minimum value for vendor specific data path ID

ESP_BLE_ISO_DATA_PATH_VS_ID_MIN: The maximum value for vendor specific data path ID

ESP_BLE_ISO_DATA_PATH_VS_ID_MAX: Minimum controller delay in microseconds

ESP_BLE_ISO_CONTROLLER_DELAY_MIN: Maximum controller delay in microseconds

ESP_BLE_ISO_CONTROLLER_DELAY_MAX: Unknown SDU interval

ESP_BLE_ISO_SDU_INTERVAL_UNKNOWN: Minimum interval value in microseconds

ESP_BLE_ISO_SDU_INTERVAL_MIN: Maximum interval value in microseconds

ESP_BLE_ISO_SDU_INTERVAL_MAX: Minimum ISO interval (N * 1.25 ms)

ESP_BLE_ISO_ISO_INTERVAL_MIN: Maximum ISO interval (N * 1.25 ms)

ESP_BLE_ISO_ISO_INTERVAL_MAX: Minimum latency value in milliseconds

ESP_BLE_ISO_LATENCY_MIN: Maximum latency value in milliseconds

ESP_BLE_ISO_LATENCY_MAX: Packets will be sent sequentially between the channels in the group

ESP_BLE_ISO_PACKING_SEQUENTIAL: Packets will be sent interleaved between the channels in the group

ESP_BLE_ISO_PACKING_INTERLEAVED: Packets may be framed or unframed

ESP_BLE_ISO_FRAMING_UNFRAMED: Packets are always framed

ESP_BLE_ISO_FRAMING_FRAMED: Maximum number of isochronous channels in a single group

ESP_BLE_ISO_MAX_GROUP_ISO_COUNT: Minimum SDU size

ESP_BLE_ISO_MIN_SDU: Maximum SDU size

ESP_BLE_ISO_MAX_SDU: Minimum PDU size

ESP_BLE_ISO_CONNECTED_PDU_MIN: Minimum PDU size

ESP_BLE_ISO_BROADCAST_PDU_MIN: Maximum PDU size

ESP_BLE_ISO_PDU_MAX: Minimum burst number

ESP_BLE_ISO_BN_MIN: Maximum burst number

ESP_BLE_ISO_BN_MAX: Minimum flush timeout

ESP_BLE_ISO_FT_MIN: Maximum flush timeout

ESP_BLE_ISO_FT_MAX: Minimum number of subevents

ESP_BLE_ISO_NSE_MIN: Maximum number of subevents

ESP_BLE_ISO_NSE_MAX: Minimum BIG sync timeout value (N * 10 ms)

ESP_BLE_ISO_SYNC_TIMEOUT_MIN: Maximum BIG sync timeout value (N * 10 ms)

ESP_BLE_ISO_SYNC_TIMEOUT_MAX: Controller controlled maximum subevent count value

ESP_BLE_ISO_SYNC_MSE_ANY: Minimum BIG sync maximum subevent count value

ESP_BLE_ISO_SYNC_MSE_MIN: Maximum BIG sync maximum subevent count value

ESP_BLE_ISO_SYNC_MSE_MAX: Minimum connected ISO retransmission value

ESP_BLE_ISO_CONNECTED_RTN_MIN: Maximum connected ISO retransmission value

ESP_BLE_ISO_CONNECTED_RTN_MAX: Minimum broadcast ISO retransmission value

ESP_BLE_ISO_BROADCAST_RTN_MIN: Maximum broadcast ISO retransmission value

ESP_BLE_ISO_BROADCAST_RTN_MAX: Broadcast code size

ESP_BLE_ISO_BROADCAST_CODE_SIZE: Lowest BIS index

ESP_BLE_ISO_BIS_INDEX_MIN: Highest BIS index

ESP_BLE_ISO_BIS_INDEX_MAX: Minimum Immediate Repetition Count

ESP_BLE_ISO_IRC_MIN: Maximum Immediate Repetition Count

ESP_BLE_ISO_IRC_MAX: Minimum pre-transmission offset

ESP_BLE_ISO_PTO_MIN: Maximum pre-transmission offset

ESP_BLE_ISO_PTO_MAX: No subinterval

ESP_BLE_ISO_SUBINTERVAL_NONE: Unknown subinterval

ESP_BLE_ISO_SUBINTERVAL_UNKNOWN: Minimum subinterval in microseconds

ESP_BLE_ISO_SUBINTERVAL_MIN: Maximum subinterval in microseconds

ESP_BLE_ISO_SUBINTERVAL_MAX: Audio Input (Host to Controller) Data Path Direction

ESP_BLE_ISO_DATA_PATH_DIR_INPUT: Audio Output (Controller to Host) Data Path Direction

ESP_BLE_ISO_DATA_PATH_DIR_OUTPUT: Value to set the ISO data path over HCI

ESP_BLE_ISO_DATA_PATH_HCI: Transparent Coding Format

ESP_BLE_ISO_CODING_FORMAT_TRANSPARENT: LC3 Coding Format

ESP_BLE_ISO_CODING_FORMAT_LC3: The ISO packet is valid

ESP_BLE_ISO_FLAGS_VALID: The ISO packet may possibly contain errors

ESP_BLE_ISO_FLAGS_ERROR: The ISO packet was lost

ESP_BLE_ISO_FLAGS_LOST: Timestamp is valid

ESP_BLE_ISO_FLAGS_TS: LE 1M PHY

ESP_BLE_ISO_PHY_1M: LE 2M PHY

ESP_BLE_ISO_PHY_2M: LE Coded PHY, coding scheme not specified

ESP_BLE_ISO_PHY_CODED: Unknown

ESP_BLE_ISO_SCA_UNKNOWN: 251 ppm to 500 ppm

ESP_BLE_ISO_SCA_251_500: 151 ppm to 250 ppm

ESP_BLE_ISO_SCA_151_250: 101 ppm to 150 ppm

ESP_BLE_ISO_SCA_101_150: 76 ppm to 100 ppm

ESP_BLE_ISO_SCA_76_100: 51 ppm to 75 ppm

ESP_BLE_ISO_SCA_51_75: 31 ppm to 50 ppm

ESP_BLE_ISO_SCA_31_50: 21 ppm to 30 ppm

ESP_BLE_ISO_SCA_21_30: 0 ppm to 20 ppm

ESP_BLE_ISO_SCA_0_20: Security Level 1: No encryption and no authentication

ESP_BLE_ISO_SECURITY_NONE: Security Level 2: Encryption and no authentication (no MITM)

ESP_BLE_ISO_SECURITY_NO_MITM: Security Level 3: Encryption and authentication (MITM)

ESP_BLE_ISO_SECURITY_MITM

ESP_BLE_ISO_GAP_EVENT_EXT_SCAN_RECV: ISO GAP Periodic Sync Established event

ESP_BLE_ISO_GAP_EVENT_PA_SYNC: ISO GAP Periodic Sync Transfer Received event

ESP_BLE_ISO_GAP_EVENT_PA_SYNC_PAST: ISO GAP Periodic Sync Lost event

ESP_BLE_ISO_GAP_EVENT_PA_SYNC_LOST: ISO GAP Connection Complete event

ESP_BLE_ISO_GAP_EVENT_ACL_CONNECT: ISO GAP Disconnection Complete event

ESP_BLE_ISO_GAP_EVENT_ACL_DISCONNECT: ISO GAP Security Changed event

ESP_BLE_ISO_GAP_EVENT_SECURITY_CHANGE: ISO GAP BIGInfo Adv Report event

ESP_BLE_ISO_GAP_EVENT_BIGINFO_RECV

Type Definitions

typedef struct bt_conn esp_ble_conn_t: Connection structure.

typedef struct bt_iso_chan esp_ble_iso_chan_t: ISO Channel structure.

typedef struct bt_iso_chan_ops esp_ble_iso_chan_ops_t: ISO Channel operations structure.

typedef struct bt_iso_chan_qos esp_ble_iso_chan_qos_t: ISO Channel QoS structure.

typedef struct bt_iso_chan_io_qos esp_ble_iso_chan_io_qos_t: ISO Channel IO QoS structure.

typedef struct bt_iso_chan_path esp_ble_iso_chan_path_t: ISO Channel Data Path structure.

typedef struct bt_iso_cig esp_ble_iso_cig_t: Connected Isochronous Group (CIG).

typedef struct bt_iso_cig_param esp_ble_iso_cig_param_t: Connected Isochronous Group (CIG) parameters.

typedef struct bt_iso_connect_param esp_ble_iso_connect_param_t: ISO connection parameters structure.

typedef struct bt_iso_accept_info esp_ble_iso_accept_info_t: ISO Accept Info Structure.

typedef struct bt_iso_server esp_ble_iso_server_t: ISO Server structure.

typedef struct bt_iso_unicast_info esp_ble_iso_unicast_info_t: ISO Unicast Info Structure.

typedef struct bt_iso_unicast_tx_info esp_ble_iso_unicast_tx_info_t: ISO Unicast TX Info Structure.

typedef struct bt_iso_big_cb esp_ble_iso_big_cb_t: ISO Broadcast callbacks

typedef struct bt_iso_big esp_ble_iso_big_t: Broadcast Isochronous Group (BIG).

typedef struct bt_iso_big_create_param esp_ble_iso_big_create_param_t: Broadcast Isochronous Group (BIG) creation parameters.

typedef struct bt_iso_big_sync_param esp_ble_iso_big_sync_param_t: Broadcast Isochronous Group (BIG) Sync Parameters.

typedef struct bt_iso_biginfo esp_ble_iso_biginfo_t: Broadcast Isochronous Group (BIG) information.

typedef struct bt_iso_broadcaster_info esp_ble_iso_broadcaster_info_t: ISO Broadcaster Info Structure.

typedef struct bt_iso_sync_receiver_info esp_ble_iso_sync_receiver_info_t: ISO Synchronized Receiver Info Structure.

typedef struct bt_iso_info esp_ble_iso_info_t: ISO channel Info Structure.

typedef struct bt_iso_recv_info esp_ble_iso_recv_info_t: ISO Meta Data structure for received ISO packets.

typedef struct bt_iso_tx_info esp_ble_iso_tx_info_t: ISO Meta Data structure for transmitted ISO packets.

typedef struct bt_iso_tx_cb_info esp_ble_iso_tx_cb_info_t: ISO Unicast & Broadcast TX Callback Info Structure.

typedef struct bt_le_gap_app_event esp_ble_iso_gap_app_event_t: ISO GAP application event structure

此文档对您有帮助吗？

反馈已收到，谢谢！
如果您有其他意见，欢迎填写乐鑫文档反馈表。

我们重视您的反馈。
您可以填写乐鑫文档反馈表告诉我们如何改进该文档。