LE Audio Stack

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. bt_bap_unicast_client_discover() and 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.

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.

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.

Bluetooth Audio Profile status

Module

Role

Version

Added in Release

Status

Remaining

VCP

Volume Renderer

1.0

2.6

  • Feature complete

  • Shell Module

  • BSIM test

  • Sample Application

Volume Controller

1.0

2.6

  • Feature complete

  • Shell Module

  • BSIM test

  • Sample Application

MICP

Microphone Device

1.0

2.7

  • Feature complete

  • Shell Module

  • BSIM test

  • Sample Application

Microphone Controller

1.0

2.7

  • Feature complete

  • Shell Module

  • BSIM test

  • Sample Application

CSIP

Set Member

1.0.1

3.0

  • Feature complete

  • Shell Module

  • BSIM test

  • Sample Application

Set Coordinator

1.0.1

3.0

  • Feature complete

  • Shell Module

  • BSIM test

  • Sample Application

CCP

Call Control Server

1.0

3.0

  • Feature complete

  • Shell Module

  • BSIM test

  • API refactor

  • Sample Application

Call Control Client

1.0

3.0

  • Feature complete

  • Shell Module

  • BSIM test

  • API refactor

  • Sample Application

MCP

Media Control Server

1.0

3.0

  • Feature complete

  • Shell Module

  • BSIM test

  • API refactor

  • Support for multiple instances and connections

  • Sample Application

Media Control Client

1.0

3.0

  • Feature complete

  • Shell Module

  • BSIM test

  • API refactor

  • Sample Application

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

  • Shell Module

  • BSIM test

  • Sample Application

Initiator

1.0

3.3

  • Feature complete

  • Shell Module

  • BSIM test

  • Sample Application

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

  • Shell Module

  • BSIM test

  • Sample Application

Unicast Game Terminal

3.5

  • Feature complete

  • Shell Module

  • BSIM test

  • Sample Application

Broadcast Game Sender

3.5

  • Feature complete

  • Shell Module

  • BSIM test

  • Sample Application

Broadcast Game Receiver

3.5

  • Feature complete

  • Shell Module

  • BSIM test

  • Sample Application

Using the Bluetooth Audio Stack

To use any of the profiles in the Bluetooth Audio Stack, including the top-level profiles outside of GAF, 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.

Common Audio Profile Procedures

Common Audio Profile Procedures

The API reference for CAP can be found in Common Audio Profile.

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 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 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 Bluetooth Volume Control.

The API reference for Microphone Control can be found in Bluetooth Microphone Control.

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 Bluetooth Media Control.

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

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:

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.