Bluetooth Coordinated Sets

API Reference

group bt_gatt_csip

Coordinated Set Identification Profile (CSIP)

SPDX-License-Identifier: Apache-2.0

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

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

void bt_csip_set_member_print_sirk(const struct bt_csip_set_member_svc_inst *svc_inst)

Print the SIRK to the debug output.

Parameters

svc_inst – Pointer to the Coordinated Set Identification Service.

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.

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.

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>