![]() |
Coming soon |
1. STM32WBA BLE Audio Firmware Architecture
The Bluetooth® LE 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 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® LE 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® LE Audio provided in the STM32CubeWBA MCU Package.
Figure 1.1 Bluetooth® LE Audio Firmware Architecture |
---|
The Audio Use Case Profiles implementation is available in Source 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 in charge to handle internal tasks and Bluetooth® LE events received from the LE Host Stack.
The "BLE 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® LE Audio Framework Interfaces
The Header files associated to the Bluetooth® LE 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® LE Audio as specified by the Bluetooth SIG |
ble_audio_stack.h | this file defines Bluetooth® LE Audio Stack interfaces initialization, task processing. |
ble_audio_plat.h | this file defines types and declares APIs required for Audio Stack integration on platform : AES, RNG, Non-Volatile Memory, Timer, Traces |
cap_types.h | This file defines :
|
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 LTV structure. |
ccp_types.h | This file defines :
|
ccp.h | This file declares functions to manage Call Control operations. |
mcp_types.h | This file defines :
|
mcp.h | This file declares functions to manage Media Control operations. |
csip_types.h | This file defines :
|
csip.h | This file declares function to register Service Instance for CSIP Set Member role. |
micp_types.h | This file defines :
|
micp.h | This file declares function to manage Microphone Control operations not handle in CAP procedures. |
vcp_types.h | This file defines :
|
vcp.h | This file declares 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® LE Audio Stack Integration
The base of the of the Bluetooth® LE Audio Stack is the BLE Host and the Link Layer.
In addition, the Bluetooth® LE Audio Stack requires external SW modules :
- Service Controller Module
- Linked List Manager Module
- Debug/Traces Module
- Timer Server Module
- Bare Metal Sequencer / Operation System Module
- Non-Volatile Memory Manager Module
- Advanced Encryption Standard (AES) Module
- Random Number Generator Module
Figure 2.1 shows the external SW modules dependencies of the Bluetooth® LE Audio Stack
Figure 2.1 STM32WBA Bluetooth® Bluetooth® LE Audio Stack Integration Dependencies |
---|
2.1. Host Stack
The Basic Audio Profile of the Generic Audio Framework, included in the Bluetooth® LE Audio Stack, is in charge to manage features based on :
- Extended Advertising features
- ISO features
- Periodic Advertising features
- Periodic Advertising Sync Transfer features
These features accesses are provided by the BLE Host Stack.
Moreover, all the profiles, and their associated services, in the Generic Audio Framework are based on ATT service model. Consequently, each profile requires an access of GATT operations. These GATT operation accesses are provided by the BLE 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® LE Audio Stack to register handlers through which asynchronous HCI, GAP and GATT events would be notified from the BLE Host to the profiles of the Generic Audio Framework.
In the Bluetooth® LE 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® LE Audio Stack integration requires for the Service Controller configuration:
- BLE_CFG_SVC_MAX_NBR_CB shall be incremented by 1
- BLE_CFG_MAX_NBR_CB shall be incremented by 1
Figure 2.2 shows the interface between the Bluetooth® LE Audio Stack and the Service Controller block. The Bluetooth® LE Audio Stack calls the SVCCTL_RegisterHandler() and SVCCTL_RegisterSvcHandler() functions to register Event handlers.
Figure 2.2 Bluetooth® LE Audio Stack Integration Dependency - Service Controller Module |
---|
2.3. Linked List Manager
The Linked List Manager offers functions and types used by the Bluetooth® LE Audio Stack to handle its internal linked lists.
The List Manager functions are implemented in a file named stm_list.c included in each project folder.
The List Manager types and APIs are declared in stm_list.h also present in each project folder.
Figure 2.2 shows interface between the Bluetooth® LE Audio Stack and the Linked List Manager block.
Figure 2.2 Bluetooth® LE Audio Stack Integration Dependency - Linked List Manager Module |
---|
2.4. Debug/Traces
The Debug Traces IP is useful for the Bluetooth® LE Audio Stack in case of debug reports are enabled in the library. For this, the Bluetooth® LE Audio Stack requests the system to print some Debug Traces thanks to the BLE_AUDIO_PLAT_DbgLog() API. This API shall be implemented in project.
Bluetooth® LE Audio Stack Integration Dependency - Debug/Traces Module |
---|
The BLE Audio Trace BLE_AUDIO_PLAT_DbgLog() API 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 |
2.5. Timer Server
The Bluetooth® LE Audio Stack requires a One-Shot Reference timer on which are multiplexed all the internal BLE Audio SW timers.
The Bluetooth® LE Audio Stack calls the BLE_AUDIO_PLAT_TimerStart() to create the reference timer and start it. When Bluetooth® LE Audio Stack needs to stop the timer, it calls the BLE_AUDIO_PLAT_TimerStop(). The Bluetooth® LE Audio Stack requires to get 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 parameter of the BLE_AUDIO_PLAT_TimerStart() API.
These APIs shall be implemented in the project.
Bluetooth® LE Audio Stack Integration Dependency - Timer Server Module |
---|
The BLE Audio Timer APIs 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 |
2.6. Bare Metal Sequencer / Operation System
The Bluetooth® LE Audio Stack requires registration of a dedicated Task responsible to run the internal BLE Audio Profiles process.
The dedicated Task should call the BLE_AUDIO_STACK_Task() function.
When the BLE Audio Task requests to be executed, the Bluetooth® LE 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 BLE 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.
Bluetooth® LE Audio Stack Integration Dependency - Bare Metal Sequencer / Operation System |
---|
The BLE Audio Stack Sequencer and Initialization APIs 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 |
2.7. Non-Volatile Memory Manager
The Bluetooth® LE Audio Stack requires Non-Volatile Memory services access to manage BLE Audio Databases associated to the ATT services of the BLE Audio Profiles composing the Generic Audio Framework.
The Bluetooth® LE Audio Stack requires functions to read/write/compare/erase information in Non-Volatile Memory. For this, the Bluetooth® LE 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.
In order to retrieve data stored in Non-Volatile Memory dedicated to each profiles included in the Generic Audio Framework, the Bluetooth® LE 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 BLE 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,
};
Bluetooth® LE Audio Stack Integration Dependency - Non-Volatile Memory Manager |
---|
The BLE Audio NVM APIs 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 |
2.8. Advanced Encryption Standard Module
The Coordinated Set Identification profile in the Generic Audio Framework requires access of many Advanced Encryption Standard operation.
For this, the Bluetooth® LE 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.
Bluetooth® LE Audio Stack Integration Dependency - Advanced Encryption Standard Module |
---|
The BLE Audio AES APIs 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 |
2.9. Random Number Generator Module
The Coordinated Set Identification profile in the Generic Audio Framework requires random number access.
For this, the Bluetooth® LE Audio stack calls the BLE_AUDIO_PLAT_RngGet() API.
This API shall be implemented in the project.
Bluetooth® LE Audio Stack Integration Dependency - Random Number Generator Module |
---|
The BLE Audio RNG API 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 |
3. Bluetooth® LE Audio Stack Configuration
The Bluetooth® LE Audio Stack is delivered in an unique library supporting all the roles of Profiles composing the Generic Audio Framework.
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 sub-profiles composing the Generic Audio Framework as shown in the figure below.
For example, the CAP Acceptor role BAP Unicast Server role but never the BAP Unicast Client role.
Generic Audio Framework- "CAP Role /Profiles" Relationship |
---|
Some mechanisms are available to configure the Bluetooth® LE Audio Stack, and so the Generic Audio Framework, for a specific usage as defined in the Use Case Profiles and so fit just required ROM/RAM resource.
3.1. Configuration of the Audio Profiles of the Generic Audio Framework
The Bluetooth® LE Audio Stack Library offers a dynamic configuration way of its internal Audio Profiles.
Each Audio Profile of the Generic Audio Framework in the BLE Audio Library is independently configurable and the RAM required by each Audio profile Context in the Bluetooth® LE Audio Stack to support its specific configuration shall be allocated in application layer according to the configuration settings.
The RAM context allocation and the configuration of each Audio Profiles of the Generic Audio Framework is performed with CAP_Init() function thanks to the following dedicated Audio Profiles 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 structure is composed of :
- configuration setting fields (role, Max Number of BLE Links, specific Audio Profiles settings)
- Settings of the RAM buffer allocated for profile Contexts memory resource
3.1.1. Media Control Profile Configuration Example
The example below describes the field of the Media Control Profile (MCP) Configuration. The MCP_Config_t structure type is defined in the mcp_types.h
In case of the Audio Use Case Profile is based on a CAP Acceptor role supporting 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 connection 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 application layer.
3.1.2. Unicast Server (CAP Acceptor) Configuration Example
The figure below show the fields in the BAP_Config_t structure to configure when Unicast Server feature is activated in CAP Acceptor role. The BAP_Config_t structure type is defined in the bap_types.h
3.1.3. Unicast Client (CAP Initiator) Configuration Example
The figure below show the fields in the BAP_Config_t structure to configure when Unicast Client feature is activated in CAP Initiator role. The BAP_Config_t structure type is defined in the bap_types.h
3.1.4. Broadcast Sink (CAP Acceptor) Configuration Example
The figure below show the fields in the BAP_Config_t structure to configure when Broadcast Sink feature is activated in CAP Acceptor role. The BAP_Config_t structure type is defined in the bap_types.h
3.1.5. Broadcast Source (CAP Initiator) Configuration Example
The figure below show the fields in the BAP_Config_t structure to configure when Broadcast Source feature is activated in CAP Initiator role. The BAP_Config_t structure type is defined in the bap_types.h
3.1.6. Scan Delegator (CAP Acceptor/ CAP Commander) Configuration Example
The figure below show the fields in the BAP_Config_t structure to configure when Scan Delegator feature is activated in CAP Acceptor or CAP Commander role. The BAP_Config_t structure type is defined in the bap_types.h
3.1.7. Broadcast Assistant (CAP Commander) Configuration Example
The figure below show the fields in the BAP_Config_t structure to configure when Broadcast Assistant feature is activated in CAP Commander role. The BAP_Config_t structure type is defined in the bap_types.h
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 application layer according to specified Audio Profile configuration submitted over parameters of CAP_Init() API.
Many MACRO and Constants are defined for each Audio Profile to calculate the required RAM size for context resource to support the specified configuration.
Example – Media Control Profile (mcp_types.h) 2 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 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
Warning:
The values of the parameters of the MACRO shall be equal to the values of the fields submitted in parameter of the Audio Profiles configuration in CAP_Init().
In case of the parameters don't match, the CAP_Init() could fails because the Audio Stack will fail to allocate 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 GATT Server role in the Generic Audio Framework requires GATT Service and GATT Attributes allocation.
These allocations are done through the BleStack_init_t type parameter of the BleStack_Init() API of the BLE Host Stack.
MACRO and Constants are defined for each Audio Profiles 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 Instance which would be registered in 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 Instance and the supported MCP option feature.
3.4. ROM Optimization of the Bluetooth® LE Audio Stack
Because the Bluetooth® LE Audio Stack is delivered in an 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® LE Audio Stack is not used and this memory could not be assigned for application layer implementation.
In order to limit the unused RAM in the Bluetooth® LE Audio Stack, a mechanism, based on weak function concept , has been integrated in the Bluetooth® LE Audio Stack. This mechanism allows to overwrite, in application layer, the functions implemented in the static library which will not be called in a specific use case.
In the Bluetooth® LE Audio Stack , many functions which generate a high ROM allocation for a specific Audio Profile role have been identified and declared as weak function.
In case of the Audio Profile role is not required/supported for the BLE Audio Use Case, the weak function is implemented in application layer as an empty function. By the way, all the ROM allocation generate by the function in the BLE Audio Stack library is removed in the final BLE Audio Use Case implementation.
The figure below shows the weak function defined in the Bluetooth® LE Audio Stack for each role of the Audio Profiles in the Generic Audio Framework.
Example 1
For a BLE Audio Use Case which doesn’t require BAP Unicast Server role, in application layer, the following functions should be overwritten to remove unused code in the BLE Audio Stack Library :
Example 2
For a LE Use Case which doesn’t require MCP Media Control Server role, in application layer, we should implement as following to remove unused code in the BLE Audio Stack Library :
4. Bluetooth® LE 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
4.1. Audio Profiles Linkup
4.1.1. Profiles of Capture and Rendering Control and Audio Stream Transitions
The Generic Audio Framework implements a CAP Linkup procedure, initiated by calling the CAP_Linkup() function, that shall be called by CAP Initiator or CAP Commander to discover/link the audio profiles supported by remote CAP Acceptor / CAP Commander.
The CAP_Linkup() function performs linkup up operation on profile composing the Capture and Rendering Control and/or the Audio Stream Transition according to the supported profiles role of the local audio device :
- Common Audio Profile
- Coordinated Set Identification Profile
- Basic Audio Profile
- Volume Control Profile
- Microphone Control Profile
Functions | Description | Header File |
---|---|---|
CAP_Linkup() | Perform Linkup operation on CAP, CSIP, BAP, VCP, MICP according to supported roles | cap_types.h |
The events CAP_CSI_LINKUP_EVT, CAP_UNICAST_LINKUP_EVT, CAP_BA_LINKUP_EVT and CAP_VOLUME_CTRL_LINKUP_EVT may notified during the CAP linkup procedure depending on the role supported by the local device and the remote device.
The CAP_LINKUP_COMPLETE_EVT event is notified once CAP procedure is complete.
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_VOLUME_CTRL_LINKUP_EVT | Event notified during CAP linkup procedure if CAP Commander supports VCP Volume Controller role and discovers that the remote device supports 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 |
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 CAP Linkup procedure with other CAP Acceptors of the Coordinated Set.
The figure below shows an example of implementation to perform CAP Linkup with all CAP Acceptors of a Coordinated Set.
4.1.2. Profiles of Content Control
The Call Control Profile and Media Control profile linkup is managed by the CAP Acceptor / CAP Commander (in GATT Client role for these profiles) with a remote CAP Initiator.
The CAP Acceptor performs automatic linkup of CCP and MCP during Unicast Audio Start procedure initiated by the remote CAP Initiator. When an Audio Stream Endpoint indicates that a Media Content Control or a Call Content Control is activated/deactivated through the metadata associated to the Audio Stream Endpoint in ENABLING/STREAMING state, the BLE Audio Stack reports CAP events :
Events | Description | Header File |
---|---|---|
CAP_CCP_INST_ACTIVATED_EVT | Event notified when a Telephone Bearer Instance of the Call Control Profile is activated and associated to an Audio Stream. | cap_types.h |
CAP_CCP_INST_DEACTIVATED_EVT | Event notified when a Telephone Bearer Instance of the Call Control Profile is deactivated. | cap_types.h |
CAP_MCP_INST_ACTIVATED_EVT | Event notified when a Media Player Instance of the Media Control Profile is activated and associated to an Audio Stream. | cap_types.h |
CAP_MCP_INST_DEACTIVATED_EVT | Event notified when a Media Player Instance of the Media Control Profile is deactivated. | cap_types.h |
The CAP Acceptor could perform Call Control operation and Media Control Operation on active CCP Instance or MCP Instance thanks to functions declared in ccp.h and mcp.h header files.
4.2. Audio Stream Transition Procedures
The procedure associated to the Audio Stream Transition are specified in the section 7.3.1 of the Common Audio Profile[1]
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 following APIs :
Functions | Description | Header File |
---|---|---|
CAP_Unicast_AudioStart() | Start Unicast Audio with specified CAP Acceptors according Sink/ Source Streams 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 |
The CAP Acceptor supporting Unicast Server role has access to many CAP APIS allowing 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 below describes the functions accessible by the CAP Acceptor in 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 context for reception and transmission. | cap.h |
CAP_SetAvailableAudioContexts() | Set/Update available audio context for reception and transmission. | 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 |
The section 3.5 of the Basic Audio Profile[2] 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 BLE Audio Use Case profile specifies its Audio Capabilities and Audio Channels requirements.
During the Unicast Audio Stream Transitions procedure, the CAP Initiator and the CAP Acceptor will receive CAP events described in table below.
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 specified Audio Stream Endpoint. | X | |
Audio Start | CAP_UNICAST_AUDIO_DATA_PATH_SETUP_REQ_EVT | Audio Data Path setup is requested for specified Audio Stream Endpoint. The CAP_Unicast_SetupAudioDataPath() shall be called to responds to the Audio Data Path Setup Request. |
X | X |
Audio Start | CAP_CODEC_CONFIGURED_EVT | Codec Configuration is Complete for specified Audio Stream Endpoint. This event could be used to configure the Audio Hardware Codec and Audio Peripheral Drivers | 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 [3]'. |
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 [4]'. |
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 doesn't change | X | X |
The figure below 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 setup the Unicast Audio.
In case of a failure occurs during the Unicast Audio Start procedure, the CAP Initiator automatically aborts the procedure in order 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 is notified to upper layer.
The figure below shows the Functions/Events flow during the CAP Unicast Audio Stop Procedure in CAP Initiator and CAP Acceptor side. In this example, a source ASE and a Sink ASE are in Streaming State when the CAP Initiator calls the CAP_Unicast_AudioStop() function.
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 following APIs :
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 |
During the CAP Broadcast Audio procedures, the CAP Initiator is notified, over CAP events, that procedure is complete and the state of Audio Path associated to the Audio Stream has changed. These events notified during the CAP Broadcast Audio procedures are listed in the table below.
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 setup. | cap_types.h |
CAP_BROADCAST_AUDIO_UP_EVT | Event notified when the Audio Path has been removed. | cap_types.h |
The figure below 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 labelled arrows represent the CAP broadcast function, which can cause a transition of the 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 BLE legacy functions and CAP functions to be able to be synchronize 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 below
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 |
During the Broadcast Audio procedure in CAP Acceptor side, many CAP events are notified in application layer resulting to operations started by the CAP Acceptor itself or remote CAP Initiator. These CAP events received in the CAP Acceptor side are listed in the table below
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 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_DOWN_EVT | Notified when Audio Data Path has been setup. | cap_types.h |
CAP_Broadcast_ParseBASEBIS() | Notified when Audio Data Path has been removed. | cap_types.h |
The figure below 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 CAP Acceptor side as shown below.
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[5]
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 volume on the Acceptors of a Coordinated Set acting in the VCP Renderer role. The procedures are initiated by specific CAP functions listed in table below.
Note that the Generic Audio Framework offers Volume Control functions, declared in vcp.h header file, which could be used in application layer to perform operations not specified in 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[6]) | 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[7]) | 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[8]) | cap.h |
(*) Not yet available
During the Volume Control procedures, the CAP Commander will receive Volume Control events defined in vcp_types.h file, and, once the procedure is complete, a dedicated CAP event defined in cap_types.h file. The table below listed the events received by 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 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 |
(*) Not yet available
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 Microphone Controller role to manage volume on the Acceptors of a Coordinated Set acting in the MICP Device role. The procedures are initiated by specific CAP functions listed in table below.
Note that the Generic Audio Framework offers Microphone Control functions, declared in micp.h header file, which could be used in application layer to perform operations not specified in 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[9]) | 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[10]) | cap.h |
During the Microphone Control procedures, the CAP Commander will receive Microphone Control events defined in micp_types.h file, and, once the procedure is complete, a dedicated CAP event defined in cap_types.h file. The table below listed the events received by 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 |
5. References
- ↑ Common Audio profile specification
- ↑ Basic Audio profile specification
- ↑ Audio Stream Control Service specification
- ↑ Audio Stream Control Service specification
- ↑ Common Audio profile specification
- ↑ Common Audio profile specification
- ↑ Common Audio profile specification
- ↑ Common Audio profile specification
- ↑ Common Audio profile specification
- ↑ Common Audio profile specification