.. _bluetooth_le_audio_arch:

LE Audio Stack
##############

.. figure:: img/ble_audio_arch.svg
   :align: center
   :alt: Bluetooth Audio Architecture

   Bluetooth Audio Architecture

Overall design
**************

The overall design of the LE Audio stack is that the implementation follows the specifications
as closely as possible,
both in terms of structure but also naming.
Most API functions are prefixed by the specification acronym
(e.g. `bt_bap` for the Basic Audio Profile (BAP) and `bt_vcp` for the Volume Control Profile (VCP)).
The functions are then further prefixed with the specific role from each profile where applicable
(e.g. :c:func:`bt_bap_unicast_client_discover` and :c:func:`bt_vcp_vol_rend_set_vol`).
There are usually a function per procedure defined by the profile or service specifications,
and additional helper or meta functions that do not correspond to procedures.

The structure of the files generally also follow this,
where BAP related files are prefixed with `bap` and VCP related files are prefixed with `vcp`.
If the file is specific for a profile role, the role is also embedded in the file name.

Generic Audio Framework (GAF)
*****************************
The Generic Audio Framework (GAF) is considered the middleware of the Bluetooth
LE Audio architecture. The GAF contains the profiles and services that allows
higher layer applications and profiles to set up streams, change volume, control
media and telephony and more. The GAF builds on GATT, GAP and isochronous
channels (ISO).

GAF uses GAP to connect, advertise and synchronize to other devices.
GAF uses GATT to configure streams, associate streams with content
(e.g. media or telephony), control volume and more.
GAF uses ISO for the audio streams themselves, both as unicast (connected)
audio streams or broadcast (unconnected) audio streams.

GAF mandates the use of the LC3 codec, but also supports other codecs.

.. figure:: img/gaf.svg
   :align: center
   :alt: Generic Audio Framework

   Generic Audio Framework

The top-level profiles TMAP and HAP are not part of the GAF, but rather provide
top-level requirements for how to use the GAF.

GAF has been implemented in Zephyr with the following structure.

.. figure:: img/zephyr_gaf.svg
   :align: center
   :alt: Generic Audio Framework

   Zephyr Generic Audio Framework

Bluetooth Audio Stack Status
============================

The following table shows the current status and support of the profiles in the
Bluetooth Audio Stack.

.. table:: Bluetooth Audio Profile status
   :widths: auto

   +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   | Module | Role                          | Version | Added in Release | Status                | Remaining                                        |
   +========+===============================+=========+==================+=======================+==================================================+
   | VCP    | Volume Renderer               | 1.0     | 2.6              | - Feature complete    | - Sample Application                             |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Volume Controller             | 1.0     | 2.6              | - Feature complete    | - Sample Application                             |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   | MICP   | Microphone Device             | 1.0     | 2.7              | - Feature complete    | - Sample Application                             |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Microphone Controller         | 1.0     | 2.7              | - Feature complete    | - Sample Application                             |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   | CSIP   | Set Member                    | 1.0.1   | 3.0              | - Feature complete    | - Sample Application                             |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Set Coordinator               | 1.0.1   | 3.0              | - Feature complete    | - Sample Application                             |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   | CCP    | Call Control Server           | 1.0     | 3.0              | - Feature complete    | - API refactor                                   |
   |        |                               |         |                  | - Shell Module        | - Sample Application                             |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Call Control Client           | 1.0     | 3.0              | - Feature complete    | - API refactor                                   |
   |        |                               |         |                  | - Shell Module        | - Sample Application                             |
   |        |                               |         |                  | - BSIM test           |                                                  |
   +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   | MCP    | Media Control Server          | 1.0     | 3.0              | - Feature complete    | - API refactor                                   |
   |        |                               |         |                  | - Shell Module        | - Support for multiple instances and connections |
   |        |                               |         |                  | - BSIM test           | - Sample Application                             |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Media Control Client          | 1.0     | 3.0              | - Feature complete    | - API refactor                                   |
   |        |                               |         |                  | - Shell Module        | - Sample Application                             |
   |        |                               |         |                  | - BSIM test           |                                                  |
   +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   | BAP    | Unicast Server                | 1.0.1   | 3.0              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Unicast Client                | 1.0.1   | 3.0              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Broadcast Source              | 1.0.1   | 3.0              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Broadcast Sink                | 1.0.1   | 3.0              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Scan Delegator                | 1.0.1   | 3.3              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Broadcast Assistant           | 1.0.1   | 3.3              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   | CAP    | Acceptor                      | 1.0     | 3.2              | - Feature complete    | - Sample Application                             |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Initiator                     | 1.0     | 3.3              | - Feature complete    | - Sample Application                             |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Commander                     |         |                  | - WIP                 | - Feature complete                               |
   |        |                               |         |                  |                       | - Shell Module                                   |
   |        |                               |         |                  |                       | - BSIM test                                      |
   |        |                               |         |                  |                       | - Sample Application                             |
   +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   | HAP    | Hearing Aid                   | 1.0     | 3.1              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Hearing Aid Unicast Client    | 1.0     | 3.1              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Hearing Aid Remote Controller |         |                  | - WIP                 | - Feature complete                               |
   |        |                               |         |                  |                       | - Shell Module                                   |
   |        |                               |         |                  |                       | - BSIM test                                      |
   |        |                               |         |                  |                       | - Sample Application                             |
   +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   | TMAP   | Call Gateway                  | 1.0     | 3.4              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Call Terminal                 | 1.0     | 3.4              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Unicast Media Sender          | 1.0     | 3.4              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Unicast Media Receiver        | 1.0     | 3.4              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Broadcast Media Sender        | 1.0     | 3.4              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Broadcast Media Receiver      | 1.0     | 3.4              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   | PBP    | Public Broadcast Source       |         | 3.5              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Public Broadcast Sink         |         | 3.5              | - Feature complete    |                                                  |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  | - Sample Application  |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Public Broadcast Assistant    |         |                  |                       | - Feature complete                               |
   |        |                               |         |                  |                       | - Shell Module                                   |
   |        |                               |         |                  |                       | - BSIM test                                      |
   |        |                               |         |                  |                       | - Sample Application                             |
   +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   | GMAP   | Unicast Game Gateway          |         | 3.5              | - Feature complete    | - Sample Application                             |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  |                       |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Unicast Game Terminal         |         | 3.5              | - Feature complete    | - Sample Application                             |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  |                       |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Broadcast Game Sender         |         | 3.5              | - Feature complete    | - Sample Application                             |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  |                       |                                                  |
   |        +-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+
   |        | Broadcast Game Receiver       |         | 3.5              | - Feature complete    | - Sample Application                             |
   |        |                               |         |                  | - Shell Module        |                                                  |
   |        |                               |         |                  | - BSIM test           |                                                  |
   |        |                               |         |                  |                       |                                                  |
   +--------+-------------------------------+---------+------------------+-----------------------+--------------------------------------------------+

Using the Bluetooth Audio Stack
===============================

To use any of the profiles in the Bluetooth Audio Stack, including the top-level
profiles outside of GAF, :kconfig:option:`CONFIG_BT_AUDIO` shall be enabled.
This Kconfig option allows the enabling of the individual profiles inside of the
Bluetooth Audio Stack. Each profile can generally be enabled on its own, but
enabling higher-layer profiles (such as CAP, TMAP and HAP) will typically
require enabling some of the lower layer profiles.

It is, however, possible to create a device that uses e.g. only Stream Control
(with just the BAP), without using any of the content control or
rendering/capture control profiles, or vice versa. Using the higher layer
profiles will however typically provide a better user experience and better
interoperability with other devices.

Common Audio Profile (CAP)
--------------------------

The Common Audio Profile introduces restrictions and requirements on the lower layer profiles.
The procedures in CAP works on one or more streams for one or more devices. Is it thus possible via
CAP to do a single function call to setup multiple streams across multiple devices.

The figure below shows a complete structure of the procedures in CAP and
how they correspond to procedures from the other profiles. The circles with I, A and C show whether
the procedure has active involvement or requirements from the CAP Initiator, CAP Accept and CAP
Commander roles respectively.

.. figure:: img/cap_proc.svg
   :align: center
   :alt: Common Audio Profile Procedures

   Common Audio Profile Procedures

The API reference for CAP can be found in :ref:`Common Audio Profile <bluetooth_cap>`.

Stream Control (BAP)
--------------------

Stream control is implemented by the Basic Audio Profile. This profile
defines multiple roles:

* Unicast Client
* Unicast Server
* Broadcast Source
* Broadcast Sink
* Scan Delegator
* Broadcast Assistant

Each role can be enabled individually, and it is possible to support more than
one role.

Notes about the stream control services
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are 3 services primarily used by stream control using the Basic Audio Profile.

Audio Stream Control Service (ASCS)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ASCS is a service used exclusively for setting up unicast streams,
and is located on the BAP Unicast Server device.
The service exposes one or more endpoints that can either be a sink or source endpoint,
from the perspective of the Unicast Server.
That means a sink endpoint is always audio from the Unicast Client to the Unicast Server,
and a source endpoint is always from the Unicast Server to the Unicast Client.

Unlike most other GATT services,
ASCS require that each characteristic in the service has unique data per client.
This means that if a Unicast Server is connected to multiple Unicast Clients,
the Unicast Clients are not able to see or control the endpoints configured by the other clients.
For example if a person's smartphone is streaming audio to a headset,
then the same person will not be able to see or control that stream from their smartwatch.

Broadcast Audio Scan Service (BASS)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

BASS is a service that is exclusively used by the Scan Delegator and Broadcast Assistant.
The main purpose of the service is to offload scanning from low power peripherals to e.g. phones
and PCs.
Unlike ASCS where the data is required to be unique per client,
the data in BASS (called receive states) are (usually) shared among all connected clients.
That means it is possible for a person to tell their headphones to synchronize to a
Broadcast Source using their phone,
and then later tell their headphones to stop synchronizing using their smartwatch.

A Broadcast Assistant can be any device,
and may only support this one role without any audio capabilities.
This allows legacy devices that do not support periodic advertisements or isochronous channels to
still provide an interface and scan offloading for peripherals.
The Bluetooth SIG have provided a guide on how to develop such legacy Broadcast Assistants that can
be found at
https://www.bluetooth.com/bluetooth-resources/developing-auracast-receivers-with-an-assistant-application-for-legacy-smartphones/.
An important note about this guide is that many operating systems (especially on phones),
do not allow generic usage of the BASS UUID,
effectively making it impossible to implement your own Broadcast Assistant,
because you cannot access the BASS.

Published Audio Capabilities Service (PACS)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

PACS is used to expose a device's audio capabilities in Published Audio Capabilities (PAC) records.
PACS is used by nearly all roles,
where the Unicast Client and Broadcast Assistant will act as PACS clients,
and Unicast Server and Broadcast Sink will act as PACS servers.
These records contain information about the codec, and which values are supported by each codec.
The values for the LC3 codec are defined by the Bluetooth Assigned numbers
(https://www.bluetooth.com/specifications/assigned-numbers/), and the values for other codecs such
as SBC are left undefined/implementation specific for BAP.

PACS also usually share the same data between each connected client,
but by using functions such as :c:func:`bt_pacs_conn_set_available_contexts_for_conn`,
it is possible to set specific values for specific clients.

The API reference for stream control can be found in
:ref:`Bluetooth Audio <bluetooth_audio>`.


Rendering and Capture Control
-----------------------------

Rendering and capture control is implemented by the Volume Control Profile
(VCP) and Microphone Control Profile (MICP).

The VCP implementation supports the following roles

* Volume Control Service (VCS) Server
* Volume Control Service (VCS) Client

The MICP implementation supports the following roles

* Microphone Control Profile (MICP) Microphone Device (server)
* Microphone Control Profile (MICP) Microphone Controller (client)

The API reference for volume control can be found in
:ref:`Bluetooth Volume Control <bluetooth_volume>`.

The API reference for Microphone Control can be found in
:ref:`Bluetooth Microphone Control <bluetooth_microphone>`.


Content Control
---------------

Content control is implemented by the Call Control Profile (CCP) and
Media Control Profile (MCP).

The CCP implementation is not yet implemented in Zephyr.

The MCP implementation supports the following roles

* Media Control Service (MCS) Server via the Media Proxy module
* Media Control Client (MCC)

The API reference for media control can be found in
:ref:`Bluetooth Media Control <bluetooth_media>`.

Generic TBS and Generic MCS
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Both the Telephone Bearer Service (TBS) used by CCP and the Media Control Service (MCS) used by MCP
have the concept of generic instances of the services called Generic TBS (GTBS) and
Generic MCS (GMCS).

While these share a common name prefix, the behavior of these two may be significantly different.

Generic TBS
^^^^^^^^^^^

The TBS spec defines GTBS as

   GTBS provides a single point of access and exposes a representation of its internal telephone
   bearers into a single telephone bearer.
   This service provides telephone status and control of the device as a single unit with a
   single set of characteristics.
   It is left up to the implementation to determine what telephone bearer a characteristic of
   GTBS represents at any time.
   There is no specified manner of representing a characteristic from each individual TBS that
   resides on the device to the same characteristic of the GTBS.

   For example, if there is more than one TBS on a device and each has a unique telephone bearer
   name (e.g., Name1 and Name2),
   the way the GTBS represents the telephone bearer name is left up to the implementation.
   GTBS is suited for clients that do not need to access or control all the
   information available on specific telephone bearers.

This means that a GTBS instance represents one or more telephone bearers.
A telephone bearer could be any application on a device that can handle (telephone) calls,
such as the default Call application on a smartphone,
but also other applications such as Signal, Discord, Teams, Slack, etc.

GTBS may be standalone (i.e.the device only has a GTBS instance without any TBS instances),
and the behavior of the GTBS is mostly left up to the implementation.
In Zephyr the implementation of GBTS is that it contains some generic information,
such as the provider name which is defined to  simply be "Generic TBS",
but the majority of the information in the GTBS instance in Zephyr has been implemented to be a
union of the data of the other bearers.
For example if you have a bearer for regular phone calls and
Teams and have an active call in both bearers,
then each of those bearers will report a single call,
but the GTBS instance will report 2 calls,
making it possible for a simple Call Control Client to control all calls from a single bearer.
Similarly the supported URIs for each bearer are also made into a union in GTBS, and when placing
a call using the GTBS the server will pick the most suited bearer depending on the URI.
For example calls with URI `tel` would go to the regular phone application,
and calls with the URI `skype` would go to the Teams application.

In conclusion the GTBS implementation in Zephyr is a union of the non-generic telephone bearers.

Generic MCS
^^^^^^^^^^^

The MCS spec defines GMCS as

   The GMCS provides status and control of media playback for the device as a single unit.
   An MCS instance describes and controls the media playback for a
   specific media player within the device.
   A device implements MCS instances to allow clients to access the
   separate internal media player entities.

and where the behavior of GMCS is defined as

   ... the behavior of MCS and GMCS is identical,
   and all the characteristics and the characteristics' behaviors are the same.
   The term “MCS” is used throughout the document.
   Unless otherwise specifically stated in this specification,
   the same meaning applies to GMCS as well.

This means that a GMCS instance works the same way as an MCS instance,
and it follows that GMCS

   controls the media playback for a specific media player within the device

A media player on a device could be anything that plays media,
such as a Spotify or Youtube application on a smartphone.
Thus if a device has multiple MCS instances,
then each of these control media for that specific application,
but the GMCS also controls media playback for a specific media player.
GMCS can thus be considered a pointer to a specific MCS instance,
and control either e.g. Spotify or Youtube, but not both.

The MCS spec does however provide an example of GMCS where a device can

   Implement a GMCS that provides status and control of media playback for the device as a whole.

Which may indicate that an implementation may use GMCS to represent all media players with GMCS and
not a specific media player as stated above. In the case where a device does not have any MCS
instances and only GMCS, then GMCS will point to a generic instance.

The Zephyr implementation of MCS and GMCS is incomplete,
and currently only supports instantiating a single instance that can either be an MCS or GMCS.
This means that the implementation is neither complete nor spec-compliant.

Difference between GTBS and GMCS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The definitions and implementations of GTBS and GMCS as stated above are notably different.
GTBS works as a union between the other TBS instances (if any),
and GMCS works as a pointer to a specific MCS instance (if any).
This effectively means that a simple Call Control Client can control all calls just using GTBS,
but a Media Control Client may only be able to control a single player using GMCS.

Coordinated Sets
----------------

Coordinated Sets is implemented by the Coordinated Sets Identification Profile
(CSIP).

The CSIP implementation supports the following roles

* Coordinated Set Identification Service (CSIP) Set Member
* Coordinated Set Identification Service (CSIP) Set Coordinator

The API reference for media control can be found in
:ref:`Bluetooth Coordinated Sets <bluetooth_coordinated_sets>`.

Specification correctness and data location
-------------------------------------------

The implementations are designed to ensure specification compliance as much as possible.
When a specification introduces a requirement with e.g. a **shall** then the implementation should
attempt to ensure that this requirement is always followed.
Depending on the context of this,
the implementation ensures this by rejecting invalid parameters from the application,
or from the remote devices.

Some requirements from the specifications are not or can not be handled by the stack itself for
various reasons.
One reason when the stack cannot handle a requirement is if the data related to the requirement is
exclusively controlled by the application.
An example of this is the advertising data,
where multiple service have requirements for what to advertise and when,
but where both the advertising state and data is exclusively controlled by the application.

Oppositely there are also requirements from the specification,
where the data related to the requirement is exclusively controlled by the stack.
An example of this is the Volume Control Service (VCS) state,
where the specifications mandata that the VCP Volume Renderer (VCS server) modify the values
without a choice,
e.g. when setting the absolutely volume.
In cases like this the application is only notified about the change with a callback,
but cannot reject the request (the stack will reject any invalid requests).

Generally when the data is simple (like the VCS state which only take up a few bytes),
the data is kept in and controlled by the stack,
as this can ensure that the requirements can be handled by the stack,
making it easier to use a profile role correctly.
When the data is more complex (e.g. the PAC records),
the data may be kept by the application and the stack only contains a reference to it.
When the data is very application specific (e.g. advertising data),
the data is kept in and controlled by the application.

As a rule of thumb, the return types of the callbacks for each profile implementation indicate
whether the data is controlled by the stack or the application.
For example all the callbacks for the VCP Volume Renderer have the return type of `void`,
but the return type of the BAP Unicast Server callbacks are `int`,
indicating that the application not only controls a lot of the Unicast Server data,
but can also reject the requests.
The choice of what the return type of the callbacks often depend on the specifications,
and how much control the role has in a given context.

Things worth knowing or considering when using LE Audio
=======================================================

This section describes a few tings to consider when contributing to or using LE Audio in Zephyr.
The things described by this section are not unique to Zephyr as they are defined by the
specifications.

Security requirements
---------------------

All LE Audio services require Security Level 2 but where the key must be 128-bit and derived via an
OOB method or via LE Secure connections.
There is no Core-spec defined way of reporting this in GATT,
as ATT does not have a specific error code for missing OOB method or LE Secure Connections
(although there is a way to report wrong key size).

In Zephyr we do not force the device to always use these, as a device that uses LE Audio may also
use other profiles and services that do not require such security.
We guard all access to services using a custom security check implemented in
:zephyr_file:`subsys/bluetooth/audio/audio.c`, where all LE Audio services must use the
internal `BT_AUDIO_CHRC` macro for proper security verification.

Access to the LTK for encrypted SIRKs in CSIS
---------------------------------------------

The Coordinated Set Identification Service (CSIS) may encrypt the SIRK (set identity resolving key).
The process of encrypting the SIRK requires the LTK as the encryption key,
which is typically not exposed to higher layer implementations such as CSIS.
This does not have any effect on the security though.

MTU requirements
----------------

The Basic Audio Profile (BAP) has a requirement that both sides shall support a minimum ATT_MTU of
at least 64 on the unenhanced ATT bearer or at least one enhanced ATT bearer.
The requirement comes from the preferred (or sometimes mandatory) use of GATT Write Without
Response, and where support for Write Long Characterstic Value is optional in most cases.

If a ASCS device supports values larger than the minimum ATT_MTU of 64 octets, then it shall supoort
Read long Characterstic Value by setting :kconfig:option:`CONFIG_BT_ATT_PREPARE_COUNT` to a
non-zero value.

LE Audio resources
##################

This section contains some links and reference to resources that are useful for either contributors
to the LE Audio Stack in Zephyr, LE Audio application developers or both.

The LE audio channel on Discord
*******************************

Zephyr has a specific Discord channel for LE Audio development, which is open to all.
Find it here at https://discordapp.com/channels/720317445772017664/1207326649591271434 or simply
search for `ble-audio` from within Discord.
Since the `ble-audio` channel is open for all,
we cannot discuss any specifications that are in development in that channel.
For discussions that require a Bluetooth SIG membership we refer to the `bluetooth-sig`
Discord channel found at https://discordapp.com/channels/720317445772017664/869172014018097162.

Zephyr weekly meetings
**********************

Anyone who is a Bluetooth SIG member and a Zephyr member can join the weekly meetings where we
discuss and plan the development of LE Audio in Zephyr. You can find the time of the meetings by
joining the Bluetooth-sig group at https://lists.zephyrproject.org/g/Bluetooth-sig.

Github project
**************

LE Audio in Zephyr has its own Github project available at
https://github.com/orgs/zephyrproject-rtos/projects/26.
The project is mostly automated,
and the LE Audio contributors almost only rely on the automated workflows
to present the state of development.
Anyone is able to pick any of the open issues and work on it.
If you cannot assign the issue to youself,
please leave a comment in the issue itself or ping the Discord channel for help.

Bluetooth SIG errata for LE Audio
*********************************

There are many specifications for LE Audio,
and several of them are still being updated and developed.
To get an overview of the errata for the LE Audio specifications you can visit

* Generic Audio (GA) errata https://bluetooth.atlassian.net/wiki/spaces/GA/pages/1634402349/GAWG+Errata+Lists
* Hearing Aid (HA) errata https://bluetooth.atlassian.net/wiki/spaces/HA/pages/1634140216/HA+WG+Errata+List
* Audio, Telephony and Automotive (ATA) errata https://bluetooth.atlassian.net/wiki/spaces/ATA/pages/1668481034/ATA+Errata+Lists

Access to errata requires a Bluetooth SIG membership.

Bluetooth SIG working groups for LE Audio
*****************************************

There are 3 working groups in the Bluetooth SIG related to LE Audio:

* Generic Audio (GA) https://www.bluetooth.org/groups/group.aspx?gId=665
* Hearing Aid (HA) https://www.bluetooth.org/groups/group.aspx?gId=605
* Audio, Telephony, and Automotive (ATA) https://www.bluetooth.org/groups/group.aspx?gId=659

By joining these groups you will also get emails from their respective mailing lists,
where multiple questions and discussions are handled.
The working groups also have scheduled weekly meetings,
where issues and the development of the specifications are handled.

Access to the Bluetooth SIG working groups requires a Bluetooth SIG membership.

The LE Audio Book
*****************

There is a free ebook on LE Audio at https://www.bluetooth.com/bluetooth-resources/le-audio-book/.
The book was released in January 2022,
and thus before some of the specifications were finalized,
but also before some of the released updates to the specifications.
Nevertheless the book still provides a good explanation for many of the concepts and ideas,
but please refer to the individual specifications for technical information.

Bluetooth SIG informational papers, reports and guides
******************************************************

The Bluetooth SIG occasionally release new informational papers, report and guides.
These can be found at https://www.bluetooth.com/bluetooth-resources/?tags=le-audio&keyword.
Here you will also find the aforementioned LE Audio book, among many other good resources.