.. _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

   audio --help
   Subcommands:
      init                 :
      discover             :[type: sink, source]
      preset               :[preset]
      config               :<direction: sink, source> <index> [codec] [preset]
      select_broadcast     :<stream>
      create_broadcast     :[codec] [preset]
      start_broadcast      :
      stop_broadcast       :
      delete_broadcast     :
      broadcast_scan       :<on, off>
      accept_broadcast     :0x<broadcast_id>
      sync_broadcast       :0x<bis_bitfield>
      stop_broadcast_sink  :Stops broadcast sink
      term_broadcast_sink  :
      qos                  :[preset] [interval] [framing] [latency] [pd] [sdu] [phy] [rtn]
      enable               :
      metadata             :[context]
      start                :
      disable              :
      stop                 :
      release              :
      list                 :
      select_unicast       :<stream>
      connect              :<direction: sink, source> <index>  [codec] [preset]
      send                 :Send to Audio Stream [data]

.. 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:~$ audio init
   uart:~$ bt connect <address>
   uart:~$ gatt exchange-mtu
   uart:~$ audio discover sink
   uart:~$ audio config sink 0
   uart:~$ audio qos
   uart:~$ audio enable

Or using connect command:

.. code-block:: console

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

Disconnect and release:

.. code-block:: console

   uart:~$ audio disable
   uart:~$ audio release

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

Listen:

.. code-block:: console

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

Server initiated disable and release:

.. code-block:: console

   uart:~$ audio disable
   uart:~$ audio release

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

Create and establish a broadcast source stream:

.. code-block:: console

   uart:~$ audio init
   uart:~$ audio create_broadcast
   uart:~$ audio start_broadcast

Stop and release a broadcast source stream:

.. code-block:: console

   uart:~$ audio stop_broadcast
   uart:~$ audio delete_broadcast


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

Scan for and establish a broadcast sink stream:

.. code-block:: console

   uart:~$ audio init
   uart:~$ audio broadcast_scan on
   Found broadcaster with ID 0xB91CD4
   uart:~$ audio accept_broadcast 0xB91CD4
   PA syncing to broadcaster
   Broadcast scan was terminated: 0
   PA synced to broadcaster with ID 0xB91CD4 as sink 0x2000d09c
   Sink 0x2000d09c is set as default
   Sink 0x2000d09c is ready to sync without encryption
   Received BASE from sink 0x2000d09c:
   Subgroup[0]:
   codec 0x06 cid 0x0000 vid 0x0000 count 4
   data #0: type 0x01 len 1
   data #1: type 0x02 len 1
   data #2: type 0x03 len 4
   00000000: 00 00 00                                         |...              |
   data #3: type 0x04 len 2
   00000000: 28                                               |(                |
   meta #0: type 0x02 len 2
   BIS[0] index 0x01
   [0]: 0x01
   Possible indexes: 0x01
   audio sync_broadcast 0x01

Stop and release a broadcast sink stream:

.. code-block:: console

   uart:~$ audio stop_broadcast_sink
   uart:~$ audio 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:~$ audio 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:~$ audio discover [type: sink, source]
   uart:~$ audio discover sink
   cap 0x8175940 type 0x01
   codec 0x06 cid 0x0000 vid 0x0000 count 4
   data #0: type 0x01 len 1
   00000000: 3f                                             |?                |
   data #1: type 0x02 len 1
   00000000: 03                                             |.                |
   data #2: type 0x03 len 1
   00000000: 03                                             |.                |
   data #3: type 0x04 len 4
   00000000: 1e 00 f0 00                                    |....             |
   meta #0: type 0x01 len 2
   00000000: 06 00                                          |..               |
   meta #1: type 0x02 len 2
   00000000: ff 03                                          |..               |
   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:~$ audio preset [preset]
   uart:~$ audio preset
   16_2_1
   codec 0x06 cid 0x0000 vid 0x0000 count 3
   data #0: type 0x01 len 1
   00000000: 02                                             |.                |
   data #1: type 0x02 len 1
   00000000: 01                                             |.                |
   data #2: type 0x04 len 2
   00000000: 28 00                                          |(.               |
   meta #0: type 0x02 len 2
   00000000: 02 00                                          |..               |
   QoS: dir 0x02 interval 10000 framing 0x00 phy 0x02 sdu 40 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:~$ audio config <direction: sink, source> <index> [codec] [preset]
   uart:~$ audio config sink 0
   ASE Codec Config: conn 0x8173800 ep 0x81754e0 cap 0x816a360
   codec 0x06 cid 0x0000 vid 0x0000 count 3
   data #0: type 0x01 len 1
   00000000: 02                                             |.                |
   data #1: type 0x02 len 1
   00000000: 01                                             |.                |
   data #2: type 0x04 len 2
   00000000: 28 00                                          |(.               |
   meta #0: type 0x02 len 2
   00000000: 02 00                                          |..               |
   ASE Codec Config stream 0x8179e60
   Default ase: 1
   ASE config: preset 16_2_1

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:~$ audio qos [preset] [interval] [framing] [latency] [pd] [sdu] [phy] [rtn]
   uart:~$ audio qos
   ASE config: preset 16_2_1

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:~$ audio enable

Start [sink only]
*****************

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:~$ audio 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:~$ audio disable

Stop [sink only]
****************

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:~$ audio 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:~$ audio 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:~$ audio 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:~$ audio select <ase>
   uart:~$ audio select 0x01
   Default stream: 1

To select a broadcast stream:

.. code-block:: console

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

Connect
*******

The :code:`connect` command combines config, qos and enable commands in one so
it can be used to quickly configure and enable a stream.

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

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

.. code-block:: console

   uart:~$ audio connect <direction: sink, source> <index> [codec] [preset]
   uart:~$ audio connect sink 0
   ASE Codec Config: conn 0x17ca40 ep 0x17f860 cap 0x19f6a0
   codec 0x06 cid 0x0000 vid 0x0000 count 3
   data #0: type 0x01 len 1
   00000000: 02                                               |.                |
   data #1: type 0x02 len 1
   00000000: 01                                               |.                |
   data #2: type 0x04 len 2
   00000000: 28 00                                            |(.               |
   meta #0: type 0x02 len 2
   00000000: 02 00                                            |..               |
   ASE Codec Config stream 0x1851c0
   Default ase: 1
   ASE config: preset 16_2_1
   ASE Codec Reconfig: stream 0x1851c0 cap 0x19f6a0
   codec 0x06 cid 0x0000 vid 0x0000 count 3
   data #0: type 0x01 len 1
   00000000: 02                                               |.                |
   data #1: type 0x02 len 1
   00000000: 01                                               |.                |
   data #2: type 0x04 len 2
   00000000: 28 00                                            |(.               |
   meta #0: type 0x02 len 2
   00000000: 02 00                                            |..               |
   QoS: stream 0x1851c0
   QoS: dir 0x02 interval 10000 framing 0x00 phy 0x02 sdu 40 rtn 2 latency 10 pd 40000
   Start: stream 0x1851c0

Send
****

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

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

   "enable","streaming","none"

.. code-block:: console

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