1. Introduction
The Bluetooth® LE Audio Coordinated Devices section introduces the Coordinated Set Identification Profile (CSIP).
The CSIP specification[1] and the Coordinated Set Identification Service (CSIS) specification[2] are accessible on the Bluetooth® SIG website.
This profile defines the roles and procedures for managing a group of multiple audio peripheral devices as a single coordinated set. Examples include earbuds, hearing aids, or other devices designed to function together.
As specified in the section 2.2 of the Common Audio Profile [3], the CAP Initiator or CAP Commander can function in the CSIP Set Coordinator role, while the CAP Acceptor can operate in the CSIP Set Member role.
2. Roles
The CSIP defines 2 roles:
- Set Coordinator: This role manages multiple set members and is typically used by central devices.
- Set Member: This role represents a device that is part of the coordinated set. It advertises its identifier and provides a service to share certain values with the coordinator. This role is typically used by peripheral devices.
The Bluetooth® Low Energy audio - STM32WBA Architecture and Integration - Bluetooth® Low Energy audio stack configuration describes how to configure and initialize profiles, such as CSIP, composing the Generic Audio Framework and how to allocate required ROM, RAM and GATT resources. This section introduces an example on how to configure the CSIP to help on the MCP configuration example.
3. Service
The Coordinated Set Member shall have at least one instance of the Coordinated Set Identification Service (CSIS).
The BLE Audio Stack provides two APIs declared in csip.h and cap.h header file to register the Coordinated Set Identification Service(Table 2.1)
| Functions | Description | Header File |
|---|---|---|
| CSIP_SET_MEMBER_RegisterServiceInstance() | Create and register a CSIS Instance | csip.h |
| CAP_RegisterCoordinatedSetMember() | Register the CSIS inside the CAP | cap.h |
The API CSIP_SET_MEMBER_RegisterServiceInstance() should be called to initialize the service. It requires an Instance_ID defined by the application, and a pServiceInfo to configure the service. This pServiceInfo is used to initialize the characteristics below:
- Set Identity Resolving Key (SIRK): Its value and type are defined by the application. Each member of the Set Member shall have the same SIRK to be identified as part of the same Coordinated Set.
- Set Size: The size of the Coordinated Set. The SIRK shall be the same for all members of the Coordinated Set.
- Rank: The rank inside the Coordinated Set. This value shall be unique inside the Coordinated Set.
- Lock: The lock is used to keep exclusive access to clients. It's not defined in pServiceInfo as it is always initialized as unlocked.
After that, the API CAP_RegisterCoordinatedSetMember() should be called to register the CSIS inside the CAP.
The Set Member application needs to call the CAP_BuildAdvPacket() to create its advertising data. The CAP calls CSIP_SET_MEMBER_BuildAdvPacket() to add the CSIS data in the advertising packets. It adds to the advertising data the Resolvable Set Identifier (RSI) generated from the SIRK.
4. Functions
The Table 4.1 lists the Coordinated Set Identification functions supported by the Set Coordinator.
| Functions | Description |
|---|---|
| CAP_StartCoordinatedSetMemberDiscoveryProcedure() | Start the Set Member Discovery Procedure |
| CAP_StopCoordinatedSetMemberDiscoveryProcedure() | Stop the Set Member Discovery Procedure |
| CAP_CSIP_StartLockRequestProcedure() | Start the Lock Request Procedure |
| CAP_CSIP_StartLockReleaseProcedure() | Start the Lock Release Procedure |
| CAP_CSIP_StartOrderedAccessProcedure() | Start the Ordered Access Procedure |
The Table 4.2 lists the Coordinated Set Identification functions supported by the Set Member.
| Functions | Description |
|---|---|
| CAP_CSIP_UpdateSIRK() | Update the SIRK characteristic |
| CAP_CSIP_UpdateSize() | Update the Set Size characteristic |
These procedures are defined in the CSIP specification[1].
4.1. Linkup
The Linkup or Service Discovery operation of the Coordinated Set Identification Profile is initialized by the CAP Initiator or the CAP Commander supporting the Set Coordinator role, thanks to the CAP_Linkup() function. This process is described in section 4.1 Audio profiles linkup of the wiki page Bluetooth® Low Energy audio - STM32WBA Architecture and Integration - Audio profiles linkup.
If the CAP Linkup is successful, and it has found a Coordinated Set Identification Service, the CAP launches the Set Member Discovery Procedure. See section 4.2 below.
4.2. Set Member Discovery Procedure
The Set Member Discovery is a procedure used to find and connect to all set Members within a Coordinated Set.
Figure 4.3 shows an example of an implementation to perform CAP Linkup with all CAP Acceptors of a Coordinated Set.
- Connect, pair and perform CAP linkup with the first Set Member.
- When the CAP linkup process is complete, the CAP_CSI_LINKUP_EVT event (received during the linkup) indicates that the connected CAP Acceptor is part of a Coordinated Set. At this point the Set Member Discovery process and the scan need to be started. Note that the CAP_CSI_LINKUP_EVT provides the size of the Coordinated Set and the rank of the CAP Acceptor.
- During the procedure, if a Set Member of the Coordinated Set in an advertising state is discovered, the CSIP_COO_ADV_REPORT_NEW_SET_MEMBER_DISCOVERED_EVT event is notified. The application should try to connect and pair with this Set Member.
- The procedure automatically launches the CSIP set member discovery process (and checks the SIRK characteristic). The CSIP_COO_NEW_SET_MEMBER_DISCOVERED_EVT event indicates that the discovery process of the remote Set Member is complete. Note that if the SIRK does not match the Coordinated Set, the application should disconnect from this device.
- Repeat the previous two steps to discover all Set Members of the Coordinated Set until the procedure is complete. The application will receive CSIP_COO_SET_MEMBER_DISCOVERY_PROCEDURE_COMPLETE_EVT event, which indicates that all members have been found, the procedure has stopped, or a timeout of 30 seconds has occurred.
- Afterward, the CAP_Linkup() should be performed for each discovered CAP Acceptor once the Set Member discovery procedure is complete.
|
|
|
Figure 4.3 CSIP Set Member Discovery Procedure |
4.3. Lock Procedures
The CSIP defines three APIs to check access to the Set Members : CAP_CSIP_StartLockRequestProcedure(), CAP_CSIP_StartLockReleaseProcedure() and CAP_CSIP_StartOrderedAccessProcedure()
- The Lock Request Procedure changes the Lock characteristic to Locked state for all Set Members, following the order of the Rank characteristic.
- The Lock Release Procedure changes the Lock characteristic to Unlocked state for all Set Members, in the reverse order of the Rank characteristic.
- The Ordered Access Procedure Reads the state of the Lock characteristic for all Set Members, following the order of the Rank characteristic.
These procedures are automatically managed by the CAP to control operations such as BAP, CCP, MCP, MICP, or VCP.
Additionally, they can be used for other application-specific operations. Applications can call these APIs through the CAP to utilize these procedures.
These procedures are designed to minimize the risk of conflict between commands from multiple Set Coordinators involving multiple Set Members. Their status is used to determine whether the access to the Set Members is possible. If the Lock Request Procedure fails, the Lock Release Procedure will be initiated to release all previously locked Set Members during the failed Lock Request attempt. The Ordered Access Procedure should be used if the Set Member is not bonded. If the Procedure fails, the application may wait for the CSIP_COO_LOCK_NOTIFIED_EVT event to retry the operation.
5. Events
The Table 5.1 lists the Coordinated Set Identification events supported by the Coordinated Set Identification Set Coordinator role.
| Functions | Description | Header File |
|---|---|---|
| CAP_CSI_LINKUP_EVT | Event notified to the application through CAP when the CSIS Linkup is finished. | cap_types.h |
| CAP_CSIP_LOCK_REQUEST_PROC_COMPLETE_EVT | Event notified to the application through CAP when the Lock Request Procedure (initiated by the application using CAP_CSIP_StartLockRequestProcedure) completed. The status indicates the result of the procedure. If it fails, the Lock Release Procedure will be automatically initiated, and the CAP_CSIP_LOCK_RELEASE_PROC_COMPLETE_EVT event will be notified afterward. | cap_types.h |
| CAP_CSIP_LOCK_RELEASE_PROC_COMPLETE_EVT | Event notified to the application through CAP when the Lock Release Procedure (initiated by the application using CAP_CSIP_StartLockReleaseProcedure) is finished. Its status indicates the result of this procedure. | cap_types.h |
| CAP_CSIP_ORDERED_ACCESS_PROC_COMPLETE_EVT | Event notified to the application through CAP when the Ordered Access Procedure (initiated by the application using CAP_CSIP_StartOrderedAccessProcedure) is finished. Its status indicates the result of this procedure. | cap_types.h |
| CAP_CSIP_META_EVT | Generic CSIP event notified to the application through CAP. A subevent is associated (defined below) | cap_types.h |
| CSIP_COO_ADV_REPORT_NEW_SET_MEMBER_DISCOVERED_EVT | Event notified to the application through CAP_CSIP_META_EVT when a set member matches the Set Member Discovery Procedure has been found. The application should connect to this Set Member. | csip_types.h |
| CSIP_COO_NEW_SET_MEMBER_DISCOVERED_EVT | Event notified to the application through CAP_CSIP_META_EVT when the Set Member has been connected, paired and linked to the Set Coordinator. If needed, the application can continue the Set Member Discovery Procedure by relaunching the scan (e.g., if there are more than two Set Members). | csip_types.h |
| CSIP_COO_SET_MEMBER_DISCOVERY_PROCEDURE_COMPLETE_EVT | Event notified to the application through CAP_CSIP_META_EVT when the entire Set Member Discovery Procedure is finished. Depending on the status, it may either fail due to a timeout (30 seconds) or succeed if all Set Members have been discovered. | csip_types.h |
| CSIP_COO_LOCKED_EVT | Event notified to the application through CAP_CSIP_META_EVT when a Set Member is successfully locked. If unsuccessful, the status indicates the reason for the failure. | csip_types.h |
| CSIP_COO_LOCKED_COMPLETE_EVT | Event notified to the application through CAP_CSIP_META_EVT when the Lock Request Procedure has been completed for all Set Members. | csip_types.h |
| CSIP_COO_UNLOCKED_EVT | Event notified to the application through CAP_CSIP_META_EVT when a Set Member is successfully locked. If unsuccessful, the status indicates the reason for the failure. | csip_types.h |
| CSIP_COO_UNLOCKED_COMPLETE_EVT | Event notified to the application through CAP_CSIP_META_EVT when the Lock Release Procedure has been completed for all Set Members. | csip_types.h |
| CSIP_COO_ORDERED_ACCESS_COMPLETE_EVT | Event notified to the application through CAP_CSIP_META_EVT when the Ordered Access Procedure is complete. The status indicates the result of the procedure. | csip_types.h |
| CSIP_COO_LOCK_NOTIFIED_EVT | Event notified to the application through CAP_CSIP_META_EVT when the Lock characteristic of one Set Member changes. It can be used to retry an operation that previously failed because the Set Member was locked by another Set Coordinator. | csip_types.h |
| CSIP_COO_SIRK_NOTIFIED_EVT | Event notified to the application through CAP_CSIP_META_EVT when the SIRK characteristic of one Set Member changes. | csip_types.h |
| CSIP_COO_SET_SIZE_NOTIFIED_EVT | Event notified to the application through CAP_CSIP_META_EVT when the Set Size characteristic of one Set Member changes. | csip_types.h |
The Table 5.2 lists the Coordinated Set Identification events supported by the Coordinated Set Identification Set Member role.
| Functions | Description | Header File |
|---|---|---|
| CAP_CSIP_META_EVT | Generic CSIP event notified to the application through CAP. A subevent is associated (defined below) | cap_types.h |
| CSIP_MEM_LOCKED_EVT | Event notified to the application through CAP_CSIP_META_EVT when the CSIP Set Member is locked by a Set Coordinator by the Lock Request Procedure | csip_types.h |
| CSIP_MEM_UNLOCKED_EVT | Event notified to the application through CAP_CSIP_META_EVT when the CSIP Set Member is unlocked by a Set Coordinator by the Lock Release Procedure | csip_types.h |
6. References