Bluetooth Coordinated Sets

API Reference

group bt_gatt_csip

SPDX-License-Identifier: Apache-2.0

Coordinated Set Identification Profile (CSIP)

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

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

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

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.

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

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 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:

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.

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

struct bt_csip_set_coordinator_set_info

#include <csip.h>

Information about a specific set.

Public Members

uint8_t set_sirk[16]

The 16 octet set Set Identity Resolving Key (SIRK)

The Set 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 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

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>