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