1 /** 2 * @file 3 * @brief Bluetooth Common Audio Profile (CAP) APIs. 4 */ 5 6 /* 7 * Copyright (c) 2022-2024 Nordic Semiconductor ASA 8 * 9 * SPDX-License-Identifier: Apache-2.0 10 */ 11 12 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CAP_H_ 13 #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CAP_H_ 14 15 /** 16 * @brief Common Audio Profile (CAP) 17 * 18 * @defgroup bt_cap Common Audio Profile (CAP) 19 * 20 * @since 3.2 21 * @version 0.8.0 22 * 23 * @ingroup bluetooth 24 * @{ 25 * 26 * Common Audio Profile (CAP) provides procedures to start, update, and stop unicast and broadcast 27 * Audio Streams on individual or groups of devices using procedures in the Basic Audio Profile 28 * (BAP). This profile also provides procedures to control volume and device input on groups of 29 * devices using procedures in the Volume Control Profile (VCP) and the Microphone Control Profile 30 * (MICP). This profile specification also refers to the Common Audio Service (CAS). 31 */ 32 33 #include <stdbool.h> 34 #include <stddef.h> 35 #include <stdint.h> 36 37 #include <zephyr/bluetooth/audio/audio.h> 38 #include <zephyr/bluetooth/audio/bap.h> 39 #include <zephyr/bluetooth/audio/csip.h> 40 #include <zephyr/bluetooth/addr.h> 41 #include <zephyr/bluetooth/bluetooth.h> 42 #include <zephyr/bluetooth/conn.h> 43 #include <zephyr/bluetooth/iso.h> 44 #include <zephyr/net_buf.h> 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** @brief Abstract Audio Broadcast Source structure. */ 51 struct bt_cap_broadcast_source; 52 53 /** 54 * @brief Register the Common Audio Service. 55 * 56 * This will register and enable the service and make it discoverable by 57 * clients. This will also register a Coordinated Set Identification 58 * Service instance. 59 * 60 * This shall only be done as a server, and requires 61 * @kconfig{BT_CAP_ACCEPTOR_SET_MEMBER}. If @kconfig{BT_CAP_ACCEPTOR_SET_MEMBER} 62 * is not enabled, the Common Audio Service will by statically registered. 63 * 64 * @param[in] param Coordinated Set Identification Service register 65 * parameters. 66 * @param[out] svc_inst Pointer to the registered Coordinated Set 67 * Identification Service. 68 * 69 * @return 0 if success, errno on failure. 70 */ 71 int bt_cap_acceptor_register(const struct bt_csip_set_member_register_param *param, 72 struct bt_csip_set_member_svc_inst **svc_inst); 73 74 /** Callback structure for CAP procedures */ 75 struct bt_cap_initiator_cb { 76 #if defined(CONFIG_BT_BAP_UNICAST_CLIENT) || defined(__DOXYGEN__) 77 /** 78 * @brief Callback for bt_cap_initiator_unicast_discover(). 79 * 80 * @param conn The connection pointer supplied to 81 * bt_cap_initiator_unicast_discover(). 82 * @param err 0 if Common Audio Service was found else -ENODATA. 83 * @param member Pointer to the set member. NULL if err != 0. 84 * @param csis_inst The Coordinated Set Identification Service if 85 * Common Audio Service was found and includes a 86 * Coordinated Set Identification Service. 87 * NULL on error or if remote device does not include 88 * Coordinated Set Identification Service. NULL if err != 0. 89 */ 90 void (*unicast_discovery_complete)( 91 struct bt_conn *conn, int err, 92 const struct bt_csip_set_coordinator_set_member *member, 93 const struct bt_csip_set_coordinator_csis_inst *csis_inst); 94 95 /** 96 * @brief Callback for bt_cap_initiator_unicast_audio_start(). 97 * 98 * @param err 0 if success, BT_GATT_ERR() with a 99 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 100 * by bt_cap_initiator_unicast_audio_cancel(). 101 * @param conn Pointer to the connection where the error 102 * occurred. NULL if @p err is 0 or if cancelled by 103 * bt_cap_initiator_unicast_audio_cancel() 104 */ 105 void (*unicast_start_complete)(int err, struct bt_conn *conn); 106 107 /** 108 * @brief Callback for bt_cap_initiator_unicast_audio_update(). 109 * 110 * @param err 0 if success, BT_GATT_ERR() with a 111 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 112 * by bt_cap_initiator_unicast_audio_cancel(). 113 * @param conn Pointer to the connection where the error 114 * occurred. NULL if @p err is 0 or if cancelled by 115 * bt_cap_initiator_unicast_audio_cancel() 116 */ 117 void (*unicast_update_complete)(int err, struct bt_conn *conn); 118 119 /** 120 * @brief Callback for bt_cap_initiator_unicast_audio_stop(). 121 * 122 * @param err 0 if success, BT_GATT_ERR() with a 123 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 124 * by bt_cap_initiator_unicast_audio_cancel(). 125 * @param conn Pointer to the connection where the error 126 * occurred. NULL if @p err is 0 or if cancelled by 127 * bt_cap_initiator_unicast_audio_cancel() 128 */ 129 void (*unicast_stop_complete)(int err, struct bt_conn *conn); 130 #endif /* CONFIG_BT_BAP_UNICAST_CLIENT */ 131 #if defined(CONFIG_BT_BAP_BROADCAST_SOURCE) 132 /** 133 * @brief The Broadcast Source has started and all of the streams are ready for audio data 134 * 135 * @param source The started Broadcast Source 136 */ 137 void (*broadcast_started)(struct bt_cap_broadcast_source *source); 138 139 /** 140 * @brief The Broadcast Source has stopped and none of the streams are ready for audio data 141 * 142 * @param source The stopped Broadcast Source 143 * @param reason The reason why the Broadcast Source stopped (see the BT_HCI_ERR_* values) 144 */ 145 void (*broadcast_stopped)(struct bt_cap_broadcast_source *source, uint8_t reason); 146 #endif /* CONFIG_BT_BAP_BROADCAST_SOURCE */ 147 }; 148 149 /** 150 * @brief Discovers audio support on a remote device. 151 * 152 * This will discover the Common Audio Service (CAS) on the remote device, to 153 * verify if the remote device supports the Common Audio Profile. 154 * 155 * @param conn Connection to a remote server. 156 * 157 * @retval 0 Success 158 * @retval -EINVAL @p conn is NULL 159 * @retval -ENOTCONN @p conn is not connected 160 * @retval -ENOMEM Could not allocated memory for the request 161 */ 162 int bt_cap_initiator_unicast_discover(struct bt_conn *conn); 163 164 /** Type of CAP set */ 165 enum bt_cap_set_type { 166 /** The set is an ad-hoc set */ 167 BT_CAP_SET_TYPE_AD_HOC, 168 /** The set is a CSIP Coordinated Set */ 169 BT_CAP_SET_TYPE_CSIP, 170 }; 171 172 /** Represents a Common Audio Set member that are either in a Coordinated or ad-hoc set */ 173 union bt_cap_set_member { 174 /** Connection pointer if the type is BT_CAP_SET_TYPE_AD_HOC. */ 175 struct bt_conn *member; 176 177 /** CSIP Coordinated Set struct used if type is BT_CAP_SET_TYPE_CSIP. */ 178 struct bt_csip_set_coordinator_csis_inst *csip; 179 }; 180 181 /** 182 * @brief Common Audio Profile stream structure. 183 * 184 * Streams represents a Basic Audio Profile (BAP) stream and operation callbacks. 185 * See @ref bt_bap_stream for additional information. 186 */ 187 struct bt_cap_stream { 188 /** The underlying BAP audio stream */ 189 struct bt_bap_stream bap_stream; 190 191 /** Audio stream operations */ 192 struct bt_bap_stream_ops *ops; 193 }; 194 195 /** 196 * @brief Register Audio operations for a Common Audio Profile stream. 197 * 198 * Register Audio operations for a stream. 199 * 200 * @param stream Stream object. 201 * @param ops Stream operations structure. 202 */ 203 void bt_cap_stream_ops_register(struct bt_cap_stream *stream, struct bt_bap_stream_ops *ops); 204 205 /** 206 * @brief Send data to Common Audio Profile stream without timestamp 207 * 208 * See bt_bap_stream_send() for more information 209 * 210 * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}. 211 * 212 * @param stream Stream object. 213 * @param buf Buffer containing data to be sent. 214 * @param seq_num Packet Sequence number. This value shall be incremented for each call to this 215 * function and at least once per SDU interval for a specific channel. 216 * 217 * @retval -EINVAL if stream object is NULL 218 * @retval Any return value from bt_bap_stream_send() 219 */ 220 int bt_cap_stream_send(struct bt_cap_stream *stream, struct net_buf *buf, uint16_t seq_num); 221 222 /** 223 * @brief Send data to Common Audio Profile stream with timestamp 224 * 225 * See bt_bap_stream_send() for more information 226 * 227 * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}. 228 * 229 * @param stream Stream object. 230 * @param buf Buffer containing data to be sent. 231 * @param seq_num Packet Sequence number. This value shall be incremented for each call to this 232 * function and at least once per SDU interval for a specific channel. 233 * @param ts Timestamp of the SDU in microseconds (us). This value can be used to transmit 234 * multiple SDUs in the same SDU interval in a CIG or BIG. 235 * 236 * @retval -EINVAL if stream object is NULL 237 * @retval Any return value from bt_bap_stream_send() 238 */ 239 int bt_cap_stream_send_ts(struct bt_cap_stream *stream, struct net_buf *buf, uint16_t seq_num, 240 uint32_t ts); 241 242 /** 243 * @brief Get ISO transmission timing info for a Common Audio Profile stream 244 * 245 * See bt_bap_stream_get_tx_sync() for more information 246 * 247 * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}. 248 * 249 * @param[in] stream Stream object. 250 * @param[out] info Transmit info object. 251 * 252 * @retval -EINVAL if stream object is NULL 253 * @retval Any return value from bt_bap_stream_get_tx_sync() 254 */ 255 int bt_cap_stream_get_tx_sync(struct bt_cap_stream *stream, struct bt_iso_tx_info *info); 256 257 /** Stream specific parameters for the bt_cap_initiator_unicast_audio_start() function */ 258 struct bt_cap_unicast_audio_start_stream_param { 259 /** Coordinated or ad-hoc set member. */ 260 union bt_cap_set_member member; 261 262 /** @brief Stream for the @p member */ 263 struct bt_cap_stream *stream; 264 265 /** Endpoint reference for the @p stream */ 266 struct bt_bap_ep *ep; 267 268 /** 269 * @brief Codec configuration. 270 * 271 * The @p codec_cfg.meta shall include a list of CCIDs 272 * (@ref BT_AUDIO_METADATA_TYPE_CCID_LIST) as well as a non-0 273 * stream context (@ref BT_AUDIO_METADATA_TYPE_STREAM_CONTEXT) bitfield. 274 * 275 * This value is assigned to the @p stream, and shall remain valid while the stream is 276 * non-idle. 277 */ 278 struct bt_audio_codec_cfg *codec_cfg; 279 }; 280 281 /** Parameters for the bt_cap_initiator_unicast_audio_start() function */ 282 struct bt_cap_unicast_audio_start_param { 283 /** The type of the set. */ 284 enum bt_cap_set_type type; 285 286 /** The number of parameters in @p stream_params */ 287 size_t count; 288 289 /** Array of stream parameters */ 290 struct bt_cap_unicast_audio_start_stream_param *stream_params; 291 }; 292 293 /** Stream specific parameters for the bt_cap_initiator_unicast_audio_update() function */ 294 struct bt_cap_unicast_audio_update_stream_param { 295 /** Stream to update */ 296 struct bt_cap_stream *stream; 297 298 /** The length of @p meta. */ 299 size_t meta_len; 300 301 /** 302 * @brief The new metadata. 303 * 304 * The metadata shall contain a list of CCIDs as well as a non-0 context bitfield. 305 */ 306 uint8_t *meta; 307 }; 308 309 /** Parameters for the bt_cap_initiator_unicast_audio_update() function */ 310 struct bt_cap_unicast_audio_update_param { 311 /** The type of the set. */ 312 enum bt_cap_set_type type; 313 314 /** The number of parameters in @p stream_params */ 315 size_t count; 316 317 /** Array of stream parameters */ 318 struct bt_cap_unicast_audio_update_stream_param *stream_params; 319 }; 320 321 /** Parameters for the bt_cap_initiator_unicast_audio_stop() function */ 322 struct bt_cap_unicast_audio_stop_param { 323 /** The type of the set. */ 324 enum bt_cap_set_type type; 325 326 /** The number of streams in @p streams */ 327 size_t count; 328 329 /** Array of streams to stop */ 330 struct bt_cap_stream **streams; 331 332 /** Whether to release the streams after they have stopped */ 333 bool release; 334 }; 335 336 /** 337 * @brief Register Common Audio Profile Initiator callbacks 338 * 339 * @param cb The callback structure. Shall remain static. 340 * 341 * @return 0 on success or negative error value on failure. 342 */ 343 int bt_cap_initiator_register_cb(const struct bt_cap_initiator_cb *cb); 344 345 /** 346 * @brief Unregister Common Audio Profile Initiator callbacks 347 * 348 * @param cb The callback structure that was previously registered. 349 * 350 * @retval 0 Success 351 * @retval -EINVAL @p cb is NULL or @p cb was not registered 352 */ 353 int bt_cap_initiator_unregister_cb(const struct bt_cap_initiator_cb *cb); 354 355 /** 356 * @brief Setup and start unicast audio streams for a set of devices. 357 * 358 * The result of this operation is that the streams in @p param will be 359 * initialized and will be usable for streaming audio data. 360 * The @p unicast_group value can be used to update and stop the streams. 361 * 362 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 363 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} must be enabled for this function 364 * to be enabled. 365 * 366 * @param param Parameters to start the audio streams. 367 * 368 * @retval 0 on success 369 * @retval -EBUSY if a CAP procedure is already in progress 370 * @retval -EINVAL if any parameter is invalid 371 * @retval -EALREADY All streams are already in the streaming state 372 */ 373 int bt_cap_initiator_unicast_audio_start(const struct bt_cap_unicast_audio_start_param *param); 374 375 /** 376 * @brief Update unicast audio streams. 377 * 378 * This will update the metadata of one or more streams. 379 * 380 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 381 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} must be enabled for this function 382 * to be enabled. 383 * 384 * @param param Update parameters. 385 * 386 * @return 0 on success or negative error value on failure. 387 */ 388 int bt_cap_initiator_unicast_audio_update(const struct bt_cap_unicast_audio_update_param *param); 389 390 /** 391 * @brief Stop unicast audio streams. 392 * 393 * This will stop one or more streams. 394 * 395 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 396 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} must be enabled for this function 397 * to be enabled. 398 * 399 * @param param Stop parameters. 400 * 401 * @return 0 on success 402 * @retval -EBUSY if a CAP procedure is already in progress 403 * @retval -EINVAL if any parameter is invalid 404 * @retval -EALREADY if no state changes will occur 405 */ 406 int bt_cap_initiator_unicast_audio_stop(const struct bt_cap_unicast_audio_stop_param *param); 407 408 /** 409 * @brief Cancel any current Common Audio Profile procedure 410 * 411 * This will stop the current procedure from continuing and making it possible to run a new 412 * Common Audio Profile procedure. 413 * 414 * It is recommended to do this if any existing procedure takes longer time than expected, which 415 * could indicate a missing response from the Common Audio Profile Acceptor. 416 * 417 * This does not send any requests to any Common Audio Profile Acceptors involved with the current 418 * procedure, and thus notifications from the Common Audio Profile Acceptors may arrive after this 419 * has been called. It is thus recommended to either only use this if a procedure has stalled, or 420 * wait a short while before starting any new Common Audio Profile procedure after this has been 421 * called to avoid getting notifications from the cancelled procedure. The wait time depends on 422 * the connection interval, the number of devices in the previous procedure and the behavior of the 423 * Common Audio Profile Acceptors. 424 * 425 * The respective callbacks of the procedure will be called as part of this with the connection 426 * pointer set to 0 and the err value set to -ECANCELED. 427 * 428 * @retval 0 on success 429 * @retval -EALREADY if no procedure is active 430 */ 431 int bt_cap_initiator_unicast_audio_cancel(void); 432 433 /** 434 * Parameters part of @p bt_cap_initiator_broadcast_subgroup_param for 435 * bt_cap_initiator_broadcast_audio_create() 436 */ 437 struct bt_cap_initiator_broadcast_stream_param { 438 /** Audio stream */ 439 struct bt_cap_stream *stream; 440 441 /** The length of the %p data array. 442 * 443 * The BIS specific data may be omitted and this set to 0. 444 */ 445 size_t data_len; 446 447 /** BIS Codec Specific Configuration */ 448 uint8_t *data; 449 }; 450 451 /** 452 * Parameters part of @p bt_cap_initiator_broadcast_create_param for 453 * bt_cap_initiator_broadcast_audio_create() 454 */ 455 struct bt_cap_initiator_broadcast_subgroup_param { 456 /** The number of parameters in @p stream_params */ 457 size_t stream_count; 458 459 /** Array of stream parameters */ 460 struct bt_cap_initiator_broadcast_stream_param *stream_params; 461 462 /** Subgroup Codec configuration. */ 463 struct bt_audio_codec_cfg *codec_cfg; 464 }; 465 466 /** Parameters for * bt_cap_initiator_broadcast_audio_create() */ 467 struct bt_cap_initiator_broadcast_create_param { 468 /** The number of parameters in @p subgroup_params */ 469 size_t subgroup_count; 470 471 /** Array of stream parameters */ 472 struct bt_cap_initiator_broadcast_subgroup_param *subgroup_params; 473 474 /** Quality of Service configuration. */ 475 struct bt_bap_qos_cfg *qos; 476 477 /** 478 * @brief Broadcast Source packing mode. 479 * 480 * @ref BT_ISO_PACKING_SEQUENTIAL or @ref BT_ISO_PACKING_INTERLEAVED. 481 * 482 * @note This is a recommendation to the controller, which the controller may ignore. 483 */ 484 uint8_t packing; 485 486 /** Whether or not to encrypt the streams. */ 487 bool encryption; 488 489 /** 490 * @brief 16-octet broadcast code. 491 * 492 * Only valid if @p encrypt is true. 493 * 494 * If the value is a string or a the value is less than 16 octets, 495 * the remaining octets shall be 0. 496 * 497 * Example: 498 * The string "Broadcast Code" shall be 499 * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00] 500 */ 501 uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE]; 502 503 #if defined(CONFIG_BT_ISO_TEST_PARAMS) || defined(__DOXYGEN__) 504 /** 505 * @brief Immediate Repetition Count 506 * 507 * The number of times the scheduled payloads are transmitted in a given event. 508 * 509 * Value range from @ref BT_ISO_IRC_MIN to @ref BT_ISO_IRC_MAX. 510 */ 511 uint8_t irc; 512 513 /** 514 * @brief Pre-transmission offset 515 * 516 * Offset used for pre-transmissions. 517 * 518 * Value range from @ref BT_ISO_PTO_MIN to @ref BT_ISO_PTO_MAX. 519 */ 520 uint8_t pto; 521 522 /** 523 * @brief ISO interval 524 * 525 * Time between consecutive BIS anchor points. 526 * 527 * Value range from @ref BT_ISO_ISO_INTERVAL_MIN to @ref BT_ISO_ISO_INTERVAL_MAX. 528 */ 529 uint16_t iso_interval; 530 #endif /* CONFIG_BT_ISO_TEST_PARAMS */ 531 }; 532 533 /** 534 * @brief Create a Common Audio Profile broadcast source. 535 * 536 * Create a new audio broadcast source with one or more audio streams. 537 * 538 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 539 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 540 * to be enabled. 541 * 542 * @param[in] param Parameters to start the audio streams. 543 * @param[out] broadcast_source Pointer to the broadcast source created. 544 * 545 * @return 0 on success or negative error value on failure. 546 */ 547 int bt_cap_initiator_broadcast_audio_create( 548 const struct bt_cap_initiator_broadcast_create_param *param, 549 struct bt_cap_broadcast_source **broadcast_source); 550 551 /** 552 * @brief Start Common Audio Profile broadcast source. 553 * 554 * The broadcast source will be visible for scanners once this has been called, 555 * and the device will advertise audio announcements. 556 * 557 * This will allow the streams in the broadcast source to send audio by calling 558 * bt_bap_stream_send(). 559 * 560 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 561 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 562 * to be enabled. 563 * 564 * @param broadcast_source Pointer to the broadcast source. 565 * @param adv Pointer to an extended advertising set with 566 * periodic advertising configured. 567 * 568 * @return 0 on success or negative error value on failure. 569 */ 570 int bt_cap_initiator_broadcast_audio_start(struct bt_cap_broadcast_source *broadcast_source, 571 struct bt_le_ext_adv *adv); 572 /** 573 * @brief Update broadcast audio streams for a Common Audio Profile broadcast source. 574 * 575 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 576 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 577 * to be enabled. 578 * 579 * @param broadcast_source The broadcast source to update. 580 * @param meta The new metadata. The metadata shall contain a list 581 * of CCIDs as well as a non-0 context bitfield. 582 * @param meta_len The length of @p meta. 583 * 584 * @return 0 on success or negative error value on failure. 585 */ 586 int bt_cap_initiator_broadcast_audio_update(struct bt_cap_broadcast_source *broadcast_source, 587 const uint8_t meta[], size_t meta_len); 588 589 /** 590 * @brief Stop broadcast audio streams for a Common Audio Profile broadcast source. 591 * 592 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 593 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 594 * to be enabled. 595 * 596 * @param broadcast_source The broadcast source to stop. The audio streams 597 * in this will be stopped and reset. 598 * 599 * @return 0 on success or negative error value on failure. 600 */ 601 int bt_cap_initiator_broadcast_audio_stop(struct bt_cap_broadcast_source *broadcast_source); 602 603 /** 604 * @brief Delete Common Audio Profile broadcast source 605 * 606 * This can only be done after the broadcast source has been stopped by calling 607 * bt_cap_initiator_broadcast_audio_stop() and after the 608 * bt_bap_stream_ops.stopped() callback has been called for all streams in the 609 * broadcast source. 610 * 611 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 612 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 613 * to be enabled. 614 * 615 * @param broadcast_source The broadcast source to delete. 616 * The @p broadcast_source will be invalidated. 617 * 618 * @return 0 on success or negative error value on failure. 619 */ 620 int bt_cap_initiator_broadcast_audio_delete(struct bt_cap_broadcast_source *broadcast_source); 621 622 /** 623 * @brief Get the Broadcast Audio Stream Endpoint of a Common Audio Profile broadcast source 624 * 625 * This will encode the BASE of a broadcast source into a buffer, that can be 626 * used for advertisement. The encoded BASE will thus be encoded as 627 * little-endian. The BASE shall be put into the periodic advertising data 628 * (see bt_le_per_adv_set_data()). 629 * 630 * See table 3.15 in the Basic Audio Profile v1.0.1 for the structure. 631 * 632 * @param broadcast_source Pointer to the broadcast source. 633 * @param base_buf Pointer to a buffer where the BASE will be inserted. 634 * 635 * @return int 0 if on success, errno on error. 636 */ 637 int bt_cap_initiator_broadcast_get_base(struct bt_cap_broadcast_source *broadcast_source, 638 struct net_buf_simple *base_buf); 639 640 /** Parameters for bt_cap_initiator_unicast_to_broadcast() */ 641 struct bt_cap_unicast_to_broadcast_param { 642 /** The source unicast group with the streams. */ 643 struct bt_bap_unicast_group *unicast_group; 644 645 /** 646 * @brief Whether or not to encrypt the streams. 647 * 648 * If set to true, then the broadcast code in @p broadcast_code 649 * will be used to encrypt the streams. 650 */ 651 bool encrypt; 652 653 /** 654 * @brief 16-octet broadcast code. 655 * 656 * Only valid if @p encrypt is true. 657 * 658 * If the value is a string or a the value is less than 16 octets, 659 * the remaining octets shall be 0. 660 * 661 * Example: 662 * The string "Broadcast Code" shall be 663 * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00] 664 */ 665 uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE]; 666 }; 667 668 /** 669 * @brief Hands over the data streams in a unicast group to a broadcast source. 670 * 671 * The streams in the unicast group will be stopped and the unicast group 672 * will be deleted. This can only be done for source streams. 673 * 674 * @note @kconfig{CONFIG_BT_CAP_INITIATOR}, 675 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} and 676 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 677 * to be enabled. 678 * 679 * @param param The parameters for the handover. 680 * @param source The resulting broadcast source. 681 * 682 * @return 0 on success or negative error value on failure. 683 */ 684 int bt_cap_initiator_unicast_to_broadcast(const struct bt_cap_unicast_to_broadcast_param *param, 685 struct bt_cap_broadcast_source **source); 686 687 /** Parameters for bt_cap_initiator_broadcast_to_unicast() */ 688 struct bt_cap_broadcast_to_unicast_param { 689 /** 690 * @brief The source broadcast source with the streams. 691 * 692 * The broadcast source will be stopped and deleted. 693 */ 694 struct bt_cap_broadcast_source *broadcast_source; 695 696 /** The type of the set. */ 697 enum bt_cap_set_type type; 698 699 /** 700 * @brief The number of set members in @p members. 701 * 702 * This value shall match the number of streams in the 703 * @p broadcast_source. 704 * 705 */ 706 size_t count; 707 708 /** Coordinated or ad-hoc set members. */ 709 union bt_cap_set_member **members; 710 }; 711 712 /** 713 * @brief Hands over the data streams in a broadcast source to a unicast group. 714 * 715 * The streams in the broadcast source will be stopped and the broadcast source 716 * will be deleted. 717 * 718 * @note @kconfig{CONFIG_BT_CAP_INITIATOR}, 719 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} and 720 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 721 * to be enabled. 722 * 723 * @param[in] param The parameters for the handover. 724 * @param[out] unicast_group The resulting broadcast source. 725 * 726 * @return 0 on success or negative error value on failure. 727 */ 728 int bt_cap_initiator_broadcast_to_unicast(const struct bt_cap_broadcast_to_unicast_param *param, 729 struct bt_bap_unicast_group **unicast_group); 730 731 /** Callback structure for CAP procedures */ 732 struct bt_cap_commander_cb { 733 /** 734 * @brief Callback for bt_cap_initiator_unicast_discover(). 735 * 736 * @param conn The connection pointer supplied to 737 * bt_cap_initiator_unicast_discover(). 738 * @param err 0 if Common Audio Service was found else -ENODATA. 739 * @param member Pointer to the set member. NULL if err != 0. 740 * @param csis_inst The Coordinated Set Identification Service if 741 * Common Audio Service was found and includes a 742 * Coordinated Set Identification Service. 743 * NULL on error or if remote device does not include 744 * Coordinated Set Identification Service. NULL if err != 0. 745 */ 746 void (*discovery_complete)(struct bt_conn *conn, int err, 747 const struct bt_csip_set_coordinator_set_member *member, 748 const struct bt_csip_set_coordinator_csis_inst *csis_inst); 749 750 #if defined(CONFIG_BT_VCP_VOL_CTLR) || defined(__DOXYGEN__) 751 /** 752 * @brief Callback for bt_cap_commander_change_volume(). 753 * 754 * @param conn Pointer to the connection where the error 755 * occurred. NULL if @p err is 0 or if cancelled by 756 * bt_cap_commander_cancel() 757 * @param err 0 on success, BT_GATT_ERR() with a 758 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 759 * by bt_cap_commander_cancel(). 760 */ 761 void (*volume_changed)(struct bt_conn *conn, int err); 762 763 /** 764 * @brief Callback for bt_cap_commander_change_volume_mute_state(). 765 * 766 * @param conn Pointer to the connection where the error 767 * occurred. NULL if @p err is 0 or if cancelled by 768 * bt_cap_commander_cancel() 769 * @param err 0 on success, BT_GATT_ERR() with a 770 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 771 * by bt_cap_commander_cancel(). 772 */ 773 void (*volume_mute_changed)(struct bt_conn *conn, int err); 774 775 #if defined(CONFIG_BT_VCP_VOL_CTLR_VOCS) || defined(__DOXYGEN__) 776 /** 777 * @brief Callback for bt_cap_commander_change_volume_offset(). 778 * 779 * @param conn Pointer to the connection where the error 780 * occurred. NULL if @p err is 0 or if cancelled by 781 * bt_cap_commander_cancel() 782 * @param err 0 on success, BT_GATT_ERR() with a 783 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 784 * by bt_cap_commander_cancel(). 785 */ 786 void (*volume_offset_changed)(struct bt_conn *conn, int err); 787 #endif /* CONFIG_BT_VCP_VOL_CTLR_VOCS */ 788 #endif /* CONFIG_BT_VCP_VOL_CTLR */ 789 #if defined(CONFIG_BT_MICP_MIC_CTLR) || defined(__DOXYGEN__) 790 /** 791 * @brief Callback for bt_cap_commander_change_microphone_mute_state(). 792 * 793 * @param conn Pointer to the connection where the error 794 * occurred. NULL if @p err is 0 or if cancelled by 795 * bt_cap_commander_cancel() 796 * @param err 0 on success, BT_GATT_ERR() with a 797 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 798 * by bt_cap_commander_cancel(). 799 */ 800 void (*microphone_mute_changed)(struct bt_conn *conn, int err); 801 #if defined(CONFIG_BT_MICP_MIC_CTLR_AICS) || defined(__DOXYGEN__) 802 /** 803 * @brief Callback for bt_cap_commander_change_microphone_gain_setting(). 804 * 805 * @param conn Pointer to the connection where the error 806 * occurred. NULL if @p err is 0 or if cancelled by 807 * bt_cap_commander_cancel() 808 * @param err 0 on success, BT_GATT_ERR() with a 809 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 810 * by bt_cap_commander_cancel(). 811 */ 812 void (*microphone_gain_changed)(struct bt_conn *conn, int err); 813 #endif /* CONFIG_BT_MICP_MIC_CTLR_AICS */ 814 #endif /* CONFIG_BT_MICP_MIC_CTLR */ 815 816 #if defined(CONFIG_BT_BAP_BROADCAST_ASSISTANT) || defined(__DOXYGEN__) 817 /** 818 * @brief Callback for bt_cap_commander_broadcast_reception_start(). 819 * 820 * @param conn Pointer to the connection where the error 821 * occurred. NULL if @p err is 0 or if cancelled by 822 * bt_cap_commander_cancel() 823 * @param err 0 on success, BT_GATT_ERR() with a 824 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 825 * by bt_cap_commander_cancel(). 826 */ 827 void (*broadcast_reception_start)(struct bt_conn *conn, int err); 828 /** 829 * @brief Callback for bt_cap_commander_broadcast_reception_stop(). 830 * 831 * @param conn Pointer to the connection where the error 832 * occurred. NULL if @p err is 0 or if cancelled by 833 * bt_cap_commander_cancel() 834 * @param err 0 on success, BT_GATT_ERR() with a 835 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 836 * by bt_cap_commander_cancel(). 837 */ 838 void (*broadcast_reception_stop)(struct bt_conn *conn, int err); 839 /** 840 * @brief Callback for bt_cap_commander_distribute_broadcast_code(). 841 * 842 * @param conn Pointer to the connection where the error 843 * occurred. NULL if @p err is 0 or if cancelled by 844 * bt_cap_commander_cancel() 845 * @param err 0 on success, BT_GATT_ERR() with a 846 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 847 * by bt_cap_commander_cancel(). 848 */ 849 void (*distribute_broadcast_code)(struct bt_conn *conn, int err); 850 #endif /* CONFIG_BT_BAP_BROADCAST_ASSISTANT */ 851 }; 852 853 /** 854 * @brief Register Common Audio Profile Commander callbacks 855 * 856 * @param cb The callback structure. Shall remain static. 857 * 858 * @retval 0 Success 859 * @retval -EINVAL @p cb is NULL 860 * @retval -EALREADY Callbacks are already registered 861 */ 862 int bt_cap_commander_register_cb(const struct bt_cap_commander_cb *cb); 863 864 /** 865 * @brief Unregister Common Audio Profile Commander callbacks 866 * 867 * @param cb The callback structure that was previously registered. 868 * 869 * @retval 0 Success 870 * @retval -EINVAL @p cb is NULL or @p cb was not registered 871 */ 872 int bt_cap_commander_unregister_cb(const struct bt_cap_commander_cb *cb); 873 874 /** 875 * @brief Discovers audio support on a remote device. 876 * 877 * This will discover the Common Audio Service (CAS) on the remote device, to 878 * verify if the remote device supports the Common Audio Profile. 879 * 880 * @note @kconfig{CONFIG_BT_CAP_COMMANDER} must be enabled for this function. If 881 * @kconfig{CONFIG_BT_CAP_INITIATOR} is also enabled, it does not matter if 882 * bt_cap_commander_discover() or bt_cap_initiator_unicast_discover() is used. 883 * 884 * @param conn Connection to a remote server. 885 * 886 * @retval 0 Success 887 * @retval -EINVAL @p conn is NULL 888 * @retval -ENOTCONN @p conn is not connected 889 * @retval -ENOMEM Could not allocated memory for the request 890 * @retval -EBUSY Already doing discovery for @p conn 891 */ 892 int bt_cap_commander_discover(struct bt_conn *conn); 893 894 /** 895 * @brief Cancel any current Common Audio Profile commander procedure 896 * 897 * This will stop the current procedure from continuing and making it possible to run a new 898 * Common Audio Profile procedure. 899 * 900 * It is recommended to do this if any existing procedure takes longer time than expected, which 901 * could indicate a missing response from the Common Audio Profile Acceptor. 902 * 903 * This does not send any requests to any Common Audio Profile Acceptors involved with the 904 * current procedure, and thus notifications from the Common Audio Profile Acceptors may 905 * arrive after this has been called. It is thus recommended to either only use this if a 906 * procedure has stalled, or wait a short while before starting any new Common Audio Profile 907 * procedure after this has been called to avoid getting notifications from the cancelled 908 * procedure. The wait time depends on the connection interval, the number of devices in the 909 * previous procedure and the behavior of the Common Audio Profile Acceptors. 910 * 911 * The respective callbacks of the procedure will be called as part of this with the connection 912 * pointer set to NULL and the err value set to -ECANCELED. 913 * 914 * @retval 0 on success 915 * @retval -EALREADY if no procedure is active 916 */ 917 int bt_cap_commander_cancel(void); 918 919 /** 920 * Parameters part of @ref bt_cap_commander_broadcast_reception_start_param for 921 * bt_cap_commander_broadcast_reception_start() 922 */ 923 struct bt_cap_commander_broadcast_reception_start_member_param { 924 /** Coordinated or ad-hoc set member. */ 925 union bt_cap_set_member member; 926 927 /** Address of the advertiser. */ 928 bt_addr_le_t addr; 929 930 /** SID of the advertising set. */ 931 uint8_t adv_sid; 932 933 /** 934 * @brief Periodic advertising interval in milliseconds. 935 * 936 * BT_BAP_PA_INTERVAL_UNKNOWN if unknown. 937 */ 938 uint16_t pa_interval; 939 940 /** 24-bit broadcast ID */ 941 uint32_t broadcast_id; 942 943 /** 944 * @brief Pointer to array of subgroups 945 * 946 * At least one bit in one of the subgroups bis_sync parameters shall be set. 947 */ 948 struct bt_bap_bass_subgroup subgroups[BT_BAP_BASS_MAX_SUBGROUPS]; 949 950 /** Number of subgroups */ 951 size_t num_subgroups; 952 }; 953 954 /** Parameters for starting broadcast reception */ 955 struct bt_cap_commander_broadcast_reception_start_param { 956 /** The type of the set. */ 957 enum bt_cap_set_type type; 958 959 /** The set of devices for this procedure */ 960 struct bt_cap_commander_broadcast_reception_start_member_param *param; 961 962 /** The number of parameters in @p param */ 963 size_t count; 964 }; 965 966 /** 967 * @brief Starts the reception of broadcast audio on one or more remote Common Audio Profile 968 * Acceptors 969 * 970 * @param param The parameters to start the broadcast audio 971 * 972 * @return 0 on success or negative error value on failure. 973 */ 974 int bt_cap_commander_broadcast_reception_start( 975 const struct bt_cap_commander_broadcast_reception_start_param *param); 976 977 /** Parameters for stopping broadcast reception */ 978 struct bt_cap_commander_broadcast_reception_stop_member_param { 979 /** Coordinated or ad-hoc set member. */ 980 union bt_cap_set_member member; 981 982 /** Source ID of the receive state. */ 983 uint8_t src_id; 984 985 /** Number of subgroups */ 986 size_t num_subgroups; 987 }; 988 989 struct bt_cap_commander_broadcast_reception_stop_param { 990 /** The type of the set. */ 991 enum bt_cap_set_type type; 992 993 /** The set of devices for this procedure */ 994 struct bt_cap_commander_broadcast_reception_stop_member_param *param; 995 996 /** The number of parameters in @p param */ 997 size_t count; 998 }; 999 1000 /** 1001 * @brief Stops the reception of broadcast audio on one or more remote Common Audio Profile 1002 * Acceptors 1003 * 1004 * @param param The parameters to stop the broadcast audio 1005 * 1006 * @return 0 on success or negative error value on failure. 1007 */ 1008 int bt_cap_commander_broadcast_reception_stop( 1009 const struct bt_cap_commander_broadcast_reception_stop_param *param); 1010 1011 /** Parameters for distributing broadcast code */ 1012 struct bt_cap_commander_distribute_broadcast_code_member_param { 1013 /** Coordinated or ad-hoc set member. */ 1014 union bt_cap_set_member member; 1015 1016 /** Source ID of the receive state. */ 1017 uint8_t src_id; 1018 }; 1019 1020 struct bt_cap_commander_distribute_broadcast_code_param { 1021 /** The type of the set. */ 1022 enum bt_cap_set_type type; 1023 1024 /** The set of devices for this procedure */ 1025 struct bt_cap_commander_distribute_broadcast_code_member_param *param; 1026 1027 /** The number of parameters in @p param */ 1028 size_t count; 1029 1030 /** 1031 * @brief 16-octet broadcast code. 1032 * 1033 * If the value is a string or a the value is less than 16 octets, 1034 * the remaining octets shall be 0. 1035 * 1036 * Example: 1037 * The string "Broadcast Code" shall be 1038 * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00] 1039 */ 1040 uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE]; 1041 }; 1042 1043 /** 1044 * @brief Distributes the broadcast code on one or more remote Common Audio Profile 1045 * Acceptors 1046 * 1047 * @param param The parameters for distributing the broadcast code 1048 * 1049 * @return 0 on success or negative error value on failure. 1050 */ 1051 int bt_cap_commander_distribute_broadcast_code( 1052 const struct bt_cap_commander_distribute_broadcast_code_param *param); 1053 1054 /** Parameters for changing absolute volume */ 1055 struct bt_cap_commander_change_volume_param { 1056 /** The type of the set. */ 1057 enum bt_cap_set_type type; 1058 1059 /** Coordinated or ad-hoc set member. */ 1060 union bt_cap_set_member *members; 1061 1062 /** The number of members in @p members */ 1063 size_t count; 1064 1065 /** The absolute volume to set */ 1066 uint8_t volume; 1067 }; 1068 1069 /** 1070 * @brief Change the volume on one or more Common Audio Profile Acceptors 1071 * 1072 * @param param The parameters for the volume change 1073 * 1074 * @return 0 on success or negative error value on failure. 1075 */ 1076 int bt_cap_commander_change_volume(const struct bt_cap_commander_change_volume_param *param); 1077 1078 /** 1079 * Parameters part of @ref bt_cap_commander_change_volume_offset_param for 1080 * bt_cap_commander_change_volume_offset() 1081 */ 1082 struct bt_cap_commander_change_volume_offset_member_param { 1083 /** Coordinated or ad-hoc set member. */ 1084 union bt_cap_set_member member; 1085 1086 /** 1087 * @brief The offset to set 1088 * 1089 * Value shall be between @ref BT_VOCS_MIN_OFFSET and @ref BT_VOCS_MAX_OFFSET 1090 */ 1091 int16_t offset; 1092 }; 1093 1094 /** Parameters for changing volume offset */ 1095 struct bt_cap_commander_change_volume_offset_param { 1096 /** The type of the set. */ 1097 enum bt_cap_set_type type; 1098 1099 /** The set of devices for this procedure */ 1100 struct bt_cap_commander_change_volume_offset_member_param *param; 1101 1102 /** The number of parameters in @p param */ 1103 size_t count; 1104 }; 1105 1106 /** 1107 * @brief Change the volume offset on one or more Common Audio Profile Acceptors 1108 * 1109 * @param param The parameters for the volume offset change 1110 * 1111 * @return 0 on success or negative error value on failure. 1112 */ 1113 int bt_cap_commander_change_volume_offset( 1114 const struct bt_cap_commander_change_volume_offset_param *param); 1115 1116 /** Parameters for changing volume mute state */ 1117 struct bt_cap_commander_change_volume_mute_state_param { 1118 /** The type of the set. */ 1119 enum bt_cap_set_type type; 1120 1121 /** Coordinated or ad-hoc set member. */ 1122 union bt_cap_set_member *members; 1123 1124 /** The number of members in @p members */ 1125 size_t count; 1126 1127 /** 1128 * @brief The volume mute state to set 1129 * 1130 * true to mute, and false to unmute 1131 */ 1132 bool mute; 1133 }; 1134 1135 /** 1136 * @brief Change the volume mute state on one or more Common Audio Profile Acceptors 1137 * 1138 * @param param The parameters for the volume mute state change 1139 * 1140 * @return 0 on success or negative error value on failure. 1141 */ 1142 int bt_cap_commander_change_volume_mute_state( 1143 const struct bt_cap_commander_change_volume_mute_state_param *param); 1144 1145 /** Parameters for changing microphone mute state */ 1146 struct bt_cap_commander_change_microphone_mute_state_param { 1147 /** The type of the set. */ 1148 enum bt_cap_set_type type; 1149 1150 /** Coordinated or ad-hoc set member. */ 1151 union bt_cap_set_member *members; 1152 1153 /** The number of members in @p members */ 1154 size_t count; 1155 1156 /** 1157 * @brief The microphone mute state to set 1158 * 1159 * true to mute, and false to unmute 1160 */ 1161 bool mute; 1162 }; 1163 1164 /** 1165 * @brief Change the microphone mute state on one or more Common Audio Profile Acceptors 1166 * 1167 * @param param The parameters for the microphone mute state change 1168 * 1169 * @return 0 on success or negative error value on failure. 1170 */ 1171 int bt_cap_commander_change_microphone_mute_state( 1172 const struct bt_cap_commander_change_microphone_mute_state_param *param); 1173 1174 /** 1175 * Parameters part of @ref bt_cap_commander_change_microphone_gain_setting_param for 1176 * bt_cap_commander_change_microphone_gain_setting() 1177 */ 1178 struct bt_cap_commander_change_microphone_gain_setting_member_param { 1179 /** Coordinated or ad-hoc set member. */ 1180 union bt_cap_set_member member; 1181 1182 /** @brief The microphone gain setting to set */ 1183 int8_t gain; 1184 }; 1185 1186 /** Parameters for changing microphone mute state */ 1187 struct bt_cap_commander_change_microphone_gain_setting_param { 1188 /** The type of the set. */ 1189 enum bt_cap_set_type type; 1190 1191 /** The set of devices for this procedure */ 1192 struct bt_cap_commander_change_microphone_gain_setting_member_param *param; 1193 1194 /** The number of parameters in @p param */ 1195 size_t count; 1196 }; 1197 1198 /** 1199 * @brief Change the microphone gain setting on one or more Common Audio Profile Acceptors 1200 * 1201 * @param param The parameters for the microphone gain setting change 1202 * 1203 * @return 0 on success or negative error value on failure. 1204 */ 1205 int bt_cap_commander_change_microphone_gain_setting( 1206 const struct bt_cap_commander_change_microphone_gain_setting_param *param); 1207 #ifdef __cplusplus 1208 } 1209 #endif 1210 1211 /** 1212 * @} 1213 */ 1214 1215 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CAP_H_ */ 1216
