# 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

此文档对您有帮助吗？

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

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