| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| |
| #ifndef H_BLE_ISO_ |
| #define H_BLE_ISO_ |
| |
| /** |
| * @file ble_iso.h |
| * |
| * @brief Bluetooth ISO |
| * @defgroup bt_iso Bluetooth ISO |
| * @ingroup bt_host |
| * @{ |
| */ |
| |
| #include <inttypes.h> |
| #include "nimble/hci_common.h" |
| #include "syscfg/syscfg.h" |
| |
| /** |
| * @defgroup ble_iso_events ISO Events |
| * @{ |
| */ |
| |
| /** ISO event: BIG Create Completed */ |
| #define BLE_ISO_EVENT_BIG_CREATE_COMPLETE 0 |
| |
| /** ISO event: BIG Terminate Completed */ |
| #define BLE_ISO_EVENT_BIG_TERMINATE_COMPLETE 1 |
| |
| /** ISO event: BIG Sync Established */ |
| #define BLE_ISO_EVENT_BIG_SYNC_ESTABLISHED 2 |
| |
| /** ISO event: BIG Sync Terminated */ |
| #define BLE_ISO_EVENT_BIG_SYNC_TERMINATED 3 |
| |
| /** ISO event: ISO Data received */ |
| #define BLE_ISO_EVENT_ISO_RX 4 |
| |
| /** @} */ |
| |
| /** @brief Broadcast Isochronous Group (BIG) description */ |
| struct ble_iso_big_desc { |
| /** |
| * The identifier of the BIG. Assigned by the Host when a new BIG is |
| * created. |
| */ |
| uint8_t big_handle; |
| |
| /** |
| * The maximum time in microseconds for transmission of PDUs of all BISes in |
| * a BIG event. |
| */ |
| uint32_t big_sync_delay; |
| |
| /** |
| * The actual transport latency of transmitting payloads of all BISes in the |
| * BIG in microseconds. |
| */ |
| uint32_t transport_latency_big; |
| |
| /** The number of subevents per BIS in each BIG event. */ |
| uint8_t nse; |
| |
| /** |
| * The Burst Number (BN) specifies the number of new payloads in each BIS |
| * event. |
| */ |
| uint8_t bn; |
| |
| /** |
| * The Pre-Transmission Offset (PTO) specifies the offset of groups that |
| * carry data associated with the future BIS events. |
| */ |
| uint8_t pto; |
| |
| /** |
| * The Immediate Repetition Count (IRC) specifies the number of groups that |
| * carry the data associated with the current BIS event. |
| */ |
| uint8_t irc; |
| |
| /** |
| * The maximum number of data octets (excluding the MIC, if any) that can be |
| * carried in each BIS Data PDU in the BIG. |
| */ |
| uint16_t max_pdu; |
| |
| /** The time between two adjacent BIG anchor points in units of 1.25 ms. */ |
| uint16_t iso_interval; |
| |
| /** The total number of BISes in the BIG. */ |
| uint8_t num_bis; |
| |
| /** The connection handles of all the BIS in the BIG. */ |
| uint16_t conn_handle[MYNEWT_VAL(BLE_ISO_MAX_BISES)]; |
| }; |
| |
| /** @brief Received ISO Data status possible values */ |
| enum ble_iso_rx_data_status { |
| /** The complete SDU was received correctly. */ |
| BLE_ISO_DATA_STATUS_VALID = BLE_HCI_ISO_PKT_STATUS_VALID, |
| |
| /** May contain errors or part of the SDU may be missing. */ |
| BLE_ISO_DATA_STATUS_ERROR = BLE_HCI_ISO_PKT_STATUS_INVALID, |
| |
| /** Part(s) of the SDU were not received correctly */ |
| BLE_ISO_DATA_STATUS_LOST = BLE_HCI_ISO_PKT_STATUS_LOST, |
| }; |
| |
| /** @brief Received ISO data info structure */ |
| struct ble_iso_rx_data_info { |
| /** ISO Data timestamp. Valid if @ref ble_iso_rx_data_info.ts_valid is set */ |
| uint32_t ts; |
| |
| /** Packet sequence number */ |
| uint16_t seq_num; |
| |
| /** SDU length */ |
| uint16_t sdu_len : 12; |
| |
| /** ISO Data status. See @ref ble_iso_rx_data_status */ |
| uint16_t status : 2; |
| |
| /** Timestamp is valid */ |
| uint16_t ts_valid : 1; |
| }; |
| |
| /** |
| * Represents a ISO-related event. When such an event occurs, the host |
| * notifies the application by passing an instance of this structure to an |
| * application-specified callback. |
| */ |
| struct ble_iso_event { |
| /** |
| * Indicates the type of ISO event that occurred. This is one of the |
| * BLE_ISO_EVENT codes. |
| */ |
| uint8_t type; |
| |
| /** |
| * A discriminated union containing additional details concerning the ISO |
| * event. The 'type' field indicates which member of the union is valid. |
| */ |
| union { |
| /** |
| * Represents a completion of BIG creation. Valid for the following |
| * event types: |
| * o BLE_ISO_EVENT_BIG_CREATE_COMPLETE |
| */ |
| struct { |
| struct ble_iso_big_desc desc; |
| uint8_t status; |
| uint8_t phy; |
| } big_created; |
| |
| /** |
| * Represents a completion of BIG termination. Valid for the following |
| * event types: |
| * o BLE_ISO_EVENT_BIG_TERMINATE_COMPLETE |
| * o BLE_ISO_EVENT_BIG_SYNC_TERMINATED |
| */ |
| struct { |
| uint16_t big_handle; |
| uint8_t reason; |
| } big_terminated; |
| |
| /** |
| * Represents a completion of BIG synchronization. Valid for the following |
| * event types: |
| * o BLE_ISO_EVENT_BIG_SYNC_ESTABLISHED |
| */ |
| struct { |
| struct ble_iso_big_desc desc; |
| uint8_t status; |
| } big_sync_established; |
| |
| /** |
| * Represents a reception of ISO Data. Valid for the following |
| * event types: |
| * o BLE_ISO_EVENT_ISO_RX |
| */ |
| struct { |
| uint16_t conn_handle; |
| const struct ble_iso_rx_data_info *info; |
| struct os_mbuf *om; |
| } iso_rx; |
| }; |
| }; |
| |
| /** Function prototype for isochronous event callback. */ |
| typedef int ble_iso_event_fn(struct ble_iso_event *event, void *arg); |
| |
| /** Broadcast Isochronous Group (BIG) parameters */ |
| struct ble_iso_big_params { |
| /** |
| * The time interval of the periodic SDUs in microseconds. The value shall |
| * be between 0x0000FF and 0x0FFFFF. |
| */ |
| uint32_t sdu_interval; |
| |
| /** |
| * The maximum size of an SDU in octets. The value shall be between 0x0001 |
| * and 0x0FFF. |
| */ |
| uint16_t max_sdu; |
| |
| /** |
| * The maximum transport latency in milliseconds. The value shall be between |
| * 0x0005 and 0x0FA0. |
| */ |
| uint16_t max_transport_latency; |
| |
| /** |
| * The Retransmission Number (RTN) parameter contains the number of times |
| * every PDU should be retransmitted, irrespective of which BIG events the |
| * retransmissions occur in. The value shall be between 0x00 and 0x1E. |
| */ |
| uint8_t rtn; |
| |
| /** |
| * The PHY parameter is a bit field that indicates the PHY used for |
| * transmission of PDUs of BISes in the BIG. The value shall be one of the |
| * following: |
| * o BLE_HCI_LE_PHY_1M_PREF_MASK |
| * o BLE_HCI_LE_PHY_2M_PREF_MASK |
| * o BLE_HCI_LE_PHY_CODED_PREF_MASK |
| */ |
| uint8_t phy; |
| |
| /** |
| * Indicates the preferred method of arranging subevents of multiple BISes. |
| * The value shall be one of the following: |
| * o 0x00 - Sequential |
| * o 0x01 - Interleaved |
| */ |
| uint8_t packing; |
| |
| /** |
| * Indicates whether the BIG carries framed or unframed data. The value |
| * shall be one of the following: |
| * o 0x00 - Unframed |
| * o 0x01 - Framed |
| */ |
| uint8_t framing; |
| |
| /** |
| * Indicates whether the BIG is encrypted or not. The value shall be one of |
| * the following: |
| * o 0x00 - Unencrypted |
| * o 0x01 - Encrypted |
| */ |
| uint8_t encryption; |
| |
| /** |
| * The 128-bit code used to derive the session key that is used to encrypt |
| * and decrypt BIS payloads. |
| */ |
| const char *broadcast_code; |
| }; |
| |
| /** Create BIG parameters */ |
| struct ble_iso_create_big_params { |
| /** The associated periodic advertising train of the BIG. */ |
| uint8_t adv_handle; |
| |
| /** The total number of BISes in the BIG. */ |
| uint8_t bis_cnt; |
| |
| /** Callback function for reporting the status of the procedure. */ |
| ble_iso_event_fn *cb; |
| |
| /** |
| * An optional user-defined argument to be passed to the callback function. |
| */ |
| void *cb_arg; |
| }; |
| |
| /** |
| * Initiates the creation of Broadcast Isochronous Group (BIG). It configures |
| * the BIG parameters based on the provided input and triggers the corresponding |
| * HCI command. |
| * |
| * @param create_params A pointer to the structure holding the |
| * parameters specific to creating the BIG. |
| * These parameters define the general settings |
| * and include a callback function for handling |
| * creation events. |
| * @param big_params A pointer to the structure holding detailed |
| * parameters specific to the configuration of |
| * the BIG. These parameters include settings |
| * such as SDU interval, maximum SDU size, |
| * transport latency, etc. |
| * |
| * @return 0 on success; |
| * an error code on failure. |
| * |
| * @note The actual BIG creation result will be reported through the callback |
| * function specified in @p create_params. |
| */ |
| int ble_iso_create_big(const struct ble_iso_create_big_params *create_params, |
| const struct ble_iso_big_params *big_params); |
| |
| /** |
| * Terminates an existing Broadcast Isochronous Group (BIG). |
| * |
| * @param big_handle The identifier of the BIG to be terminated. |
| * |
| * @return 0 on success; |
| * an error code on failure. |
| */ |
| int ble_iso_terminate_big(uint8_t big_handle); |
| |
| /** @brief BIS parameters for @ref ble_iso_big_sync_create */ |
| struct ble_iso_bis_params { |
| /** BIS index */ |
| uint8_t bis_index; |
| |
| /** The callback to associate with the BIS. |
| * Received ISO data is reported through this callback. |
| */ |
| ble_iso_event_fn *cb; |
| |
| /** The optional argument to pass to the callback function */ |
| void *cb_arg; |
| }; |
| |
| /** @brief BIG Sync parameters for @ref ble_iso_big_sync_create */ |
| struct ble_iso_big_sync_create_params { |
| /** Periodic advertising train sync handle */ |
| uint16_t sync_handle; |
| |
| /** Null-terminated broadcast code for encrypted BIG or |
| * NULL if the BIG is unencrypted |
| */ |
| const char *broadcast_code; |
| |
| /** Maximum Subevents to be used to receive data payloads in each BIS event */ |
| uint8_t mse; |
| |
| /** The maximum permitted time between successful receptions of BIS PDUs */ |
| uint16_t sync_timeout; |
| |
| /** The callback to associate with this sync procedure. |
| * Sync establishment and termination are reported through this callback. |
| */ |
| ble_iso_event_fn *cb; |
| |
| /** The optional argument to pass to the callback function */ |
| void *cb_arg; |
| |
| /** Number of a BISes */ |
| uint8_t bis_cnt; |
| |
| /** BIS parameters */ |
| struct ble_iso_bis_params *bis_params; |
| }; |
| |
| /** |
| * @brief Synchronize to Broadcast Isochronous Group (BIG) |
| * |
| * This function is used to synchronize to a BIG described in the periodic |
| * advertising train specified by the @p param->pa_sync_handle parameter. |
| * |
| * @param[in] params BIG synchronization parameters |
| * @param[out] big_handle BIG instance handle |
| * |
| * @return 0 on success; |
| * A non-zero value on failure. |
| */ |
| int ble_iso_big_sync_create(const struct ble_iso_big_sync_create_params *params, |
| uint8_t *big_handle); |
| |
| /** |
| * @brief Terminate Broadcast Isochronous Group (BIG) sync |
| * |
| * This function is used to stop synchronizing or cancel the process of |
| * synchronizing to the BIG identified by the @p big_handle parameter. |
| * The command also terminates the reception of BISes in the BIG. |
| * |
| * @param[in] big_handle BIG handle |
| * |
| * @return 0 on success; |
| * A non-zero value on failure. |
| */ |
| int ble_iso_big_sync_terminate(uint8_t big_handle); |
| |
| /** @brief ISO Data direction */ |
| enum ble_iso_data_dir { |
| BLE_ISO_DATA_DIR_TX, |
| BLE_ISO_DATA_DIR_RX, |
| }; |
| |
| /** @brief ISO Codec ID */ |
| struct ble_iso_codec_id { |
| /** Coding Format */ |
| uint8_t format; |
| |
| /** Company ID */ |
| uint16_t company_id; |
| |
| /** Vendor Specific Codec ID */ |
| uint16_t vendor_specific; |
| }; |
| |
| /** @brief Setup ISO Data Path parameters */ |
| struct ble_iso_data_path_setup_params { |
| /** Connection handle of the CIS or BIS */ |
| uint16_t conn_handle; |
| |
| /** Data path direction */ |
| enum ble_iso_data_dir data_path_dir; |
| |
| /** Data path ID. 0x00 for HCI */ |
| uint8_t data_path_id; |
| |
| /** Controller delay */ |
| uint32_t ctrl_delay; |
| |
| /** Codec ID */ |
| struct ble_iso_codec_id codec_id; |
| |
| /** Codec Configuration Length */ |
| uint8_t codec_config_len; |
| |
| /** Codec Configuration */ |
| const uint8_t *codec_config; |
| }; |
| |
| /** |
| * @brief Setup ISO Data Path |
| * |
| * This function is used to identify and create the isochronous data path |
| * between the Host and the Controller for a CIS, CIS configuration, or BIS |
| * identified by the @p param->conn_handle parameter. |
| * |
| * @param[in] param BIG synchronization parameters |
| * |
| * @return 0 on success; |
| * A non-zero value on failure. |
| */ |
| int ble_iso_data_path_setup(const struct ble_iso_data_path_setup_params *param); |
| |
| /** @brief @brief Remove ISO Data Path parameters */ |
| struct ble_iso_data_path_remove_params { |
| /** Connection handle of the CIS or BIS */ |
| uint16_t conn_handle; |
| |
| /** Data path direction */ |
| enum ble_iso_data_dir data_path_dir; |
| }; |
| |
| /** |
| * @brief Remove ISO Data Path |
| * |
| * This function is used to remove the input and/or output data path(s) |
| * associated with a CIS, CIS configuration, or BIS identified by the |
| * @p param->conn_handle parameter. |
| * |
| * @param[in] param BIG synchronization parameters |
| * |
| * @return 0 on success; |
| * A non-zero value on failure. |
| */ |
| int ble_iso_data_path_remove(const struct ble_iso_data_path_remove_params *param); |
| |
| /** |
| * Initiates the transmission of isochronous data. |
| * |
| * @param conn_handle The connection over which to execute the procedure. |
| * @param data A pointer to the data to be transmitted. |
| * @param data_len Number of the data octets to be transmitted. |
| * |
| * @return 0 on success; |
| * an error code on failure. |
| */ |
| int ble_iso_tx(uint16_t conn_handle, void *data, uint16_t data_len); |
| |
| /** |
| * Initializes memory for ISO. |
| * |
| * @return 0 on success |
| */ |
| int ble_iso_init(void); |
| |
| /** |
| * @} |
| */ |
| |
| #endif /* H_BLE_ISO_ */ |
