1Bluetooth: Common Audio Profile Shell 2##################################### 3 4This document describes how to run the Common Audio Profile functionality. 5 6CAP Acceptor 7************ 8 9The Acceptor will typically be a resource-constrained device, such as a headset, earbud or hearing 10aid. The Acceptor can initialize a Coordinated Set Identification Service instance, if it is in 11a pair with one or more other CAP Acceptors. 12 13Using the CAP Acceptor 14====================== 15 16When the Bluetooth stack has been initialized (:code:`bt init`), the Acceptor can be registered by 17calling :code:`cap_acceptor init`, which will register the CAS and CSIS services, as well as 18register callbacks. 19 20.. code-block:: console 21 22 23 cap_acceptor --help 24 cap_acceptor - Bluetooth CAP acceptor shell commands 25 Subcommands: 26 init :Initialize the service and register callbacks [size <int>] 27 [rank <int>] [not-lockable] [sirk <data>] 28 lock :Lock the set 29 release :Release the set [force] 30 sirk :Set the currently used SIRK <sirk> 31 get_info :Get CSIS info 32 sirk_rsp :Set the response used in SIRK requests <accept, accept_enc, 33 reject, oob> 34 35Besides initializing the CAS and the CSIS, there are also commands to lock and release the CSIS 36instance, as well as printing and modifying access to the SIRK of the CSIS. 37 38Setting a new SIRK 39------------------ 40 41This command can modify the currently used SIRK. To get the new RSI to advertise on air, 42:code:`bt adv-data` or :code:`bt advertise` must be called again to set the new advertising data. 43If :code:`CONFIG_BT_CSIP_SET_MEMBER_SIRK_NOTIFIABLE` is enabled, this will also notify connected 44clients. 45 46.. code-block:: console 47 48 uart:~$ cap_acceptor sirk 00112233445566778899aabbccddeeff 49 SIRK updated 50 51Getting the current SIRK 52------------------------ 53 54This command can get the currently used SIRK. 55 56.. code-block:: console 57 58 uart:~$ cap_acceptor get_info 59 Info for 0x2003b0c8 60 SIRK 61 00000000: 20 37 0a 00 95 c4 04 20 00 00 00 00 f1 79 09 00 | 7..... .....y..| 62 Set size: 2 63 Rank: 1 64 Lockable: true 65 Locked: false 66 67CAP Initiator 68************* 69 70The Initiator will typically be a resource-rich device, such as a phone or PC. The Initiator can 71discover CAP Acceptors's CAS and optional CSIS services. The CSIS service can be read to provide 72information about other CAP Acceptors in the same Coordinated Set. The Initiator can execute 73stream control procedures on sets of devices, either ad-hoc or Coordinated, and thus provides an 74easy way to setup multiple streams on multiple devices at once. 75 76Using the CAP Initiator 77======================= 78 79When the Bluetooth stack has been initialized (:code:`bt init`), the Initiator can discover CAS and 80the optionally included CSIS instance by calling (:code:`cap_initiator discover`). 81The CAP initiator also supports broadcast audio as a source. 82 83.. code-block:: console 84 85 uart:~$ cap_initiator --help 86 cap_initiator - Bluetooth CAP initiator shell commands 87 Subcommands: 88 discover : Discover CAS 89 unicast_start : Unicast Start [csip] [sinks <cnt> (default 1)] [sources 90 <cnt> (default 1)] [conns (<cnt> | all) (default 1)] 91 unicast_list : Unicast list streams 92 unicast_update : Unicast Update <all | stream [stream [stream...]]> 93 unicast_stop : Unicast stop streams [stream [stream [stream...]]] (all by default) 94 unicast_cancel : Unicast cancel current procedure 95 ac_1 : Unicast audio configuration 1 96 ac_2 : Unicast audio configuration 2 97 ac_3 : Unicast audio configuration 3 98 ac_4 : Unicast audio configuration 4 99 ac_5 : Unicast audio configuration 5 100 ac_6_i : Unicast audio configuration 6(i) 101 ac_6_ii : Unicast audio configuration 6(ii) 102 ac_7_i : Unicast audio configuration 7(i) 103 ac_7_ii : Unicast audio configuration 7(ii) 104 ac_8_i : Unicast audio configuration 8(i) 105 ac_8_ii : Unicast audio configuration 8(ii) 106 ac_9_i : Unicast audio configuration 9(i) 107 ac_9_ii : Unicast audio configuration 9(ii) 108 ac_10 : Unicast audio configuration 10 109 ac_11_i : Unicast audio configuration 11(i) 110 ac_11_ii : Unicast audio configuration 11(ii) 111 broadcast_start : 112 broadcast_update : <meta> 113 broadcast_stop : 114 broadcast_delete : 115 ac_12 : Broadcast audio configuration 12 116 ac_13 : Broadcast audio configuration 13 117 ac_14 : Broadcast audio configuration 14 118 119Before being able to perform any stream operation, the device must also perform the 120:code:`bap discover` operation to discover the ASEs and PAC records. The :code:`bap init` 121command also needs to be called. 122 123When connected 124-------------- 125 126Discovering CAS and CSIS on a device: 127 128.. code-block:: console 129 130 uart:~$ cap_initiator discover 131 discovery completed with CSIS 132 133 134Discovering ASEs and PAC records on a device: 135 136.. code-block:: console 137 138 uart:~$ bap discover 139 conn 0x81cc260: #0: codec 0x81d5b28 dir 0x01 140 codec 0x06 cid 0x0000 vid 0x0000 count 5 141 data #0: type 0x01 len 2 142 00000000: f5 |. | 143 data #1: type 0x02 len 1 144 data #2: type 0x03 len 1 145 data #3: type 0x04 len 4 146 00000000: 1e 00 f0 |... | 147 data #4: type 0x05 len 1 148 meta #0: type 0x01 len 2 149 00000000: 06 |. | 150 dir 1 loc 1 151 snk ctx 6 src ctx 6 152 Conn: 0x81cc260, Sink #0: ep 0x81e4248 153 Conn: 0x81cc260, Sink #1: ep 0x81e46a8 154 conn 0x81cc260: #0: codec 0x81d5f00 dir 0x02 155 codec 0x06 cid 0x0000 vid 0x0000 count 5 156 data #0: type 0x01 len 2 157 00000000: f5 |. | 158 data #1: type 0x02 len 1 159 data #2: type 0x03 len 1 160 data #3: type 0x04 len 4 161 00000000: 1e 00 f0 |... | 162 data #4: type 0x05 len 1 163 meta #0: type 0x01 len 2 164 00000000: 06 |. | 165 dir 2 loc 1 166 snk ctx 6 src ctx 6 167 Conn: 0x81cc260, Source #0: ep 0x81e5c88 168 Conn: 0x81cc260, Source #1: ep 0x81e60e8 169 Discover complete: err 0 170 171Both of the above commands should be done for each device that you want to use in the set. 172To use multiple devices, simply connect to more and then use :code:`bt select` the device to execute 173the commands on. 174 175Once all devices have been connected and the respective discovery commands have been called, the 176:code:`cap_initiator unicast_start` command can be used to put one or more streams into the 177streaming state. 178 179.. code-block:: console 180 181 uart:~$ cap_initiator unicast_start sinks 1 sources 0 conns all 182 Setting up 1 sinks and 0 sources on each (2) conn 183 Starting 1 streams 184 Unicast start completed 185 186To stop all the streams that has been started, the :code:`cap_initiator unicast_stop` command can be 187used. 188 189 190.. code-block:: console 191 192 uart:~$ cap_initiator unicast_stop all 193 Unicast stop completed 194 195When doing broadcast 196-------------------- 197 198To start a broadcast as the CAP initiator there are a few steps to be done: 199 2001. Create and configure an extended advertising set with periodic advertising 2012. Create and configure a broadcast source 2023. Setup extended and periodic advertising data 203 204The following commands will setup a CAP broadcast source using the 16_2_1 preset (defined by BAP): 205 206 207.. code-block:: console 208 209 bt init 210 bap init 211 bt adv-create nconn-nscan ext-adv name 212 bt per-adv-param 213 bap preset broadcast 16_2_1 214 cap_initiator ac_12 215 bt adv-data discov 216 bt per-adv-data 217 cap_initiator broadcast_start 218 219 220The broadcast source is created by the :code:`cap_initiator ac_12`, :code:`cap_initiator ac_13`, 221and :code:`cap_initiator ac_14` commands, configuring the broadcast source for the defined audio 222configurations from BAP. The broadcast source can then be stopped with 223:code:`cap_initiator broadcast_stop` or deleted with :code:`cap_initiator broadcast_delete`. 224 225The metadata of the broadcast source can be updated at any time, including when it is already 226streaming. To update the metadata the :code:`cap_initiator broadcast_update` command can be used. 227The command takes an array of data, and the only requirement (besides having valid data) is that the 228streaming context shall be set. For example to set the streaming context to media, the command can 229be used as 230 231.. code-block:: console 232 233 cap_initiator broadcast_update 03020400 234 CAP Broadcast source updated with new metadata. Update the advertised base via `bt per-adv-data` 235 bt per-adv-data 236 237The :code:`bt per-adv-data` command should be used afterwards to update the data is the advertised 238BASE. The data must be little-endian, so in the above example the metadata :code:`03020400` is 239setting the metadata entry with :code:`03` as the length, :code:`02` as the type (streaming context) 240and :code:`0400` as the value :code:`BT_AUDIO_CONTEXT_TYPE_MEDIA` 241(which has the numeric value of 0x). 242 243CAP Commander 244************* 245 246The Commander will typically be a either co-located with a CAP Initiator or be on a separate 247resource-rich mobile device, such as a phone or smartwatch. The Commander can 248discover CAP Acceptors's CAS and optional CSIS services. The CSIS service can be read to provide 249information about other CAP Acceptors in the same Coordinated Set. The Commander can provide 250information about broadcast sources to CAP Acceptors or coordinate capture and rendering information 251such as mute or volume states. 252 253Using the CAP Commander 254======================= 255 256When the Bluetooth stack has been initialized (:code:`bt init`), the Commander can discover CAS and 257the optionally included CSIS instance by calling (:code:`cap_commander discover`). 258 259.. code-block:: console 260 261 cap_commander --help 262 cap_commander - Bluetooth CAP commander shell commands 263 Subcommands: 264 discover :Discover CAS 265 cancel :CAP commander cancel current procedure 266 change_volume :Change volume on all connections <volume> 267 change_volume_mute :Change volume mute state on all connections <mute> 268 change_volume_offset :Change volume offset per connection <volume_offset 269 [volume_offset [...]]> 270 change_microphone_mute :Change microphone mute state on all connections <mute> 271 change_microphone_gain :Change microphone gain per connection <gain 272 [gain [...]]> 273 broadcast_reception_start : Start broadcast reception with 274 source <address: XX:XX:XX:XX:XX:XX> 275 <type: public/random> <adv_sid> <broadcast_id> 276 [<pa_interval>] [<sync_bis>] [<metadata>] 277 broadcast_reception_stop : Stop broadcast reception <src_id [...]> 278 distribute_broadcast_code : Distribute broadcast code <src_id [...]> <broadcast_code> 279 280 281Before being able to perform any stream operation, the device must also perform the 282:code:`bap discover` operation to discover the ASEs and PAC records. The :code:`bap init` 283command also needs to be called. 284 285When connected 286-------------- 287 288Discovering CAS and CSIS on a device 289^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 290 291.. code-block:: console 292 293 uart:~$ cap_commander discover 294 discovery completed with CSIS 295 296 297Setting the volume on all connected devices 298^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 299 300.. code-block:: console 301 302 uart:~$ vcp_vol_ctlr discover 303 VCP discover done with 1 VOCS and 1 AICS 304 uart:~$ cap_commander change_volume 15 305 uart:~$ cap_commander change_volume 15 306 Setting volume to 15 on 2 connections 307 VCP volume 15, mute 0 308 VCP vol_set done 309 VCP volume 15, mute 0 310 VCP flags 0x01 311 VCP vol_set done 312 Volume change completed 313 314Setting the volume offset on one or more devices 315^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 316The offsets are set by connection index, so connection index 0 gets the first offset, 317and index 1 gets the second offset, etc.: 318 319.. code-block:: console 320 321 uart:~$ bt connect <device A> 322 Connected: <device A> 323 uart:~$ cap_commander discover 324 discovery completed with CSIS 325 uart:~$ vcp_vol_ctlr discover 326 VCP discover done with 1 VOCS and 1 AICS 327 uart:~$ 328 uart:~$ bt connect <device B> 329 Connected: <device B> 330 uart:~$ cap_commander discover 331 discovery completed with CSIS 332 uart:~$ vcp_vol_ctlr discover 333 VCP discover done with 1 VOCS and 1 AICS 334 uart:~$ 335 uart:~$ cap_commander change_volume_offset 10 336 Setting volume offset on 1 connections 337 VOCS inst 0x200140a4 offset 10 338 Offset set for inst 0x200140a4 339 Volume offset change completed 340 uart:~$ 341 uart:~$ cap_commander change_volume_offset 10 15 342 Setting volume offset on 2 connections 343 Offset set for inst 0x200140a4 344 VOCS inst 0x20014188 offset 15 345 Offset set for inst 0x20014188 346 Volume offset change completed 347 348Setting the volume mute on all connected devices 349^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 350 351.. code-block:: console 352 353 uart:~$ bt connect <device A> 354 Connected: <device A> 355 uart:~$ cap_commander discover 356 discovery completed with CSIS 357 uart:~$ vcp_vol_ctlr discover 358 VCP discover done with 1 VOCS and 1 AICS 359 uart:~$ 360 uart:~$ bt connect <device B> 361 Connected: <device B> 362 uart:~$ cap_commander discover 363 discovery completed with CSIS 364 uart:~$ vcp_vol_ctlr discover 365 VCP discover done with 1 VOCS and 1 AICS 366 uart:~$ 367 uart:~$ cap_commander change_volume_mute 1 368 Setting volume mute to 1 on 2 connections 369 VCP volume 100, mute 1 370 VCP mute done 371 VCP volume 100, mute 1 372 VCP mute done 373 Volume mute change completed 374 uart:~$ cap_commander change_volume_mute 0 375 Setting volume mute to 0 on 2 connections 376 VCP volume 100, mute 0 377 VCP unmute done 378 VCP volume 100, mute 0 379 VCP unmute done 380 Volume mute change completed 381 382Setting the microphone mute on all connected devices 383^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 384 385.. code-block:: console 386 387 uart:~$ bt connect <device A> 388 Connected: <device A> 389 uart:~$ cap_commander discover 390 discovery completed with CSIS 391 uart:~$ micp_mic_ctlr discover 392 MICP discover done with 1 VOCS and 1 AICS 393 uart:~$ 394 uart:~$ bt connect <device B> 395 Connected: <device B> 396 uart:~$ cap_commander discover 397 discovery completed with CSIS 398 uart:~$ micp_mic_ctlr discover 399 MICP discover done with 1 VOCS and 1 AICS 400 uart:~$ 401 uart:~$ cap_commander change_microphone_mute 1 402 Setting microphone mute to 1 on 2 connections 403 MICP microphone 100, mute 1 404 MICP mute done 405 MICP microphone 100, mute 1 406 MICP mute done 407 Microphone mute change completed 408 uart:~$ cap_commander change_microphone_mute 0 409 Setting microphone mute to 0 on 2 connections 410 MICP microphone 100, mute 0 411 MICP unmute done 412 MICP microphone 100, mute 0 413 MICP unmute done 414 Microphone mute change completed 415 416Setting the microphone gain on one or more devices 417^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 418The gains are set by connection index, so connection index 0 gets the first offset, 419and index 1 gets the second offset, etc.: 420 421.. code-block:: console 422 423 uart:~$ bt connect <device A> 424 Connected: <device A> 425 uart:~$ cap_commander discover 426 discovery completed with CSIS 427 uart:~$ micp_mic_ctlr discover 428 MICP discover done with 1 AICS 429 uart:~$ 430 uart:~$ bt connect <device B> 431 Connected: <device B> 432 uart:~$ cap_commander discover 433 discovery completed with CSIS 434 uart:~$ micp_mic_ctlr discover 435 MICP discover done with 1 AICS 436 uart:~$ 437 uart:~$ cap_commander change_microphone_gain 10 438 Setting microphone gain on 1 connections 439 AICS inst 0x200140a4 state gain 10, mute 0, mode 0 440 Gain set for inst 0x200140a4 441 Microphone gain change completed 442 uart:~$ 443 uart:~$ cap_commander change_microphone_gain 10 15 444 Setting microphone gain on 2 connections 445 Gain set for inst 0x200140a4 446 AICS inst 0x20014188 state gain 15, mute 0, mode 0 447 Gain set for inst 0x20014188 448 Microphone gain change completed 449 450Starting and stopping broadcast reception 451^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 452 453.. code-block:: console 454 455 uart:~$ bt connect <device A> 456 Connected: <device A> 457 uart:~$ bap_init 458 uart:~$ cap_commander discover 459 discovery completed with CSIS 460 uart:~$ bap_broadcast_assistant discover 461 BASS discover done with 1 recv states 462 uart:~$ cap_commander broadcast_reception_start <device B> 0 4 463 Starting broadcast reception on 1 connection(s) 464 Broadcast reception start completed 465 uart:~$ cap_commander broadcast_reception_stop 0 466 Stopping broadcast reception on 1 connection(s) 467 Broadcast reception stop completed 468 469Distributing the broadcast code 470^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 471 472.. code-block:: console 473 474 uart:~$ bt connect <device A> 475 Connected: <device A> 476 uart:~$ bap_init 477 uart:~$ cap_commander discover 478 discovery completed with CSIS 479 uart:~$ bap_broadcast_assistant discover 480 BASS discover done with 1 recv states 481 uart:~$ cap_commander broadcast_reception_start <device B> 0 4 482 Starting broadcast reception on 1 connection(s) 483 Broadcast reception start completed 484 uart:~$ cap_commander distribute_broadcast_code 0 "BroadcastCode" 485 Distribute broadcast code completed 486