.. _bluetooth_shell_audio:

Bluetooth: Basic Audio Profile
##############################

This document describes how to run Basic Audio Profile functionality which
includes:

  - Capabilities and Endpoint discovery
  - Audio Stream Endpoint procedures

Commands
********

.. code-block:: console

   bap --help
   Subcommands:
      init
      select_broadcast       : <stream>
      create_broadcast       : [preset <preset_name>] [enc <broadcast_code>]
      start_broadcast        :
      stop_broadcast         :
      delete_broadcast       :
      create_broadcast_sink  : 0x<broadcast_id>
      sync_broadcast         : 0x<bis_index> [[[0x<bis_index>] 0x<bis_index>] ...]
                              [bcode <broadcast code> || bcode_str <broadcast code
                              as string>]
      stop_broadcast_sink    : Stops broadcast sink
      term_broadcast_sink    :
      discover               : [dir: sink, source]
      config                 : <direction: sink, source> <index> [loc <loc_bits>]
                              [preset <preset_name>]
      stream_qos             : interval [framing] [latency] [pd] [sdu] [phy] [rtn]
      qos                    : Send QoS configure for Unicast Group
      enable                 : [context]
      stop
      list
      print_ase_info         : Print ASE info for default connection
      metadata               : [context]
      start
      disable
      release
      select_unicast         : <stream>
      preset                 : <sink, source, broadcast> [preset]
                              [config
                                    [freq <frequency>]
                                    [dur <duration>]
                                    [chan_alloc <location>]
                                    [frame_len <frame length>]
                                    [frame_blks <frame blocks>]]
                              [meta
                                    [pref_ctx <context>]
                                    [stream_ctx <context>]
                                    [program_info <program info>]
                                    [stream_lang <ISO 639-3 lang>]
                                    [ccid_list <ccids>]
                                    [parental_rating <rating>]
                                    [program_info_uri <URI>]
                                    [audio_active_state <state>]
                                    [bcast_flag]
                                    [extended <meta>]
                                    [vendor <meta>]]
      send                   : Send to Audio Stream [data]
      start_sine             : Start sending a LC3 encoded sine wave [all]
      stop_sine              : Stop sending a LC3 encoded sine wave [all]
      recv_stats             : Sets or gets the receive statistics reporting interval
                              in # of packets
      set_location           : <direction: sink, source> <location bitmask>
      set_context            : <direction: sink, source><context bitmask> <type:
                              supported, available>


.. csv-table:: State Machine Transitions
   :header: "Command", "Depends", "Allowed States", "Next States"
   :widths: auto

   "init","none","any","none"
   "discover","init","any","any"
   "config","discover","idle/codec-configured/qos-configured","codec-configured"
   "qos","config","codec-configured/qos-configured","qos-configured"
   "enable","qos","qos-configured","enabling"
   "[start]","enable","enabling","streaming"
   "disable","enable", "enabling/streaming","disabling"
   "[stop]","disable","disabling","qos-configure/idle"
   "release","config","any","releasing/codec-configure/idle"
   "list","none","any","none"
   "select_unicast","none","any","none"
   "connect","discover","idle/codec-configured/qos-configured","codec-configured"
   "send","enable","streaming","none"

Example Central
***************

Connect and establish a stream:

.. code-block:: console

   uart:~$ bt init
   uart:~$ bap init
   uart:~$ bt connect <address>
   uart:~$ gatt exchange-mtu
   uart:~$ bap discover sink
   uart:~$ bap config sink 0
   uart:~$ bap qos
   uart:~$ bap enable

Or using connect command:

.. code-block:: console

   uart:~$ bt init
   uart:~$ bap init
   uart:~$ bt connect <address>
   uart:~$ gatt exchange-mtu
   uart:~$ bap discover sink
   uart:~$ bap connect sink 0

Disconnect and release:

.. code-block:: console

   uart:~$ bap disable
   uart:~$ bap release

Example Peripheral
******************

Listen:

.. code-block:: console

   uart:~$ bt init
   uart:~$ bap init
   uart:~$ bt advertise on

Server initiated disable and release:

.. code-block:: console

   uart:~$ bap disable
   uart:~$ bap release

Example Broadcast Source
************************

Create and establish a broadcast source stream:

.. code-block:: console

   uart:~$ bap init
   uart:~$ bap create_broadcast
   uart:~$ bap start_broadcast

Stop and release a broadcast source stream:

.. code-block:: console

   uart:~$ bap stop_broadcast
   uart:~$ bap delete_broadcast


Example Broadcast Sink
**********************

Scan for and establish a broadcast sink stream.
The command :code:`bap create_broadcast_sink` will either use existing periodic advertising
sync (if exist) or start scanning and sync to the periodic advertising with the provided broadcast
ID before syncing to the BIG.

.. code-block:: console

   uart:~$ bap init
   uart:~$ bap create_broadcast_sink 0xEF6716
   No PA sync available, starting scanning for broadcast_id
   Found broadcaster with ID 0xEF6716 and addr 03:47:95:75:C0:08 (random) and sid 0x00
   Attempting to PA sync to the broadcaster
   PA synced to broadcast with broadcast ID 0xEF6716
   Attempting to sync to the BIG
   Received BASE from sink 0x20019080:
   Presentation delay: 40000
   Subgroup count: 1
   Subgroup 0x20024182:
      Codec Format: 0x06
      Company ID  : 0x0000
      Vendor ID   : 0x0000
      codec cfg id 0x06 cid 0x0000 vid 0x0000 count 16
         Codec specific configuration:
         Sampling frequency: 16000 Hz (3)
         Frame duration: 10000 us (1)
         Channel allocation:
                  Front left (0x00000001)
                  Front right (0x00000002)
         Octets per codec frame: 40
         Codec specific metadata:
         Streaming audio contexts:
            Unspecified (0x0001)
         BIS index: 0x01
            codec cfg id 0x06 cid 0x0000 vid 0x0000 count 6
            Codec specific configuration:
               Channel allocation:
                  Front left (0x00000001)
            Codec specific metadata:
               None
         BIS index: 0x02
            codec cfg id 0x06 cid 0x0000 vid 0x0000 count 6
            Codec specific configuration:
               Channel allocation:
                  Front right (0x00000002)
            Codec specific metadata:
               None
   Possible indexes: 0x01 0x02
   Sink 0x20019110 is ready to sync without encryption
   uart:~$ bap sync_broadcast 0x01

Syncing to encrypted broadcast
------------------------------

If the broadcast is encrypted, the broadcast code can be entered with the :code:`bap sync_broadcast`
command as such:

.. code-block:: console

   Sink 0x20019110 is ready to sync with encryption
   uart:~$ bap sync_broadcast 0x01 bcode 0102030405060708090a0b0c0d0e0f

The broadcast code can be 1-16 values, either as a string or a hexadecimal value.

.. code-block:: console

   Sink 0x20019110 is ready to sync with encryption
   uart:~$ bap sync_broadcast 0x01 bcode_str thisismycode

Stop and release a broadcast sink stream:

.. code-block:: console

   uart:~$ bap stop_broadcast_sink
   uart:~$ bap term_broadcast_sink

Init
****

The :code:`init` command register local PAC records which are necessary to be
able to configure stream and properly manage capabilities in use.

.. csv-table:: State Machine Transitions
   :header: "Depends", "Allowed States", "Next States"
   :widths: auto

   "none","any","none"

.. code-block:: console

   uart:~$ bap init

Discover PAC(s) and ASE(s)
**************************

Once connected the :code:`discover` command discover PAC records and ASE
characteristics representing remote endpoints.

.. csv-table:: State Machine Transitions
   :header: "Depends", "Allowed States", "Next States"
   :widths: auto

   "init","any","any"

.. note::

   Use command :code:`gatt exchange-mtu` to make sure the MTU is configured
   properly.

.. code-block:: console

   uart:~$ gatt exchange-mtu
   Exchange pending
   Exchange successful
   uart:~$ bap discover [type: sink, source]
   uart:~$ bap discover sink
   conn 0x2000b168: codec_cap 0x2001f8ec dir 0x02
   codec cap id 0x06 cid 0x0000 vid 0x0000
      Codec specific capabilities:
         Supported sampling frequencies:
            8000 Hz (0x0001)
            11025 Hz (0x0002)
            16000 Hz (0x0004)
            22050 Hz (0x0008)
            24000 Hz (0x0010)
            32000 Hz (0x0020)
            44100 Hz (0x0040)
            48000 Hz (0x0080)
            88200 Hz (0x0100)
            96000 Hz (0x0200)
            176400 Hz (0x0400)
            192000 Hz (0x0800)
            384000 Hz (0x1000)
         Supported frame durations:
            10 ms (0x02)
         Supported channel counts:
            1 channel (0x01)
         Supported octets per codec frame counts:
            Min: 40
            Max: 120
         Supported max codec frames per SDU: 1
      Codec capabilities metadata:
         Preferred audio contexts:
            Converstation (0x0002)
            Media (0x0004)
   ep 0x81754e0
   ep 0x81755d4
   Discover complete: err 0

Select preset
*************

The :code:`preset` command can be used to either print the default preset
configuration or set a different one, it is worth noting that it doesn't change
any stream previously configured.

.. code-block:: console

   uart:~$ bap preset
   preset - <sink, source, broadcast> [preset]
            [config
                  [freq <frequency>]
                  [dur <duration>]
                  [chan_alloc <location>]
                  [frame_len <frame length>]
                  [frame_blks <frame blocks>]]
            [meta
                  [pref_ctx <context>]
                  [stream_ctx <context>]
                  [program_info <program info>]
                  [stream_lang <ISO 639-3 lang>]
                  [ccid_list <ccids>]
                  [parental_rating <rating>]
                  [program_info_uri <URI>]
                  [audio_active_state <state>]
                  [bcast_flag]
                  [extended <meta>]
                  [vendor <meta>]]
   uart:~$ bap preset sink
   16_2_1
   codec cfg id 0x06 cid 0x0000 vid 0x0000 count 16
      Codec specific configuration:
         Sampling frequency: 16000 Hz (3)
         Frame duration: 10000 us (1)
         Channel allocation:
                     Front left (0x00000001)
                     Front right (0x00000002)
         Octets per codec frame: 40
      Codec specific metadata:
         Streaming audio contexts:
            Game (0x0008)
   QoS: interval 10000 framing 0x00 phy 0x02 sdu 40 rtn 2 latency 10 pd 40000

   uart:~$ bap preset sink 32_2_1
   32_2_1
   codec cfg id 0x06 cid 0x0000 vid 0x0000 count 16
      Codec specific configuration:
         Sampling frequency: 32000 Hz (6)
         Frame duration: 10000 us (1)
         Channel allocation:
                     Front left (0x00000001)
                     Front right (0x00000002)
         Octets per codec frame: 80
      Codec specific metadata:
         Streaming audio contexts:
            Game (0x0008)
      QoS: interval 10000 framing 0x00 phy 0x02 sdu 80 rtn 2 latency 10 pd 40000


Configure preset
****************

The :code:`bap preset` command can also be used to configure the preset used for the subsequent
commands. It is possible to add or set (or reset) any value. To reset the preset, the command can \
simply be run without the :code:`config` or :code:`meta` parameter. The parameters are using the
assigned numbers values.

.. code-block:: console

   uart:~$ bap preset sink 32_2_1
   32_2_1
   codec cfg id 0x06 cid 0x0000 vid 0x0000 count 16
   data #0: type 0x01 value_len 1
   00000000: 06                                               |.                |
   data #1: type 0x02 value_len 1
   00000000: 01                                               |.                |
   data #2: type 0x03 value_len 4
   00000000: 03 00 00 00                                      |....             |
   data #3: type 0x04 value_len 2
   00000000: 50 00                                            |P.               |
   meta #0: type 0x02 value_len 2
   00000000: 08 00                                            |..               |
   QoS: interval 10000 framing 0x00 phy 0x02 sdu 80 rtn 2 latency 10 pd 40000

   uart:~$ bap preset sink 32_2_1 config freq 10
   32_2_1
   codec cfg id 0x06 cid 0x0000 vid 0x0000 count 16
   data #0: type 0x01 value_len 1
   00000000: 0a                                               |.                |
   data #1: type 0x02 value_len 1
   00000000: 01                                               |.                |
   data #2: type 0x03 value_len 4
   00000000: 03 00 00 00                                      |....             |
   data #3: type 0x04 value_len 2
   00000000: 50 00                                            |P.               |
   meta #0: type 0x02 value_len 2
   00000000: 08 00                                            |..               |
   QoS: interval 10000 framing 0x00 phy 0x02 sdu 80 rtn 2 latency 10 pd 40000

   uart:~$ bap preset sink 32_2_1 config freq 10 meta stream_lang "eng" stream_ctx 4
   32_2_1
   codec cfg id 0x06 cid 0x0000 vid 0x0000 count 16
   data #0: type 0x01 value_len 1
   00000000: 0a                                               |.                |
   data #1: type 0x02 value_len 1
   00000000: 01                                               |.                |
   data #2: type 0x03 value_len 4
   00000000: 03 00 00 00                                      |....             |
   data #3: type 0x04 value_len 2
   00000000: 50 00                                            |P.               |
   meta #0: type 0x02 value_len 2
   00000000: 04 00                                            |..               |
   meta #1: type 0x04 value_len 3
   00000000: 65 6e 67                                         |eng              |
   QoS: interval 10000 framing 0x00 phy 0x02 sdu 80 rtn 2 latency 10 pd 40000

Configure Codec
***************

The :code:`config` command attempts to configure a stream for the given
direction using a preset codec configuration which can either be passed directly
or in case it is omitted the default preset is used.

.. csv-table:: State Machine Transitions
   :header: "Depends", "Allowed States", "Next States"
   :widths: auto

   "discover","idle/codec-configured/qos-configured","codec-configured"

.. code-block:: console

   uart:~$ bap config <direction: sink, source> <index> [loc <loc_bits>] [preset <preset_name>]
   uart:~$ bap config sink 0
   Setting location to 0x00000000
   ASE config: preset 16_2_1
   stream 0x2000df70 config operation rsp_code 0 reason 0

Configure Stream QoS
********************

The :code:`stream_qos` Sets a new stream QoS.

.. code-block:: console

   uart:~$ bap stream_qos <interval> [framing] [latency] [pd] [sdu] [phy] [rtn]
   uart:~$ bap stream_qos 10

Configure QoS
*************

The :code:`qos` command attempts to configure the stream QoS using the preset
configuration, each individual QoS parameter can be set with use optional
parameters.

.. csv-table:: State Machine Transitions
   :header: "Depends", "Allowed States", "Next States"
   :widths: auto

   "config","qos-configured/codec-configured","qos-configured"

.. code-block:: console

   uart:~$ bap qos

Enable
******

The :code:`enable` command attempts to enable the stream previously configured,
if the remote peer accepts then the ISO connection procedure is also initiated.

.. csv-table:: State Machine Transitions
   :header: "Depends", "Allowed States", "Next States"
   :widths: auto

   "qos","qos-configured","enabling"

.. code-block:: console

   uart:~$ bap enable [context]
   uart:~$ bap enable Media

Start
*****

The :code:`start` command is only necessary when acting as a sink as it
indicates to the source the stack is ready to start receiving data.

.. csv-table:: State Machine Transitions
   :header: "Depends", "Allowed States", "Next States"
   :widths: auto

   "enable","enabling","streaming"

.. code-block:: console

   uart:~$ bap start

Disable
*******

The :code:`disable` command attempts to disable the stream previously enabled,
if the remote peer accepts then the ISO disconnection procedure is also
initiated.

.. csv-table:: State Machine Transitions
   :header: "Depends", "Allowed States", "Next States"
   :widths: auto

   "enable","enabling/streaming","disabling"

.. code-block:: console

   uart:~$ bap disable

Stop
****

The :code:`stop` command is only necessary when acting as a sink as it indicates
to the source the stack is ready to stop receiving data.

.. csv-table:: State Machine Transitions
   :header: "Depends", "Allowed States", "Next States"
   :widths: auto

   "disable","disabling","qos-configure/idle"

.. code-block:: console

   uart:~$ bap stop

Release
*******

The :code:`release` command releases the current stream and its configuration.

.. csv-table:: State Machine Transitions
   :header: "Depends", "Allowed States", "Next States"
   :widths: auto

   "config","any","releasing/codec-configure/idle"

.. code-block:: console

   uart:~$ bap release

List
****

The :code:`list` command list the available streams.

.. csv-table:: State Machine Transitions
   :header: "Depends", "Allowed States", "Next States"
   :widths: auto

   "none","any","none"

.. code-block:: console

   uart:~$ bap list
   *0: ase 0x01 dir 0x01 state 0x01

Select Unicast
**************

The :code:`select_unicast` command set a unicast stream as default.

.. csv-table:: State Machine Transitions
   :header: "Depends", "Allowed States", "Next States"
   :widths: auto

   "none","any","none"

.. code-block:: console

   uart:~$ bap select <ase>
   uart:~$ bap select 0x01
   Default stream: 1

To select a broadcast stream:

.. code-block:: console

   uart:~$ bap select 0x01 broadcast
   Default stream: 1 (broadcast)

Send
****

The :code:`send` command sends data over BAP Stream.

.. csv-table:: State Machine Transitions
   :header: "Depends", "Allowed States", "Next States"
   :widths: auto

   "enable","streaming","none"

.. code-block:: console

   uart:~$ bap send [count]
   uart:~$ bap send
   Audio sending...