Bluetooth Coordinated Sets

API Reference

group bt_gatt_csip

Coordinated Set Identification Profile (CSIP)

Published Audio Capabilities Service (PACS)

The Coordinated Set Identification Profile (CSIP) provides procedures to discover and coordinate sets of devices.

Since: 3.0
Version: 0.8.0

The Published Audio Capabilities Service (PACS) is used to expose capabilities to remote devices.

Since: 3.0
Version: 0.8.0

Defines

BT_CSIP_SET_COORDINATOR_DISCOVER_TIMER_VALUE: Recommended timer for member discovery.

BT_CSIP_SET_COORDINATOR_MAX_CSIS_INSTANCES: Defines the maximum number of Coordinated Set Identification service instances for the Coordinated Set Identification Set Coordinator.

BT_CSIP_READ_SIRK_REQ_RSP_ACCEPT: Accept the request to read the SIRK as plaintext.

BT_CSIP_READ_SIRK_REQ_RSP_ACCEPT_ENC: Accept the request to read the SIRK, but return encrypted SIRK.

BT_CSIP_READ_SIRK_REQ_RSP_REJECT: Reject the request to read the SIRK.

BT_CSIP_READ_SIRK_REQ_RSP_OOB_ONLY: SIRK is available only via an OOB procedure.

BT_CSIP_SIRK_SIZE: Size of the Set Identification Resolving Key (SIRK)

BT_CSIP_RSI_SIZE: Size of the Resolvable Set Identifier (RSI)

BT_CSIP_ERROR_LOCK_DENIED: Service is already locked.

BT_CSIP_ERROR_LOCK_RELEASE_DENIED: Service is not locked.

BT_CSIP_ERROR_LOCK_INVAL_VALUE: Invalid lock value.

BT_CSIP_ERROR_SIRK_OOB_ONLY: SIRK only available out-of-band.

BT_CSIP_ERROR_LOCK_ALREADY_GRANTED: Client is already owner of the lock.

BT_CSIP_DATA_RSI(_rsi)

Helper to declare bt_data array including RSI.

This macro is mainly for creating an array of struct bt_data elements which is then passed to e.g. bt_le_ext_adv_start().

Parameters:

_rsi – Pointer to the RSI value

Typedefs

typedef void (*bt_csip_set_coordinator_discover_cb)(struct bt_conn *conn, const struct bt_csip_set_coordinator_set_member *member, int err, size_t set_count)

Callback for discovering Coordinated Set Identification Services.

Param conn:: Pointer to the remote device.
Param member:: Pointer to the set member.
Param err:: 0 on success, or an errno value on error.
Param set_count:: Number of sets on the member.

typedef void (*bt_csip_set_coordinator_lock_set_cb)(int err)

Callback for locking a set across one or more devices.

Param err:: 0 on success, or an errno value on error.

typedef void (*bt_csip_set_coordinator_lock_changed_cb)(struct bt_csip_set_coordinator_csis_inst *inst, bool locked)

Callback when the lock value on a set of a connected device changes.

Param inst:: The Coordinated Set Identification Service instance that was changed.
Param locked:: Whether the lock is locked or release.
Return:: int Return 0 on success, or an errno value on error.

typedef void (*bt_csip_set_coordinator_sirk_changed_cb)(struct bt_csip_set_coordinator_csis_inst *inst)

Callback when the SIRK value of a set of a connected device changes.

Param inst:: The Coordinated Set Identification Service instance that was changed. The new SIRK can be accessed via the inst.info.

typedef void (*bt_csip_set_coordinator_ordered_access_cb_t)(const struct bt_csip_set_coordinator_set_info *set_info, int err, bool locked, struct bt_csip_set_coordinator_set_member *member)

Callback for bt_csip_set_coordinator_ordered_access()

If any of the set members supplied to bt_csip_set_coordinator_ordered_access() is in the locked state, this will be called with locked true and member will be the locked member, and the ordered access procedure is cancelled. Likewise, if any error occurs, the procedure will also be aborted.

Param set_info:: Pointer to the a specific set_info struct.
Param err:: Error value. 0 on success, GATT error or errno on fail.
Param locked:: Whether the lock is locked or release.
Param member:: The locked member if locked is true, otherwise NULL.

typedef bool (*bt_csip_set_coordinator_ordered_access_t)(const struct bt_csip_set_coordinator_set_info *set_info, struct bt_csip_set_coordinator_set_member *members[], size_t count)

Callback function definition for bt_csip_set_coordinator_ordered_access()

Param set_info:: Pointer to the a specific set_info struct.
Param members:: Array of members ordered by rank. The procedure shall be done on the members in ascending order.
Param count:: Number of members in members.
Return:: true if the procedures can be successfully done, or false to stop the procedure.

typedef bool (*bt_pacs_cap_foreach_func_t)(const struct bt_pacs_cap *cap, void *user_data)

Published Audio Capability iterator callback.

Param cap:: Capability found.
Param user_data:: Data given.
Return:: true to continue to the next capability
Return:: false to stop the iteration

Functions

void *bt_csip_set_member_svc_decl_get(const struct bt_csip_set_member_svc_inst *svc_inst)

Get the service declaration attribute.

The first service attribute can be included in any other GATT service.

Parameters:

svc_inst – Pointer to the Coordinated Set Identification Service.

Returns:

The first CSIS attribute instance.

int bt_csip_set_member_register(const struct bt_csip_set_member_register_param *param, struct bt_csip_set_member_svc_inst **svc_inst)

Register a Coordinated Set Identification Service instance.

This will register and enable the service and make it discoverable by clients.

This shall only be done as a server.

Parameters:

param – Coordinated Set Identification Service register parameters.
svc_inst – [out] Pointer to the registered Coordinated Set Identification Service.

Returns:

0 if success, errno on failure.

int bt_csip_set_member_unregister(struct bt_csip_set_member_svc_inst *svc_inst)

Unregister a Coordinated Set Identification Service instance.

This will unregister and disable the service instance.

Parameters:

svc_inst – Pointer to the registered Coordinated Set Identification Service.

Returns:

0 if success, errno on failure.

int bt_csip_set_member_sirk(struct bt_csip_set_member_svc_inst *svc_inst, const uint8_t sirk[16])

Set the SIRK of a service instance.

Parameters:

svc_inst – Pointer to the registered Coordinated Set Identification Service.
sirk – The new SIRK.

int bt_csip_set_member_get_sirk(struct bt_csip_set_member_svc_inst *svc_inst, uint8_t sirk[16])

Get the SIRK of a service instance.

Parameters:

svc_inst – [in] Pointer to the registered Coordinated Set Identification Service.
sirk – [out] Array to store the SIRK in.

int bt_csip_set_member_generate_rsi(const struct bt_csip_set_member_svc_inst *svc_inst, uint8_t rsi[6])

Generate the Resolvable Set Identifier (RSI) value.

This will generate RSI for given svc_inst instance.

Parameters:

svc_inst – Pointer to the Coordinated Set Identification Service.
rsi – Pointer to the 6-octet newly generated RSI data in little-endian.

Returns:

int 0 if on success, errno on error.

int bt_csip_set_member_lock(struct bt_csip_set_member_svc_inst *svc_inst, bool lock, bool force)

Locks a specific Coordinated Set Identification Service instance on the server.

Parameters:

svc_inst – Pointer to the Coordinated Set Identification Service.
lock – If true lock the set, if false release the set.
force – This argument only have meaning when lock is false (release) and will force release the lock, regardless of who took the lock.

Returns:

0 on success, GATT error on error.

int bt_csip_set_coordinator_discover(struct bt_conn *conn)

Initialise the csip_set_coordinator instance for a connection.

This will do a discovery on the device and prepare the instance for following commands.

Parameters:

conn – Pointer to remote device to perform discovery on.

Returns:

int Return 0 on success, or an errno value on error.

struct bt_csip_set_coordinator_set_member *bt_csip_set_coordinator_set_member_by_conn(const struct bt_conn *conn)

Get the set member from a connection pointer.

Get the Coordinated Set Identification Profile Set Coordinator pointer from a connection pointer. Only Set Coordinators that have been initiated via bt_csip_set_coordinator_discover() can be retrieved.

Parameters:

conn – Connection pointer.

Return values:

Pointer – to a Coordinated Set Identification Profile Set Coordinator instance
NULL – if conn is NULL or if the connection has not done discovery yet

bool bt_csip_set_coordinator_is_set_member(const uint8_t sirk[16], struct bt_data *data)

Check if advertising data indicates a set member.

Parameters:

sirk – The SIRK of the set to check against
data – The advertising data

Returns:

true if the advertising data indicates a set member, false otherwise

int bt_csip_set_coordinator_register_cb(struct bt_csip_set_coordinator_cb *cb)

Registers callbacks for csip_set_coordinator.

Parameters:

cb – Pointer to the callback structure.

Returns:

Return 0 on success, or an errno value on error.

int bt_csip_set_coordinator_ordered_access(const struct bt_csip_set_coordinator_set_member *members[], uint8_t count, const struct bt_csip_set_coordinator_set_info *set_info, bt_csip_set_coordinator_ordered_access_t cb)

Access Coordinated Set devices in an ordered manner as a client.

This function will read the lock state of all devices and if all devices are in the unlocked state, then cb will be called with the same members as provided by members, but where the members are ordered by rank (if present). Once this procedure is finished or an error occurs, bt_csip_set_coordinator_cb::ordered_access will be called.

This procedure only works if all the members have the lock characteristic, and all either has rank = 0 or unique ranks.

If any of the members are in the locked state, the procedure will be cancelled.

This can only be done on members that are bonded.

Parameters:

members – Array of set members to access.
count – Number of set members in members.
set_info – Pointer to the a specific set_info struct, as a member may be part of multiple sets.
cb – The callback function to be called for each member.

int bt_csip_set_coordinator_lock(const struct bt_csip_set_coordinator_set_member **members, uint8_t count, const struct bt_csip_set_coordinator_set_info *set_info)

Lock an array of set members.

The members will be locked starting from lowest rank going up.

TODO: If locking fails, the already locked members will not be unlocked.

Parameters:

members – Array of set members to lock.
count – Number of set members in members.
set_info – Pointer to the a specific set_info struct, as a member may be part of multiple sets.

Returns:

Return 0 on success, or an errno value on error.

int bt_csip_set_coordinator_release(const struct bt_csip_set_coordinator_set_member **members, uint8_t count, const struct bt_csip_set_coordinator_set_info *set_info)

Release an array of set members.

The members will be released starting from highest rank going down.

Parameters:

members – Array of set members to lock.
count – Number of set members in members.
set_info – Pointer to the a specific set_info struct, as a member may be part of multiple sets.

Returns:

Return 0 on success, or an errno value on error.

void bt_pacs_cap_foreach(enum bt_audio_dir dir, bt_pacs_cap_foreach_func_t func, void *user_data)

Published Audio Capability iterator.

Iterate capabilities with endpoint direction specified.

Parameters:

dir – Direction of the endpoint to look capability for.
func – Callback function.
user_data – Data to pass to the callback.

int bt_pacs_cap_register(enum bt_audio_dir dir, struct bt_pacs_cap *cap)

Register Published Audio Capability.

Register Audio Local Capability.

Parameters:

dir – Direction of the endpoint to register capability for.
cap – Capability structure.

Returns:

0 in case of success or negative value in case of error.

int bt_pacs_cap_unregister(enum bt_audio_dir dir, struct bt_pacs_cap *cap)

Unregister Published Audio Capability.

Unregister Audio Local Capability.

Parameters:

dir – Direction of the endpoint to unregister capability for.
cap – Capability structure.

Returns:

0 in case of success or negative value in case of error.

int bt_pacs_set_location(enum bt_audio_dir dir, enum bt_audio_location location)

Set the location for an endpoint type.

Parameters:

dir – Direction of the endpoints to change location for.
location – The location to be set.

Returns:

0 in case of success or negative value in case of error.

int bt_pacs_set_available_contexts(enum bt_audio_dir dir, enum bt_audio_context contexts)

Set the available contexts for an endpoint type.

Parameters:

dir – Direction of the endpoints to change available contexts for.
contexts – The contexts to be set.

Returns:

0 in case of success or negative value in case of error.

enum bt_audio_context bt_pacs_get_available_contexts(enum bt_audio_dir dir)

Get the available contexts for an endpoint type.

Parameters:

dir – Direction of the endpoints to get contexts for.

Returns:

Bitmask of available contexts.

int bt_pacs_conn_set_available_contexts_for_conn(struct bt_conn *conn, enum bt_audio_dir dir, enum bt_audio_context *contexts)

Set the available contexts for a given connection.

This function sets the available contexts value for a given conn connection object. If the contexts parameter is NULL the available contexts value is reset to default. The default value of the available contexts is set using bt_pacs_set_available_contexts function. The Available Context Value is reset to default on ACL disconnection.

Parameters:

conn – Connection object.
dir – Direction of the endpoints to change available contexts for.
contexts – The contexts to be set or NULL to reset to default.

Returns:

0 in case of success or negative value in case of error.

enum bt_audio_context bt_pacs_get_available_contexts_for_conn(struct bt_conn *conn, enum bt_audio_dir dir)

Get the available contexts for a given connection.

This server function returns the available contexts value for a given conn connection object. The value returned is the one set with bt_pacs_conn_set_available_contexts_for_conn function or the default value set with bt_pacs_set_available_contexts function.

Parameters:

conn – Connection object.
dir – Direction of the endpoints to get contexts for.

Return values:

BT_AUDIO_CONTEXT_TYPE_PROHIBITED – if conn or dir are invalid

Returns:

Bitmask of available contexts.

int bt_pacs_set_supported_contexts(enum bt_audio_dir dir, enum bt_audio_context contexts)

Set the supported contexts for an endpoint type.

Parameters:

dir – Direction of the endpoints to change available contexts for.
contexts – The contexts to be set.

Returns:

0 in case of success or negative value in case of error.

struct bt_csip_set_member_cb

#include <csip.h>

Callback structure for the Coordinated Set Identification Service.

Public Members

void (*lock_changed)(struct bt_conn *conn, struct bt_csip_set_member_svc_inst *svc_inst, bool locked)

Callback whenever the lock changes on the server.

Param conn:: The connection to the client that changed the lock. NULL if server changed it, either by calling bt_csip_set_member_lock() or by timeout.
Param svc_inst:: Pointer to the Coordinated Set Identification Service.
Param locked:: Whether the lock was locked or released.

uint8_t (*sirk_read_req)(struct bt_conn *conn, struct bt_csip_set_member_svc_inst *svc_inst)

Request from a peer device to read the sirk.

If this callback is not set, all clients will be allowed to read the SIRK unencrypted.

Param conn:: The connection to the client that requested to read the SIRK.
Param svc_inst:: Pointer to the Coordinated Set Identification Service.
Return:: A BT_CSIP_READ_SIRK_REQ_RSP_* response code.

struct bt_csip_set_member_register_param

#include <csip.h>

Register structure for Coordinated Set Identification Service.

Public Members

uint8_t set_size

Size of the set.

If set to 0, the set size characteristic won’t be initialized.

uint8_t sirk[16]

The unique Set Identity Resolving Key (SIRK)

This shall be unique between different sets, and shall be the same for each set member for each set.

bool lockable

Boolean to set whether the set is lockable by clients.

Setting this to false will disable the lock characteristic.

uint8_t rank

Rank of this device in this set.

If the lockable parameter is set to true, this shall be > 0 and <= to the set_size. If the lockable parameter is set to false, this may be set to 0 to disable the rank characteristic.

struct bt_csip_set_member_cb *cb: Pointer to the callback structure.

const struct bt_gatt_service *parent

Parent service pointer.

Mandatory parent service pointer if this CSIS instance is included by another service. All CSIS instances when CONFIG_BT_CSIP_SET_MEMBER_MAX_INSTANCE_COUNT is above 1 shall be included by another service, as per the Coordinated Set Identification Profile (CSIP).

struct bt_csip_set_coordinator_set_info

#include <csip.h>

Information about a specific set.

Public Members

uint8_t sirk[16]

The 16 octet set Set Identity Resolving Key (SIRK)

The SIRK may not be exposed by the server over Bluetooth, and may require an out-of-band solution.

uint8_t set_size

The size of the set.

Will be 0 if not exposed by the server.

uint8_t rank

The rank of the set on the remote device.

Will be 0 if not exposed by the server.

bool lockable: Whether or not the set can be locked on this device.

struct bt_csip_set_coordinator_csis_inst

#include <csip.h>

Struct representing a coordinated set instance on a remote device.

The values in this struct will be populated during discovery of sets (bt_csip_set_coordinator_discover()).

Public Members

struct bt_csip_set_coordinator_set_info info: Information about the coordinated set.

void *svc_inst: Internally used pointer value.

struct bt_csip_set_coordinator_set_member

#include <csip.h>

Struct representing a remote device as a set member.

Public Members

struct bt_csip_set_coordinator_csis_inst insts[0]: Array of Coordinated Set Identification Service instances for the remote device.

struct bt_csip_set_coordinator_cb

#include <csip.h>

Struct to hold the Coordinated Set Identification Profile Set Coordinator callbacks.

These can be registered for usage with bt_csip_set_coordinator_register_cb().

Public Members

bt_csip_set_coordinator_discover_cb discover: Callback when discovery has finished.

bt_csip_set_coordinator_lock_set_cb lock_set: Callback when locking a set has finished.

bt_csip_set_coordinator_lock_set_cb release_set: Callback when unlocking a set has finished.

bt_csip_set_coordinator_lock_changed_cb lock_changed: Callback when a set’s lock state has changed.

bt_csip_set_coordinator_sirk_changed_cb sirk_changed: Callback when a set’s SIRK has changed.

bt_csip_set_coordinator_ordered_access_cb_t ordered_access: Callback for the ordered access procedure.

struct bt_pacs_cap

#include <pacs.h>

Published Audio Capability structure.

Public Members

const struct bt_audio_codec_cap *codec_cap: Codec capability reference.