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