1 /* 2 * Copyright (c) 2022-2023 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CAP_H_ 8 #define ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CAP_H_ 9 10 /** 11 * @brief Common Audio Profile (CAP) 12 * 13 * @defgroup bt_cap Common Audio Profile (CAP) 14 * 15 * @ingroup bluetooth 16 * @{ 17 * 18 * [Experimental] Users should note that the APIs can change 19 * as a part of ongoing development. 20 */ 21 22 #include <stdint.h> 23 24 #include <zephyr/bluetooth/audio/csip.h> 25 #include <zephyr/bluetooth/iso.h> 26 #include <zephyr/bluetooth/audio/audio.h> 27 #include <zephyr/bluetooth/audio/bap.h> 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /** @brief Abstract Audio Broadcast Source structure. */ 34 struct bt_cap_broadcast_source; 35 36 /** 37 * @brief Register the Common Audio Service. 38 * 39 * This will register and enable the service and make it discoverable by 40 * clients. This will also register a Coordinated Set Identification 41 * Service instance. 42 * 43 * This shall only be done as a server, and requires 44 * @kconfig{BT_CAP_ACCEPTOR_SET_MEMBER}. If @kconfig{BT_CAP_ACCEPTOR_SET_MEMBER} 45 * is not enabled, the Common Audio Service will by statically registered. 46 * 47 * @param[in] param Coordinated Set Identification Service register 48 * parameters. 49 * @param[out] svc_inst Pointer to the registered Coordinated Set 50 * Identification Service. 51 * 52 * @return 0 if success, errno on failure. 53 */ 54 int bt_cap_acceptor_register(const struct bt_csip_set_member_register_param *param, 55 struct bt_csip_set_member_svc_inst **svc_inst); 56 57 /** Callback structure for CAP procedures */ 58 struct bt_cap_initiator_cb { 59 #if defined(CONFIG_BT_BAP_UNICAST_CLIENT) 60 /** 61 * @brief Callback for bt_cap_initiator_unicast_discover(). 62 * 63 * @param conn The connection pointer supplied to 64 * bt_cap_initiator_unicast_discover(). 65 * @param err 0 if Common Audio Service was found else -ENODATA. 66 * @param csis_inst The Coordinated Set Identification Service if 67 * Common Audio Service was found and includes a 68 * Coordinated Set Identification Service. 69 * NULL on error or if remote device does not include 70 * Coordinated Set Identification Service. 71 */ 72 void (*unicast_discovery_complete)( 73 struct bt_conn *conn, int err, 74 const struct bt_csip_set_coordinator_csis_inst *csis_inst); 75 76 /** 77 * @brief Callback for bt_cap_initiator_unicast_audio_start(). 78 * 79 * @param unicast_group The unicast group pointer supplied to 80 * bt_cap_initiator_unicast_audio_start(). 81 * @param err 0 if success, BT_GATT_ERR() with a 82 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 83 * by bt_cap_initiator_unicast_audio_cancel(). 84 * @param conn Pointer to the connection where the error 85 * occurred. NULL if @p err is 0 or if cancelled by 86 * bt_cap_initiator_unicast_audio_cancel() 87 */ 88 void (*unicast_start_complete)(struct bt_bap_unicast_group *unicast_group, 89 int err, struct bt_conn *conn); 90 91 /** 92 * @brief Callback for bt_cap_initiator_unicast_audio_update(). 93 * 94 * @param err 0 if success, BT_GATT_ERR() with a 95 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 96 * by bt_cap_initiator_unicast_audio_cancel(). 97 * @param conn Pointer to the connection where the error 98 * occurred. NULL if @p err is 0 or if cancelled by 99 * bt_cap_initiator_unicast_audio_cancel() 100 */ 101 void (*unicast_update_complete)(int err, struct bt_conn *conn); 102 103 /** 104 * @brief Callback for bt_cap_initiator_unicast_audio_stop(). 105 * 106 * If @p err is 0, then @p unicast_group has been deleted and can no 107 * longer be used. 108 * 109 * If @p err is not 0 and @p conn is NULL, then the deletion of the 110 * @p unicast_group failed with @p err as the error. 111 * 112 * @param unicast_group The unicast group pointer supplied to 113 * bt_cap_initiator_unicast_audio_stop(). 114 * @param err 0 if success, BT_GATT_ERR() with a 115 * specific ATT (BT_ATT_ERR_*) error code or -ECANCELED if cancelled 116 * by bt_cap_initiator_unicast_audio_cancel(). 117 * @param conn Pointer to the connection where the error 118 * occurred. NULL if @p err is 0 or if cancelled by 119 * bt_cap_initiator_unicast_audio_cancel() 120 */ 121 void (*unicast_stop_complete)(struct bt_bap_unicast_group *unicast_group, 122 int err, struct bt_conn *conn); 123 #endif /* CONFIG_BT_BAP_UNICAST_CLIENT */ 124 }; 125 126 /** 127 * @brief Discovers audio support on a remote device. 128 * 129 * This will discover the Common Audio Service (CAS) on the remote device, to 130 * verify if the remote device supports the Common Audio Profile. 131 * 132 * @param conn Connection to a remote server. 133 * 134 * @return 0 on success or negative error value on failure. 135 */ 136 int bt_cap_initiator_unicast_discover(struct bt_conn *conn); 137 138 /** Type of CAP set */ 139 enum bt_cap_set_type { 140 /** The set is an ad-hoc set */ 141 BT_CAP_SET_TYPE_AD_HOC, 142 /** The set is a CSIP Coordinated Set */ 143 BT_CAP_SET_TYPE_CSIP, 144 }; 145 146 /** Represents a Common Audio Set member that are either in a Coordinated or ad-hoc set */ 147 union bt_cap_set_member { 148 /** Connection pointer if the type is BT_CAP_SET_TYPE_AD_HOC. */ 149 struct bt_conn *member; 150 151 /** CSIP Coordinated Set struct used if type is BT_CAP_SET_TYPE_CSIP. */ 152 struct bt_csip_set_coordinator_csis_inst *csip; 153 }; 154 155 struct bt_cap_stream { 156 struct bt_bap_stream bap_stream; 157 struct bt_bap_stream_ops *ops; 158 }; 159 160 /** @brief Register Audio operations for a Common Audio Profile stream. 161 * 162 * Register Audio operations for a stream. 163 * 164 * @param stream Stream object. 165 * @param ops Stream operations structure. 166 */ 167 void bt_cap_stream_ops_register(struct bt_cap_stream *stream, struct bt_bap_stream_ops *ops); 168 169 /** 170 * @brief Send data to Common Audio Profile stream 171 * 172 * See bt_bap_stream_send() for more information 173 * 174 * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}. 175 * 176 * @param stream Stream object. 177 * @param buf Buffer containing data to be sent. 178 * @param seq_num Packet Sequence number. This value shall be incremented for each call to this 179 * function and at least once per SDU interval for a specific channel. 180 * @param ts Timestamp of the SDU in microseconds (us). This value can be used to transmit 181 * multiple SDUs in the same SDU interval in a CIG or BIG. Can be omitted by using 182 * @ref BT_ISO_TIMESTAMP_NONE which will simply enqueue the ISO SDU in a FIFO 183 * manner. 184 * 185 * @retval -EINVAL if stream object is NULL 186 * @retval Any return value from bt_bap_stream_send() 187 */ 188 int bt_cap_stream_send(struct bt_cap_stream *stream, struct net_buf *buf, uint16_t seq_num, 189 uint32_t ts); 190 191 /** 192 * @brief Get ISO transmission timing info for a Common Audio Profile stream 193 * 194 * See bt_bap_stream_get_tx_sync() for more information 195 * 196 * @note Support for sending must be supported, determined by @kconfig{CONFIG_BT_AUDIO_TX}. 197 * 198 * @param[in] stream Stream object. 199 * @param[out] info Transmit info object. 200 * 201 * @retval -EINVAL if stream object is NULL 202 * @retval Any return value from bt_bap_stream_get_tx_sync() 203 */ 204 int bt_cap_stream_get_tx_sync(struct bt_cap_stream *stream, struct bt_iso_tx_info *info); 205 206 struct bt_cap_unicast_audio_start_stream_param { 207 /** Coordinated or ad-hoc set member. */ 208 union bt_cap_set_member member; 209 210 /** @brief Stream for the @p member */ 211 struct bt_cap_stream *stream; 212 213 /** Endpoint reference for the @p stream */ 214 struct bt_bap_ep *ep; 215 216 /** 217 * @brief Codec configuration. 218 * 219 * The @p codec_cfg.meta shall include a list of CCIDs 220 * (@ref BT_AUDIO_METADATA_TYPE_CCID_LIST) as well as a non-0 221 * stream context (@ref BT_AUDIO_METADATA_TYPE_STREAM_CONTEXT) bitfield. 222 */ 223 struct bt_audio_codec_cfg *codec_cfg; 224 }; 225 226 struct bt_cap_unicast_audio_start_param { 227 /** The type of the set. */ 228 enum bt_cap_set_type type; 229 230 /** The number of parameters in @p stream_params */ 231 size_t count; 232 233 /** Array of stream parameters */ 234 struct bt_cap_unicast_audio_start_stream_param *stream_params; 235 }; 236 237 struct bt_cap_unicast_audio_update_param { 238 /** @brief Stream for the @p member */ 239 struct bt_cap_stream *stream; 240 241 /** The length of @p meta. */ 242 size_t meta_len; 243 244 /** @brief The new metadata. 245 * 246 * The metadata shall a list of CCIDs as 247 * well as a non-0 context bitfield. 248 */ 249 uint8_t *meta; 250 }; 251 252 /** 253 * @brief Register Common Audio Profile callbacks 254 * 255 * @param cb The callback structure. Shall remain static. 256 * 257 * @return 0 on success or negative error value on failure. 258 */ 259 int bt_cap_initiator_register_cb(const struct bt_cap_initiator_cb *cb); 260 261 /** 262 * @brief Setup and start unicast audio streams for a set of devices. 263 * 264 * The result of this operation is that the streams in @p param will be 265 * initialized and will be usable for streaming audio data. 266 * The @p unicast_group value can be used to update and stop the streams. 267 * 268 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 269 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} must be enabled for this function 270 * to be enabled. 271 * 272 * @param[in] param Parameters to start the audio streams. 273 * @param[out] unicast_group Pointer to the unicast group. 274 * 275 * @return 0 on success or negative error value on failure. 276 */ 277 int bt_cap_initiator_unicast_audio_start(const struct bt_cap_unicast_audio_start_param *param, 278 struct bt_bap_unicast_group *unicast_group); 279 280 /** 281 * @brief Update unicast audio streams. 282 * 283 * This will update the metadata of one or more streams. 284 * 285 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 286 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} must be enabled for this function 287 * to be enabled. 288 * 289 * @param params Array of update parameters. 290 * @param count The number of entries in @p params. 291 * 292 * @return 0 on success or negative error value on failure. 293 */ 294 int bt_cap_initiator_unicast_audio_update(const struct bt_cap_unicast_audio_update_param params[], 295 size_t count); 296 297 /** 298 * @brief Stop unicast audio streams for a unicast group. 299 * 300 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 301 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} must be enabled for this function 302 * to be enabled. 303 * 304 * @param unicast_group The group of unicast devices to stop. The audio streams 305 * in this will be stopped and reset, and the 306 * @p unicast_group will be invalidated. 307 * 308 * @return 0 on success or negative error value on failure. 309 */ 310 int bt_cap_initiator_unicast_audio_stop(struct bt_bap_unicast_group *unicast_group); 311 312 /** @brief Cancel any current Common Audio Profile procedure 313 * 314 * This will stop the current procedure from continuing and making it possible to run a new 315 * Common Audio Profile procedure. 316 * 317 * It is recommended to do this if any existing procedure take longer time than expected, which 318 * could indicate a missing response from the Common Audio Profile Acceptor. 319 * 320 * This does not send any requests to any Common Audio Profile Acceptors involved with the current 321 * procedure, and thus notifications from the Common Audio Profile Acceptors may arrive after this 322 * has been called. It is thus recommended to either only use this if a procedure has stalled, or 323 * wait a short while before starting any new Common Audio Profile procedure after this has been 324 * called to avoid getting notifications from the cancelled procedure. The wait time depends on 325 * the connection interval, the number of devices in the previous procedure and the behavior of the 326 * Common Audio Profile Acceptors. 327 * 328 * The respective callbacks of the procedure will be called as part of this with the connection 329 * pointer set to 0 and the err value set to -ECANCELED. 330 * 331 * @retval 0 on success 332 * @retval -EALREADY if no procedure is active 333 */ 334 int bt_cap_initiator_unicast_audio_cancel(void); 335 336 struct bt_cap_initiator_broadcast_stream_param { 337 /** Audio stream */ 338 struct bt_cap_stream *stream; 339 340 /** The length of the %p data array. 341 * 342 * The BIS specific data may be omitted and this set to 0. 343 */ 344 size_t data_len; 345 346 /** BIS Codec Specific Configuration */ 347 uint8_t *data; 348 }; 349 350 struct bt_cap_initiator_broadcast_subgroup_param { 351 /** The number of parameters in @p stream_params */ 352 size_t stream_count; 353 354 /** Array of stream parameters */ 355 struct bt_cap_initiator_broadcast_stream_param *stream_params; 356 357 /** Subgroup Codec configuration. */ 358 struct bt_audio_codec_cfg *codec_cfg; 359 }; 360 361 struct bt_cap_initiator_broadcast_create_param { 362 /** The number of parameters in @p subgroup_params */ 363 size_t subgroup_count; 364 365 /** Array of stream parameters */ 366 struct bt_cap_initiator_broadcast_subgroup_param *subgroup_params; 367 368 /** Quality of Service configuration. */ 369 struct bt_audio_codec_qos *qos; 370 371 /** @brief Broadcast Source packing mode. 372 * 373 * @ref BT_ISO_PACKING_SEQUENTIAL or @ref BT_ISO_PACKING_INTERLEAVED. 374 * 375 * @note This is a recommendation to the controller, which the 376 * controller may ignore. 377 */ 378 uint8_t packing; 379 380 /** Whether or not to encrypt the streams. */ 381 bool encryption; 382 383 /** 384 * @brief 16-octet broadcast code. 385 * 386 * Only valid if @p encrypt is true. 387 * 388 * If the value is a string or a the value is less than 16 octets, 389 * the remaining octets shall be 0. 390 * 391 * Example: 392 * The string "Broadcast Code" shall be 393 * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00] 394 */ 395 uint8_t broadcast_code[BT_AUDIO_BROADCAST_CODE_SIZE]; 396 }; 397 398 /** 399 * @brief Create a Common Audio Profile broadcast source. 400 * 401 * Create a new audio broadcast source with one or more audio streams. 402 * * * 403 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 404 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 405 * to be enabled. 406 * 407 * @param[in] param Parameters to start the audio streams. 408 * @param[out] broadcast_source Pointer to the broadcast source created. 409 * 410 * @return 0 on success or negative error value on failure. 411 */ 412 int bt_cap_initiator_broadcast_audio_create( 413 const struct bt_cap_initiator_broadcast_create_param *param, 414 struct bt_cap_broadcast_source **broadcast_source); 415 416 /** 417 * @brief Start Common Audio Profile broadcast source. 418 * 419 * The broadcast source will be visible for scanners once this has been called, 420 * and the device will advertise audio announcements. 421 * 422 * This will allow the streams in the broadcast source to send audio by calling 423 * bt_bap_stream_send(). 424 * 425 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 426 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 427 * to be enabled. 428 * 429 * @param broadcast_source Pointer to the broadcast source. 430 * @param adv Pointer to an extended advertising set with 431 * periodic advertising configured. 432 * 433 * @return 0 on success or negative error value on failure. 434 */ 435 int bt_cap_initiator_broadcast_audio_start(struct bt_cap_broadcast_source *broadcast_source, 436 struct bt_le_ext_adv *adv); 437 /** 438 * @brief Update broadcast audio streams for a Common Audio Profile broadcast source. 439 * 440 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 441 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 442 * to be enabled. 443 * 444 * @param broadcast_source The broadcast source to update. 445 * @param meta The new metadata. The metadata shall contain a list 446 * of CCIDs as well as a non-0 context bitfield. 447 * @param meta_len The length of @p meta. 448 * 449 * @return 0 on success or negative error value on failure. 450 */ 451 int bt_cap_initiator_broadcast_audio_update(struct bt_cap_broadcast_source *broadcast_source, 452 const uint8_t meta[], size_t meta_len); 453 454 /** 455 * @brief Stop broadcast audio streams for a Common Audio Profile broadcast source. 456 * 457 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 458 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 459 * to be enabled. 460 * 461 * @param broadcast_source The broadcast source to stop. The audio streams 462 * in this will be stopped and reset. 463 * 464 * @return 0 on success or negative error value on failure. 465 */ 466 int bt_cap_initiator_broadcast_audio_stop(struct bt_cap_broadcast_source *broadcast_source); 467 468 /* 469 * @brief Delete Common Audio Profile broadcast source 470 * 471 * This can only be done after the broadcast source has been stopped by calling 472 * bt_cap_initiator_broadcast_audio_stop() and after the 473 * bt_bap_stream_ops.stopped() callback has been called for all streams in the 474 * broadcast source. 475 * 476 * @note @kconfig{CONFIG_BT_CAP_INITIATOR} and 477 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 478 * to be enabled. 479 * 480 * @param broadcast_source The broadcast source to delete. 481 * The @p broadcast_source will be invalidated. 482 * 483 * @return 0 on success or negative error value on failure. 484 */ 485 int bt_cap_initiator_broadcast_audio_delete(struct bt_cap_broadcast_source *broadcast_source); 486 487 /** 488 * @brief Get the broadcast ID of a Common Audio Profile broadcast source 489 * 490 * This will return the 3-octet broadcast ID that should be advertised in the 491 * extended advertising data with @ref BT_UUID_BROADCAST_AUDIO_VAL as 492 * @ref BT_DATA_SVC_DATA16. 493 * 494 * See table 3.14 in the Basic Audio Profile v1.0.1 for the structure. 495 * 496 * @param[in] broadcast_source Pointer to the broadcast source. 497 * @param[out] broadcast_id Pointer to the 3-octet broadcast ID. 498 * 499 * @return int 0 if on success, errno on error. 500 */ 501 int bt_cap_initiator_broadcast_get_id(const struct bt_cap_broadcast_source *broadcast_source, 502 uint32_t *const broadcast_id); 503 504 /** 505 * @brief Get the Broadcast Audio Stream Endpoint of a Common Audio Profile broadcast source 506 * 507 * This will encode the BASE of a broadcast source into a buffer, that can be 508 * used for advertisement. The encoded BASE will thus be encoded as 509 * little-endian. The BASE shall be put into the periodic advertising data 510 * (see bt_le_per_adv_set_data()). 511 * 512 * See table 3.15 in the Basic Audio Profile v1.0.1 for the structure. 513 * 514 * @param broadcast_source Pointer to the broadcast source. 515 * @param base_buf Pointer to a buffer where the BASE will be inserted. 516 * 517 * @return int 0 if on success, errno on error. 518 */ 519 int bt_cap_initiator_broadcast_get_base(struct bt_cap_broadcast_source *broadcast_source, 520 struct net_buf_simple *base_buf); 521 522 struct bt_cap_unicast_to_broadcast_param { 523 /** The source unicast group with the streams. */ 524 struct bt_bap_unicast_group *unicast_group; 525 526 /** 527 * @brief Whether or not to encrypt the streams. 528 * 529 * If set to true, then the broadcast code in @p broadcast_code 530 * will be used to encrypt the streams. 531 */ 532 bool encrypt; 533 534 /** 535 * @brief 16-octet broadcast code. 536 * 537 * Only valid if @p encrypt is true. 538 * 539 * If the value is a string or a the value is less than 16 octets, 540 * the remaining octets shall be 0. 541 * 542 * Example: 543 * The string "Broadcast Code" shall be 544 * [42 72 6F 61 64 63 61 73 74 20 43 6F 64 65 00 00] 545 */ 546 uint8_t broadcast_code[BT_ISO_BROADCAST_CODE_SIZE]; 547 }; 548 549 /** 550 * @brief Hands over the data streams in a unicast group to a broadcast source. 551 * 552 * The streams in the unicast group will be stopped and the unicast group 553 * will be deleted. This can only be done for source streams. 554 * 555 * @note @kconfig{CONFIG_BT_CAP_INITIATOR}, 556 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} and 557 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 558 * to be enabled. 559 * 560 * @param param The parameters for the handover. 561 * @param source The resulting broadcast source. 562 * 563 * @return 0 on success or negative error value on failure. 564 */ 565 int bt_cap_initiator_unicast_to_broadcast(const struct bt_cap_unicast_to_broadcast_param *param, 566 struct bt_cap_broadcast_source **source); 567 568 struct bt_cap_broadcast_to_unicast_param { 569 /** 570 * @brief The source broadcast source with the streams. 571 * 572 * The broadcast source will be stopped and deleted. 573 */ 574 struct bt_cap_broadcast_source *broadcast_source; 575 576 /** The type of the set. */ 577 enum bt_cap_set_type type; 578 579 /** 580 * @brief The number of set members in @p members. 581 * 582 * This value shall match the number of streams in the 583 * @p broadcast_source. 584 * 585 */ 586 size_t count; 587 588 /** Coordinated or ad-hoc set members. */ 589 union bt_cap_set_member **members; 590 }; 591 592 /** 593 * @brief Hands over the data streams in a broadcast source to a unicast group. 594 * 595 * The streams in the broadcast source will be stopped and the broadcast source 596 * will be deleted. 597 * 598 * @note @kconfig{CONFIG_BT_CAP_INITIATOR}, 599 * @kconfig{CONFIG_BT_BAP_UNICAST_CLIENT} and 600 * @kconfig{CONFIG_BT_BAP_BROADCAST_SOURCE} must be enabled for this function 601 * to be enabled. 602 * 603 * @param[in] param The parameters for the handover. 604 * @param[out] unicast_group The resulting broadcast source. 605 * 606 * @return 0 on success or negative error value on failure. 607 */ 608 int bt_cap_initiator_broadcast_to_unicast(const struct bt_cap_broadcast_to_unicast_param *param, 609 struct bt_bap_unicast_group **unicast_group); 610 611 #ifdef __cplusplus 612 } 613 #endif 614 615 /** 616 * @} 617 */ 618 619 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_AUDIO_CAP_H_ */ 620
