Bluetooth® Low Energy audio - STM32WBA Architecture and Integration

1. STM32WBA BLE Audio firmware architecture

The Bluetooth® Low Energy Audio firmware, as represented by the Bluetooth® Special Interest Group (Bluetooth® SIG), is composed to two layers:

• Profiles grouped in a block called Generic Audio Framework (BAP, MCP, CCP...). This layer is responsible to offer to the audio use case profiles all the features required to implement an audio application based on the Bluetooth® Low Energy.
• Profiles dedicated to the specific Audio use case (PBP: published broadcast profile, HAP: hearing aids profile...). This part is closed to the final audio application and interact with the Generic Audio Framework.

The single Core Arm® Cortex®-M33 STM32WBA Bluetooth® Low Energy solution is designed to develop audio application firmware based on audio use case profiles on top of the generic audio framework.

The Generic Audio Framework is on top of the Bluetooth® Low Energy firmware stack (Controller & host) and offers audio stream management service access and remote control service access.

1.1. Bluetooth® Low Energy Audio Firmware package overview

STMicroelectronics provides, in the STM32CubeWBA MCU package, a software solution to develop audio application.

The Figure 1.1 represents the firmware architecture of the Bluetooth® Low Energy Audio provided in the STM32CubeWBA MCU package.

Figure 1.1 Bluetooth® Low Energy Audio firmware architecture

The audio use case profile implementation is available insource code format in each audio project assigned to an audio application based on a specific audio use case as defined by the Bluetooth® SIG.

The generic audio framework is included in an entity named "BLE Audio Stack" which includes:

• The entire generic audio framework
• Audio utils (Audio timer service, RAM allocation utils)
• Audio management is in charge of handling internal tasks and Bluetooth® Low Energy events received from the LE host stack.

The Bluetooth® Low Energy audio stack is delivered in library format:

• The library is available in the \Middlewares\ST\STM32_WPAN\ble\audio\lib directory.
• The header files declaring the types and the APIs are available in the \Middlewares\ST\STM32_WPAN\ble\audio\Inc directory

Figure 1.2 STM32WBA Bluetooth® package overview

1.2. Bluetooth® Low Energy Audio Framework interfaces

The Header files associated to the Bluetooth® Low Energy Audio Stack are described in the Table 1.1. The files are located in the \Middlewares\ST\STM32_WPAN\ble\audio\Inc directory.

File Name	Description
audio_types.h	this file defines types for Bluetooth® Low Energy Audio as specified by the Bluetooth SIG
ble_audio_stack.h	this file defines Bluetooth® Low Energy Audio Stack interfaces initialization, task processing.
ble_audio_plat.h	this file defines types and declares the APIs required for audio stack integration on the platform: AES, RNG, nonvolatile memory, timer, traces
cap_types.h	This file defines: Many MACROs to calculate the number of GATT services, the RAM size allocation required to support a common audio profile configuration Common audio profile types
cap.h	This file declares functions to manage procedures defined by the common audio profile.
bap_bufsize.h	This file defines MACROs to calculate the number of GATT services, GATT attributes, and ATT array size allocation required to support a basic audio profile configuration.
bap_types.h	This file defines specific basic audio profile types.
ltv_utils.h	This file declares functions to parse information included in the LTV structure.
ccp_types.h	This file defines: Many MACROs to calculate the number of GATT services, the RAM size allocation required to support a call control profile configuration Call control profile types.
ccp.h	This file declares functions to manage call control operations.
mcp_types.h	This file defines: Many MACROs to calculate the number of GATT services, the RAM size allocation required to support a media control profile configuration Media control profile types.
mcp.h	This file declares functions to manage media control operations.
csip_types.h	This file defines: Many MACROs to calculate the number of GATT services, the RAM size allocation required to support a coordinated set identification profile configuration Coordinated set identification profile types.
csip.h	This file declares the function to register service instance for CSIP set member role.
micp_types.h	This file defines: Many MACROs to calculate the number of GATT services, the RAM size allocation required to support a microphone control profile configuration Microphone control profile types.
micp.h	This file declares the function to manage microphone control operations not handled in CAP procedures.
vcp_types.h	This file defines: Many MACROs to calculate the number of GATT services, the RAM size allocation required to support a volume control profile configuration Volume control profile types.
vcp.h	This file declares the function to manage volume control operations not handle in CAP procedures.

Table 1.1 Header Files of the Generic Audio Framework'

The Figure 1.3 represents the Header files of the Generic Audio Framework.

Figure 1.3 STM32WBA Bluetooth® Header files of the Generic Audio Framework

2. Bluetooth® Low Energy Audio stack integration

The base of the Bluetooth® Low Energy audio stack is the Bluetooth® Low Energy host and the Link Layer.

In addition, the Bluetooth® Low Energy Audio stack requires external software modules:

• Service controller module
• Linked List manager module
• Debug/Traces module
• Timer server module
• Bare metal sequencer / Operation system module
• Nonvolatile memory manager module
• Advanced encryption standard (AES) module
• Random number generator module

The Figure 2.1 shows the external software modules dependencies of the Bluetooth® Low Energy audio stack

Figure 2.1 STM32WBA Bluetooth® Bluetooth® Low Energy audio stack integration dependencies

2.1. Host stack

The basic audio profile of the Generic Audio Framework, included in the Bluetooth® Low Energy audio stack, is in charge to manage features based on:

• Extended advertising features
• ISO features
• Periodic advertising features
• Periodic advertising sync transfer features

These feature accesses are provided by the Bluetooth® Low Energy host stack.

Moreover, all the profiles, and their associated services, in the Generic Audio Framework arebased on the ATT service model. Consequently, each profile requires an access to GATT operations. These GATT operation accesses are provided by the Bluetooth® Low Energy host stack.

2.2. Service controller

The service controller, located in the Middlewares\ST\STM32_WPAN\ble\svc folder, is a software block used by the Bluetooth® Low Energy audio stack to register handlers through which asynchronous HCI, GAP, and GATT events would be notified from the Bluetooth® Low Energy host to the profiles of the Generic Audio Framework.

In the Bluetooth® Low Energy audio stack, a centric audio manager block is responsible to submit the events to the profiles of the Generic Audio Framework. For this reason, the Bluetooth® Low Energy Audio stack integration requires for the service controller configuration:

• BLE_CFG_SVC_MAX_NBR_CB is incremented by 1
  
• BLE_CFG_MAX_NBR_CB is incremented by 1
  

The Figure 2.2 shows the interface between the Bluetooth® Low Energy Audio stack and the service controller block. The Bluetooth® Low Energy audio stack calls the SVCCTL_RegisterHandler() and SVCCTL_RegisterSvcHandler() functions to register event handlers.

Figure 2.2 Bluetooth® Low Energy audio stack integration dependency - Service controller module

2.3. Linked List manager

The Linked List manager offers functions and types used by the Bluetooth® Low Energy audio stack to handle its internal linked lists.
The List Manager functions are implemented in a file named stm_list.c and the List Manager types and APIs are declared in stm_list.h. These files are present in the Projects\Common\WPAN\Modules folder directory or in each project folder (depending of the COMMON_WPAN configuration).
The Figure 2.3 shows an interface between the Bluetooth® Low Energy audio stack and the Linked List manager block.

Figure 2.3 Bluetooth® Low Energy audio stack integration dependency - Linked List manager module

2.4. Debug/Traces

The Debug Traces IP is useful for the Bluetooth® Low Energy audio stack in case of debug reports are enabled in the library.
For this, the Bluetooth® Low Energy audio stack requests the system to print some debug traces thanks to the BLE_AUDIO_PLAT_DbgLog() API. This API is implemented in the project.
The Figure 2.4 shows an interface between the Bluetooth® Low Energy audio stack and the debug traces block.

Figure 2.4 Bluetooth® Low Energy audio stack integration dependency - Debug/Traces module

The Bluetooth® Low Energy audio trace BLE_AUDIO_PLAT_DbgLog() API (see Table 2.1) is declared in ble_audio_plat.h header file in the Middlewares\ST\STM32_WPAN\ble\audio\Inc folder.

Functions	Header File
void BLE_AUDIO_PLAT_DbgLog(char *format,...)	ble_audio_plat.h

Table 2.1 Bluetooth® Low Energy audio debug log porting function

2.5. Timer server

The Bluetooth® Low Energy audio stack requires a one-shot reference timer on which are multiplexed all the internal Bluetooth® Low Energy audio software timers.
The Bluetooth® Low Energy audio stack calls the BLE_AUDIO_PLAT_TimerStart() to create the reference timer and start it. When the Bluetooth® Low Energy audio stack needs to stop the timer, it calls the BLE_AUDIO_PLAT_TimerStop(). The Bluetooth® Low Energy audio stack requires to get the remaining time of the reference timer. For this, it calls the BLE_AUDIO_PLAT_TimerGetRemainMs().
The Reference timer expiration should be notified, from the system layer, in a background task, thanks to the callback function passed in the parameter of the BLE_AUDIO_PLAT_TimerStart() API.
These APIs shall be implemented in the project.
The Figure 2.5 shows the interface between the Bluetooth® Low Energy audio stack and the timer server block.

Figure 2.5 Bluetooth® Low Energy audio stack integration dependency - Timer server module

The Bluetooth® Low Energy audio timer APIs, listed in the Table 2.2, are declared in ble_audio_plat.h header file in the Middlewares\ST\STM32_WPAN\ble\audio\Inc folder.

Functions	Header File
void BLE_AUDIO_PLAT_TimerStart(void *pCallbackFunc,void *pParam,uint32_t Timeout)	ble_audio_plat.h
void BLE_AUDIO_PLAT_TimerStop(void)	ble_audio_plat.h
uint32_t BLE_AUDIO_PLAT_TimerGetRemainMs(void)	ble_audio_plat.h

Table 2.2 Bluetooth® Low Energy audio timer porting functions

2.6. Bare metal sequencer / Operation system

The Bluetooth® Low Energy audio stack requires the registration of a dedicated task responsible to run the internal Bluetooth® Low Energy audio profiles process.
The dedicated task should call the BLE_AUDIO_STACK_Task() function.
When the Bluetooth® Low Energy audio task requests to be executed, the Bluetooth® Low Energy audio stack calls the BLE_AUDIO_STACK_NotifyToRun() to notify the system that the BLE_AUDIO_STACK_Task() function should be executed.
Note the BLE_AUDIO_STACK_Task() shall not be executed in the BLE_AUDIO_STACK_NotifyToRun() context.
The Bluetooth® Low Energy audio process stack is initialized with the BLE_AUDIO_STACK_Init() API call.

The BLE_AUDIO_STACK_NotifyToRun() API shall be implemented in the project.

TheFigure 2.6 shows the interface between the Bluetooth® Low Energy audio stack and the operating system block.

Figure 2.6 Bluetooth® Low Energy audio stack integration dependency - Bare metal sequencer / operation system

The Bluetooth® Low Energy audio stack sequencer and initialization APIs, listed in the Table 2.3, are declared in ble_audio_stack.h header file in the Middlewares\ST\STM32_WPAN\ble\audio\Inc folder.

Functions	Header File
void BLE_AUDIO_STACK_Init(void)	ble_audio_stack.h
void BLE_AUDIO_STACK_NotifyToRun(void)	ble_audio_stack.h
void BLE_AUDIO_STACK_Task(void)	ble_audio_stack.h

Table 2.3 Bluetooth® Low Energy audio task porting functions

2.7. Nonvolatile memory manager

The Bluetooth® Low Energy audio stack requires Nonvolatile memory services access to manage Bluetooth® Low Energy audio databases associated to the ATT services of the Bluetooth® Low Energy audio profiles composing the Generic Audio Framework.

The Bluetooth® Low Energy audio stack requires functions to read/write/compare/erase information in nonvolatile memory. For this, the Bluetooth® Low Energy audio stack calls the following APIs:

• BLE_AUDIO_PLAT_NvmAdd()
• BLE_AUDIO_PLAT_NvmGet()
• BLE_AUDIO_PLAT_NvmCompare()
• BLE_AUDIO_PLAT_NvmDiscard()

These APIs shall be implemented in the project.

To retrieve data stored in nonvolatile memory dedicated to each profile included in the Generic Audio Framework, the Bluetooth® Low Energy audio stack enumerates specific NVM types (in ble_audio_if.h header file) in addition to the types declared in ble_plat.h for the Bluetooth® Low Energy host (BLEPLAT_NVM_TYPE_SEC & BLEPLAT_NVM_TYPE_GATT):
enum
{
BLEAUDIO_PLAT_NVM_TYPE_BAP_PACS = 2,
BLEAUDIO_PLAT_NVM_TYPE_BAP_ASCS = 3,
BLEAUDIO_PLAT_NVM_TYPE_BAP_BASS = 4,
BLEAUDIO_PLAT_NVM_TYPE_CCP = 5,
BLEAUDIO_PLAT_NVM_TYPE_CSIP = 6,
BLEAUDIO_PLAT_NVM_TYPE_MCP = 7,
BLEAUDIO_PLAT_NVM_TYPE_VCP = 8,
BLEAUDIO_PLAT_NVM_TYPE_MICP = 9,
};

TheFigure 2.7 shows an interface between the Bluetooth® Low Energy audio stack and the nonvolatile memory manager block.

Figure 2.7 Bluetooth® Low Energy audio stack integration dependency - nonvolatile memory manager

The Bluetooth® Low Energy audio NVM APIs, listed in the Table 2.4, are declared in ble_audio_plat.h header file in the Middlewares\ST\STM32_WPAN\ble\audio\Inc folder.

Functions	Header File
int BLE_AUDIO_PLAT_NvmAdd( uint8_t type,const uint8_t* data,uint16_t size,const uint8_t* extra_data,uint16_t extra_size )	ble_audio_plat.h
int BLE_AUDIO_PLAT_NvmGet( uint8_t mode,uint8_t type,uint16_t offset,uint8_t* data,uint16_t size )	ble_audio_plat.h
Int BLE_AUDIO_PLAT_NvmCompare( uint16_t offset,const uint8_t* data,uint16_t size )	ble_audio_plat.h
Int BLE_AUDIO_PLAT_NvmDiscard( uint8_t mode)	ble_audio_plat.h

Table 2.4 Bluetooth® Low Energy audio NVM porting functions

2.8. Advanced encryption standard module

The coordinated set identification profile in the Generic Audio Framework requires access of many advanced encryption standard operations.

For this, the Bluetooth® Low Energy audio stack calls the following APIs:

• BLE_AUDIO_PLAT_AesEcbEncrypt()
• BLE_AUDIO_PLAT_AesCmacSetKey()
• BLE_AUDIO_PLAT_AesCmacCompute()

These APIs shall be implemented in the project.
The Figure 2.8 shows the interface between the Bluetooth® Low Energy audio stack and the AES block.

Figure 2.8 Bluetooth® Low Energy audio stack integration dependency - Advanced encryption standard module

The Bluetooth® Low Energy audio AES APIs, listed in the Table 2.5, are declared in ble_audio_plat.h header file in the Middlewares\ST\STM32_WPAN\ble\audio\Inc folder.

Functions	Header File
void BLE_AUDIO_PLAT_AesEcbEncrypt( const uint8_t* key,const uint8_t* input,uint8_t* output )	ble_audio_plat.h
void BLE_AUDIO_PLAT_AesCmacSetKey( const uint8_t* key )	ble_audio_plat.h
void BLE_AUDIO_PLAT_AesCmacCompute( const uint8_t* input,uint32_t input_length,uint8_t* output_tag )	ble_audio_plat.h

Table 2.5 Bluetooth® Low Energy audio AES porting functions

2.9. Random number generator module

The coordinated set identification profile in the Generic Audio Framework requires random number access.

For this, the Bluetooth® Low Energy audio stack calls the BLE_AUDIO_PLAT_RngGet() API.

This API shall be implemented in the project.

TheFigure 2.9 shows the interface between the Bluetooth® Low Energy audio stack and the random number generator block.

Figure 2.9 Bluetooth® Low Energy audio stack integration dependency - Random number generator module

The Bluetooth® Low Energy audio RNG API, listed in the Table 2.6, is declared in ble_audio_plat.h header file in the Middlewares\ST\STM32_WPAN\ble\audio\Inc folder.

Functions	Header File
void BLE_AUDIO_PLAT_RngGet( uint8_t n, uint32_t* val )	ble_audio_plat.h

Table 2.6 Bluetooth® Low Energy audio RNG porting functions

3. Bluetooth® Low Energy audio stack configuration

The Bluetooth® Low Energy audio stack is delivered in a unique library supporting all the roles of profiles composing the Generic Audio Framework defined by the Bluetooth® SIG.

Nevertheless, the audio use case profiles, and so the final audio application, are based on common audio profile roles, as defined by the Bluetooth® SIG, which are limited to three types (CAP Acceptor, CAP Commander and CAP Initiator). Each CAP role is associated to specific roles in the subprofiles composing the Generic Audio Framework as shown in the Figure 3.1.

Figure 3.1 Generic Audio Framework- "CAP role /Profiles" Relationship

Some mechanisms are available to configure the Bluetooth® Low Energy audio stack, and so the Generic Audio Framework, for a specific usage as defined in the use case profiles and so fit just the required ROM/RAM resource to support the application configuration.

3.1. Configuration of the audio profiles of the Generic Audio Framework

The Bluetooth® Low Energy audio stack library offers a dynamic configuration way of its internal audio profiles.

Each audio profile of the Generic Audio Framework in the Bluetooth® Low Energy audio library is independently configurable and the RAM required by each audio profile context in the Bluetooth® Low Energy audio stack to support its specific configuration shall be allocated in the application layer according to the configuration settings.

The RAM context allocation and the configuration of each audio profile of the Generic Audio Framework is performed with CAP_Init() function thanks to the following dedicated audio profile configuration structure parameters:

• CAP_Config_t
• BAP_Config_t
• CCP_Config_t
• MCP_Config_t
• CSIP_Config_t
• VCP_Config_t
• MICP_Config_t

Each of these configuration structures is composed of:

• configuration setting fields (role, max number of Bluetooth® Low Energy links, specific audio profiles settings)
• Settings of the RAM buffer allocated for profile context memory resource

3.1.1. Media control profile configuration example

The Figure 3.2 describes the field of the media control profile (MCP) Configuration. The MCP_Config_t structure type is defined in the mcp_types.h

Figure 3.2 MCP_Config_t definition (mcp_types.h)

In case of an audio use case profile based on a CAP Acceptor role supporting the MCP feature (MCP client role):

• the Role field shall be set to MCP_CLIENT_ROLE
• the MaxNumBleLinks shall be set to the maximum number of connections with remote CAP Initiators the CAP Acceptor would support.
• The Clt field shall be filled in which pStartRamAdd field shall points on a RAM allocated in the application layer.
  

3.1.2. Unicast server (CAP Acceptor) configuration example

The Figure 3.3 shows the fields in the BAP_Config_t structure to configure when the unicast server feature is activated in the CAP Acceptor role. The BAP_Config_t structure type is defined in the bap_types.h

Figure 3.3 Fields of BAP_Config_t to configure in the unicast server role

3.1.3. Unicast client (CAP Initiator) configuration example

The Figure 3.4 shows the fields in the BAP_Config_t structure to configure when the unicast client feature is activated in the CAP Initiator role. The BAP_Config_t structure type is defined in the bap_types.h

Figure 3.4 Fields of BAP_Config_t to configure in the unicast client role

3.1.4. Broadcast sink (CAP Acceptor) configuration example

The Figure 3.5 shows the fields in the BAP_Config_t structure to configure when the broadcast sink feature is activated in the CAP Acceptor role. The BAP_Config_t structure type is defined in the bap_types.h

Figure 3.5 Fields of BAP_Config_t to configure in the broadcast sink role

3.1.5. Broadcast source (CAP Initiator) configuration example

The Figure 3.6 shows the fields in the BAP_Config_t structure to configure when the broadcast source feature is activated in CAP Initiator role. The BAP_Config_t structure type is defined in the bap_types.h

Figure 3.6 Fields of BAP_Config_t to configure in broadcast source role

3.1.6. Scan delegator (CAP Acceptor/ CAP Commander) configuration example

The Figure 3.7 shows the fields in the BAP_Config_t structure to configure when the Scan Delegator feature is activated in the CAP Acceptor or CAP Commander role. The BAP_Config_t structure type is defined in the bap_types.h

Figure 3.7 Fields of BAP_Config_t to configure in Scan Delegator role

3.1.7. Broadcast assistant (CAP Commander) configuration example

The Figure 3.8 shows the fields in the BAP_Config_t structure to configure when the broadcast assistant feature is activated in the CAP Commander role. The BAP_Config_t structure type is defined in the bap_types.h

Figure 3.8 Fields of BAP_Config_t to configure in the broadcast assistant role

3.2. RAM context allocation of the audio profiles of the Generic Audio Framework

The context memory of the audio profiles in the Generic Audio Framework is allocated in the application layer according to the specified audio profile configuration submitted over the parameters of CAP_Init() API.

ManyMACRO and Constants are defined for each audio profile to calculate the required RAM size for the context resource to support the specified configuration.

Example – Media control profile (mcp_types.h) Two macros are defined to calculate RAM size:

• BLE_MCP_CLT_TOTAL_BUFFER_SIZE() returns the amount of memory, in bytes, needed for the storage of data structures in the MCP client.
  
• BLE_MCP_SRV_TOTAL_BUFFER_SIZE() returns the amount of memory, in bytes, needed for the storage of data structures in MCP server
  

The Figure 3.9 shows RAM allocation to support the MCP client and MCP server role.

Figure 3.9 MCP RAM context' allocation

Warning:
The values of the parameters of the MACRO shall be equal to the values of the fields submitted in the parameters of the audio profiles configuration in CAP_Init().
In cases of the parameters do not match, the CAP_Init() could fail because the audio stack will fail to allocate the memory required by the audio profile or the CAP_Init() could unused memory to allocate the context of the audio profile.

3.3. GATT allocation of the audio profiles of the Generic Audio Framework

Each audio profile in the GATT server role in the Generic Audio Framework requires GATT service and GATT attributes allocation.

These allocations are done through theBleStack_init_t type parameter of the BleStack_Init() API of the Bluetooth® Low Energy host stack.

MACRO and Constants are defined for each audio profile to calculate the required number of GATT services and GATT attributes to support a specified audio profile configuration.

Example – Media control profile (mcp_types.h)

• MCP_SRV_NUM_GATT_SERVICES(num_media_players) is defined to calculate the number of GATT services required to configure the server role of the media control profile according to the number of Media Player instances which would be registered in the application layer.
  
• MCP_SRV_NUM_GATT_ATTRIBUTES(num_media_players,mcp_feature) is defined to calculate the number of GATT attributes required to configure the server role of the media control profile according to the number of Media Player instances and the supported MCP option feature.

3.4. ROM optimization of the Bluetooth® Low Energy audio stack

bBecause the Bluetooth® Low Energy audio stack is delivered in a unique library, the library supports all the roles of the profiles of the Generic Audio Framework.
Consequently, if the final audio application is based on only limited audio profiles and limited profiles role, a lot of code in the Bluetooth® Low Energy audio stack is not used and this memory could not be assigned for the application layer implementation.
In order to limit the unused RAM in the Bluetooth® Low Energy audio stack, a mechanism, based on weak function concept, has been integrated in the Bluetooth® Low Energy audio stack. This mechanism allows overwriting, in the application layer, the functions implemented in the static library that will not be called in a specific use case.

In the Bluetooth® Low Energy audio stack , many functions that generate a high ROM allocation for a specific audio profile role have been identified and declared asweak function.
If the audio profile role is not required/supported for the Bluetooth® Low Energy audio use case, the weak function is implemented in the application layer as an empty function. By the way, all the ROM allocation generated by the function in the Bluetooth® Low Energy audio stack library is removed in the final Bluetooth® Low Energy audio use case implementation.

TheFigure 3.10 shows the weak function defined in the Bluetooth® Low Energy audio stack for each role of the audio profiles in the Generic Audio Framework.

Figure 3.10 WEAK functions in the Generic Audio Framework

Example 1
For a Bluetooth® Low Energy audio use case which does not require the BAP unicast server role, the following functions should be overwritten, in application layer (cf ble_audio_if.c), to remove unused code in the Bluetooth® Low Energy audio stack library as shown in Figure 3.11

Figure 3.11 ROM optimization if unicast server role not required

Example 2
For a LE use case which does not require media control server role, the following functions should be overwritten, in the application layer (cf be_audio_if.c), to remove unused code in the Bluetooth® Low Energy audio stack library as shown in Figure 3.12

Figure 3.12 ROM optimization if MCP server role not required

4. Bluetooth® Low Energy Generic Audio Framework procedures

This section describes the main procedures handled by the CAP layer of the Generic Audio Framework:

• Audio profiles of the Generic Audio Framework Linkup procedure
• Unicast audio procedures
• Broadcast audio procedures
• Capture and rendering control procedures

4.1. Audio profiles linkup

The audio profiles link up procedures, described in this section, consist to discover the services and the associated characteristics of the audio profiles composing the Generic Audio Framework of the remote Bluetooth device.

The Generic Audio Framework implements a CAP Linkup procedure, initiated by calling the CAP_Linkup() function (defined in cap.h), that shall be called to discover/link the audio profiles supported by the remote CAP device. The linkup procedure shall be called only if the link with the remote device is encrypted.

The CAP_Linkup() function performs a linkup operation on profiles composing the Generic Audio Framework, according to the input parameter type GAF_Profiles_Link_t. The linkup operation could be a complete link process (e.g: Service and characteristic discovery) or just a service restoration from information stored in the nonvolatile memory.
This function could be called by any of the CAP roles in a GATT client role for an audio profile. For example, a CAP Initiator could try to perform a linkup procedure for profiles associated to the unicast feature and for the coordinated set identification profile because the CAP Initiator could be BAP unicast client and CSIP set coordinator. However, it could not perform linkup of call control profile because the CAP Initiator could be only the call control server (GATT server role) for this profile.
On the other side, the CAP Acceptor could performed linkup procedure of call control profile and media control profile with a remote CAP Initiator

TheCAP_DB_GetPresentGAFProfiles() function enables to get the profiles of the Generic Audio Framework that are present/saved in nonvolatile memory for a specific Bluetooth device.

TheCAP_GetCurrentLinkedProfiles() function enables to get the current linked profiles of the Generic Audio Framework issued from a previous CAP linkup procedure.

TheCAP_Unlink() function enables to unlink specified profiles of the Generic Audio Framework of a current connection and to indicate if the associated information should be stored in the nonvolatile memory.

Functions	Description	Header File
CAP_Linkup()	Perform Linkup operation on specified profiles composing the Generic Audio Framework. If a profile is already linked, the function returns a failure status.	cap.h
CAP_DB_GetPresentGAFProfiles()	Indicate the profiles in ATT client role of the Generic Audio Framework present in the persistent memory.	cap.h
CAP_GetCurrentLinkedProfiles()	Indicate the linked profiles of the Generic Audio Framework issued from a CAP linkup procedure.	cap.h
CAP_Unlink()	Unlink the linked profiles of the Generic Audio Framework issued from a previous CAP linkup procedure.	cap.h

The events CAP_CSI_LINKUP_EVT, CAP_UNICAST_LINKUP_EVT, CAP_BA_LINKUP_EVT , CAP_CCP_LINKUP_EVT, CAP_MCP_LINKUP_EVT, CAP_CSI_LINKUP_EVT, CAP_VOLUME_CTRL_LINKUP_EVT and CAP_MICROPHONE_CTRL_LINKUP_EVT may be notified during the CAP linkup procedure depending on requested audio profiles and if they are supported by the remote device.
The CAP_LINKUP_COMPLETE_EVT event is notified once CAP procedure is complete. These events are listed in the Table 4.1 .

Events	Description	Header File
CAP_UNICAST_LINKUP_EVT	Event notified during CAP linkup procedure if CAP Initiator supports BAP unicast client role and discovers that the remote device supports BAP unicast server role.	cap_types.h
CAP_CSI_LINKUP_EVT	Event notified during CAP linkup procedure if CAP Initiator/Commander supports CSIP set coordinator role and discovers that the remote device supports CSIP set member role.	cap_types.h
CAP_BA_LINKUP_EVT	Event notified during CAP linkup procedure if CAP Commander supports BAP broadcast assistant role and discovers that the remote device supports Scan Delegator role.	cap_types.h
CAP_CCP_LINKUP_EVT	Event notified during CAP linkup procedure if CAP Commander or CAP Acceptor supports call control client role and discovers that the remote device supports CCP server role.
CAP_MCP_LINKUP_EVT	Event notified during CAP linkup procedure if CAP Commander or CAP Acceptor supports Media Control Client role and discovers that the remote device supports MCP server role.	cap_types.h
CAP_VOLUME_CTRL_LINKUP_EVT	Event notified during CAP linkup procedure if CAP Commander supports the VCP volume controller role and discovers that the remote device supports the VCP volume renderer role.	cap_types.h
CAP_MICROPHONE_CTRL_LINKUP_EVT	Event notified during CAP linkup procedure if CAP Commander supports MICP microphone controller role and discovers that the remote device supports MICP microphone device role.	cap_types.h
CAP_LINKUP_COMPLETE_EVT	Event notified once CAP Linkup is complete.	cap_types.h

Table 4.1 CAP events reported during CAP Linkup procedure

In case of the remote CAP Acceptor is a Set Member of a Coordinated Set, the local CAP Initiator or CAP Commander should discover and performs the CAP Linkup procedure with other CAP Acceptors of the Coordinated Set.

The Figure 4.1 shows an example of an implementation to perform CAP Linkup with all CAP Acceptors of a coordinated set.

• Connect with the first CAP Acceptor (thanks to the aci_gap_create_connection())
• When the LE connection complete event is received, call the aci_gap_send_pairing_req() to pair or directly start encryption with the remote CAP Acceptor
• When the pairing complete event is received, CAP_Linkup() function is called to linkup with remote supported audio profiles composing the Generic Audio Framework.
• When the CAP linkup process is complete (CAP_LINKUP_COMPLETE_EVT event notification), if CAP_CSI_LINKUP_EVT event has been received during the process indicating that the connected CAP Acceptor is a set member of a Coordinated Set, the aci_gap_start_general_connection_establish_proc() and CAP_StartCoordinatedSetMemberDiscoveryProcedure() could be called to discover the other CAP Acceptors composing the Coordinated Set of the first CAP Acceptor. Note that the CAP_CSI_LINKUP_EVT enables to know, if supported by the CAP Acceptor, the size of the Coordinated Set and the rank of the CAP Acceptor.
• When a CAP Acceptor of the Coordinated Set in advertising state is discovered, the CSIP_COO_ADV_REPORT_NEW_SET_MEMBER_DISCOVERED_EVT event is notified. At this moment, the aci_gap_create_connection() could be called to connect with the discovered CAP Acceptor.
• When the LE connection complete event is received, call the aci_gap_send_pairing_req() to pair or directly start encryption with the remote CAP Acceptor.
• Once the CSIP set member discovery process is complete (Matching of SIR process), the CSIP_COO_NEW_SET_MEMBER_DISCOVERED_EVT is received.
• In case of another CAP Acceptor is discovered, CSIP_COO_ADV_REPORT_NEW_SET_MEMBER_DISCOVERED_EVT event is notified and connection + pairing should be performed for each discovered CAP Acceptor
• Once the Set Member discovery procedure is complete (All Set Members have been discovered or timeout), the CSIP_COO_SET_MEMBER_DISCOVERY_PROCEDURE_COMPLETE_EVT event is received.
• The CAP_Linkup() should be performed for each discovered CAP Acceptor once the Set Member discovery procedure is complete

Figure 4.1 CAP Linkup with all CAP Acceptors of a coordinated set

4.2. Audio stream transition procedures

The procedures associated to the audio stream transition are specified in the section 7.3.1 of the Common Audio Profile

4.2.1. Unicast audio procedures

The unicast audio procedures (Unicast Audio Start, Unicast Audio Stop, Unicast Audio Update) described in the CAP specification are performed by the CAP Initiator thanks to the function listed in the Table 4.2.

Functions	Description	Header File
CAP_Unicast_AudioStart()	Start unicast audio with specified CAP Acceptors according to sink/ source stream configuration.	cap.h
CAP_Unicast_AudioStop()	Stop Unicast Audio with specified CAP Acceptors.	cap.h
CAP_Unicast_AudioUpdate()	Change context type values and/or CCID values associated with one or more unicast audio streams.	cap.h

Table 4.2 Functions for unicast audio procedure management

ForCAP Acceptor supporting Unicast server role, the Generic Audio Framework provides functions to :

• Register sink/source audio channels accessible by the remote CAP Initiator
• Set/Update the audio contexts (Conversational, media… Audio_Context_t defined in audio_types.h)
• Set/Update the audio locations (Front left, front right…Audio_Location_t defined in audio_types.h)
• Register/Update the audio capabilities of the unicast server

The Table 4.3 describes the functions dedicated to the CAP Acceptor in the unicast server role.

Functions	Description	Header File
CAP_RegisterAudioChannels()	Register sink/source audio channels (and associated audio stream endpoint) supported by unicast server.	cap.h
CAP_SetSupportedAudioContexts()	Set/Update supported audio contexts for reception and transmission.	cap.h
CAP_SetAvailableAudioContexts()	Set available audio contexts for reception and transmission which will be used for BAP Announcement and for future connections.	cap.h
CAP_UpdateAvailableAudioContexts()	Update available audio contexts for reception and transmission associated to the specified remote CAP device.	cap.h
CAP_SetSnkAudioLocations()	Set/Update the supported sink audio locations.	cap.h
CAP_SetSrcAudioLocations()	Set/Update the supported source audio locations.	cap.h
CAP_RegisterSnkPACRecord()	Register published audio capabilities record for audio sink role.	cap.h
CAP_RegisterSrcPACRecord()	Register published audio capabilities record for audio source role.	cap.h
CAP_UpdatePACRecord()	Update a registered audio codec capabilities record for audio sink/source role.	cap.h

Table 4.3 CAP functions dedicated to CAP Acceptor for unicast audio configuration

The section 3.5 of the Basic audio profile describes the requirement of the CAP Acceptor in unicast server role concerning the audio capabilities configuration and the audio channels configuration to support according to the audio role (sink and/or source) and the audio locations.
Note that each Bluetooth® Low Energy audio use case profile specifies its audio capabilities and audio channels requirements.

During the unicast audio stream transition procedure, the CAP Initiator and the CAP Acceptor receive CAP events described inTable 4.4.

CAP procedure	Events	Description	CAP Initiator	CAP Acceptor
Audio start	CAP_UNICAST_AUDIO_STARTED.	Unicast audio start procedure is complete with all the specified CAP Acceptors.	X
Audio start	CAP_UNICAST_PREFERRED_QOS_REQ_EVT	Preferred QoS settings are requested for the specified audio stream endpoint.		X
Audio start	CAP_UNICAST_AUDIO_DATA_PATH_SETUP_REQ_EVT	Audio data path setup is requested for the specified audio stream endpoint. The CAP_Unicast_SetupAudioDataPath() shall be called to respond to the audio data path setup request.	X	X
Audio start	CAP_AUDIO_CLOCK_REQ_EVT	Audio Clock subsystem should be updated to support submitted audio sample frequency	X	X
Audio start Audio stop	CAP_UNICAST_SERVER_ASE_STATE_EVT	The state of an audio stream endpoint has changed in unicast server side (CAP Acceptor) The state and the transition are described in the section 3 of the Audio stream control service '.		X
Audio start Audio stop	CAP_UNICAST_CLIENT_ASE_STATE_EVT	The state of an audio stream endpoint has changed in unicast client side (CAP Initiator) The state and the transition are described in the section 3 of the Audio stream control service '.	X
Audio start	CAP_UNICAST_AUDIO_CONNECTION_UP_EVT	Audio path is up for specified audio stream endpoint	X	X
Audio start Audio stop	CAP_UNICAST_AUDIO_CONNECTION_DOWN_EVT	Audio path is down for specified audio stream endpoint	X	X
Audio stop	CAP_UNICAST_AUDIO_STOPPED	Unicast audio stop procedure is complete with all the specified CAP Acceptors	X
Audio update	CAP_UNICAST_AUDIO_UPDATED	Unicast audio update procedure is complete with all the specified CAP Acceptors	X
Audio update	CAP_UNICAST_ASE_METADATA_UPDATED_EVT	Metadata associated to an audio stream endpoint is updated but audio stream endpoint State does not change	X	X

Table 4.4 CAP events of unicast audio transition

TheFigure 4.2 shows the Functions/Events flow during the CAP Unicast audio start procedure in CAP Initiator and CAP Acceptor side. In this example, the CAP Initiator starts a bidirectional unicast audio with one CAP Acceptor. Consequently, a source ASE and a Sink ASE are used by the CAP Initiator to set up the unicast audio.

Figure 4.2 unicast audio start procedure sequence

In case of a failure occurs during the unicast audio start procedure, the CAP Initiator automatically aborts the procedure to move the audio stream endpoints in IDLE or CODEC CONFIGURED state. Once the abort operation is complete, the CAP_UNICAST_AUDIO_STARTED events with failure status are notified to the upper layer.

TheFigure 4.3 shows the Functions/Events flow during the CAP Unicast audio stop procedure in CAP Initiator and CAP Acceptor side. In this example, at the starting point, a source ASE and a Sink ASE are in streaming state when the CAP Initiator calls the CAP_Unicast_AudioStop() function.

Figure 4.3 Unicast audio stop procedure sequence

4.2.2. Broadcast audio procedures

The broadcast audio procedures (Broadcast Audio Start, Broadcast Audio Stop, Broadcast Audio Update) described in the CAP specification are performed by the CAP Initiator thanks to the functions listed in the Table 4.5.

Functions	Description	Header File
CAP_Broadcast_AudioStart()	Configure and start a broadcast source with the given parameters.	cap.h
CAP_Broadcast_AudioStop()	Stop a broadcast source and go to configured or idle State.	cap.h
CAP_Broadcast_AudioUpdate()	Update a streaming broadcast source metadata Cannot change an audio configuration.	cap.h

Table 4.5 CAP functions of broadcast audio transition management in the CAP Initiator side

During the CAP broadcast audio procedures, the CAP Initiator is notified, over CAP events, that the procedure is complete and the state of the audio path associated to the audio stream has changed. These events notified during the CAP broadcast audio procedures are listed in theTable 4.6.

Events	Description	Header File
CAP_BROADCAST_AUDIOSTARTED_EVT	Event notified when the broadcast audio start procedure is complete.	cap_types.h
CAP_BROADCAST_AUDIOSTOPPED_EVT	Event notified when the broadcast audio stop procedure is complete.	cap_types.h
CAP_BROADCAST_AUDIO_UP_EVT	Event notified when the audio path has been set up.	cap_types.h
CAP_BROADCAST_AUDIO_UP_EVT	Event notified when the audio path has been removed.	cap_types.h

Table 4.6 CAP events of broadcast audio transition in CAP Initiator side

TheFigure 4.4 shows the broadcast state machine of the CAP Initiator in broadcast source role. The oval shapes represent the states of the CAP Initiator state machine. The labeled arrows represent the CAP broadcast function, which can cause a transition of the state machine.

Figure 4.4 CAP Initiator broadcast state machine

When a broadcast audio stream is in progress, a CAP Acceptor, supporting broadcast sink role, which would be synchronized with the broadcast audio stream needs to call successive Bluetooth® Low Energy legacy functions and CAP functions to be able to be synchronized with the broadcast isochronous stream emitted by a CAP Initiator. The CAP functions allowing the CAP Acceptor to manage broadcast audio stream are listed in the Table 4.7.

Functions	Description	Header File
CAP_Broadcast_StartAdvReportParsing()	Start parsing extended advertising events to look for broadcast UUIDs and generate CAP_ACC_BROADCAST_SOURCE_ADV_REPORT_EVT events An observation procedure must be started by the user in parallel.	cap.h
CAP_Broadcast_StopAdvReportParsing()	Stop parsing extended advertising events.	cap.h
CAP_Broadcast_StartPASync()	Start synchronization to a periodic advertising train.	cap.h
CAP_Broadcast_StartBIGSync()	Start synchronization to a broadcast isochronous group.	cap.h
CAP_Broadcast_StopPASync()	Stop synchronization to a periodic advertising train.	cap.h
CAP_Broadcast_StopBIGSync()	Stop synchronization to a broadcast isochronous group.	cap.h
CAP_Broadcast_ParseBASEGroup()	Parse a BASE payload reported by a CAP_ACC_BASE_REPORT_EVT and fill a BAP_BASE_Group_t structure.	cap.h
CAP_Broadcast_ParseBASESubgroup()	Parse a BASE payload reported by a CAP_ACC_BASE_REPORT_EVT and fill a BAP_BASE_Subgroup_t structure.	cap.h
CAP_Broadcast_ParseBASEBIS()	Parse a BASE payload reported by a CAP_ACC_BASE_REPORT_EVT and fill a BAP_BASE_BIS_t structure.	cap.h

Table 4.7 CAP functions of broadcast audio transition management in CAP Acceptor side

During the broadcast audio procedure in CAP Acceptor side, many CAP events are notified in the application layer resulting to operations started by the CAP Acceptor itself or the remote CAP Initiator. These CAP events received in the CAP Acceptor side are listed in the Table 4.8.

Events	Description	Header File
CAP_BROADCAST_SOURCE_ADV_REPORT_EVT	Notified when a broadcast source has been scanned.	cap_types.h
CAP_BROADCAST_PA_SYNC_ESTABLISHED_EVT	Notified when synchronization to a periodic advertising train has been established.	cap_types.h
CAP_BROADCAST_BASE_REPORT_EVT	Notified when a BASE report is received.	cap_types.h
CAP_BROADCAST_BIGINFO_REPORT_EVT	Notified when a BIG info is received.	cap_types.h
CAP_BROADCAST_BIG_SYNC_ESTABLISHED_EVT	Notified when synchronization to a BIG info has been established.	cap_types.h
CAP_BROADCAST_PA_SYNC_LOST_EVT	Notified when synchronization to a periodic advertising train has been lost.	cap_types.h
CAP_BROADCAST_BIG_SYNC_LOST_EVT	Notified when synchronization to a BIG has been lost.	cap_types.h
CAP_BROADCAST_AUDIO_UP_EVT	Notified when audio data path has been set up.	cap_types.h
CAP_BROADCAST_AUDIO_DOWN_EVT	Notified when audio data path has been removed.	cap_types.h

Table 4.8 CAP events of broadcast audio transition in CAP Acceptor side

TheFigure 4.5 describes the broadcast sink sequence diagram during the broadcast audio stream synchronization procedure in CAP Acceptor side. To synchronize with broadcast audio stream, successive CAP broadcast operations are required in the CAP Acceptor side.

Figure 4.5 CAP Acceptor broadcast sequence diagram

4.3. Capture and rendering control procedures

The procedures associated to the capture and rendering control are specified in the section 7.3.2 of the Common audio profile

4.3.1. Volume control procedures

The volume control procedures (Change volume procedure, Change volume offset procedure and Change volume mute state procedure), described in the CAP specification, are performed by the CAP Commander in volume controller role to manage the volume on the Acceptors of a coordinated set acting in the VCP renderer role. The procedures are initiated by the specific CAP functions listed in Table 4.9.
Note that the Generic Audio Framework offers volume control functions, declared in vcp.h header file, which could be used in the application layer to perform operations not specified in the procedure defined in the common audio profile specification:

Functions	Description	Header File
CAP_VolumeController_StartSetVolumeProcedure()	Start procedure to change the volume level on all the Acceptors of the coordinated set acting in the VCP volume renderer role. (Section 7.3.2.2)	cap.h
CAP_VolumeController_StartSetVolumeMuteStateProcedure()	Start the procedure to change the (Volume) mute state on all the Acceptors of the Coordinated Set acting in the VCP volume renderer role (section 7.3.2.4)	cap.h
CAP_VolumeController_StartSetVolumeOffsetProcedure() *	Start procedure to set the volume offset relative to the volume level set by the change volume procedure on the Acceptors of the Coordinated Set acting in the VCP renderer role. (Section 7.3.2.3)	cap.h

Table 4.9 Functions for Volume control procedure management

(*) Not yet available

During the volume control procedures, the CAP Commander receives volume control events, defined in vcp_types.h file, through the CAP_VCP_META_EVT event, and, once the procedure is complete, a dedicated CAP event defined in cap_types.h file. The Table 4.10 describes the events received by the CAP Commander during the CAP volume control procedures.

Event	Description	Header File
VCP_CONTROLLER_UPDATED_VOLUME_STATE_EVT	Volume state has changed on a CAP Acceptor of the Coordinated Set Note: This event occurs during the change volume procedure and the change volume mute state procedure.	vcp_types.h
CAP_SET_VOLUME_PROCEDURE_COMPLETE_EVT	CAP change volume procedure is complete for all the CAP Acceptors of the Coordinated Set	cap_types.h
CAP_SET_VOLUME_MUTE_STATE_PROCEDURE_COMPLETE_EVT	CAP change volume mute state procedure is complete for all the CAP Acceptors of the Coordinated Set	cap_types.h
VCP_CONTROLLER_VOLUME_OFFSET_STATE_EVT	Volume offset state has changed on a volume offset instance of a CAP Acceptor of the Coordinated Set Note: This event occurs during the change volume offset procedure.	vcp_types.h
CAP_SET_VOLUME_OFFSET_PROCEDURE_COMPLETE_EVT*	CAP set volume offset procedure is complete for all the CAP Acceptors of the Coordinated Set.	cap_types.h

Table 4.10 Events of volume control procedures

(*) Not yet available

TheFigure 4.6 shows the sequence of CAP change volume procedure initiated by a CAP Initiator with a Coordinated Set composed of two Set Members, CAP Acceptor 1 and CAP Acceptor 2. Note that the CAP_VolumeController_StartSetVolumeProcedure() is called with the connection handle of the CAP Acceptor 1 and the Generic Audio Framework is responsible to send the change volume operation request to the other Set Members of the Coordinated Set.

Figure 4.6 CAP change volume procedure sequence diagram

4.3.2. Microphone control procedures

The microphone control procedures (Change microphone volume mute state procedure and Change microphone gain setting procedure), described in the CAP specification, are performed by the CAP Commander in the microphone controller role to manage the microphone volume on the Acceptors of a coordinated set acting in the MICP device role. The procedures are initiated by the specific CAP functions listed in Table 4.11.
Note that the Generic Audio Framework offers microphone control functions, declared in micp.h header file, which could be used in the application layer to perform operations not specified in the procedure defined in the common audio profile specification:

Functions	Description	Header File
CAP_MicrophoneController_StartSetMuteProcedure()	Start the procedure to change the microphone mute value on all the Acceptors of the Coordinated Set acting in the MICP microphone device role. (Section 7.3.2.5)	cap.h
CAP_MicrophoneController_StartSetGainSettingProcedure()	Start procedure to set the microphone gain setting on the Acceptors of the Coordinated Set acting in the MICP device role. (Section 7.3.2.6)	cap.h

Table 4.11 Functions for microphone control procedure management

During the microphone control procedures, the CAP Commander receives microphone control events defined in micp_types.h file, through the CAP_MICP_META_EVT event, and, once the procedure is complete, a dedicated CAP event defined in cap_types.h file. The Table 4.12 describes the events received by the CAP Commander during the CAP microphone control procedures.

Event	Description	Header File
MICP_CONTROLLER_UPDATED_MUTE_EVT	Microphone state has changed on a CAP Acceptor of the Coordinated Set Note: This event occurs during the change microphone volume mute state procedure.	micp_types.h
CAP_SET_MICROPHONE_MUTE_COMPLETE_EVT	CAP change microphone volume mute state procedure is complete for all the CAP Acceptors of the Coordinated Set	cap_types.h
MICP_DEVICE_UPDATED_AUDIO_INPUT_STATE_EVT	Audio input state of an audio input instance has changed on a CAP Acceptor of the Coordinated Set Note: This event occurs during the change gain setting procedure.	micp_types.h
CAP_SET_MICROPHONE_GAIN_SETTING_COMPLETE_EVT	CAP change gain setting procedure is complete for all the CAP Acceptors of the Coordinated Set	cap_types.h

Table 4.11 Events of microphone control procedures

TheFigure 4.7 shows the sequence of CAP change microphone volume mute state procedure initiated by a CAP Initiator with a Coordinated Set composed of two set members, CAP Acceptor 1 and CAP Acceptor 2. Note that the CAP_MicrophoneController_StartSetMuteProcedure() is called with the connection handle of the CAP Acceptor 1 and the Generic Audio Framework is responsible to send the change microphone volume mute state operation request to the other Set Members of the Coordinated Set.

Figure 4.7 CAP change microphone volume mute state procedure sequence diagram

4.4. Content control procedure

The content control procedure concerns operations related to the Call Control and the Media Control services.
All related items in the BLE Audio Stack (events, commands) are described in Content Control.