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