1 /** 2 * @file 3 * @brief Header for Bluetooth BAP. 4 * 5 * Copyright (c) 2020 Bose Corporation 6 * Copyright (c) 2021-2024 Nordic Semiconductor ASA 7 * 8 * SPDX-License-Identifier: Apache-2.0 9 */ 10 11 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_BAP_ 12 #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_BAP_ 13 14 /** 15 * @brief Bluetooth Basic Audio Profile (BAP) 16 * @defgroup bt_bap Bluetooth Basic Audio Profile 17 * 18 * @since 3.0 19 * @version 0.8.0 20 * 21 * @ingroup bluetooth 22 * @{ 23 * 24 * The Basic Audio Profile (BAP) allows for both unicast and broadcast Audio Stream control. 25 */ 26 27 #include <stdbool.h> 28 #include <stddef.h> 29 #include <stdint.h> 30 31 #include <zephyr/bluetooth/audio/audio.h> 32 #include <zephyr/bluetooth/addr.h> 33 #include <zephyr/bluetooth/bluetooth.h> 34 #include <zephyr/bluetooth/conn.h> 35 #include <zephyr/bluetooth/iso.h> 36 #include <zephyr/net_buf.h> 37 #include <zephyr/sys/slist.h> 38 #include <zephyr/sys/util_macro.h> 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 #if defined(CONFIG_BT_BAP_BASS_MAX_SUBGROUPS) 45 #define BT_BAP_BASS_MAX_SUBGROUPS CONFIG_BT_BAP_BASS_MAX_SUBGROUPS 46 #else 47 #define BT_BAP_BASS_MAX_SUBGROUPS 0 48 #endif /* CONFIG_BT_BAP_BASS_MAX_SUBGROUPS*/ 49 50 /** An invalid Broadcast ID */ 51 #define BT_BAP_INVALID_BROADCAST_ID 0xFFFFFFFFU 52 53 /** 54 * @brief Check if a BAP BASS BIS_Sync bitfield is valid 55 * 56 * Valid options are eiter a bitmask of valid BIS indices, including none (0x00000000) 57 * or @ref BT_BAP_BIS_SYNC_NO_PREF (0xFFFFFFFF). 58 * 59 * @param _bis_bitfield BIS_Sync bitfield (uint32) 60 */ 61 #define BT_BAP_BASS_VALID_BIT_BITFIELD(_bis_bitfield) \ 62 ((_bis_bitfield) == 0U || (_bis_bitfield) == BT_BAP_BIS_SYNC_NO_PREF || \ 63 BT_ISO_VALID_BIS_BITFIELD(_bis_bitfield)) 64 65 /** 66 * @brief Helper to declare elements of bt_bap_qos_cfg 67 * 68 * @param _interval SDU interval (usec) 69 * @param _framing Framing 70 * @param _phy Target PHY 71 * @param _sdu Maximum SDU Size 72 * @param _rtn Retransmission number 73 * @param _latency Maximum Transport Latency (msec) 74 * @param _pd Presentation Delay (usec) 75 */ 76 #define BT_BAP_QOS_CFG(_interval, _framing, _phy, _sdu, _rtn, _latency, _pd) \ 77 ((struct bt_bap_qos_cfg){ \ 78 .interval = _interval, \ 79 .framing = _framing, \ 80 .phy = _phy, \ 81 .sdu = _sdu, \ 82 .rtn = _rtn, \ 83 IF_ENABLED(UTIL_OR(IS_ENABLED(CONFIG_BT_BAP_BROADCAST_SOURCE), \ 84 IS_ENABLED(CONFIG_BT_BAP_UNICAST)), \ 85 (.latency = _latency,)) \ 86 .pd = _pd, \ 87 }) 88 89 /** @brief QoS Framing */ 90 enum bt_bap_qos_cfg_framing { 91 /** Packets may be framed or unframed */ 92 BT_BAP_QOS_CFG_FRAMING_UNFRAMED = 0x00, 93 /** Packets are always framed */ 94 BT_BAP_QOS_CFG_FRAMING_FRAMED = 0x01, 95 }; 96 97 /** @brief QoS Preferred PHY */ 98 enum { 99 /** LE 1M PHY */ 100 BT_BAP_QOS_CFG_1M = BIT(0), 101 /** LE 2M PHY */ 102 BT_BAP_QOS_CFG_2M = BIT(1), 103 /** LE Coded PHY */ 104 BT_BAP_QOS_CFG_CODED = BIT(2), 105 }; 106 107 /** 108 * @brief Helper to declare Input Unframed bt_bap_qos_cfg 109 * 110 * @param _interval SDU interval (usec) 111 * @param _sdu Maximum SDU Size 112 * @param _rtn Retransmission number 113 * @param _latency Maximum Transport Latency (msec) 114 * @param _pd Presentation Delay (usec) 115 */ 116 #define BT_BAP_QOS_CFG_UNFRAMED(_interval, _sdu, _rtn, _latency, _pd) \ 117 BT_BAP_QOS_CFG(_interval, BT_BAP_QOS_CFG_FRAMING_UNFRAMED, BT_BAP_QOS_CFG_2M, _sdu, _rtn, \ 118 _latency, _pd) 119 120 /** 121 * @brief Helper to declare Input Framed bt_bap_qos_cfg 122 * 123 * @param _interval SDU interval (usec) 124 * @param _sdu Maximum SDU Size 125 * @param _rtn Retransmission number 126 * @param _latency Maximum Transport Latency (msec) 127 * @param _pd Presentation Delay (usec) 128 */ 129 #define BT_BAP_QOS_CFG_FRAMED(_interval, _sdu, _rtn, _latency, _pd) \ 130 BT_BAP_QOS_CFG(_interval, BT_BAP_QOS_CFG_FRAMING_FRAMED, BT_BAP_QOS_CFG_2M, _sdu, _rtn, \ 131 _latency, _pd) 132 133 /** @brief QoS configuration structure. */ 134 struct bt_bap_qos_cfg { 135 /** 136 * @brief Presentation Delay in microseconds 137 * 138 * This value can be changed up and until bt_bap_stream_qos() has been called. 139 * Once a stream has been QoS configured, modifying this field does not modify the value. 140 * It is however possible to modify this field and call bt_bap_stream_qos() again to update 141 * the value, assuming that the stream is in the correct state. 142 * 143 * Value range 0 to @ref BT_AUDIO_PD_MAX. 144 */ 145 uint32_t pd; 146 147 /** 148 * @brief Connected Isochronous Group (CIG) parameters 149 * 150 * The fields in this struct affect the value sent to the controller via HCI 151 * when creating the CIG. Once the group has been created with 152 * bt_bap_unicast_group_create(), modifying these fields will not affect the group. 153 */ 154 struct { 155 /** QoS Framing */ 156 enum bt_bap_qos_cfg_framing framing; 157 158 /** 159 * @brief PHY 160 * 161 * Allowed values are @ref BT_BAP_QOS_CFG_1M, @ref BT_BAP_QOS_CFG_2M and 162 * @ref BT_BAP_QOS_CFG_CODED. 163 */ 164 uint8_t phy; 165 166 /** 167 * @brief Retransmission Number 168 * 169 * This a recommendation to the controller, and the actual retransmission number 170 * may be different than this. 171 */ 172 uint8_t rtn; 173 174 /** 175 * @brief Maximum SDU size 176 * 177 * Value range @ref BT_ISO_MIN_SDU to @ref BT_ISO_MAX_SDU. 178 */ 179 uint16_t sdu; 180 181 #if defined(CONFIG_BT_BAP_BROADCAST_SOURCE) || defined(CONFIG_BT_BAP_UNICAST) || \ 182 defined(__DOXYGEN__) 183 /** 184 * @brief Maximum Transport Latency 185 * 186 * Not used for the @kconfig{CONFIG_BT_BAP_BROADCAST_SINK} role. 187 */ 188 uint16_t latency; 189 #endif /* CONFIG_BT_BAP_BROADCAST_SOURCE || CONFIG_BT_BAP_UNICAST */ 190 191 /** 192 * @brief SDU Interval 193 * 194 * Value range @ref BT_ISO_SDU_INTERVAL_MIN to @ref BT_ISO_SDU_INTERVAL_MAX 195 */ 196 uint32_t interval; 197 198 #if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__) 199 /** 200 * @brief Maximum PDU size 201 * 202 * Maximum size, in octets, of the payload from link layer to link layer. 203 * 204 * Value range @ref BT_ISO_CONNECTED_PDU_MIN to @ref BT_ISO_PDU_MAX for 205 * connected ISO. 206 * 207 * Value range @ref BT_ISO_BROADCAST_PDU_MIN to @ref BT_ISO_PDU_MAX for 208 * broadcast ISO. 209 */ 210 uint16_t max_pdu; 211 212 /** 213 * @brief Burst number 214 * 215 * Value range @ref BT_ISO_BN_MIN to @ref BT_ISO_BN_MAX. 216 */ 217 uint8_t burst_number; 218 219 /** 220 * @brief Number of subevents 221 * 222 * Maximum number of subevents in each CIS or BIS event. 223 * 224 * Value range @ref BT_ISO_NSE_MIN to @ref BT_ISO_NSE_MAX. 225 */ 226 uint8_t num_subevents; 227 #endif /* CONFIG_BT_ISO_TEST_PARAMS */ 228 }; 229 }; 230 231 /** 232 * @brief Helper to declare elements of @ref bt_bap_qos_cfg_pref 233 * 234 * @param _unframed_supported Unframed PDUs supported 235 * @param _phy Preferred Target PHY 236 * @param _rtn Preferred Retransmission number 237 * @param _latency Preferred Maximum Transport Latency (msec) 238 * @param _pd_min Minimum Presentation Delay (usec) 239 * @param _pd_max Maximum Presentation Delay (usec) 240 * @param _pref_pd_min Preferred Minimum Presentation Delay (usec) 241 * @param _pref_pd_max Preferred Maximum Presentation Delay (usec) 242 */ 243 #define BT_BAP_QOS_CFG_PREF(_unframed_supported, _phy, _rtn, _latency, _pd_min, _pd_max, \ 244 _pref_pd_min, _pref_pd_max) \ 245 { \ 246 .unframed_supported = _unframed_supported, .phy = _phy, .rtn = _rtn, \ 247 .latency = _latency, .pd_min = _pd_min, .pd_max = _pd_max, \ 248 .pref_pd_min = _pref_pd_min, .pref_pd_max = _pref_pd_max, \ 249 } 250 251 /** @brief Audio Stream Quality of Service Preference structure. */ 252 struct bt_bap_qos_cfg_pref { 253 /** 254 * @brief Unframed PDUs supported 255 * 256 * Unlike the other fields, this is not a preference but whether 257 * the codec supports unframed ISOAL PDUs. 258 */ 259 bool unframed_supported; 260 261 /** 262 * @brief Preferred PHY bitfield 263 * 264 * Bitfield consisting of one or more of @ref BT_GAP_LE_PHY_1M, @ref BT_GAP_LE_PHY_2M and 265 * @ref BT_GAP_LE_PHY_CODED. 266 */ 267 uint8_t phy; 268 269 /** 270 * @brief Preferred Retransmission Number 271 * 272 * @ref BT_AUDIO_RTN_PREF_NONE indicates no preference. 273 */ 274 uint8_t rtn; 275 276 /** 277 * Preferred Transport Latency 278 * 279 * Value range @ref BT_ISO_LATENCY_MIN to @ref BT_ISO_LATENCY_MAX 280 */ 281 uint16_t latency; 282 283 /** 284 * @brief Minimum Presentation Delay in microseconds 285 * 286 * Unlike the other fields, this is not a preference but a minimum requirement. 287 * 288 * Value range 0 to @ref BT_AUDIO_PD_MAX 289 */ 290 uint32_t pd_min; 291 292 /** 293 * @brief Maximum Presentation Delay in microseconds 294 * 295 * Unlike the other fields, this is not a preference but a maximum requirement. 296 * 297 * Value range @ref bt_bap_qos_cfg_pref.pd_min to @ref BT_AUDIO_PD_MAX 298 */ 299 uint32_t pd_max; 300 301 /** 302 * @brief Preferred minimum Presentation Delay in microseconds 303 * 304 * Value range @ref bt_bap_qos_cfg_pref.pd_min to @ref bt_bap_qos_cfg_pref.pd_max, or 305 * @ref BT_AUDIO_PD_PREF_NONE to indicate no preference. 306 */ 307 uint32_t pref_pd_min; 308 309 /** 310 * @brief Preferred maximum Presentation Delay in microseconds 311 * 312 * Value range @ref bt_bap_qos_cfg_pref.pd_min to @ref bt_bap_qos_cfg_pref.pd_max, 313 * and higher than or equal to @ref bt_bap_qos_cfg_pref.pref_pd_min, or 314 * @ref BT_AUDIO_PD_PREF_NONE to indicate no preference. 315 */ 316 uint32_t pref_pd_max; 317 }; 318 319 /** Periodic advertising state reported by the Scan Delegator */ 320 enum bt_bap_pa_state { 321 /** The periodic advertising has not been synchronized */ 322 BT_BAP_PA_STATE_NOT_SYNCED = 0x00, 323 324 /** Waiting for SyncInfo from Broadcast Assistant */ 325 BT_BAP_PA_STATE_INFO_REQ = 0x01, 326 327 /** Synchronized to periodic advertising */ 328 BT_BAP_PA_STATE_SYNCED = 0x02, 329 330 /** Failed to synchronized to periodic advertising */ 331 BT_BAP_PA_STATE_FAILED = 0x03, 332 333 /** No periodic advertising sync transfer receiver from Broadcast Assistant */ 334 BT_BAP_PA_STATE_NO_PAST = 0x04, 335 }; 336 337 /** Broadcast Isochronous Group encryption state reported by the Scan Delegator */ 338 enum bt_bap_big_enc_state { 339 /** The Broadcast Isochronous Group not encrypted */ 340 BT_BAP_BIG_ENC_STATE_NO_ENC = 0x00, 341 342 /** The Broadcast Isochronous Group broadcast code requested */ 343 BT_BAP_BIG_ENC_STATE_BCODE_REQ = 0x01, 344 345 /** The Broadcast Isochronous Group decrypted */ 346 BT_BAP_BIG_ENC_STATE_DEC = 0x02, 347 348 /** The Broadcast Isochronous Group bad broadcast code */ 349 BT_BAP_BIG_ENC_STATE_BAD_CODE = 0x03, 350 }; 351 352 /** Broadcast Audio Scan Service (BASS) specific ATT error codes */ 353 enum bt_bap_bass_att_err { 354 /** Opcode not supported */ 355 BT_BAP_BASS_ERR_OPCODE_NOT_SUPPORTED = 0x80, 356 357 /** Invalid source ID supplied */ 358 BT_BAP_BASS_ERR_INVALID_SRC_ID = 0x81, 359 }; 360 361 /** Value indicating that the periodic advertising interval is unknown */ 362 #define BT_BAP_PA_INTERVAL_UNKNOWN 0xFFFF 363 364 /** 365 * @brief Broadcast Assistant no BIS sync preference 366 * 367 * Value indicating that the Broadcast Assistant has no preference to which BIS 368 * the Scan Delegator syncs to 369 */ 370 #define BT_BAP_BIS_SYNC_NO_PREF 0xFFFFFFFF 371 /** BIS sync value indicating that the BIG sync has failed for any reason */ 372 #define BT_BAP_BIS_SYNC_FAILED 0xFFFFFFFF 373 374 /** Endpoint states */ 375 enum bt_bap_ep_state { 376 /** Audio Stream Endpoint Idle state */ 377 BT_BAP_EP_STATE_IDLE = 0x00, 378 379 /** Audio Stream Endpoint Codec Configured state */ 380 BT_BAP_EP_STATE_CODEC_CONFIGURED = 0x01, 381 382 /** Audio Stream Endpoint QoS Configured state */ 383 BT_BAP_EP_STATE_QOS_CONFIGURED = 0x02, 384 385 /** Audio Stream Endpoint Enabling state */ 386 BT_BAP_EP_STATE_ENABLING = 0x03, 387 388 /** Audio Stream Endpoint Streaming state */ 389 BT_BAP_EP_STATE_STREAMING = 0x04, 390 391 /** Audio Stream Endpoint Disabling state */ 392 BT_BAP_EP_STATE_DISABLING = 0x05, 393 394 /** Audio Stream Endpoint Streaming state */ 395 BT_BAP_EP_STATE_RELEASING = 0x06, 396 }; 397 398 /** 399 * @brief Response Status Code 400 * 401 * These are sent by the server to the client when a stream operation is 402 * requested. 403 */ 404 enum bt_bap_ascs_rsp_code { 405 /** Server completed operation successfully */ 406 BT_BAP_ASCS_RSP_CODE_SUCCESS = 0x00, 407 /** Server did not support operation by client */ 408 BT_BAP_ASCS_RSP_CODE_NOT_SUPPORTED = 0x01, 409 /** Server rejected due to invalid operation length */ 410 BT_BAP_ASCS_RSP_CODE_INVALID_LENGTH = 0x02, 411 /** Invalid ASE ID */ 412 BT_BAP_ASCS_RSP_CODE_INVALID_ASE = 0x03, 413 /** Invalid ASE state */ 414 BT_BAP_ASCS_RSP_CODE_INVALID_ASE_STATE = 0x04, 415 /** Invalid operation for direction */ 416 BT_BAP_ASCS_RSP_CODE_INVALID_DIR = 0x05, 417 /** Capabilities not supported by server */ 418 BT_BAP_ASCS_RSP_CODE_CAP_UNSUPPORTED = 0x06, 419 /** Configuration parameters not supported by server */ 420 BT_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED = 0x07, 421 /** Configuration parameters rejected by server */ 422 BT_BAP_ASCS_RSP_CODE_CONF_REJECTED = 0x08, 423 /** Invalid Configuration parameters */ 424 BT_BAP_ASCS_RSP_CODE_CONF_INVALID = 0x09, 425 /** Unsupported metadata */ 426 BT_BAP_ASCS_RSP_CODE_METADATA_UNSUPPORTED = 0x0a, 427 /** Metadata rejected by server */ 428 BT_BAP_ASCS_RSP_CODE_METADATA_REJECTED = 0x0b, 429 /** Invalid metadata */ 430 BT_BAP_ASCS_RSP_CODE_METADATA_INVALID = 0x0c, 431 /** Server has insufficient resources */ 432 BT_BAP_ASCS_RSP_CODE_NO_MEM = 0x0d, 433 /** Unspecified error */ 434 BT_BAP_ASCS_RSP_CODE_UNSPECIFIED = 0x0e, 435 }; 436 437 /** 438 * @brief Response Reasons 439 * 440 * These are used if the @ref bt_bap_ascs_rsp_code value is 441 * @ref BT_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED, @ref BT_BAP_ASCS_RSP_CODE_CONF_REJECTED or 442 * @ref BT_BAP_ASCS_RSP_CODE_CONF_INVALID. 443 */ 444 enum bt_bap_ascs_reason { 445 /** No reason */ 446 BT_BAP_ASCS_REASON_NONE = 0x00, 447 /** Codec ID */ 448 BT_BAP_ASCS_REASON_CODEC = 0x01, 449 /** Codec configuration */ 450 BT_BAP_ASCS_REASON_CODEC_DATA = 0x02, 451 /** SDU interval */ 452 BT_BAP_ASCS_REASON_INTERVAL = 0x03, 453 /** Framing */ 454 BT_BAP_ASCS_REASON_FRAMING = 0x04, 455 /** PHY */ 456 BT_BAP_ASCS_REASON_PHY = 0x05, 457 /** Maximum SDU size*/ 458 BT_BAP_ASCS_REASON_SDU = 0x06, 459 /** RTN */ 460 BT_BAP_ASCS_REASON_RTN = 0x07, 461 /** Max transport latency */ 462 BT_BAP_ASCS_REASON_LATENCY = 0x08, 463 /** Presendation delay */ 464 BT_BAP_ASCS_REASON_PD = 0x09, 465 /** Invalid CIS mapping */ 466 BT_BAP_ASCS_REASON_CIS = 0x0a, 467 }; 468 469 /** @brief Structure storing values of fields of ASE Control Point notification. */ 470 struct bt_bap_ascs_rsp { 471 /** 472 * @brief Value of the Response Code field. 473 * 474 * The following response codes are accepted: 475 * - @ref BT_BAP_ASCS_RSP_CODE_SUCCESS 476 * - @ref BT_BAP_ASCS_RSP_CODE_CAP_UNSUPPORTED 477 * - @ref BT_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED 478 * - @ref BT_BAP_ASCS_RSP_CODE_CONF_REJECTED 479 * - @ref BT_BAP_ASCS_RSP_CODE_METADATA_UNSUPPORTED 480 * - @ref BT_BAP_ASCS_RSP_CODE_METADATA_REJECTED 481 * - @ref BT_BAP_ASCS_RSP_CODE_NO_MEM 482 * - @ref BT_BAP_ASCS_RSP_CODE_UNSPECIFIED 483 */ 484 enum bt_bap_ascs_rsp_code code; 485 486 /** 487 * @brief Value of the Reason field. 488 * 489 * The meaning of this value depend on the Response Code field. 490 */ 491 union { 492 /** 493 * @brief Response reason 494 * 495 * If the Response Code is one of the following: 496 * - @ref BT_BAP_ASCS_RSP_CODE_CONF_UNSUPPORTED 497 * - @ref BT_BAP_ASCS_RSP_CODE_CONF_REJECTED 498 * all values from @ref bt_bap_ascs_reason can be used. 499 * 500 * If the Response Code is one of the following: 501 * - @ref BT_BAP_ASCS_RSP_CODE_SUCCESS 502 * - @ref BT_BAP_ASCS_RSP_CODE_CAP_UNSUPPORTED 503 * - @ref BT_BAP_ASCS_RSP_CODE_NO_MEM 504 * - @ref BT_BAP_ASCS_RSP_CODE_UNSPECIFIED 505 * only value @ref BT_BAP_ASCS_REASON_NONE shall be used. 506 */ 507 enum bt_bap_ascs_reason reason; 508 509 /** 510 * @brief Response metadata type 511 * 512 * If the Response Code is one of the following: 513 * - @ref BT_BAP_ASCS_RSP_CODE_METADATA_UNSUPPORTED 514 * - @ref BT_BAP_ASCS_RSP_CODE_METADATA_REJECTED 515 * the value of the Metadata Type shall be used. 516 */ 517 enum bt_audio_metadata_type metadata_type; 518 }; 519 }; 520 521 /** 522 * @brief Macro used to initialise the object storing values of ASE Control Point notification. 523 * 524 * @param c Response Code field 525 * @param r Reason field - @ref bt_bap_ascs_reason or @ref bt_audio_metadata_type (see notes in 526 * @ref bt_bap_ascs_rsp). 527 */ 528 #define BT_BAP_ASCS_RSP(c, r) (struct bt_bap_ascs_rsp) { .code = c, .reason = r } 529 530 /** @brief Abstract Audio Broadcast Source structure. */ 531 struct bt_bap_broadcast_source; 532 533 /** @brief Abstract Audio Broadcast Sink structure. */ 534 struct bt_bap_broadcast_sink; 535 536 /** @brief Abstract Audio Unicast Group structure. */ 537 struct bt_bap_unicast_group; 538 539 /** @brief Abstract Audio Endpoint structure. */ 540 struct bt_bap_ep; 541 542 /** Struct to hold subgroup specific information for the receive state */ 543 struct bt_bap_bass_subgroup { 544 /** BIS synced bitfield */ 545 uint32_t bis_sync; 546 547 /** Length of the metadata */ 548 uint8_t metadata_len; 549 550 #if defined(CONFIG_BT_AUDIO_CODEC_CFG_MAX_METADATA_SIZE) || defined(__DOXYGEN__) 551 /** The metadata */ 552 uint8_t metadata[CONFIG_BT_AUDIO_CODEC_CFG_MAX_METADATA_SIZE]; 553 #endif /* CONFIG_BT_AUDIO_CODEC_CFG_MAX_METADATA_SIZE */ 554 }; 555 556 /** Represents the Broadcast Audio Scan Service receive state */ 557 struct bt_bap_scan_delegator_recv_state { 558 /** The source ID */ 559 uint8_t src_id; 560 561 /** The Bluetooth address */ 562 bt_addr_le_t addr; 563 564 /** The advertising set ID*/ 565 uint8_t adv_sid; 566 567 /** The periodic adverting sync state */ 568 enum bt_bap_pa_state pa_sync_state; 569 570 /** The broadcast isochronous group encryption state */ 571 enum bt_bap_big_enc_state encrypt_state; 572 573 /** The 24-bit broadcast ID */ 574 uint32_t broadcast_id; 575 576 /** 577 * @brief The bad broadcast code 578 * 579 * Only valid if encrypt_state is @ref BT_BAP_BIG_ENC_STATE_BCODE_REQ 580 */ 581 uint8_t bad_code[BT_ISO_BROADCAST_CODE_SIZE]; 582 583 /** Number of subgroups */ 584 uint8_t num_subgroups; 585 586 /** Subgroup specific information 587 * 588 * If the @ref bt_bap_bass_subgroup.bis_sync value is @ref BT_BAP_BIS_SYNC_FAILED then it 589 * indicates that the BIG sync failed. 590 */ 591 struct bt_bap_bass_subgroup subgroups[BT_BAP_BASS_MAX_SUBGROUPS]; 592 }; 593 594 /** 595 * @brief Struct to hold the Basic Audio Profile Scan Delegator callbacks 596 * 597 * These can be registered for usage with bt_bap_scan_delegator_register(). 598 */ 599 struct bt_bap_scan_delegator_cb { 600 /** 601 * @brief Receive state updated 602 * 603 * @param conn Pointer to the connection to a remote device if 604 * the change was caused by it, otherwise NULL. 605 * @param recv_state Pointer to the receive state that was updated. 606 * 607 * @return 0 in case of success or negative value in case of error. 608 */ 609 void (*recv_state_updated)(struct bt_conn *conn, 610 const struct bt_bap_scan_delegator_recv_state *recv_state); 611 612 /** 613 * @brief Periodic advertising sync request 614 * 615 * Request from peer device to synchronize with the periodic advertiser 616 * denoted by the @p recv_state. To notify the Broadcast Assistant about 617 * any pending sync 618 * 619 * @param conn Pointer to the connection requesting the 620 * periodic advertising sync. 621 * @param recv_state Pointer to the receive state that is being 622 * requested for periodic advertising sync. 623 * @param past_avail True if periodic advertising sync transfer is available. 624 * @param pa_interval The periodic advertising interval. 625 * 626 * @return 0 in case of accept, or other value to reject. 627 */ 628 int (*pa_sync_req)(struct bt_conn *conn, 629 const struct bt_bap_scan_delegator_recv_state *recv_state, 630 bool past_avail, uint16_t pa_interval); 631 632 /** 633 * @brief Periodic advertising sync termination request 634 * 635 * Request from peer device to terminate the periodic advertiser sync 636 * denoted by the @p recv_state. 637 * 638 * @param conn Pointer to the connection requesting the periodic 639 * advertising sync termination. 640 * @param recv_state Pointer to the receive state that is being 641 * requested for periodic advertising sync. 642 * 643 * @return 0 in case of success or negative value in case of error. 644 */ 645 int (*pa_sync_term_req)(struct bt_conn *conn, 646 const struct bt_bap_scan_delegator_recv_state *recv_state); 647 648 /** 649 * @brief Broadcast code received 650 * 651 * Broadcast code received from a broadcast assistant 652 * 653 * @param conn Pointer to the connection providing the 654 * broadcast code. 655 * @param recv_state Pointer to the receive state the broadcast code 656 * is being provided for. 657 * @param broadcast_code The 16-octet broadcast code 658 */ 659 void (*broadcast_code)(struct bt_conn *conn, 660 const struct bt_bap_scan_delegator_recv_state *recv_state, 661 const uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE]); 662 /** 663 * @brief Broadcast Isochronous Stream synchronize request 664 * 665 * Request from Broadcast Assistant device to modify the Broadcast 666 * Isochronous Stream states. The request shall be fulfilled with 667 * accordance to the @p bis_sync_req within reasonable time. The 668 * Broadcast Assistant may also request fewer, or none, indexes to 669 * be synchronized. 670 * 671 * @param[in] conn Pointer to the connection of the 672 * Broadcast Assistant requesting the sync. 673 * @param[in] recv_state Pointer to the receive state that is being 674 * requested for the sync. 675 * @param[in] bis_sync_req Array of bitfields of which BIS indexes 676 * that is requested to sync for each subgroup 677 * by the Broadcast Assistant. A value of 0 678 * indicates a request to terminate the BIG 679 * sync. 680 * 681 * @return 0 in case of accept, or other value to reject. 682 */ 683 int (*bis_sync_req)(struct bt_conn *conn, 684 const struct bt_bap_scan_delegator_recv_state *recv_state, 685 const uint32_t bis_sync_req[BT_BAP_BASS_MAX_SUBGROUPS]); 686 /** 687 * @brief Broadcast Assistant scanning state callback 688 * 689 * Callback triggered when a Broadcast Assistant notifies the Scan Delegator about the 690 * assistants scanning state. 691 * 692 * @param conn Pointer to the connection that initiated the scan. 693 * @param is_scanning true if scanning started, false if scanning stopped. 694 */ 695 void (*scanning_state)(struct bt_conn *conn, bool is_scanning); 696 }; 697 698 /** Structure holding information of audio stream endpoint */ 699 struct bt_bap_ep_info { 700 /** The ID of the endpoint */ 701 uint8_t id; 702 703 /** The state of the endpoint */ 704 enum bt_bap_ep_state state; 705 706 /** Capabilities type */ 707 enum bt_audio_dir dir; 708 709 /** The isochronous channel associated with the endpoint. */ 710 struct bt_iso_chan *iso_chan; 711 712 /** @brief True if the stream associated with the endpoint is able to send data */ 713 bool can_send; 714 715 /** @brief True if the stream associated with the endpoint is able to receive data */ 716 bool can_recv; 717 718 /** Pointer to paired endpoint if the endpoint is part of a bidirectional CIS, 719 * otherwise NULL 720 */ 721 struct bt_bap_ep *paired_ep; 722 723 /** Pointer to the preferred QoS settings associated with the endpoint */ 724 const struct bt_bap_qos_cfg_pref *qos_pref; 725 }; 726 727 /** 728 * @brief Return structure holding information of audio stream endpoint 729 * 730 * @param ep The audio stream endpoint object. 731 * @param info The structure object to be filled with the info. 732 * 733 * @retval 0 in case of success 734 * @retval -EINVAL if @p ep or @p info are NULL 735 */ 736 int bt_bap_ep_get_info(const struct bt_bap_ep *ep, struct bt_bap_ep_info *info); 737 738 /** 739 * @brief Basic Audio Profile stream structure. 740 * 741 * Streams represents a stream configuration of a Remote Endpoint and a Local Capability. 742 * 743 * @note Streams are unidirectional but can be paired with other streams to use a bidirectional 744 * connected isochronous stream. 745 */ 746 struct bt_bap_stream { 747 /** Connection reference */ 748 struct bt_conn *conn; 749 750 /** Endpoint reference */ 751 struct bt_bap_ep *ep; 752 753 /** Codec Configuration */ 754 struct bt_audio_codec_cfg *codec_cfg; 755 756 /** QoS Configuration */ 757 struct bt_bap_qos_cfg *qos; 758 759 /** Audio stream operations */ 760 struct bt_bap_stream_ops *ops; 761 762 #if defined(CONFIG_BT_BAP_UNICAST_CLIENT) || defined(__DOXYGEN__) 763 /** 764 * @internal Audio ISO reference 765 * 766 * This is only used for Unicast Client streams, and is handled internally. 767 */ 768 struct bt_bap_iso *bap_iso; 769 #endif /* CONFIG_BT_BAP_UNICAST_CLIENT */ 770 771 /** @internal Unicast or Broadcast group - Used internally */ 772 void *group; 773 774 /** Stream user data */ 775 void *user_data; 776 777 #if defined(CONFIG_BT_BAP_DEBUG_STREAM_SEQ_NUM) || defined(__DOXYGEN__) 778 /** @internal Previously sent sequence number */ 779 uint16_t _prev_seq_num; 780 #endif /* CONFIG_BT_BAP_DEBUG_STREAM_SEQ_NUM */ 781 782 /** @internal Internally used list node */ 783 sys_snode_t _node; 784 }; 785 786 /** @brief Stream operation. */ 787 struct bt_bap_stream_ops { 788 #if defined(CONFIG_BT_BAP_UNICAST) || defined(__DOXYGEN__) 789 /** 790 * @brief Stream configured callback 791 * 792 * Configured callback is called whenever an Audio Stream has been configured. 793 * 794 * @param stream Stream object that has been configured. 795 * @param pref Remote QoS preferences. 796 */ 797 void (*configured)(struct bt_bap_stream *stream, const struct bt_bap_qos_cfg_pref *pref); 798 799 /** 800 * @brief Stream QoS set callback 801 * 802 * QoS set callback is called whenever an Audio Stream Quality of Service has been set or 803 * updated. 804 * 805 * @param stream Stream object that had its QoS updated. 806 */ 807 void (*qos_set)(struct bt_bap_stream *stream); 808 809 /** 810 * @brief Stream enabled callback 811 * 812 * Enabled callback is called whenever an Audio Stream has been enabled. 813 * 814 * @param stream Stream object that has been enabled. 815 */ 816 void (*enabled)(struct bt_bap_stream *stream); 817 818 /** 819 * @brief Stream metadata updated callback 820 * 821 * Metadata Updated callback is called whenever an Audio Stream's metadata has been 822 * updated. 823 * 824 * @param stream Stream object that had its metadata updated. 825 */ 826 void (*metadata_updated)(struct bt_bap_stream *stream); 827 828 /** 829 * @brief Stream disabled callback 830 * 831 * Disabled callback is called whenever an Audio Stream has been disabled. 832 * 833 * @param stream Stream object that has been disabled. 834 */ 835 void (*disabled)(struct bt_bap_stream *stream); 836 837 /** 838 * @brief Stream released callback 839 * 840 * Released callback is called whenever a Audio Stream has been released and can be 841 * deallocated. 842 * 843 * @param stream Stream object that has been released. 844 */ 845 void (*released)(struct bt_bap_stream *stream); 846 #endif /* CONFIG_BT_BAP_UNICAST */ 847 848 /** 849 * @brief Stream started callback 850 * 851 * Started callback is called whenever an Audio Stream has been started 852 * and will be usable for streaming. 853 * 854 * @param stream Stream object that has been started. 855 */ 856 void (*started)(struct bt_bap_stream *stream); 857 858 /** 859 * @brief Stream stopped callback 860 * 861 * Stopped callback is called whenever an Audio Stream has been stopped. 862 * 863 * @param stream Stream object that has been stopped. 864 * @param reason BT_HCI_ERR_* reason for the disconnection. 865 */ 866 void (*stopped)(struct bt_bap_stream *stream, uint8_t reason); 867 868 #if defined(CONFIG_BT_AUDIO_RX) || defined(__DOXYGEN__) 869 /** 870 * @brief Stream audio HCI receive callback. 871 * 872 * This callback is only used if the ISO data path is HCI. 873 * 874 * @param stream Stream object. 875 * @param info Pointer to the metadata for the buffer. The lifetime of the pointer is 876 * linked to the lifetime of the net_buf. Metadata such as sequence number and 877 * timestamp can be provided by the bluetooth controller. 878 * @param buf Buffer containing incoming audio data. 879 */ 880 void (*recv)(struct bt_bap_stream *stream, const struct bt_iso_recv_info *info, 881 struct net_buf *buf); 882 #endif /* CONFIG_BT_AUDIO_RX */ 883 884 #if defined(CONFIG_BT_AUDIO_TX) || defined(__DOXYGEN__) 885 /** 886 * @brief Stream audio HCI sent callback 887 * 888 * This callback will be called once the controller marks the SDU 889 * as completed. When the controller does so is implementation 890 * dependent. It could be after the SDU is enqueued for transmission, 891 * or after it is sent on air or flushed. 892 * 893 * This callback is only used if the ISO data path is HCI. 894 * 895 * @param stream Stream object. 896 */ 897 void (*sent)(struct bt_bap_stream *stream); 898 #endif /* CONFIG_BT_AUDIO_TX */ 899 900 /** 901 * @brief Isochronous channel connected callback 902 * 903 * If this callback is provided it will be called whenever the isochronous channel for the 904 * stream has been connected. This does not mean that the stream is ready to be used, which 905 * is indicated by the @ref bt_bap_stream_ops.started callback. 906 * 907 * If the stream shares an isochronous channel with another stream, then this callback may 908 * still be called, without the stream going into the started state. 909 * 910 * @param stream Stream object. 911 */ 912 void (*connected)(struct bt_bap_stream *stream); 913 914 /** 915 * @brief Isochronous channel disconnected callback 916 * 917 * If this callback is provided it will be called whenever the isochronous channel is 918 * disconnected, including when a connection gets rejected. 919 * 920 * If the stream shares an isochronous channel with another stream, then this callback may 921 * not be called, even if the stream is leaving the streaming state. 922 * 923 * @param stream Stream object. 924 * @param reason BT_HCI_ERR_* reason for the disconnection. 925 */ 926 void (*disconnected)(struct bt_bap_stream *stream, uint8_t reason); 927 }; 928 929 /** Structure for registering Unicast Server */ 930 struct bt_bap_unicast_server_register_param { 931 /** 932 * @brief Sink Count to register. 933 * 934 * Should be in range 0 to @kconfig{CONFIG_BT_ASCS_MAX_ASE_SNK_COUNT} 935 */ 936 uint8_t snk_cnt; 937 938 /** @brief Source Count to register. 939 * 940 * Should be in range 0 to @kconfig{CONFIG_BT_ASCS_MAX_ASE_SRC_COUNT} 941 */ 942 uint8_t src_cnt; 943 }; 944 945 /** 946 * @brief Register Audio callbacks for a stream. 947 * 948 * Register Audio callbacks for a stream. 949 * 950 * @param stream Stream object. 951 * @param ops Stream operations structure. 952 */ 953 void bt_bap_stream_cb_register(struct bt_bap_stream *stream, struct bt_bap_stream_ops *ops); 954 955 /** 956 * @brief Configure Audio Stream 957 * 958 * This procedure is used by a client to configure a new stream using the 959 * remote endpoint, local capability and codec configuration. 960 * 961 * @param conn Connection object 962 * @param stream Stream object being configured 963 * @param ep Remote Audio Endpoint being configured 964 * @param codec_cfg Codec configuration 965 * 966 * @return Allocated Audio Stream object or NULL in case of error. 967 */ 968 int bt_bap_stream_config(struct bt_conn *conn, struct bt_bap_stream *stream, struct bt_bap_ep *ep, 969 struct bt_audio_codec_cfg *codec_cfg); 970 971 /** 972 * @brief Reconfigure Audio Stream 973 * 974 * This procedure is used by a unicast client or unicast server to reconfigure 975 * a stream to use a different local codec configuration. 976 * 977 * This can only be done for unicast streams. 978 * 979 * @param stream Stream object being reconfigured 980 * @param codec_cfg Codec configuration 981 * 982 * @return 0 in case of success or negative value in case of error. 983 */ 984 int bt_bap_stream_reconfig(struct bt_bap_stream *stream, struct bt_audio_codec_cfg *codec_cfg); 985 986 /** 987 * @brief Configure Audio Stream QoS 988 * 989 * This procedure is used by a client to configure the Quality of Service of streams in a unicast 990 * group. All streams in the group for the specified @p conn will have the Quality of Service 991 * configured. This shall only be used to configure unicast streams. 992 * 993 * @param conn Connection object 994 * @param group Unicast group object 995 * 996 * @return 0 in case of success or negative value in case of error. 997 */ 998 int bt_bap_stream_qos(struct bt_conn *conn, struct bt_bap_unicast_group *group); 999 1000 /** 1001 * @brief Enable Audio Stream 1002 * 1003 * This procedure is used by a client to enable a stream. 1004 * 1005 * This shall only be called for unicast streams, as broadcast streams will always be enabled once 1006 * created. 1007 * 1008 * @param stream Stream object 1009 * @param meta Metadata 1010 * @param meta_len Metadata length 1011 * 1012 * @return 0 in case of success or negative value in case of error. 1013 */ 1014 int bt_bap_stream_enable(struct bt_bap_stream *stream, const uint8_t meta[], size_t meta_len); 1015 1016 /** 1017 * @brief Change Audio Stream Metadata 1018 * 1019 * This procedure is used by a unicast client or unicast server to change the metadata of a stream. 1020 * 1021 * @param stream Stream object 1022 * @param meta Metadata 1023 * @param meta_len Metadata length 1024 * 1025 * @return 0 in case of success or negative value in case of error. 1026 */ 1027 int bt_bap_stream_metadata(struct bt_bap_stream *stream, const uint8_t meta[], size_t meta_len); 1028 1029 /** 1030 * @brief Disable Audio Stream 1031 * 1032 * This procedure is used by a unicast client or unicast server to disable a stream. 1033 * 1034 * This shall only be called for unicast streams, as broadcast streams will 1035 * always be enabled once created. 1036 * 1037 * @param stream Stream object 1038 * 1039 * @return 0 in case of success or negative value in case of error. 1040 */ 1041 int bt_bap_stream_disable(struct bt_bap_stream *stream); 1042 1043 /** 1044 * @brief Connect unicast audio stream 1045 * 1046 * This procedure is used by a unicast client to connect the connected isochronous stream (CIS) 1047 * associated with the audio stream. If two audio streams share a CIS, then this only needs to be 1048 * done once for those streams. This can only be done for streams in the QoS configured or enabled 1049 * states. 1050 * 1051 * The bt_bap_stream_ops.connected() callback will be called on the streams once this has finished. 1052 * 1053 * This shall only be called for unicast streams, and only as the unicast client 1054 * (@kconfig{CONFIG_BT_BAP_UNICAST_CLIENT}). 1055 * 1056 * @param stream Stream object 1057 * 1058 * @retval 0 in case of success 1059 * @retval -EINVAL if the stream, endpoint, ISO channel or connection is NULL 1060 * @retval -EBADMSG if the stream or ISO channel is in an invalid state for connection 1061 * @retval -EOPNOTSUPP if the role of the stream is not @ref BT_HCI_ROLE_CENTRAL 1062 * @retval -EALREADY if the ISO channel is already connecting or connected 1063 * @retval -EBUSY if another ISO channel is connecting 1064 * @retval -ENOEXEC if otherwise rejected by the ISO layer 1065 */ 1066 int bt_bap_stream_connect(struct bt_bap_stream *stream); 1067 1068 /** 1069 * @brief Start Audio Stream 1070 * 1071 * This procedure is used by a unicast client or unicast server to make a stream start streaming. 1072 * 1073 * For the unicast client, this will send the receiver start ready command to the unicast server for 1074 * @ref BT_AUDIO_DIR_SOURCE ASEs. The CIS is required to be connected first by 1075 * bt_bap_stream_connect() before the command can be sent. 1076 * 1077 * For the unicast server, this will execute the receiver start ready command on the unicast server 1078 * for @ref BT_AUDIO_DIR_SINK ASEs. If the CIS is not connected yet, the stream will go into the 1079 * streaming state as soon as the CIS is connected. 1080 * 1081 * This shall only be called for unicast streams. 1082 * 1083 * Broadcast sinks will always be started once synchronized, and broadcast 1084 * source streams shall be started with bt_bap_broadcast_source_start(). 1085 * 1086 * @param stream Stream object 1087 * 1088 * @return 0 in case of success or negative value in case of error. 1089 */ 1090 int bt_bap_stream_start(struct bt_bap_stream *stream); 1091 1092 /** 1093 * @brief Stop Audio Stream 1094 * 1095 * This procedure is used by a client to make a stream stop streaming. 1096 * 1097 * This shall only be called for unicast streams. 1098 * Broadcast sinks cannot be stopped. 1099 * Broadcast sources shall be stopped with bt_bap_broadcast_source_stop(). 1100 * 1101 * @param stream Stream object 1102 * 1103 * @retval 0 Success 1104 * @retval -EINVAL The @p stream does not have an endpoint or a connection, of the stream's 1105 * connection's role is not @p BT_HCI_ROLE_CENTRAL 1106 * @retval -EBADMSG The state of the @p stream endpoint is not @ref BT_BAP_EP_STATE_DISABLING 1107 * @retval -EALREADY The CIS state of the @p is not in a connected state, and thus is already 1108 * stopping 1109 * @retval -EBUSY The @p stream is busy with another operation 1110 * @retval -ENOTCONN The @p stream ACL connection is not connected 1111 * @retval -ENOMEM No memory to send request 1112 * @retval -ENOEXEC The request was rejected by GATT 1113 * @return 0 in case of success or negative value in case of error. 1114 */ 1115 int bt_bap_stream_stop(struct bt_bap_stream *stream); 1116 1117 /** 1118 * @brief Release Audio Stream 1119 * 1120 * This procedure is used by a unicast client or unicast server to release a unicast stream. 1121 * 1122 * Broadcast sink streams cannot be released, but can be deleted by bt_bap_broadcast_sink_delete(). 1123 * Broadcast source streams cannot be released, but can be deleted by 1124 * bt_bap_broadcast_source_delete(). 1125 * 1126 * @param stream Stream object 1127 * 1128 * @return 0 in case of success or negative value in case of error. 1129 */ 1130 int bt_bap_stream_release(struct bt_bap_stream *stream); 1131 1132 /** 1133 * @brief Send data to Audio stream without timestamp 1134 * 1135 * Send data from buffer to the stream. 1136 * 1137 * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}. 1138 * 1139 * @param stream Stream object. 1140 * @param buf Buffer containing data to be sent. 1141 * @param seq_num Packet Sequence number. This value shall be incremented for each call to this 1142 * function and at least once per SDU interval for a specific channel. 1143 * 1144 * @return Bytes sent in case of success or negative value in case of error. 1145 */ 1146 int bt_bap_stream_send(struct bt_bap_stream *stream, struct net_buf *buf, uint16_t seq_num); 1147 1148 /** 1149 * @brief Send data to Audio stream with timestamp 1150 * 1151 * Send data from buffer to the stream. 1152 * 1153 * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}. 1154 * 1155 * @param stream Stream object. 1156 * @param buf Buffer containing data to be sent. 1157 * @param seq_num Packet Sequence number. This value shall be incremented for each call to this 1158 * function and at least once per SDU interval for a specific channel. 1159 * @param ts Timestamp of the SDU in microseconds (us). This value can be used to transmit 1160 * multiple SDUs in the same SDU interval in a CIG or BIG. 1161 * 1162 * @return Bytes sent in case of success or negative value in case of error. 1163 */ 1164 int bt_bap_stream_send_ts(struct bt_bap_stream *stream, struct net_buf *buf, uint16_t seq_num, 1165 uint32_t ts); 1166 1167 /** 1168 * @brief Get ISO transmission timing info for a Basic Audio Profile stream 1169 * 1170 * Reads timing information for transmitted ISO packet on an ISO channel. 1171 * The HCI_LE_Read_ISO_TX_Sync HCI command is used to retrieve this information from the controller. 1172 * 1173 * @note An SDU must have already been successfully transmitted on the ISO channel 1174 * for this function to return successfully. 1175 * Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}. 1176 * 1177 * @param[in] stream Stream object. 1178 * @param[out] info Transmit info object. 1179 * 1180 * @retval 0 on success 1181 * @retval -EINVAL if the stream is invalid, if the stream is not configured for sending or if it is 1182 * not connected with a isochronous stream 1183 * @retval Any return value from bt_iso_chan_get_tx_sync() 1184 */ 1185 int bt_bap_stream_get_tx_sync(struct bt_bap_stream *stream, struct bt_iso_tx_info *info); 1186 1187 /** 1188 * @defgroup bt_bap_unicast_server BAP Unicast Server APIs 1189 * @ingroup bt_bap 1190 * @{ 1191 */ 1192 1193 /** Unicast Server callback structure */ 1194 struct bt_bap_unicast_server_cb { 1195 /** 1196 * @brief Endpoint config request callback 1197 * 1198 * Config callback is called whenever an endpoint is requested to be 1199 * configured 1200 * 1201 * @param[in] conn Connection object. 1202 * @param[in] ep Local Audio Endpoint being configured. 1203 * @param[in] dir Direction of the endpoint. 1204 * @param[in] codec_cfg Codec configuration. 1205 * @param[out] stream Pointer to stream that will be configured for the endpoint. 1206 * @param[out] pref Pointer to a QoS preference object that shall be populated with 1207 * values. Invalid values will reject the codec configuration request. 1208 * @param[out] rsp Object for the ASE operation response. Only used if the return 1209 * value is non-zero. 1210 * 1211 * @return 0 in case of success or negative value in case of error. 1212 */ 1213 int (*config)(struct bt_conn *conn, const struct bt_bap_ep *ep, enum bt_audio_dir dir, 1214 const struct bt_audio_codec_cfg *codec_cfg, struct bt_bap_stream **stream, 1215 struct bt_bap_qos_cfg_pref *const pref, struct bt_bap_ascs_rsp *rsp); 1216 1217 /** 1218 * @brief Stream reconfig request callback 1219 * 1220 * Reconfig callback is called whenever an Audio Stream needs to be 1221 * reconfigured with different codec configuration. 1222 * 1223 * @param[in] stream Stream object being reconfigured. 1224 * @param[in] dir Direction of the endpoint. 1225 * @param[in] codec_cfg Codec configuration. 1226 * @param[out] pref Pointer to a QoS preference object that shall be populated with 1227 * values. Invalid values will reject the codec configuration request. 1228 * @param[out] rsp Object for the ASE operation response. Only used if the return 1229 * value is non-zero. 1230 * 1231 * @return 0 in case of success or negative value in case of error. 1232 */ 1233 int (*reconfig)(struct bt_bap_stream *stream, enum bt_audio_dir dir, 1234 const struct bt_audio_codec_cfg *codec_cfg, 1235 struct bt_bap_qos_cfg_pref *const pref, struct bt_bap_ascs_rsp *rsp); 1236 1237 /** 1238 * @brief Stream QoS request callback 1239 * 1240 * QoS callback is called whenever an Audio Stream Quality of 1241 * Service needs to be configured. 1242 * 1243 * @param[in] stream Stream object being reconfigured. 1244 * @param[in] qos Quality of Service configuration. 1245 * @param[out] rsp Object for the ASE operation response. Only used if the return 1246 * value is non-zero. 1247 * 1248 * @return 0 in case of success or negative value in case of error. 1249 */ 1250 int (*qos)(struct bt_bap_stream *stream, const struct bt_bap_qos_cfg *qos, 1251 struct bt_bap_ascs_rsp *rsp); 1252 1253 /** 1254 * @brief Stream Enable request callback 1255 * 1256 * Enable callback is called whenever an Audio Stream is requested to be enabled to stream. 1257 * 1258 * @param[in] stream Stream object being enabled. 1259 * @param[in] meta Metadata entries. 1260 * @param[in] meta_len Length of metadata. 1261 * @param[out] rsp Object for the ASE operation response. Only used if the return 1262 * value is non-zero. 1263 * 1264 * @return 0 in case of success or negative value in case of error. 1265 */ 1266 int (*enable)(struct bt_bap_stream *stream, const uint8_t meta[], size_t meta_len, 1267 struct bt_bap_ascs_rsp *rsp); 1268 1269 /** 1270 * @brief Stream Start request callback 1271 * 1272 * Start callback is called whenever an Audio Stream is requested to start streaming. 1273 * 1274 * @param[in] stream Stream object. 1275 * @param[out] rsp Object for the ASE operation response. Only used if the return 1276 * value is non-zero. 1277 * 1278 * @return 0 in case of success or negative value in case of error. 1279 */ 1280 int (*start)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp); 1281 1282 /** 1283 * @brief Stream Metadata update request callback 1284 * 1285 * Metadata callback is called whenever an Audio Stream is requested to update its metadata. 1286 * 1287 * @param[in] stream Stream object. 1288 * @param[in] meta Metadata entries. 1289 * @param[in] meta_len Length of metadata. 1290 * @param[out] rsp Object for the ASE operation response. Only used if the return 1291 * value is non-zero. 1292 * 1293 * @return 0 in case of success or negative value in case of error. 1294 */ 1295 int (*metadata)(struct bt_bap_stream *stream, const uint8_t meta[], size_t meta_len, 1296 struct bt_bap_ascs_rsp *rsp); 1297 1298 /** 1299 * @brief Stream Disable request callback 1300 * 1301 * Disable callback is called whenever an Audio Stream is requested to disable the stream. 1302 * 1303 * @param[in] stream Stream object being disabled. 1304 * @param[out] rsp Object for the ASE operation response. Only used if the return 1305 * value is non-zero. 1306 * 1307 * @return 0 in case of success or negative value in case of error. 1308 */ 1309 int (*disable)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp); 1310 1311 /** 1312 * @brief Stream Stop callback 1313 * 1314 * Stop callback is called whenever an Audio Stream is requested to stop streaming. 1315 * 1316 * @param[in] stream Stream object. 1317 * @param[out] rsp Object for the ASE operation response. Only used if the return 1318 * value is non-zero. 1319 * 1320 * @return 0 in case of success or negative value in case of error. 1321 */ 1322 int (*stop)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp); 1323 1324 /** 1325 * @brief Stream release callback 1326 * 1327 * Release callback is called whenever a new Audio Stream needs to be released and thus 1328 * deallocated. 1329 * 1330 * @param[in] stream Stream object. 1331 * @param[out] rsp Object for the ASE operation response. Only used if the return 1332 * value is non-zero. 1333 * 1334 * @return 0 in case of success or negative value in case of error. 1335 */ 1336 int (*release)(struct bt_bap_stream *stream, struct bt_bap_ascs_rsp *rsp); 1337 }; 1338 1339 /** 1340 * @brief Register the Unicast Server. 1341 * 1342 * Register the Unicast Server. Only a single Unicast Server can be registered at any one time. 1343 * This will register ASCS in the GATT database. 1344 * 1345 * @param param Registration parameters for ascs. 1346 * 1347 * @return 0 in case of success, negative error code otherwise. 1348 */ 1349 int bt_bap_unicast_server_register(const struct bt_bap_unicast_server_register_param *param); 1350 1351 /** 1352 * @brief Unregister the Unicast Server. 1353 * 1354 * Unregister the Unicast Server. 1355 * This will unregister ASCS in the GATT database. 1356 * Before calling this function, any callbacks registered through 1357 * bt_bap_unicast_server_register_cb() needs to be unregistered with 1358 * bt_bap_unicast_server_unregister_cb(). 1359 * 1360 * Calling this function will issue an release operation on any ASE 1361 * in a non-idle state. 1362 * 1363 * @return 0 in case of success, negative error code otherwise. 1364 */ 1365 int bt_bap_unicast_server_unregister(void); 1366 1367 /** 1368 * @brief Register unicast server callbacks. 1369 * 1370 * Only one callback structure can be registered, and attempting to 1371 * registering more than one will result in an error. 1372 * Prior to calling this function the Unicast Server needs to be 1373 * registered with bt_bap_unicast_server_register(). 1374 * 1375 * @param cb Unicast server callback structure. 1376 * 1377 * @return 0 in case of success or negative value in case of error. 1378 */ 1379 int bt_bap_unicast_server_register_cb(const struct bt_bap_unicast_server_cb *cb); 1380 1381 /** 1382 * @brief Unregister unicast server callbacks. 1383 * 1384 * May only unregister a callback structure that has previously been 1385 * registered by bt_bap_unicast_server_register_cb(). 1386 * 1387 * Calling this function will issue an release operation on any ASE 1388 * in a non-idle state. 1389 * 1390 * @param cb Unicast server callback structure. 1391 * 1392 * @return 0 in case of success or negative value in case of error. 1393 */ 1394 int bt_bap_unicast_server_unregister_cb(const struct bt_bap_unicast_server_cb *cb); 1395 1396 /** 1397 * @typedef bt_bap_ep_func_t 1398 * @brief The callback function called for each endpoint. 1399 * 1400 * @param ep The structure object with endpoint info. 1401 * @param user_data Data to pass to the function. 1402 */ 1403 typedef void (*bt_bap_ep_func_t)(struct bt_bap_ep *ep, void *user_data); 1404 1405 /** 1406 * @brief Iterate through all endpoints of the given connection. 1407 * 1408 * @param conn Connection object 1409 * @param func Function to call for each endpoint. 1410 * @param user_data Data to pass to the callback function. 1411 */ 1412 void bt_bap_unicast_server_foreach_ep(struct bt_conn *conn, bt_bap_ep_func_t func, void *user_data); 1413 1414 /** 1415 * @brief Initialize and configure a new ASE. 1416 * 1417 * @param conn Connection object 1418 * @param stream Configured stream object to be attached to the ASE 1419 * @param codec_cfg Codec configuration 1420 * @param qos_pref Audio Stream Quality of Service Preference 1421 * 1422 * @return 0 in case of success or negative value in case of error. 1423 */ 1424 int bt_bap_unicast_server_config_ase(struct bt_conn *conn, struct bt_bap_stream *stream, 1425 struct bt_audio_codec_cfg *codec_cfg, 1426 const struct bt_bap_qos_cfg_pref *qos_pref); 1427 1428 /** @} */ /* End of group bt_bap_unicast_server */ 1429 1430 /** 1431 * @defgroup bt_bap_unicast_client BAP Unicast Client APIs 1432 * @ingroup bt_bap 1433 * @{ 1434 */ 1435 1436 /** Parameter struct for each stream in the unicast group */ 1437 struct bt_bap_unicast_group_stream_param { 1438 /** Pointer to a stream object. */ 1439 struct bt_bap_stream *stream; 1440 1441 /** The QoS settings for the stream object. */ 1442 struct bt_bap_qos_cfg *qos; 1443 }; 1444 1445 /** 1446 * @brief Parameter struct for the unicast group functions 1447 * 1448 * Parameter struct for the bt_bap_unicast_group_create() and 1449 * bt_bap_unicast_group_add_streams() functions. 1450 */ 1451 struct bt_bap_unicast_group_stream_pair_param { 1452 /** Pointer to a receiving stream parameters. */ 1453 struct bt_bap_unicast_group_stream_param *rx_param; 1454 1455 /** Pointer to a transmitting stream parameters. */ 1456 struct bt_bap_unicast_group_stream_param *tx_param; 1457 }; 1458 1459 /** Parameters for the creating unicast groups with bt_bap_unicast_group_create() */ 1460 struct bt_bap_unicast_group_param { 1461 /** The number of parameters in @p params */ 1462 size_t params_count; 1463 1464 /** Array of stream parameters */ 1465 struct bt_bap_unicast_group_stream_pair_param *params; 1466 1467 /** 1468 * @brief Unicast Group packing mode. 1469 * 1470 * @ref BT_ISO_PACKING_SEQUENTIAL or @ref BT_ISO_PACKING_INTERLEAVED. 1471 * 1472 * @note This is a recommendation to the controller, which the controller may ignore. 1473 */ 1474 uint8_t packing; 1475 1476 #if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__) 1477 /** 1478 * @brief Central to Peripheral flush timeout 1479 * 1480 * The flush timeout in multiples of ISO_Interval for each payload sent 1481 * from the Central to Peripheral. 1482 * 1483 * Value range from @ref BT_ISO_FT_MIN to @ref BT_ISO_FT_MAX 1484 */ 1485 uint8_t c_to_p_ft; 1486 1487 /** 1488 * @brief Peripheral to Central flush timeout 1489 * 1490 * The flush timeout in multiples of ISO_Interval for each payload sent 1491 * from the Peripheral to Central. 1492 * 1493 * Value range from @ref BT_ISO_FT_MIN to @ref BT_ISO_FT_MAX. 1494 */ 1495 uint8_t p_to_c_ft; 1496 1497 /** 1498 * @brief ISO interval 1499 * 1500 * Time between consecutive CIS anchor points. 1501 * 1502 * Value range from @ref BT_ISO_ISO_INTERVAL_MIN to @ref BT_ISO_ISO_INTERVAL_MAX. 1503 */ 1504 uint16_t iso_interval; 1505 #endif /* CONFIG_BT_ISO_TEST_PARAMS */ 1506 }; 1507 1508 /** 1509 * @brief Create unicast group. 1510 * 1511 * Create a new audio unicast group with one or more audio streams as a unicast client. 1512 * All streams shall share the same framing. 1513 * All streams in the same direction shall share the same interval and latency (see 1514 * @ref bt_bap_qos_cfg). 1515 * 1516 * @param[in] param The unicast group create parameters. 1517 * @param[out] unicast_group Pointer to the unicast group created. 1518 * 1519 * @return Zero on success or (negative) error code otherwise. 1520 */ 1521 int bt_bap_unicast_group_create(struct bt_bap_unicast_group_param *param, 1522 struct bt_bap_unicast_group **unicast_group); 1523 1524 /** 1525 * @brief Reconfigure unicast group. 1526 * 1527 * Reconfigure a unicast group with one or more audio streams as a unicast client. 1528 * All streams shall share the same framing. 1529 * All streams in the same direction shall share the same interval and latency (see 1530 * @ref bt_bap_qos_cfg). 1531 * All streams in @p param shall already belong to @p unicast_group. 1532 * Use bt_bap_unicast_group_add_streams() to add additional streams. 1533 * 1534 * @param unicast_group Pointer to the unicast group created. 1535 * @param param The unicast group reconfigure parameters. 1536 * 1537 * @return Zero on success or (negative) error code otherwise. 1538 */ 1539 int bt_bap_unicast_group_reconfig(struct bt_bap_unicast_group *unicast_group, 1540 const struct bt_bap_unicast_group_param *param); 1541 1542 /** 1543 * @brief Add streams to a unicast group as a unicast client 1544 * 1545 * This function can be used to add additional streams to a bt_bap_unicast_group. 1546 * 1547 * This can be called at any time before any of the streams in the group has been started 1548 * (see bt_bap_stream_ops.started()). 1549 * This can also be called after the streams have been stopped (see bt_bap_stream_ops.stopped()). 1550 * 1551 * Once a stream has been added to a unicast group, it cannot be removed. To remove a stream from a 1552 * group, the group must be deleted with bt_bap_unicast_group_delete(), but this will require all 1553 * streams in the group to be released first. 1554 * 1555 * @param unicast_group Pointer to the unicast group 1556 * @param params Array of stream parameters with streams being added to the group. 1557 * @param num_param Number of parameters in @p params. 1558 * 1559 * @return 0 in case of success or negative value in case of error. 1560 */ 1561 int bt_bap_unicast_group_add_streams(struct bt_bap_unicast_group *unicast_group, 1562 struct bt_bap_unicast_group_stream_pair_param params[], 1563 size_t num_param); 1564 1565 /** 1566 * @brief Delete audio unicast group. 1567 * 1568 * Delete a audio unicast group as a client. All streams in the group shall 1569 * be in the idle or configured state. 1570 * 1571 * @param unicast_group Pointer to the unicast group to delete 1572 * 1573 * @return Zero on success or (negative) error code otherwise. 1574 */ 1575 int bt_bap_unicast_group_delete(struct bt_bap_unicast_group *unicast_group); 1576 1577 /** Unicast Client callback structure */ 1578 struct bt_bap_unicast_client_cb { 1579 /** 1580 * @brief Remote Unicast Server Audio Locations 1581 * 1582 * This callback is called whenever the audio locations is read from 1583 * the server or otherwise notified to the client. 1584 * 1585 * @param conn Connection to the remote unicast server. 1586 * @param dir Direction of the location. 1587 * @param loc The location bitfield value. 1588 * 1589 * @return 0 in case of success or negative value in case of error. 1590 */ 1591 void (*location)(struct bt_conn *conn, enum bt_audio_dir dir, enum bt_audio_location loc); 1592 1593 /** 1594 * @brief Remote Unicast Server Available Contexts 1595 * 1596 * This callback is called whenever the available contexts are read 1597 * from the server or otherwise notified to the client. 1598 * 1599 * @param conn Connection to the remote unicast server. 1600 * @param snk_ctx The sink context bitfield value. 1601 * @param src_ctx The source context bitfield value. 1602 * 1603 * @return 0 in case of success or negative value in case of error. 1604 */ 1605 void (*available_contexts)(struct bt_conn *conn, enum bt_audio_context snk_ctx, 1606 enum bt_audio_context src_ctx); 1607 1608 /** 1609 * @brief Callback function for bt_bap_stream_config() and bt_bap_stream_reconfig(). 1610 * 1611 * Called when the codec configure operation is completed on the server. 1612 * 1613 * @param stream Stream the operation was performed on. 1614 * @param rsp_code Response code. 1615 * @param reason Reason code. 1616 */ 1617 void (*config)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1618 enum bt_bap_ascs_reason reason); 1619 1620 /** 1621 * @brief Callback function for bt_bap_stream_qos(). 1622 * 1623 * Called when the QoS configure operation is completed on the server. 1624 * This will be called for each stream in the group that was being QoS 1625 * configured. 1626 * 1627 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1628 * associated with the ASE ID sent by the server. 1629 * @param rsp_code Response code. 1630 * @param reason Reason code. 1631 */ 1632 void (*qos)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1633 enum bt_bap_ascs_reason reason); 1634 1635 /** 1636 * @brief Callback function for bt_bap_stream_enable(). 1637 * 1638 * Called when the enable operation is completed on the server. 1639 * 1640 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1641 * associated with the ASE ID sent by the server. 1642 * @param rsp_code Response code. 1643 * @param reason Reason code. 1644 */ 1645 void (*enable)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1646 enum bt_bap_ascs_reason reason); 1647 1648 /** 1649 * @brief Callback function for bt_bap_stream_start(). 1650 * 1651 * Called when the start operation is completed on the server. This will 1652 * only be called if the stream supplied to bt_bap_stream_start() is 1653 * for a @ref BT_AUDIO_DIR_SOURCE endpoint. 1654 * 1655 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1656 * associated with the ASE ID sent by the server. 1657 * @param rsp_code Response code. 1658 * @param reason Reason code. 1659 */ 1660 void (*start)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1661 enum bt_bap_ascs_reason reason); 1662 1663 /** 1664 * @brief Callback function for bt_bap_stream_stop(). 1665 * 1666 * Called when the stop operation is completed on the server. This will 1667 * only be called if the stream supplied to bt_bap_stream_stop() is 1668 * for a @ref BT_AUDIO_DIR_SOURCE endpoint. 1669 * 1670 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1671 * associated with the ASE ID sent by the server. 1672 * @param rsp_code Response code. 1673 * @param reason Reason code. 1674 */ 1675 void (*stop)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1676 enum bt_bap_ascs_reason reason); 1677 1678 /** 1679 * @brief Callback function for bt_bap_stream_disable(). 1680 * 1681 * Called when the disable operation is completed on the server. 1682 * 1683 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1684 * associated with the ASE ID sent by the server. 1685 * @param rsp_code Response code. 1686 * @param reason Reason code. 1687 */ 1688 void (*disable)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1689 enum bt_bap_ascs_reason reason); 1690 1691 /** 1692 * @brief Callback function for bt_bap_stream_metadata(). 1693 * 1694 * Called when the metadata operation is completed on the server. 1695 * 1696 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1697 * associated with the ASE ID sent by the server. 1698 * @param rsp_code Response code. 1699 * @param reason Reason code. 1700 */ 1701 void (*metadata)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1702 enum bt_bap_ascs_reason reason); 1703 1704 /** 1705 * @brief Callback function for bt_bap_stream_release(). 1706 * 1707 * Called when the release operation is completed on the server. 1708 * 1709 * @param stream Stream the operation was performed on. May be NULL if there is no stream 1710 * associated with the ASE ID sent by the server. 1711 * @param rsp_code Response code. 1712 * @param reason Reason code. 1713 */ 1714 void (*release)(struct bt_bap_stream *stream, enum bt_bap_ascs_rsp_code rsp_code, 1715 enum bt_bap_ascs_reason reason); 1716 1717 /** 1718 * @brief Remote Published Audio Capability (PAC) record discovered 1719 * 1720 * Called when a PAC record has been discovered as part of the discovery procedure. 1721 * 1722 * The @p codec is only valid while in the callback, so the values must be stored by the 1723 * receiver if future use is wanted. 1724 * 1725 * @param conn Connection to the remote unicast server. 1726 * @param dir The type of remote endpoints and capabilities discovered. 1727 * @param codec_cap Remote capabilities. 1728 * 1729 * If discovery procedure has complete both @p codec and @p ep are set to NULL. 1730 */ 1731 void (*pac_record)(struct bt_conn *conn, enum bt_audio_dir dir, 1732 const struct bt_audio_codec_cap *codec_cap); 1733 1734 /** 1735 * @brief Remote Audio Stream Endpoint (ASE) discovered 1736 * 1737 * Called when an ASE has been discovered as part of the discovery procedure. 1738 * 1739 * @param conn Connection to the remote unicast server. 1740 * @param dir The type of remote endpoints and capabilities discovered. 1741 * @param ep Remote endpoint. 1742 * 1743 * If discovery procedure has complete both @p codec and @p ep are set to NULL. 1744 */ 1745 void (*endpoint)(struct bt_conn *conn, enum bt_audio_dir dir, struct bt_bap_ep *ep); 1746 1747 /** 1748 * @brief BAP discovery callback function. 1749 * 1750 * If discovery procedure has completed @p ep is set to NULL and @p err is 0. 1751 * 1752 * @param conn Connection to the remote unicast server. 1753 * @param err Error value. 0 on success, GATT error on positive value or errno on 1754 * negative value. 1755 * @param dir The type of remote endpoints and capabilities discovered. 1756 * 1757 * If discovery procedure has complete both @p codec and @p ep are set to NULL. 1758 */ 1759 void (*discover)(struct bt_conn *conn, int err, enum bt_audio_dir dir); 1760 1761 /** @cond INTERNAL_HIDDEN */ 1762 /** Internally used field for list handling */ 1763 sys_snode_t _node; 1764 /** @endcond */ 1765 }; 1766 1767 /** 1768 * @brief Register unicast client callbacks. 1769 * 1770 * Only one callback structure can be registered, and attempting to 1771 * registering more than one will result in an error. 1772 * 1773 * @param cb Unicast client callback structure. 1774 * 1775 * @retval 0 Success 1776 * @retval -EINVAL @p cb is NULL. 1777 * @retval -EEXIST @p cb is already registered. 1778 */ 1779 int bt_bap_unicast_client_register_cb(struct bt_bap_unicast_client_cb *cb); 1780 1781 /** 1782 * @brief Discover remote capabilities and endpoints 1783 * 1784 * This procedure is used by a client to discover remote capabilities and 1785 * endpoints and notifies via params callback. 1786 * 1787 * @param conn Connection object 1788 * @param dir The type of remote endpoints and capabilities to discover. 1789 */ 1790 int bt_bap_unicast_client_discover(struct bt_conn *conn, enum bt_audio_dir dir); 1791 1792 /** @} */ /* End of group bt_bap_unicast_client */ 1793 /** 1794 * @brief BAP Broadcast APIs 1795 * @defgroup bt_bap_broadcast BAP Broadcast APIs 1796 * @ingroup bt_bap 1797 * @{ 1798 */ 1799 1800 /** @brief Abstract Broadcast Audio Source Endpoint (BASE) subgroup structure. */ 1801 struct bt_bap_base_subgroup; 1802 /** @brief Abstract Broadcast Audio Source Endpoint (BASE) structure. */ 1803 struct bt_bap_base; 1804 1805 /** Codec ID structure for a Broadcast Audio Source Endpoint (BASE) */ 1806 struct bt_bap_base_codec_id { 1807 /** Codec ID */ 1808 uint8_t id; 1809 /** Codec Company ID */ 1810 uint16_t cid; 1811 /** Codec Company Vendor ID */ 1812 uint16_t vid; 1813 }; 1814 1815 /** BIS structure for each BIS in a Broadcast Audio Source Endpoint (BASE) subgroup */ 1816 struct bt_bap_base_subgroup_bis { 1817 /** Unique index of the BIS */ 1818 uint8_t index; 1819 /** Codec Specific Data length. */ 1820 uint8_t data_len; 1821 /** Codec Specific Data */ 1822 uint8_t *data; 1823 }; 1824 1825 /** 1826 * @brief Generate a pointer to a BASE from periodic advertising data 1827 * 1828 * @param ad The periodic advertising data 1829 * 1830 * @retval NULL if the data does not contain a BASE 1831 * @retval Pointer to a bt_bap_base structure 1832 */ 1833 const struct bt_bap_base *bt_bap_base_get_base_from_ad(const struct bt_data *ad); 1834 1835 /** 1836 * @brief Get the size of a BASE 1837 * 1838 * @param base The BASE pointer 1839 * 1840 * @retval -EINVAL if arguments are invalid 1841 * @retval The size of the BASE 1842 */ 1843 int bt_bap_base_get_size(const struct bt_bap_base *base); 1844 1845 /** 1846 * @brief Get the presentation delay value of a BASE 1847 * 1848 * @param base The BASE pointer 1849 * 1850 * @retval -EINVAL if arguments are invalid 1851 * @retval The 24-bit presentation delay value 1852 */ 1853 int bt_bap_base_get_pres_delay(const struct bt_bap_base *base); 1854 1855 /** 1856 * @brief Get the subgroup count of a BASE 1857 * 1858 * @param base The BASE pointer 1859 * 1860 * @retval -EINVAL if arguments are invalid 1861 * @retval The 8-bit subgroup count value 1862 */ 1863 int bt_bap_base_get_subgroup_count(const struct bt_bap_base *base); 1864 1865 /** 1866 * @brief Get all BIS indexes of a BASE 1867 * 1868 * @param[in] base The BASE pointer 1869 * @param[out] bis_indexes 32-bit BIS index bitfield that will be populated 1870 * 1871 * @retval -EINVAL if arguments are invalid 1872 * @retval 0 on success 1873 */ 1874 int bt_bap_base_get_bis_indexes(const struct bt_bap_base *base, uint32_t *bis_indexes); 1875 1876 /** 1877 * @brief Iterate on all subgroups in the BASE 1878 * 1879 * @param base The BASE pointer 1880 * @param func Callback function. Return true to continue iterating, or false to stop. 1881 * @param user_data Userdata supplied to @p func 1882 * 1883 * @retval -EINVAL if arguments are invalid 1884 * @retval -ECANCELED if iterating over the subgroups stopped prematurely by @p func 1885 * @retval 0 if all subgroups were iterated 1886 */ 1887 int bt_bap_base_foreach_subgroup(const struct bt_bap_base *base, 1888 bool (*func)(const struct bt_bap_base_subgroup *subgroup, 1889 void *user_data), 1890 void *user_data); 1891 1892 /** 1893 * @brief Get the codec ID of a subgroup 1894 * 1895 * @param[in] subgroup The subgroup pointer 1896 * @param[out] codec_id Pointer to the struct where the results are placed 1897 * 1898 * @retval -EINVAL if arguments are invalid 1899 * @retval 0 on success 1900 */ 1901 int bt_bap_base_get_subgroup_codec_id(const struct bt_bap_base_subgroup *subgroup, 1902 struct bt_bap_base_codec_id *codec_id); 1903 1904 /** 1905 * @brief Get the codec configuration data of a subgroup 1906 * 1907 * @param[in] subgroup The subgroup pointer 1908 * @param[out] data Pointer that will point to the resulting codec configuration data 1909 * 1910 * @retval -EINVAL if arguments are invalid 1911 * @retval 0 on success 1912 */ 1913 int bt_bap_base_get_subgroup_codec_data(const struct bt_bap_base_subgroup *subgroup, 1914 uint8_t **data); 1915 1916 /** 1917 * @brief Get the codec metadata of a subgroup 1918 * 1919 * @param[in] subgroup The subgroup pointer 1920 * @param[out] meta Pointer that will point to the resulting codec metadata 1921 * 1922 * @retval -EINVAL if arguments are invalid 1923 * @retval 0 on success 1924 */ 1925 int bt_bap_base_get_subgroup_codec_meta(const struct bt_bap_base_subgroup *subgroup, 1926 uint8_t **meta); 1927 1928 /** 1929 * @brief Store subgroup codec data in a @ref bt_audio_codec_cfg 1930 * 1931 * @param[in] subgroup The subgroup pointer 1932 * @param[out] codec_cfg Pointer to the struct where the results are placed 1933 * 1934 * @retval -EINVAL if arguments are invalid 1935 * @retval -ENOMEM if the @p codec_cfg cannot store the @p subgroup codec data 1936 * @retval 0 on success 1937 */ 1938 int bt_bap_base_subgroup_codec_to_codec_cfg(const struct bt_bap_base_subgroup *subgroup, 1939 struct bt_audio_codec_cfg *codec_cfg); 1940 1941 /** 1942 * @brief Get the BIS count of a subgroup 1943 * 1944 * @param subgroup The subgroup pointer 1945 * 1946 * @retval -EINVAL if arguments are invalid 1947 * @retval The 8-bit BIS count value 1948 */ 1949 int bt_bap_base_get_subgroup_bis_count(const struct bt_bap_base_subgroup *subgroup); 1950 1951 /** 1952 * @brief Get all BIS indexes of a subgroup 1953 * 1954 * @param[in] subgroup The subgroup pointer 1955 * @param[out] bis_indexes 32-bit BIS index bitfield that will be populated 1956 * 1957 * @retval -EINVAL if arguments are invalid 1958 * @retval 0 on success 1959 */ 1960 int bt_bap_base_subgroup_get_bis_indexes(const struct bt_bap_base_subgroup *subgroup, 1961 uint32_t *bis_indexes); 1962 1963 /** 1964 * @brief Iterate on all BIS in the subgroup 1965 * 1966 * @param subgroup The subgroup pointer 1967 * @param func Callback function. Return true to continue iterating, or false to stop. 1968 * @param user_data Userdata supplied to @p func 1969 * 1970 * @retval -EINVAL if arguments are invalid 1971 * @retval -ECANCELED if iterating over the subgroups stopped prematurely by @p func 1972 * @retval 0 if all BIS were iterated 1973 */ 1974 int bt_bap_base_subgroup_foreach_bis(const struct bt_bap_base_subgroup *subgroup, 1975 bool (*func)(const struct bt_bap_base_subgroup_bis *bis, 1976 void *user_data), 1977 void *user_data); 1978 1979 /** 1980 * @brief Store BIS codec configuration data in a @ref bt_audio_codec_cfg 1981 * 1982 * This only sets the @ref bt_audio_codec_cfg data and @ref bt_audio_codec_cfg data_len, but is 1983 * useful to use the BIS codec configuration data with the bt_audio_codec_cfg_* functions. 1984 * 1985 * @param[in] bis The BIS pointer 1986 * @param[out] codec_cfg Pointer to the struct where the results are placed 1987 * 1988 * @retval -EINVAL if arguments are invalid 1989 * @retval -ENOMEM if the @p codec_cfg cannot store the @p subgroup codec data 1990 * @retval 0 on success 1991 */ 1992 int bt_bap_base_subgroup_bis_codec_to_codec_cfg(const struct bt_bap_base_subgroup_bis *bis, 1993 struct bt_audio_codec_cfg *codec_cfg); 1994 1995 /** @} */ /* End of group bt_bap_broadcast */ 1996 1997 /** 1998 * @brief BAP Broadcast Source APIs 1999 * @defgroup bt_bap_broadcast_source BAP Broadcast Source APIs 2000 * @ingroup bt_bap_broadcast 2001 * @{ 2002 */ 2003 2004 /** 2005 * @brief Struct to hold the Broadcast Source callbacks 2006 * 2007 * These can be registered for usage with bt_bap_broadcast_source_register_cb(). 2008 */ 2009 struct bt_bap_broadcast_source_cb { 2010 /** 2011 * @brief The Broadcast Source has started and all of the streams are ready for audio data 2012 * 2013 * @param source The started Broadcast Source 2014 */ 2015 void (*started)(struct bt_bap_broadcast_source *source); 2016 2017 /** 2018 * @brief The Broadcast Source has stopped and none of the streams are ready for audio data 2019 * 2020 * @param source The stopped Broadcast Source 2021 * @param reason The reason why the Broadcast Source stopped (see the BT_HCI_ERR_* values) 2022 */ 2023 void (*stopped)(struct bt_bap_broadcast_source *source, uint8_t reason); 2024 2025 /** @internal Internally used field for list handling */ 2026 sys_snode_t _node; 2027 }; 2028 2029 /** 2030 * @brief Registers callbacks for Broadcast Sources 2031 * 2032 * @param cb Pointer to the callback structure. 2033 * 2034 * @retval 0 on success 2035 * @retval -EINVAL if @p cb is NULL 2036 * @retval -EEXIST if @p cb is already registered 2037 */ 2038 int bt_bap_broadcast_source_register_cb(struct bt_bap_broadcast_source_cb *cb); 2039 2040 /** 2041 * @brief Unregisters callbacks for Broadcast Sources 2042 * 2043 * @param cb Pointer to the callback structure. 2044 * 2045 * @retval 0 on success 2046 * @retval -EINVAL if @p cb is NULL 2047 * @retval -ENOENT if @p cb is not registered 2048 */ 2049 int bt_bap_broadcast_source_unregister_cb(struct bt_bap_broadcast_source_cb *cb); 2050 2051 /** Broadcast Source stream parameters */ 2052 struct bt_bap_broadcast_source_stream_param { 2053 /** Audio stream */ 2054 struct bt_bap_stream *stream; 2055 2056 #if CONFIG_BT_AUDIO_CODEC_CFG_MAX_DATA_SIZE > 0 || defined(__DOXYGEN__) 2057 /** 2058 * @brief The number of elements in the @p data array. 2059 * 2060 * The BIS specific data may be omitted and this set to 0. 2061 */ 2062 size_t data_len; 2063 2064 /** BIS Codec Specific Configuration */ 2065 uint8_t *data; 2066 #endif /* CONFIG_BT_AUDIO_CODEC_CFG_MAX_DATA_SIZE > 0 */ 2067 }; 2068 2069 /** Broadcast Source subgroup parameters*/ 2070 struct bt_bap_broadcast_source_subgroup_param { 2071 /** The number of parameters in @p stream_params */ 2072 size_t params_count; 2073 2074 /** Array of stream parameters */ 2075 struct bt_bap_broadcast_source_stream_param *params; 2076 2077 /** Subgroup Codec configuration. */ 2078 struct bt_audio_codec_cfg *codec_cfg; 2079 }; 2080 2081 /** Broadcast Source create parameters */ 2082 struct bt_bap_broadcast_source_param { 2083 /** The number of parameters in @p subgroup_params */ 2084 size_t params_count; 2085 2086 /** Array of stream parameters */ 2087 struct bt_bap_broadcast_source_subgroup_param *params; 2088 2089 /** Quality of Service configuration. */ 2090 struct bt_bap_qos_cfg *qos; 2091 2092 /** 2093 * @brief Broadcast Source packing mode. 2094 * 2095 * @ref BT_ISO_PACKING_SEQUENTIAL or @ref BT_ISO_PACKING_INTERLEAVED. 2096 * 2097 * @note This is a recommendation to the controller, which the controller may ignore. 2098 */ 2099 uint8_t packing; 2100 2101 /** Whether or not to encrypt the streams. */ 2102 bool encryption; 2103 2104 /** 2105 * @brief Broadcast code 2106 * 2107 * If the value is a string or a the value is less than 16 octets, 2108 * the remaining octets shall be 0. 2109 * 2110 * Example: 2111 * The string "Broadcast Code" shall be 2112 * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00] 2113 */ 2114 uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE]; 2115 2116 #if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__) 2117 /** 2118 * @brief Immediate Repetition Count 2119 * 2120 * The number of times the scheduled payloads are transmitted in a given event. 2121 * 2122 * Value range from @ref BT_ISO_IRC_MIN to @ref BT_ISO_IRC_MAX. 2123 */ 2124 uint8_t irc; 2125 2126 /** 2127 * @brief Pre-transmission offset 2128 * 2129 * Offset used for pre-transmissions. 2130 * 2131 * Value range from @ref BT_ISO_PTO_MIN to @ref BT_ISO_PTO_MAX. 2132 */ 2133 uint8_t pto; 2134 2135 /** 2136 * @brief ISO interval 2137 * 2138 * Time between consecutive BIS anchor points. 2139 * 2140 * Value range from @ref BT_ISO_ISO_INTERVAL_MIN to @ref BT_ISO_ISO_INTERVAL_MAX. 2141 */ 2142 uint16_t iso_interval; 2143 #endif /* CONFIG_BT_ISO_TEST_PARAMS */ 2144 }; 2145 2146 /** 2147 * @brief Create audio broadcast source. 2148 * 2149 * Create a new audio broadcast source with one or more audio streams. 2150 * 2151 * The broadcast source will be visible for scanners once this has been called, 2152 * and the device will advertise audio announcements. 2153 * 2154 * No audio data can be sent until bt_bap_broadcast_source_start() has been called and no audio 2155 * information (BIGInfo) will be visible to scanners (see @ref bt_le_per_adv_sync_cb). 2156 * 2157 * @param[in] param Pointer to parameters used to create the broadcast source. 2158 * @param[out] source Pointer to the broadcast source created 2159 * 2160 * @return Zero on success or (negative) error code otherwise. 2161 */ 2162 int bt_bap_broadcast_source_create(struct bt_bap_broadcast_source_param *param, 2163 struct bt_bap_broadcast_source **source); 2164 2165 /** 2166 * @brief Reconfigure audio broadcast source. 2167 * 2168 * Reconfigure an audio broadcast source with a new codec and codec quality of 2169 * service parameters. This can only be done when the source is stopped. 2170 * 2171 * Since this may modify the Broadcast Audio Source Endpoint (BASE), 2172 * bt_bap_broadcast_source_get_base() should be called after this to get the new BASE information. 2173 * 2174 * If the @p param.params_count is smaller than the number of subgroups that have been created in 2175 * the Broadcast Source, only the first @p param.params_count subgroups are updated. If a stream 2176 * exist in a subgroup not part of @p param, then that stream is left as is (i.e. it is not removed; 2177 * the only way to remove a stream from a Broadcast Source is to recreate the Broadcast Source). 2178 * 2179 * @param source Pointer to the broadcast source 2180 * @param param Pointer to parameters used to reconfigure the broadcast source. 2181 * 2182 * @return Zero on success or (negative) error code otherwise. 2183 */ 2184 int bt_bap_broadcast_source_reconfig(struct bt_bap_broadcast_source *source, 2185 struct bt_bap_broadcast_source_param *param); 2186 2187 /** 2188 * @brief Modify the metadata of an audio broadcast source. 2189 * 2190 * Modify the metadata an audio broadcast source. This can only be done when the source is started. 2191 * To update the metadata in the stopped state, use bt_bap_broadcast_source_reconfig(). 2192 * 2193 * @param source Pointer to the broadcast source. 2194 * @param meta Metadata. 2195 * @param meta_len Length of metadata. 2196 * 2197 * @return Zero on success or (negative) error code otherwise. 2198 */ 2199 int bt_bap_broadcast_source_update_metadata(struct bt_bap_broadcast_source *source, 2200 const uint8_t meta[], size_t meta_len); 2201 2202 /** 2203 * @brief Start audio broadcast source. 2204 * 2205 * Start an audio broadcast source with one or more audio streams. 2206 * The broadcast source will start advertising BIGInfo, and audio data can be streamed. 2207 * 2208 * @param source Pointer to the broadcast source 2209 * @param adv Pointer to an extended advertising set with periodic advertising configured. 2210 * 2211 * @return Zero on success or (negative) error code otherwise. 2212 */ 2213 int bt_bap_broadcast_source_start(struct bt_bap_broadcast_source *source, 2214 struct bt_le_ext_adv *adv); 2215 2216 /** 2217 * @brief Stop audio broadcast source. 2218 * 2219 * Stop an audio broadcast source. 2220 * The broadcast source will stop advertising BIGInfo, and audio data can no longer be streamed. 2221 * 2222 * @param source Pointer to the broadcast source 2223 * 2224 * @return Zero on success or (negative) error code otherwise. 2225 */ 2226 int bt_bap_broadcast_source_stop(struct bt_bap_broadcast_source *source); 2227 2228 /** 2229 * @brief Delete audio broadcast source. 2230 * 2231 * Delete an audio broadcast source. 2232 * The broadcast source will stop advertising entirely, and the source can no longer be used. 2233 * 2234 * @param source Pointer to the broadcast source 2235 * 2236 * @return Zero on success or (negative) error code otherwise. 2237 */ 2238 int bt_bap_broadcast_source_delete(struct bt_bap_broadcast_source *source); 2239 2240 /** 2241 * @brief Get the Broadcast Audio Stream Endpoint of a broadcast source 2242 * 2243 * This will encode the BASE of a broadcast source into a buffer, that can be used for 2244 * advertisement. The encoded BASE will thus be encoded as little-endian. The BASE shall be put into 2245 * the periodic advertising data (see bt_le_per_adv_set_data()). 2246 * 2247 * See table 3.15 in the Basic Audio Profile v1.0.1 for the structure. 2248 * 2249 * @param source Pointer to the broadcast source. 2250 * @param base_buf Pointer to a buffer where the BASE will be inserted. 2251 * 2252 * @return Zero on success or (negative) error code otherwise. 2253 */ 2254 int bt_bap_broadcast_source_get_base(struct bt_bap_broadcast_source *source, 2255 struct net_buf_simple *base_buf); 2256 2257 /** @} */ /* End of bt_bap_broadcast_source */ 2258 2259 /** 2260 * @brief BAP Broadcast Sink APIs 2261 * @defgroup bt_bap_broadcast_sink BAP Broadcast Sink APIs 2262 * @ingroup bt_bap_broadcast 2263 * @{ 2264 */ 2265 2266 /** Broadcast Audio Sink callback structure */ 2267 struct bt_bap_broadcast_sink_cb { 2268 /** 2269 * @brief Broadcast Audio Source Endpoint (BASE) received 2270 * 2271 * Callback for when we receive a BASE from a broadcaster after 2272 * syncing to the broadcaster's periodic advertising. 2273 * 2274 * @param sink Pointer to the sink structure. 2275 * @param base Broadcast Audio Source Endpoint (BASE). 2276 * @param base_size Size of the @p base 2277 */ 2278 void (*base_recv)(struct bt_bap_broadcast_sink *sink, const struct bt_bap_base *base, 2279 size_t base_size); 2280 2281 /** 2282 * @brief Broadcast sink is syncable 2283 * 2284 * Called whenever a broadcast sink is not synchronized to audio, but the audio is 2285 * synchronizable. This is inferred when a BIGInfo report is received. 2286 * 2287 * Once this callback has been called, it is possible to call 2288 * bt_bap_broadcast_sink_sync() to synchronize to the audio stream(s). 2289 * 2290 * @param sink Pointer to the sink structure. 2291 * @param biginfo The BIGInfo report. 2292 */ 2293 void (*syncable)(struct bt_bap_broadcast_sink *sink, const struct bt_iso_biginfo *biginfo); 2294 2295 /** 2296 * @brief The Broadcast Sink has started and audio data may be received from all of the 2297 * streams 2298 * 2299 * @param sink The started Broadcast Sink 2300 */ 2301 void (*started)(struct bt_bap_broadcast_sink *sink); 2302 2303 /** 2304 * @brief The Broadcast Sink has stopped and none of the streams will receive audio data 2305 * 2306 * @param sink The stopped Broadcast Sink 2307 * @param reason The reason why the Broadcast Sink stopped (see the BT_HCI_ERR_* values) 2308 */ 2309 void (*stopped)(struct bt_bap_broadcast_sink *sink, uint8_t reason); 2310 2311 /** @internal Internally used list node */ 2312 sys_snode_t _node; 2313 }; 2314 2315 /** 2316 * @brief Register Broadcast sink callbacks 2317 * 2318 * It is possible to register multiple struct of callbacks, but a single struct can only be 2319 * registered once. 2320 * Registering the same callback multiple times is undefined behavior and may break the stack. 2321 2322 * @param cb Broadcast sink callback structure. 2323 * 2324 * @retval 0 on success 2325 * @retval -EINVAL if @p cb is NULL 2326 * @retval -EALREADY if @p cb was already registered 2327 */ 2328 int bt_bap_broadcast_sink_register_cb(struct bt_bap_broadcast_sink_cb *cb); 2329 2330 /** 2331 * @brief Create a Broadcast Sink from a periodic advertising sync 2332 * 2333 * This should only be done after verifying that the periodic advertising sync 2334 * is from a Broadcast Source. 2335 * 2336 * The created Broadcast Sink will need to be supplied to 2337 * bt_bap_broadcast_sink_sync() in order to synchronize to the broadcast audio. 2338 * 2339 * bt_bap_broadcast_sink_cb.pa_synced() will be called with the Broadcast 2340 * Sink object created if this is successful. 2341 * 2342 * @param pa_sync Pointer to the periodic advertising sync object. 2343 * @param broadcast_id 24-bit broadcast ID. 2344 * @param[out] sink Pointer to the Broadcast Sink created. 2345 * 2346 * @return 0 in case of success or errno value in case of error. 2347 */ 2348 int bt_bap_broadcast_sink_create(struct bt_le_per_adv_sync *pa_sync, uint32_t broadcast_id, 2349 struct bt_bap_broadcast_sink **sink); 2350 2351 /** 2352 * @brief Sync to a broadcaster's audio 2353 * 2354 * @param sink Pointer to the sink object from the base_recv callback. 2355 * @param indexes_bitfield Bitfield of the BIS index to sync to. To sync to e.g. BIS index 1 and 2356 * 2, this should have the value of BIT(1) | BIT(2). 2357 * @param streams Stream object pointers to be used for the receiver. If multiple BIS 2358 * indexes shall be synchronized, multiple streams shall be provided. 2359 * @param broadcast_code The 16-octet broadcast code. Shall be supplied if the broadcast is 2360 * encrypted (see @ref bt_bap_broadcast_sink_cb.syncable). 2361 * If the value is a string or a the value is less 2362 * than 16 octets, the remaining octets shall be 0. 2363 * 2364 * Example: 2365 * The string "Broadcast Code" shall be 2366 * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00] 2367 * 2368 * @return 0 in case of success or negative value in case of error. 2369 */ 2370 int bt_bap_broadcast_sink_sync(struct bt_bap_broadcast_sink *sink, uint32_t indexes_bitfield, 2371 struct bt_bap_stream *streams[], 2372 const uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE]); 2373 2374 /** 2375 * @brief Stop audio broadcast sink. 2376 * 2377 * Stop an audio broadcast sink. 2378 * The broadcast sink will stop receiving BIGInfo, and audio data can no longer be streamed. 2379 * 2380 * @param sink Pointer to the broadcast sink 2381 * 2382 * @return Zero on success or (negative) error code otherwise. 2383 */ 2384 int bt_bap_broadcast_sink_stop(struct bt_bap_broadcast_sink *sink); 2385 2386 /** 2387 * @brief Release a broadcast sink 2388 * 2389 * Once a broadcast sink has been allocated after the pa_synced callback, it can be deleted using 2390 * this function. If the sink has synchronized to any broadcast audio streams, these must first be 2391 * stopped using bt_bap_stream_stop. 2392 * 2393 * @param sink Pointer to the sink object to delete. 2394 * 2395 * @return 0 in case of success or negative value in case of error. 2396 */ 2397 int bt_bap_broadcast_sink_delete(struct bt_bap_broadcast_sink *sink); 2398 2399 /** @} */ /* End of group bt_bap_broadcast_sink */ 2400 2401 /** 2402 * @brief Register the Basic Audio Profile Scan Delegator and BASS. 2403 * 2404 * Register the scan deligator and Broadcast Audio Scan Service (BASS) 2405 * dynamically at runtime. 2406 * 2407 * Only one set of callbacks can be registered at any one time, and calling this function multiple 2408 * times will override any previously registered callbacks. 2409 * 2410 * @param cb Pointer to the callback struct 2411 * 2412 * @return 0 in case of success or negative value in case of error. 2413 */ 2414 int bt_bap_scan_delegator_register(struct bt_bap_scan_delegator_cb *cb); 2415 2416 /** 2417 * @brief unregister the Basic Audio Profile Scan Delegator and BASS. 2418 * 2419 * Unregister the scan deligator and Broadcast Audio Scan Service (BASS) 2420 * dynamically at runtime. 2421 * 2422 * @return 0 in case of success or negative value in case of error. 2423 */ 2424 int bt_bap_scan_delegator_unregister(void); 2425 2426 /** 2427 * @brief Set the periodic advertising sync state to syncing 2428 * 2429 * Set the periodic advertising sync state for a receive state to syncing, 2430 * notifying Broadcast Assistants. 2431 * 2432 * @param src_id The source id used to identify the receive state. 2433 * @param pa_state The Periodic Advertising sync state to set. 2434 * BT_BAP_PA_STATE_NOT_SYNCED and BT_BAP_PA_STATE_SYNCED is 2435 * not necessary to provide, as they are handled internally. 2436 * 2437 * @return int Error value. 0 on success, errno on fail. 2438 */ 2439 int bt_bap_scan_delegator_set_pa_state(uint8_t src_id, 2440 enum bt_bap_pa_state pa_state); 2441 2442 /** 2443 * @brief Set the sync state of a receive state in the server 2444 * 2445 * @param src_id The source id used to identify the receive state. 2446 * @param bis_synced Array of bitfields to set the BIS sync state for each 2447 * subgroup. 2448 * @return int Error value. 0 on success, ERRNO on fail. 2449 */ 2450 int bt_bap_scan_delegator_set_bis_sync_state(uint8_t src_id, 2451 uint32_t bis_synced[BT_BAP_BASS_MAX_SUBGROUPS]); 2452 2453 /** Parameters for bt_bap_scan_delegator_add_src() */ 2454 struct bt_bap_scan_delegator_add_src_param { 2455 /** Periodic Advertiser Address */ 2456 bt_addr_le_t addr; 2457 2458 /** Advertiser SID */ 2459 uint8_t sid; 2460 2461 /** The broadcast isochronous group encryption state */ 2462 enum bt_bap_big_enc_state encrypt_state; 2463 2464 /** The 24-bit broadcast ID */ 2465 uint32_t broadcast_id; 2466 2467 /** Number of subgroups */ 2468 uint8_t num_subgroups; 2469 2470 /** Subgroup specific information */ 2471 struct bt_bap_bass_subgroup subgroups[BT_BAP_BASS_MAX_SUBGROUPS]; 2472 }; 2473 2474 /** 2475 * @brief Add a receive state source locally 2476 * 2477 * This will notify any connected clients about the new source. This allows them 2478 * to modify and even remove it. 2479 * 2480 * If @kconfig{CONFIG_BT_BAP_BROADCAST_SINK} is enabled, any Broadcast Sink 2481 * sources are autonomously added. 2482 * 2483 * @param param The parameters for adding the new source 2484 * 2485 * @return int errno on failure, or source ID on success. 2486 */ 2487 int bt_bap_scan_delegator_add_src(const struct bt_bap_scan_delegator_add_src_param *param); 2488 2489 /** Parameters for bt_bap_scan_delegator_mod_src() */ 2490 struct bt_bap_scan_delegator_mod_src_param { 2491 /** The periodic adverting sync */ 2492 uint8_t src_id; 2493 2494 /** The broadcast isochronous group encryption state */ 2495 enum bt_bap_big_enc_state encrypt_state; 2496 2497 /** The 24-bit broadcast ID */ 2498 uint32_t broadcast_id; 2499 2500 /** Number of subgroups */ 2501 uint8_t num_subgroups; 2502 2503 /** 2504 * @brief Subgroup specific information 2505 * 2506 * If a subgroup's metadata_len is set to 0, the existing metadata 2507 * for the subgroup will remain unchanged 2508 */ 2509 struct bt_bap_bass_subgroup subgroups[BT_BAP_BASS_MAX_SUBGROUPS]; 2510 }; 2511 2512 /** 2513 * @brief Add a receive state source locally 2514 * 2515 * This will notify any connected clients about the new source. This allows them 2516 * to modify and even remove it. 2517 * 2518 * If @kconfig{CONFIG_BT_BAP_BROADCAST_SINK} is enabled, any Broadcast Sink 2519 * sources are autonomously modified. 2520 * 2521 * @param param The parameters for adding the new source 2522 * 2523 * @return int errno on failure, or source ID on success. 2524 */ 2525 int bt_bap_scan_delegator_mod_src(const struct bt_bap_scan_delegator_mod_src_param *param); 2526 2527 /** 2528 * @brief Remove a receive state source 2529 * 2530 * This will remove the receive state. If the receive state periodic advertising 2531 * is synced, bt_bap_scan_delegator_cb.pa_sync_term_req() will be called. 2532 * 2533 * If @kconfig{CONFIG_BT_BAP_BROADCAST_SINK} is enabled, any Broadcast Sink 2534 * sources are autonomously removed. 2535 * 2536 * @param src_id The source ID to remove 2537 * 2538 * @return int Error value. 0 on success, errno on fail. 2539 */ 2540 int bt_bap_scan_delegator_rem_src(uint8_t src_id); 2541 2542 /** Callback function for Scan Delegator receive state search functions 2543 * 2544 * @param recv_state The receive state. 2545 * @param user_data User data. 2546 * 2547 * @retval true to stop iterating. If this is used in the context of 2548 * bt_bap_scan_delegator_find_state(), the recv_state will be returned by 2549 * bt_bap_scan_delegator_find_state() 2550 * @retval false to continue iterating 2551 */ 2552 typedef bool (*bt_bap_scan_delegator_state_func_t)( 2553 const struct bt_bap_scan_delegator_recv_state *recv_state, void *user_data); 2554 2555 /** 2556 * @brief Iterate through all existing receive states 2557 * 2558 * @param func The callback function 2559 * @param user_data User specified data that sent to the callback function 2560 */ 2561 void bt_bap_scan_delegator_foreach_state(bt_bap_scan_delegator_state_func_t func, 2562 void *user_data); 2563 2564 /** 2565 * @brief Find and return a receive state based on a compare function 2566 * 2567 * @param func The compare callback function 2568 * @param user_data User specified data that sent to the callback function 2569 * 2570 * @return The first receive state where the @p func returned true, or NULL 2571 */ 2572 const struct bt_bap_scan_delegator_recv_state *bt_bap_scan_delegator_find_state( 2573 bt_bap_scan_delegator_state_func_t func, void *user_data); 2574 2575 /******************************** CLIENT API ********************************/ 2576 2577 /** 2578 * @brief Callback function for writes. 2579 * 2580 * @param conn The connection to the peer device. 2581 * @param err Error value. 0 on success, GATT error on fail. 2582 */ 2583 typedef void (*bt_bap_broadcast_assistant_write_cb)(struct bt_conn *conn, 2584 int err); 2585 2586 /** 2587 * @brief Struct to hold the Basic Audio Profile Broadcast Assistant callbacks 2588 * 2589 * These can be registered for usage with bt_bap_broadcast_assistant_register_cb(). 2590 */ 2591 struct bt_bap_broadcast_assistant_cb { 2592 /** 2593 * @brief Callback function for bt_bap_broadcast_assistant_discover. 2594 * 2595 * @param conn The connection that was used to discover 2596 * Broadcast Audio Scan Service. 2597 * @param err Error value. 0 on success, 2598 * GATT error or ERRNO on fail. 2599 * @param recv_state_count Number of receive states on the server. 2600 */ 2601 void (*discover)(struct bt_conn *conn, int err, 2602 uint8_t recv_state_count); 2603 2604 /** 2605 * @brief Callback function for Broadcast Audio Scan Service client scan results 2606 * 2607 * Called when the scanner finds an advertiser that advertises the 2608 * BT_UUID_BROADCAST_AUDIO UUID. 2609 * 2610 * @param info Advertiser information. 2611 * @param broadcast_id 24-bit broadcast ID. 2612 */ 2613 void (*scan)(const struct bt_le_scan_recv_info *info, 2614 uint32_t broadcast_id); 2615 2616 /** 2617 * @brief Callback function for when a receive state is read or updated 2618 * 2619 * Called whenever a receive state is read or updated. 2620 * 2621 * @param conn The connection to the Broadcast Audio Scan Service server. 2622 * @param err Error value. 0 on success, GATT error on fail. 2623 * @param state The receive state or NULL if the receive state is empty. 2624 */ 2625 void (*recv_state)(struct bt_conn *conn, int err, 2626 const struct bt_bap_scan_delegator_recv_state *state); 2627 2628 /** 2629 * @brief Callback function for when a receive state is removed. 2630 * 2631 * @param conn The connection to the Broadcast Audio Scan Service server. 2632 * @param src_id The receive state. 2633 */ 2634 void (*recv_state_removed)(struct bt_conn *conn, uint8_t src_id); 2635 2636 /** 2637 * @brief Callback function for bt_bap_broadcast_assistant_scan_start(). 2638 * 2639 * @param conn The connection to the peer device. 2640 * @param err Error value. 0 on success, GATT error on fail. 2641 */ 2642 void (*scan_start)(struct bt_conn *conn, int err); 2643 2644 /** 2645 * @brief Callback function for bt_bap_broadcast_assistant_scan_stop(). 2646 * 2647 * @param conn The connection to the peer device. 2648 * @param err Error value. 0 on success, GATT error on fail. 2649 */ 2650 void (*scan_stop)(struct bt_conn *conn, int err); 2651 2652 /** 2653 * @brief Callback function for bt_bap_broadcast_assistant_add_src(). 2654 * 2655 * @param conn The connection to the peer device. 2656 * @param err Error value. 0 on success, GATT error on fail. 2657 */ 2658 void (*add_src)(struct bt_conn *conn, int err); 2659 2660 /** 2661 * @brief Callback function for bt_bap_broadcast_assistant_mod_src(). 2662 * 2663 * @param conn The connection to the peer device. 2664 * @param err Error value. 0 on success, GATT error on fail. 2665 */ 2666 void (*mod_src)(struct bt_conn *conn, int err); 2667 2668 /** 2669 * @brief Callback function for bt_bap_broadcast_assistant_set_broadcast_code(). 2670 * 2671 * @param conn The connection to the peer device. 2672 * @param err Error value. 0 on success, GATT error on fail. 2673 */ 2674 void (*broadcast_code)(struct bt_conn *conn, int err); 2675 2676 /** 2677 * @brief Callback function for bt_bap_broadcast_assistant_rem_src(). 2678 * 2679 * @param conn The connection to the peer device. 2680 * @param err Error value. 0 on success, GATT error on fail. 2681 */ 2682 void (*rem_src)(struct bt_conn *conn, int err); 2683 2684 /** @internal Internally used list node */ 2685 sys_snode_t _node; 2686 }; 2687 2688 /** 2689 * @brief Discover Broadcast Audio Scan Service on the server. 2690 * 2691 * Warning: Only one connection can be active at any time; discovering for a 2692 * new connection, will delete all previous data. 2693 * 2694 * @param conn The connection 2695 * 2696 * @retval 0 Success 2697 * @retval -EINVAL @p conn is NULL 2698 * @retval -EBUSY Another operation is already in progress for this @p conn 2699 * @retval -ENOTCONN @p conn is not connected 2700 * @retval -ENOMEM Could not allocated memory for the request 2701 * @retval -ENOEXEC Unexpected GATT error 2702 */ 2703 int bt_bap_broadcast_assistant_discover(struct bt_conn *conn); 2704 2705 /** 2706 * @brief Scan start for BISes for a remote server. 2707 * 2708 * This will let the Broadcast Audio Scan Service server know that this device 2709 * is actively scanning for broadcast sources. 2710 * The function can optionally also start scanning, if the caller does not want 2711 * to start scanning itself. 2712 * 2713 * Scan results, if @p start_scan is true, is sent to the 2714 * bt_bap_broadcast_assistant_scan_cb callback. 2715 * 2716 * @param conn Connection to the Broadcast Audio Scan Service server. 2717 * Used to let the server know that we are scanning. 2718 * @param start_scan Start scanning if true. If false, the application should 2719 * enable scan itself. 2720 2721 * @retval 0 Success 2722 * @retval -EINVAL @p conn is NULL of if @p conn has not done discovery 2723 * @retval -EBUSY Another operation is already in progress for this @p conn 2724 * @retval -EAGAIN Bluetooth has not been enabled. 2725 * @retval -ENOTCONN @p conn is not connected 2726 * @retval -ENOMEM Could not allocated memory for the request 2727 * @retval -ENOEXEC Unexpected scan or GATT error 2728 */ 2729 int bt_bap_broadcast_assistant_scan_start(struct bt_conn *conn, 2730 bool start_scan); 2731 2732 /** 2733 * @brief Stop remote scanning for BISes for a server. 2734 * 2735 * @param conn Connection to the server. 2736 2737 * @retval 0 Success 2738 * @retval -EINVAL @p conn is NULL of if @p conn has not done discovery 2739 * @retval -EBUSY Another operation is already in progress for this @p conn 2740 * @retval -EAGAIN Bluetooth has not been enabled. 2741 * @retval -ENOTCONN @p conn is not connected 2742 * @retval -ENOMEM Could not allocated memory for the request 2743 * @retval -ENOEXEC Unexpected scan or GATT error 2744 */ 2745 int bt_bap_broadcast_assistant_scan_stop(struct bt_conn *conn); 2746 2747 /** 2748 * @brief Registers the callbacks used by Broadcast Audio Scan Service client. 2749 * 2750 * @param cb The callback structure. 2751 * 2752 * @retval 0 on success 2753 * @retval -EINVAL if @p cb is NULL 2754 * @retval -EALREADY if @p cb was already registered 2755 */ 2756 int bt_bap_broadcast_assistant_register_cb(struct bt_bap_broadcast_assistant_cb *cb); 2757 2758 /** 2759 * @brief Unregisters the callbacks used by the Broadcast Audio Scan Service client. 2760 * 2761 * @param cb The callback structure. 2762 * 2763 * @retval 0 on success 2764 * @retval -EINVAL if @p cb is NULL 2765 * @retval -EALREADY if @p cb was not registered 2766 */ 2767 int bt_bap_broadcast_assistant_unregister_cb(struct bt_bap_broadcast_assistant_cb *cb); 2768 2769 2770 /** Parameters for adding a source to a Broadcast Audio Scan Service server */ 2771 struct bt_bap_broadcast_assistant_add_src_param { 2772 /** Address of the advertiser. */ 2773 bt_addr_le_t addr; 2774 2775 /** SID of the advertising set. */ 2776 uint8_t adv_sid; 2777 2778 /** Whether to sync to periodic advertisements. */ 2779 bool pa_sync; 2780 2781 /** 24-bit broadcast ID */ 2782 uint32_t broadcast_id; 2783 2784 /** 2785 * @brief Periodic advertising interval in milliseconds. 2786 * 2787 * BT_BAP_PA_INTERVAL_UNKNOWN if unknown. 2788 */ 2789 uint16_t pa_interval; 2790 2791 /** Number of subgroups */ 2792 uint8_t num_subgroups; 2793 2794 /** Pointer to array of subgroups 2795 * 2796 * The @ref bt_bap_bass_subgroup.bis_sync value can be set to BT_BAP_BIS_SYNC_NO_PREF to 2797 * let the broadcast sink decide which BIS to synchronize to. 2798 */ 2799 struct bt_bap_bass_subgroup *subgroups; 2800 }; 2801 2802 /** 2803 * @brief Add a source on the server. 2804 * 2805 * @param conn Connection to the server. 2806 * @param param Parameter struct. 2807 * 2808 * @retval 0 Success 2809 * @retval -EINVAL @p conn is NULL or %p conn has not done discovery or if @p param is invalid 2810 * @retval -EBUSY Another operation is already in progress for this @p conn 2811 * @retval -ENOTCONN @p conn is not connected 2812 * @retval -ENOMEM Could not allocated memory for the request 2813 * @retval -ENOEXEC Unexpected scan or GATT error 2814 */ 2815 int bt_bap_broadcast_assistant_add_src( 2816 struct bt_conn *conn, const struct bt_bap_broadcast_assistant_add_src_param *param); 2817 2818 /** Parameters for modifying a source */ 2819 struct bt_bap_broadcast_assistant_mod_src_param { 2820 /** Source ID of the receive state. */ 2821 uint8_t src_id; 2822 2823 /** Whether to sync to periodic advertisements. */ 2824 bool pa_sync; 2825 2826 /** 2827 * @brief Periodic advertising interval. 2828 * 2829 * BT_BAP_PA_INTERVAL_UNKNOWN if unknown. 2830 */ 2831 uint16_t pa_interval; 2832 2833 /** Number of subgroups */ 2834 uint8_t num_subgroups; 2835 2836 /** Pointer to array of subgroups */ 2837 struct bt_bap_bass_subgroup *subgroups; 2838 }; 2839 2840 /** 2841 * @brief Modify a source on the server. 2842 * 2843 * @param conn Connection to the server. 2844 * @param param Parameter struct. 2845 * 2846 * @retval 0 Success 2847 * @retval -EINVAL @p conn is NULL or %p conn has not done discovery or if @p param is invalid 2848 * @retval -EBUSY Another operation is already in progress for this @p conn 2849 * @retval -ENOTCONN @p conn is not connected 2850 * @retval -ENOMEM Could not allocated memory for the request 2851 * @retval -ENOEXEC Unexpected scan or GATT error 2852 */ 2853 int bt_bap_broadcast_assistant_mod_src( 2854 struct bt_conn *conn, const struct bt_bap_broadcast_assistant_mod_src_param *param); 2855 2856 /** 2857 * @brief Set a broadcast code to the specified receive state. 2858 * 2859 * @param conn Connection to the server. 2860 * @param src_id Source ID of the receive state. 2861 * @param broadcast_code The broadcast code. 2862 * 2863 * @retval 0 Success 2864 * @retval -EINVAL @p conn is NULL or %p conn has not done discovery or @p src_id is invalid 2865 * @retval -EBUSY Another operation is already in progress for this @p conn 2866 * @retval -ENOTCONN @p conn is not connected 2867 * @retval -ENOMEM Could not allocated memory for the request 2868 * @retval -ENOEXEC Unexpected scan or GATT error 2869 */ 2870 int bt_bap_broadcast_assistant_set_broadcast_code( 2871 struct bt_conn *conn, uint8_t src_id, 2872 const uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE]); 2873 2874 /** 2875 * @brief Remove a source from the server. 2876 * 2877 * @param conn Connection to the server. 2878 * @param src_id Source ID of the receive state. 2879 * 2880 * @retval 0 Success 2881 * @retval -EINVAL @p conn is NULL or %p conn has not done discovery or @p src_id is invalid 2882 * @retval -EBUSY Another operation is already in progress for this @p conn 2883 * @retval -ENOTCONN @p conn is not connected 2884 * @retval -ENOMEM Could not allocated memory for the request 2885 * @retval -ENOEXEC Unexpected scan or GATT error 2886 */ 2887 int bt_bap_broadcast_assistant_rem_src(struct bt_conn *conn, uint8_t src_id); 2888 2889 /** 2890 * @brief Read the specified receive state from the server. 2891 * 2892 * @param conn Connection to the server. 2893 * @param idx The index of the receive start (0 up to the value from 2894 * bt_bap_broadcast_assistant_discover_cb) 2895 * 2896 * @retval 0 Success 2897 * @retval -EINVAL @p conn is NULL or %p conn has not done discovery or @p src_id is invalid 2898 * @retval -EBUSY Another operation is already in progress for this @p conn 2899 * @retval -ENOTCONN @p conn is not connected 2900 * @retval -ENOMEM Could not allocated memory for the request 2901 * @retval -ENOEXEC Unexpected scan or GATT error 2902 */ 2903 int bt_bap_broadcast_assistant_read_recv_state(struct bt_conn *conn, uint8_t idx); 2904 2905 /** @} */ /* end of bt_bap */ 2906 2907 #ifdef __cplusplus 2908 } 2909 #endif 2910 2911 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_BAP_ */ 2912
