Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Coordinated Set Identification Profile (CSIP)

Copyright (c) 2021-2022 Nordic Semiconductor ASA. More...

Data Structures

struct  bt_csip_set_member_cb
 Callback structure for the Coordinated Set Identification Service. More...
 
struct  bt_csip_set_member_register_param
 Register structure for Coordinated Set Identification Service. More...
 
struct  bt_csip_set_coordinator_set_info
 Information about a specific set. More...
 
struct  bt_csip_set_coordinator_csis_inst
 Struct representing a coordinated set instance on a remote device. More...
 
struct  bt_csip_set_coordinator_set_member
 Struct representing a remote device as a set member. More...
 
struct  bt_csip_set_coordinator_cb
 

Macros

#define BT_CSIP_SET_COORDINATOR_DISCOVER_TIMER_VALUE   K_SECONDS(10)
 Recommended timer for member discovery.
 
#define BT_CSIP_SET_COORDINATOR_MAX_CSIS_INSTANCES   0
 
#define BT_CSIP_READ_SIRK_REQ_RSP_ACCEPT   0x00
 Accept the request to read the SIRK as plaintext.
 
#define BT_CSIP_READ_SIRK_REQ_RSP_ACCEPT_ENC   0x01
 Accept the request to read the SIRK, but return encrypted SIRK.
 
#define BT_CSIP_READ_SIRK_REQ_RSP_REJECT   0x02
 Reject the request to read the SIRK.
 
#define BT_CSIP_READ_SIRK_REQ_RSP_OOB_ONLY   0x03
 SIRK is available only via an OOB procedure.
 
#define BT_CSIP_SET_SIRK_SIZE   16
 Size of the Set Identification Resolving Key (SIRK)
 
#define BT_CSIP_RSI_SIZE   6
 Size of the Resolvable Set Identifier (RSI)
 
#define BT_CSIP_ERROR_LOCK_DENIED   0x80
 Service is already locked.
 
#define BT_CSIP_ERROR_LOCK_RELEASE_DENIED   0x81
 Service is not locked.
 
#define BT_CSIP_ERROR_LOCK_INVAL_VALUE   0x82
 Invalid lock value.
 
#define BT_CSIP_ERROR_SIRK_OOB_ONLY   0x83
 SIRK only available out-of-band.
 
#define BT_CSIP_ERROR_LOCK_ALREADY_GRANTED   0x84
 Client is already owner of the lock.
 
#define BT_CSIP_DATA_RSI(_rsi)   BT_DATA(BT_DATA_CSIS_RSI, _rsi, BT_CSIP_RSI_SIZE)
 Helper to declare bt_data array including RSI.
 

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.
 
typedef void(* bt_csip_set_coordinator_lock_set_cb) (int err)
 Callback for locking a set across one or more devices.
 
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.
 
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.
 
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()
 
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()
 

Functions

void * bt_csip_set_member_svc_decl_get (const struct bt_csip_set_member_svc_inst *svc_inst)
 Get the service declaration attribute.
 
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.
 
int bt_csip_set_member_unregister (struct bt_csip_set_member_svc_inst *svc_inst)
 Unregister a Coordinated Set Identification Service instance.
 
int bt_csip_set_member_set_sirk (struct bt_csip_set_member_svc_inst *svc_inst, const uint8_t sirk[16])
 Set the SIRK of a service instance.
 
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.
 
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.
 
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.
 
int bt_csip_set_coordinator_discover (struct bt_conn *conn)
 Initialise the csip_set_coordinator instance for a connection.
 
bool bt_csip_set_coordinator_is_set_member (const uint8_t set_sirk[16], struct bt_data *data)
 Check if advertising data indicates a set member.
 
int bt_csip_set_coordinator_register_cb (struct bt_csip_set_coordinator_cb *cb)
 Registers callbacks for csip_set_coordinator.
 
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.
 
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.
 
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.
 

Detailed Description

Copyright (c) 2021-2022 Nordic Semiconductor ASA.

SPDX-License-Identifier: Apache-2.0

Coordinated Set Identification Profile (CSIP)

Since
3.0
Version
0.8.0

Macro Definition Documentation

◆ BT_CSIP_DATA_RSI

#define BT_CSIP_DATA_RSI (   _rsi)    BT_DATA(BT_DATA_CSIS_RSI, _rsi, BT_CSIP_RSI_SIZE)

#include <zephyr/bluetooth/audio/csip.h>

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
_rsiPointer to the RSI value

◆ BT_CSIP_ERROR_LOCK_ALREADY_GRANTED

#define BT_CSIP_ERROR_LOCK_ALREADY_GRANTED   0x84

#include <zephyr/bluetooth/audio/csip.h>

Client is already owner of the lock.

◆ BT_CSIP_ERROR_LOCK_DENIED

#define BT_CSIP_ERROR_LOCK_DENIED   0x80

#include <zephyr/bluetooth/audio/csip.h>

Service is already locked.

◆ BT_CSIP_ERROR_LOCK_INVAL_VALUE

#define BT_CSIP_ERROR_LOCK_INVAL_VALUE   0x82

#include <zephyr/bluetooth/audio/csip.h>

Invalid lock value.

◆ BT_CSIP_ERROR_LOCK_RELEASE_DENIED

#define BT_CSIP_ERROR_LOCK_RELEASE_DENIED   0x81

#include <zephyr/bluetooth/audio/csip.h>

Service is not locked.

◆ BT_CSIP_ERROR_SIRK_OOB_ONLY

#define BT_CSIP_ERROR_SIRK_OOB_ONLY   0x83

#include <zephyr/bluetooth/audio/csip.h>

SIRK only available out-of-band.

◆ BT_CSIP_READ_SIRK_REQ_RSP_ACCEPT

#define BT_CSIP_READ_SIRK_REQ_RSP_ACCEPT   0x00

#include <zephyr/bluetooth/audio/csip.h>

Accept the request to read the SIRK as plaintext.

◆ BT_CSIP_READ_SIRK_REQ_RSP_ACCEPT_ENC

#define BT_CSIP_READ_SIRK_REQ_RSP_ACCEPT_ENC   0x01

#include <zephyr/bluetooth/audio/csip.h>

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

◆ BT_CSIP_READ_SIRK_REQ_RSP_OOB_ONLY

#define BT_CSIP_READ_SIRK_REQ_RSP_OOB_ONLY   0x03

#include <zephyr/bluetooth/audio/csip.h>

SIRK is available only via an OOB procedure.

◆ BT_CSIP_READ_SIRK_REQ_RSP_REJECT

#define BT_CSIP_READ_SIRK_REQ_RSP_REJECT   0x02

#include <zephyr/bluetooth/audio/csip.h>

Reject the request to read the SIRK.

◆ BT_CSIP_RSI_SIZE

#define BT_CSIP_RSI_SIZE   6

#include <zephyr/bluetooth/audio/csip.h>

Size of the Resolvable Set Identifier (RSI)

◆ BT_CSIP_SET_COORDINATOR_DISCOVER_TIMER_VALUE

#define BT_CSIP_SET_COORDINATOR_DISCOVER_TIMER_VALUE   K_SECONDS(10)

#include <zephyr/bluetooth/audio/csip.h>

Recommended timer for member discovery.

◆ BT_CSIP_SET_COORDINATOR_MAX_CSIS_INSTANCES

#define BT_CSIP_SET_COORDINATOR_MAX_CSIS_INSTANCES   0

◆ BT_CSIP_SET_SIRK_SIZE

#define BT_CSIP_SET_SIRK_SIZE   16

#include <zephyr/bluetooth/audio/csip.h>

Size of the Set Identification Resolving Key (SIRK)

Typedef Documentation

◆ bt_csip_set_coordinator_discover_cb

bt_csip_set_coordinator_discover_cb

#include <zephyr/bluetooth/audio/csip.h>

Callback for discovering Coordinated Set Identification Services.

Parameters
connPointer to the remote device.
memberPointer to the set member.
err0 on success, or an errno value on error.
set_countNumber of sets on the member.

◆ bt_csip_set_coordinator_lock_changed_cb

bt_csip_set_coordinator_lock_changed_cb

#include <zephyr/bluetooth/audio/csip.h>

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

Parameters
instThe Coordinated Set Identification Service instance that was changed.
lockedWhether the lock is locked or release.
Returns
int Return 0 on success, or an errno value on error.

◆ bt_csip_set_coordinator_lock_set_cb

bt_csip_set_coordinator_lock_set_cb

#include <zephyr/bluetooth/audio/csip.h>

Callback for locking a set across one or more devices.

Parameters
err0 on success, or an errno value on error.

◆ bt_csip_set_coordinator_ordered_access_cb_t

bt_csip_set_coordinator_ordered_access_cb_t

#include <zephyr/bluetooth/audio/csip.h>

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.

Parameters
set_infoPointer to the a specific set_info struct.
errError value. 0 on success, GATT error or errno on fail.
lockedWhether the lock is locked or release.
memberThe locked member if locked is true, otherwise NULL.

◆ bt_csip_set_coordinator_ordered_access_t

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)

#include <zephyr/bluetooth/audio/csip.h>

Callback function definition for bt_csip_set_coordinator_ordered_access()

Parameters
set_infoPointer to the a specific set_info struct.
membersArray of members ordered by rank. The procedure shall be done on the members in ascending order.
countNumber of members in members.
Returns
true if the procedures can be successfully done, or false to stop the procedure.

◆ bt_csip_set_coordinator_sirk_changed_cb

bt_csip_set_coordinator_sirk_changed_cb

#include <zephyr/bluetooth/audio/csip.h>

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

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

Function Documentation

◆ bt_csip_set_coordinator_discover()

int bt_csip_set_coordinator_discover ( struct bt_conn *  conn)

#include <zephyr/bluetooth/audio/csip.h>

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
connPointer to remote device to perform discovery on.
Returns
int Return 0 on success, or an errno value on error.

◆ bt_csip_set_coordinator_is_set_member()

bool bt_csip_set_coordinator_is_set_member ( const uint8_t  set_sirk[16],
struct bt_data data 
)

#include <zephyr/bluetooth/audio/csip.h>

Check if advertising data indicates a set member.

Parameters
set_sirkThe SIRK of the set to check against
dataThe advertising data
Returns
true if the advertising data indicates a set member, false otherwise

◆ bt_csip_set_coordinator_lock()

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 
)

#include <zephyr/bluetooth/audio/csip.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
membersArray of set members to lock.
countNumber of set members in members.
set_infoPointer 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_csip_set_coordinator_ordered_access()

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 
)

#include <zephyr/bluetooth/audio/csip.h>

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 characterstic, 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
membersArray of set members to access.
countNumber of set members in members.
set_infoPointer to the a specific set_info struct, as a member may be part of multiple sets.
cbThe callback function to be called for each member.

◆ bt_csip_set_coordinator_register_cb()

int bt_csip_set_coordinator_register_cb ( struct bt_csip_set_coordinator_cb cb)

#include <zephyr/bluetooth/audio/csip.h>

Registers callbacks for csip_set_coordinator.

Parameters
cbPointer to the callback structure.
Returns
Return 0 on success, or an errno value on error.

◆ bt_csip_set_coordinator_release()

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 
)

#include <zephyr/bluetooth/audio/csip.h>

Release an array of set members.

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

Parameters
membersArray of set members to lock.
countNumber of set members in members.
set_infoPointer 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_csip_set_member_generate_rsi()

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

#include <zephyr/bluetooth/audio/csip.h>

Generate the Resolvable Set Identifier (RSI) value.

This will generate RSI for given svc_inst instance.

Parameters
svc_instPointer to the Coordinated Set Identification Service.
rsiPointer to the 6-octet newly generated RSI data in little-endian.
Returns
int 0 if on success, errno on error.

◆ bt_csip_set_member_get_sirk()

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

#include <zephyr/bluetooth/audio/csip.h>

Get the SIRK of a service instance.

Parameters
[in]svc_instPointer to the registered Coordinated Set Identification Service.
[out]sirkArray to store the SIRK in.

◆ bt_csip_set_member_lock()

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

#include <zephyr/bluetooth/audio/csip.h>

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

Parameters
svc_instPointer to the Coordinated Set Identification Service.
lockIf true lock the set, if false release the set.
forceThis 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_csip_set_member_register()

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

#include <zephyr/bluetooth/audio/csip.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
paramCoordinated Set Identification Service register parameters.
[out]svc_instPointer to the registered Coordinated Set Identification Service.
Returns
0 if success, errno on failure.

◆ bt_csip_set_member_set_sirk()

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

#include <zephyr/bluetooth/audio/csip.h>

Set the SIRK of a service instance.

Parameters
svc_instPointer to the registered Coordinated Set Identification Service.
sirkThe new SIRK.

◆ bt_csip_set_member_svc_decl_get()

void * bt_csip_set_member_svc_decl_get ( const struct bt_csip_set_member_svc_inst *  svc_inst)

#include <zephyr/bluetooth/audio/csip.h>

Get the service declaration attribute.

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

Parameters
svc_instPointer to the Coordinated Set Identification Service.
Returns
The first CSIS attribute instance.

◆ bt_csip_set_member_unregister()

int bt_csip_set_member_unregister ( struct bt_csip_set_member_svc_inst *  svc_inst)

#include <zephyr/bluetooth/audio/csip.h>

Unregister a Coordinated Set Identification Service instance.

This will unregister and disable the service instance.

Parameters
svc_instPointer to the registered Coordinated Set Identification Service.
Returns
0 if success, errno on failure.