Coordinated Set Identification Service (CSIS)

Coordinated Set Identification Service (CSIS) More...

Data Structures
struct	bt_csis_cb
struct	bt_csis_register_param
struct	bt_csis_client_set_info
struct	bt_csis_client_csis_inst
	Struct representing a coordinated set instance on a remote device. More...
struct	bt_csis_client_set_member
struct	bt_csis_client_cb

Macros
#define	CSIS_CLIENT_DISCOVER_TIMER_VALUE   K_SECONDS(10)
#define	BT_CSIS_CLIENT_MAX_CSIS_INSTANCES   0
#define	BT_CSIS_MINIMUM_SET_SIZE   2
#define	BT_CSIS_READ_SIRK_REQ_RSP_ACCEPT   0x00
#define	BT_CSIS_READ_SIRK_REQ_RSP_ACCEPT_ENC   0x01
#define	BT_CSIS_READ_SIRK_REQ_RSP_REJECT   0x02
#define	BT_CSIS_READ_SIRK_REQ_RSP_OOB_ONLY   0x03
#define	BT_CSIS_SET_SIRK_SIZE   16
#define	BT_CSIS_ERROR_LOCK_DENIED   0x80
#define	BT_CSIS_ERROR_LOCK_RELEASE_DENIED   0x81
#define	BT_CSIS_ERROR_LOCK_INVAL_VALUE   0x82
#define	BT_CSIS_ERROR_SIRK_OOB_ONLY   0x83
#define	BT_CSIS_ERROR_LOCK_ALREADY_GRANTED   0x84

Typedefs
typedef void(*	bt_csis_client_discover_cb) (struct bt_csis_client_set_member *member, int err, uint8_t set_count)
	Callback for discovering Coordinated Set Identification Services. More...
typedef void(*	bt_csis_client_lock_set_cb) (int err)
	Callback for locking a set across one or more devices. More...
typedef void(*	bt_csis_client_lock_changed_cb) (struct bt_csis_client_csis_inst *inst, bool locked)
	Callback when the lock value on a set of a connected device changes. More...
typedef void(*	bt_csis_client_lock_state_read_cb) (const struct bt_csis_client_set_info *set_info, int err, bool locked)
	Callback for bt_csis_client_get_lock_state() More...

Functions
void *	bt_csis_svc_decl_get (const struct bt_csis *csis)
	Get the service declaration attribute. More...
int	bt_csis_register (const struct bt_csis_register_param *param, struct bt_csis **csis)
	Register a Coordinated Set Identification Service instance. More...
void	bt_csis_print_sirk (const struct bt_csis *csis)
	Print the SIRK to the debug output. More...
int	bt_csis_advertise (struct bt_csis *csis, bool enable)
	Starts advertising the Resolveable Set Identifier value. More...
int	bt_csis_lock (struct bt_csis *csis, bool lock, bool force)
	Locks a specific Coordinated Set Identification Service instance on the server. More...
int	bt_csis_client_discover (struct bt_csis_client_set_member *member)
	Initialise the csis_client instance for a connection. This will do a discovery on the device and prepare the instance for following commands. More...
bool	bt_csis_client_is_set_member (uint8_t set_sirk[16], struct bt_data *data)
	Check if advertising data indicates a set member. More...
void	bt_csis_client_register_cb (struct bt_csis_client_cb *cb)
	Registers callbacks for csis_client. More...
int	bt_csis_client_get_lock_state (const struct bt_csis_client_set_member **members, uint8_t count, const struct bt_csis_client_set_info *set_info)
	Check if an array of set members are unlocked. More...
int	bt_csis_client_lock (const struct bt_csis_client_set_member **members, uint8_t count, const struct bt_csis_client_set_info *set_info)
	Lock an array of set members. More...
int	bt_csis_client_release (const struct bt_csis_client_set_member **members, uint8_t count, const struct bt_csis_client_set_info *set_info)
	Release an array of set members. More...

Detailed Description

Coordinated Set Identification Service (CSIS)

Copyright (c) 2021 Nordic Semiconductor ASA

SPDX-License-Identifier: Apache-2.0

• [Experimental] Users should note that the APIs can change as a part of ongoing development.

Macro Definition Documentation

BT_CSIS_CLIENT_MAX_CSIS_INSTANCES

#define BT_CSIS_CLIENT_MAX_CSIS_INSTANCES   0

#include <include/bluetooth/audio/csis.h>

BT_CSIS_ERROR_LOCK_ALREADY_GRANTED

#define BT_CSIS_ERROR_LOCK_ALREADY_GRANTED   0x84

#include <include/bluetooth/audio/csis.h>

Client is already owner of the lock

BT_CSIS_ERROR_LOCK_DENIED

#define BT_CSIS_ERROR_LOCK_DENIED   0x80

#include <include/bluetooth/audio/csis.h>

Service is already locked

BT_CSIS_ERROR_LOCK_INVAL_VALUE

#define BT_CSIS_ERROR_LOCK_INVAL_VALUE   0x82

#include <include/bluetooth/audio/csis.h>

Invalid lock value

BT_CSIS_ERROR_LOCK_RELEASE_DENIED

#define BT_CSIS_ERROR_LOCK_RELEASE_DENIED   0x81

#include <include/bluetooth/audio/csis.h>

Service is not locked

BT_CSIS_ERROR_SIRK_OOB_ONLY

#define BT_CSIS_ERROR_SIRK_OOB_ONLY   0x83

#include <include/bluetooth/audio/csis.h>

SIRK only available out-of-band

BT_CSIS_MINIMUM_SET_SIZE

#define BT_CSIS_MINIMUM_SET_SIZE   2

#include <include/bluetooth/audio/csis.h>

Minimum size of a set

BT_CSIS_READ_SIRK_REQ_RSP_ACCEPT

#define BT_CSIS_READ_SIRK_REQ_RSP_ACCEPT   0x00

#include <include/bluetooth/audio/csis.h>

Accept the request to read the SIRK as plaintext

BT_CSIS_READ_SIRK_REQ_RSP_ACCEPT_ENC

#define BT_CSIS_READ_SIRK_REQ_RSP_ACCEPT_ENC   0x01

#include <include/bluetooth/audio/csis.h>

Accept the request to read the SIRK, but return encrypted SIRK

BT_CSIS_READ_SIRK_REQ_RSP_OOB_ONLY

#define BT_CSIS_READ_SIRK_REQ_RSP_OOB_ONLY   0x03

#include <include/bluetooth/audio/csis.h>

SIRK is available only via an OOB procedure

BT_CSIS_READ_SIRK_REQ_RSP_REJECT

#define BT_CSIS_READ_SIRK_REQ_RSP_REJECT   0x02

#include <include/bluetooth/audio/csis.h>

Reject the request to read the SIRK

BT_CSIS_SET_SIRK_SIZE

#define BT_CSIS_SET_SIRK_SIZE   16

#include <include/bluetooth/audio/csis.h>

Size of the Set Identification Resolving Key (SIRK)

CSIS_CLIENT_DISCOVER_TIMER_VALUE

#define CSIS_CLIENT_DISCOVER_TIMER_VALUE   K_SECONDS(10)

#include <include/bluetooth/audio/csis.h>

Recommended timer for member discovery

Typedef Documentation

bt_csis_client_discover_cb

bt_csis_client_discover_cb

#include <include/bluetooth/audio/csis.h>

Callback for discovering Coordinated Set Identification Services.

Parameters

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

bt_csis_client_lock_changed_cb

bt_csis_client_lock_changed_cb

#include <include/bluetooth/audio/csis.h>

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

Parameters

inst	The Coordinated Set Identification Service instance that was changed.
locked	Whether the lock is locked or release.

Returns

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

bt_csis_client_lock_set_cb

bt_csis_client_lock_set_cb

#include <include/bluetooth/audio/csis.h>

Callback for locking a set across one or more devices.

Parameters

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

bt_csis_client_lock_state_read_cb

bt_csis_client_lock_state_read_cb

#include <include/bluetooth/audio/csis.h>

Callback for bt_csis_client_get_lock_state()

If any of the set members supplied to bt_csis_client_get_lock_state() is in the locked state, this will be called with locked true. If any set member is in the locked state, the remaining (if any) won't be read. Likewise, if any error occurs, the procedure will also be aborted.

Parameters

set_info	Pointer to the a specific set_info struct.
err	Error value. 0 on success, GATT error or errno on fail.
locked	Whether the lock is locked or release.

Function Documentation

bt_csis_advertise()

int bt_csis_advertise	(	struct bt_csis *	csis,
		bool	enable
	)

#include <include/bluetooth/audio/csis.h>

Starts advertising the Resolveable Set Identifier value.

This cannot be used with other connectable advertising sets.

Parameters

csis	Pointer to the Coordinated Set Identification Service.
enable	If true start advertising, if false stop advertising

Returns

int 0 if on success, errno on error.

bt_csis_client_discover()

int bt_csis_client_discover

(

struct bt_csis_client_set_member *

member

)

#include <include/bluetooth/audio/csis.h>

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

Parameters

member

Pointer to a set member struct to store discovery results in.

Returns

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

bt_csis_client_get_lock_state()

int bt_csis_client_get_lock_state	(	const struct bt_csis_client_set_member **	members,
		uint8_t	count,
		const struct bt_csis_client_set_info *	set_info
	)

#include <include/bluetooth/audio/csis.h>

Check if an array of set members are unlocked.

This will read the set lock value on all members and respond with a single state.

Parameters

members	Array of set members to check lock state for.
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.

bt_csis_client_is_set_member()

bool bt_csis_client_is_set_member	(	uint8_t	set_sirk[16],
		struct bt_data *	data
	)

#include <include/bluetooth/audio/csis.h>

Check if advertising data indicates a set member.

Parameters

set_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

bt_csis_client_lock()

int bt_csis_client_lock	(	const struct bt_csis_client_set_member **	members,
		uint8_t	count,
		const struct bt_csis_client_set_info *	set_info
	)

#include <include/bluetooth/audio/csis.h>

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.

bt_csis_client_register_cb()

void bt_csis_client_register_cb

(

struct bt_csis_client_cb *

cb

)

#include <include/bluetooth/audio/csis.h>

Registers callbacks for csis_client.

Parameters

cb	Pointer to the callback structure.

bt_csis_client_release()

int bt_csis_client_release	(	const struct bt_csis_client_set_member **	members,
		uint8_t	count,
		const struct bt_csis_client_set_info *	set_info
	)

#include <include/bluetooth/audio/csis.h>

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.

bt_csis_lock()

int bt_csis_lock	(	struct bt_csis *	csis,
		bool	lock,
		bool	force
	)

#include <include/bluetooth/audio/csis.h>

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

Parameters

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

bt_csis_print_sirk()

void bt_csis_print_sirk

(

const struct bt_csis *

csis

)

#include <include/bluetooth/audio/csis.h>

Print the SIRK to the debug output.

Parameters

csis	Pointer to the Coordinated Set Identification Service.

bt_csis_register()

int bt_csis_register	(	const struct bt_csis_register_param *	param,
		struct bt_csis **	csis
	)

#include <include/bluetooth/audio/csis.h>

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.
[out]	csis	Pointer to the registered Coordinated Set Identification Service.

Returns

0 if success, errno on failure.

bt_csis_svc_decl_get()

void * bt_csis_svc_decl_get

(

const struct bt_csis *

csis

)

#include <include/bluetooth/audio/csis.h>

Get the service declaration attribute.

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

Parameters

csis	Pointer to the Coordinated Set Identification Service.

Returns

The first CSIS attribute instance.