| Bluetooth: Common Audio Profile Shell |
| ##################################### |
| |
| This document describes how to run the Common Audio Profile functionality. |
| |
| CAP Acceptor |
| ************ |
| |
| The Acceptor will typically be a resource-constrained device, such as a headset, earbud or hearing |
| aid. The Acceptor can initialize a Coordinated Set Identification Service instance, if it is in |
| a pair with one or more other CAP Acceptors. |
| |
| Using the CAP Acceptor |
| ====================== |
| |
| When the Bluetooth stack has been initialized (:code:`bt init`), the Acceptor can be registered by |
| calling :code:`cap_acceptor init`, which will register the CAS and CSIS services, as well as |
| register callbacks. |
| |
| .. code-block:: console |
| |
| |
| cap_acceptor --help |
| cap_acceptor - Bluetooth CAP acceptor shell commands |
| Subcommands: |
| init :Initialize the service and register callbacks [size <int>] |
| [rank <int>] [not-lockable] [sirk <data>] |
| lock :Lock the set |
| release :Release the set [force] |
| set_sirk :Set the currently used SIRK <sirk> |
| get_sirk :Get the currently used SIRK |
| set_sirk_rsp :Set the response used in SIRK requests <accept, accept_enc, |
| reject, oob> |
| |
| Besides initializing the CAS and the CSIS, there are also commands to lock and release the CSIS |
| instance, as well as printing and modifying access to the SIRK of the CSIS. |
| |
| Setting a new SIRK |
| ------------------ |
| |
| This command can modify the currently used SIRK. To get the new RSI to advertise on air, |
| :code:`bt adv-data` or :code:`bt advertise` must be called again to set the new advertising data. |
| If :code:`CONFIG_BT_CSIP_SET_MEMBER_NOTIFIABLE` is enabled, this will also notify connected |
| clients. |
| |
| .. code-block:: console |
| |
| uart:~$ cap_acceptor set_sirk 00112233445566778899aabbccddeeff |
| Set SIRK updated |
| |
| Getting the current SIRK |
| ------------------------ |
| |
| This command can get the currently used SIRK. |
| |
| .. code-block:: console |
| |
| uart:~$ cap_acceptor get_sirk |
| Set SIRK |
| 36 04 9a dc 66 3a a1 a1 |6...f:.. |
| 1d 9a 2f 41 01 73 3e 01 |../A.s>. |
| |
| CAP Initiator |
| ************* |
| |
| The Initiator will typically be a resource-rich device, such as a phone or PC. The Initiator can |
| discover CAP Acceptors's CAS and optional CSIS services. The CSIS service can be read to provide |
| information about other CAP Acceptors in the same Coordinated Set. The Initiator can execute |
| stream control procedures on sets of devices, either ad-hoc or Coordinated, and thus provides an |
| easy way to setup multiple streams on multiple devices at once. |
| |
| Using the CAP Initiator |
| ======================= |
| |
| When the Bluetooth stack has been initialized (:code:`bt init`), the Initiator can discover CAS and |
| the optionally included CSIS instance by calling (:code:`cap_initiator discover`). |
| The CAP initiator also supports broadcast audio as a source. |
| |
| .. code-block:: console |
| |
| cap_initiator --help |
| cap_initiator - Bluetooth CAP initiator shell commands |
| Subcommands: |
| discover :Discover CAS |
| unicast_start :Unicast Start [csip] [sinks <cnt> (default 1)] [sources <cnt> |
| (default 1)] [conns (<cnt> | all) (default 1)] |
| unicast_list :Unicast list streams |
| unicast_update :Unicast Update <all | stream [stream [stream...]]> |
| unicast_stop :Unicast stop streams <all | stream [stream [stream...]]> |
| unicast_cancel :Unicast cancel current procedure |
| |
| Before being able to perform any stream operation, the device must also perform the |
| :code:`bap discover` operation to discover the ASEs and PAC records. The :code:`bap init` |
| command also needs to be called. |
| |
| When connected |
| -------------- |
| |
| Discovering CAS and CSIS on a device: |
| |
| .. code-block:: console |
| |
| uart:~$ cap_initiator discover |
| discovery completed with CSIS |
| |
| |
| Discovering ASEs and PAC records on a device: |
| |
| .. code-block:: console |
| |
| uart:~$ bap discover |
| conn 0x81cc260: #0: codec 0x81d5b28 dir 0x01 |
| codec 0x06 cid 0x0000 vid 0x0000 count 5 |
| data #0: type 0x01 len 2 |
| 00000000: f5 |. | |
| data #1: type 0x02 len 1 |
| data #2: type 0x03 len 1 |
| data #3: type 0x04 len 4 |
| 00000000: 1e 00 f0 |... | |
| data #4: type 0x05 len 1 |
| meta #0: type 0x01 len 2 |
| 00000000: 06 |. | |
| dir 1 loc 1 |
| snk ctx 6 src ctx 6 |
| Conn: 0x81cc260, Sink #0: ep 0x81e4248 |
| Conn: 0x81cc260, Sink #1: ep 0x81e46a8 |
| conn 0x81cc260: #0: codec 0x81d5f00 dir 0x02 |
| codec 0x06 cid 0x0000 vid 0x0000 count 5 |
| data #0: type 0x01 len 2 |
| 00000000: f5 |. | |
| data #1: type 0x02 len 1 |
| data #2: type 0x03 len 1 |
| data #3: type 0x04 len 4 |
| 00000000: 1e 00 f0 |... | |
| data #4: type 0x05 len 1 |
| meta #0: type 0x01 len 2 |
| 00000000: 06 |. | |
| dir 2 loc 1 |
| snk ctx 6 src ctx 6 |
| Conn: 0x81cc260, Source #0: ep 0x81e5c88 |
| Conn: 0x81cc260, Source #1: ep 0x81e60e8 |
| Discover complete: err 0 |
| |
| Both of the above commands should be done for each device that you want to use in the set. |
| To use multiple devices, simply connect to more and then use :code:`bt select` the device to execute |
| the commands on. |
| |
| Once all devices have been connected and the respective discovery commands have been called, the |
| :code:`cap_initiator unicast_start` command can be used to put one or more streams into the |
| streaming state. |
| |
| .. code-block:: console |
| |
| uart:~$ cap_initiator unicast_start sinks 1 sources 0 conns all |
| Setting up 1 sinks and 0 sources on each (2) conn |
| Starting 1 streams |
| Unicast start completed |
| |
| To stop all the streams that has been started, the :code:`cap_initiator unicast_stop` command can be |
| used. |
| |
| |
| .. code-block:: console |
| |
| uart:~$ cap_initiator unicast_stop all |
| Unicast stop completed |
| |
| When doing broadcast |
| -------------------- |
| |
| To start a broadcast as the CAP initiator there are a few steps to be done: |
| |
| 1. Create and configure an extended advertising set with periodic advertising |
| 2. Create and configure a broadcast source |
| 3. Setup extended and periodic advertising data |
| |
| The following commands will setup a CAP broadcast source using the 16_2_1 preset (defined by BAP): |
| |
| |
| .. code-block:: console |
| |
| bt init |
| bap init |
| bt adv-create nconn-nscan ext-adv name |
| bt per-adv-param |
| cap_initiator ac_12 16_2_1 |
| bt adv-data discov |
| bt per-adv-data |
| cap_initiator broadcast_start |
| |
| |
| The broadcast source is created by the :code:`cap_initiator ac_12`, :code:`cap_initiator ac_13`, |
| and :code:`cap_initiator ac_14` commands, configuring the broadcast source for the defined audio |
| configurations from BAP. The broadcast source can then be stopped with |
| :code:`cap_initiator broadcast_stop` or deleted with :code:`cap_initiator broadcast_delete`. |
| |
| The metadata of the broadcast source can be updated at any time, including when it is already |
| streaming. To update the metadata the :code:`cap_initiator broadcast_update` command can be used. |
| The command takes an array of data, and the only requirement (besides having valid data) is that the |
| streaming context shall be set. For example to set the streaming context to media, the command can |
| be used as |
| |
| .. code-block:: console |
| |
| cap_initiator broadcast_update 03020400 |
| CAP Broadcast source updated with new metadata. Update the advertised base via `bt per-adv-data` |
| bt per-adv-data |
| |
| The :code:`bt per-adv-data` command should be used afterwards to update the data is the advertised |
| BASE. The data must be little-endian, so in the above example the metadata :code:`03020400` is |
| setting the metadata entry with :code:`03` as the length, :code:`02` as the type (streaming context) |
| and :code:`0400` as the value :code:`BT_AUDIO_CONTEXT_TYPE_MEDIA` |
| (which has the numeric value of 0x). |
| |
| CAP Commander |
| ************* |
| |
| The Commander will typically be a either co-located with a CAP Initiator or be on a separate |
| resource-rich mobile device, such as a phone or smartwatch. The Commander can |
| discover CAP Acceptors's CAS and optional CSIS services. The CSIS service can be read to provide |
| information about other CAP Acceptors in the same Coordinated Set. The Commander can provide |
| information about broadcast sources to CAP Acceptors or coordinate capture and rendering information |
| such as mute or volume states. |
| |
| Using the CAP Commander |
| ======================= |
| |
| When the Bluetooth stack has been initialized (:code:`bt init`), the Commander can discover CAS and |
| the optionally included CSIS instance by calling (:code:`cap_commander discover`). |
| |
| .. code-block:: console |
| |
| cap_commander --help |
| cap_commander - Bluetooth CAP commander shell commands |
| Subcommands: |
| discover :Discover CAS |
| change_volume :Change volume on all connections <volume> |
| change_volume_offset :Change volume offset per connection <volume_offset |
| [volume_offset [...]]> |
| |
| |
| Before being able to perform any stream operation, the device must also perform the |
| :code:`bap discover` operation to discover the ASEs and PAC records. The :code:`bap init` |
| command also needs to be called. |
| |
| When connected |
| -------------- |
| |
| Discovering CAS and CSIS on a device |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| .. code-block:: console |
| |
| uart:~$ cap_commander discover |
| discovery completed with CSIS |
| |
| |
| Setting the volume on all connected devices |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| .. code-block:: console |
| |
| uart:~$ vcp_vol_ctlr discover |
| VCP discover done with 1 VOCS and 1 AICS |
| uart:~$ cap_commander change_volume 15 |
| uart:~$ cap_commander change_volume 15 |
| Setting volume to 15 on 2 connections |
| VCP volume 15, mute 0 |
| VCP vol_set done |
| VCP volume 15, mute 0 |
| VCP flags 0x01 |
| VCP vol_set done |
| Volume change completed |
| |
| Setting the volume offset on one or more devices |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| The offsets are set by connection index, so connection index 0 gets the first offset, |
| and index 1 gets the second offset, etc.: |
| |
| .. code-block:: console |
| |
| uart:~$ bt connect <device A> |
| Connected: <device A> |
| uart:~$ cap_commander discover |
| discovery completed with CSIS |
| uart:~$ vcp_vol_ctlr discover |
| VCP discover done with 1 VOCS and 1 AICS |
| uart:~$ |
| uart:~$ bt connect <device B> |
| Connected: <device B> |
| uart:~$ cap_commander discover |
| discovery completed with CSIS |
| uart:~$ vcp_vol_ctlr discover |
| VCP discover done with 1 VOCS and 1 AICS |
| uart:~$ |
| uart:~$ cap_commander change_volume_offset 10 |
| Setting volume offset on 1 connections |
| VOCS inst 0x200140a4 offset 10 |
| Offset set for inst 0x200140a4 |
| Volume offset change completed |
| uart:~$ |
| uart:~$ cap_commander change_volume_offset 10 15 |
| Setting volume offset on 2 connections |
| Offset set for inst 0x200140a4 |
| VOCS inst 0x20014188 offset 15 |
| Offset set for inst 0x20014188 |
| Volume offset change completed |
| |
| Setting the volume mute on all connected devices |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| .. code-block:: console |
| |
| uart:~$ bt connect <device A> |
| Connected: <device A> |
| uart:~$ cap_commander discover |
| discovery completed with CSIS |
| uart:~$ vcp_vol_ctlr discover |
| VCP discover done with 1 VOCS and 1 AICS |
| uart:~$ |
| uart:~$ bt connect <device B> |
| Connected: <device B> |
| uart:~$ cap_commander discover |
| discovery completed with CSIS |
| uart:~$ vcp_vol_ctlr discover |
| VCP discover done with 1 VOCS and 1 AICS |
| uart:~$ |
| uart:~$ cap_commander change_volume_mute 1 |
| Setting volume mute to 1 on 2 connections |
| VCP volume 100, mute 1 |
| VCP mute done |
| VCP volume 100, mute 1 |
| VCP mute done |
| Volume mute change completed |
| uart:~$ cap_commander change_volume_mute 0 |
| Setting volume mute to 0 on 2 connections |
| VCP volume 100, mute 0 |
| VCP unmute done |
| VCP volume 100, mute 0 |
| VCP unmute done |
| Volume mute change completed |
| |
| Setting the microphone gain on one or more devices |
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| The gains are set by connection index, so connection index 0 gets the first offset, |
| and index 1 gets the second offset, etc.: |
| |
| .. code-block:: console |
| |
| uart:~$ bt connect <device A> |
| Connected: <device A> |
| uart:~$ cap_commander discover |
| discovery completed with CSIS |
| uart:~$ micp_mic_ctlr discover |
| MICP discover done with 1 AICS |
| uart:~$ |
| uart:~$ bt connect <device B> |
| Connected: <device B> |
| uart:~$ cap_commander discover |
| discovery completed with CSIS |
| uart:~$ micp_mic_ctlr discover |
| MICP discover done with 1 AICS |
| uart:~$ |
| uart:~$ cap_commander change_microphone_gain 10 |
| Setting microphone gain on 1 connections |
| AICS inst 0x200140a4 state gain 10, mute 0, mode 0 |
| Gain set for inst 0x200140a4 |
| Microphone gain change completed |
| uart:~$ |
| uart:~$ cap_commander change_microphone_gain 10 15 |
| Setting microphone gain on 2 connections |
| Gain set for inst 0x200140a4 |
| AICS inst 0x20014188 state gain 15, mute 0, mode 0 |
| Gain set for inst 0x20014188 |
| Microphone gain change completed |
