Bluetooth Coordinated Sets

API Reference

group bt_gatt_csis

Coordinated Set Identification Service (CSIS)

SPDX-License-Identifier: Apache-2.0

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

Defines

CSIS_CLIENT_DISCOVER_TIMER_VALUE: Recommended timer for member discovery

BT_CSIS_CLIENT_MAX_CSIS_INSTANCES

BT_CSIS_READ_SIRK_REQ_RSP_ACCEPT: Accept the request to read the SIRK as plaintext

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

BT_CSIS_READ_SIRK_REQ_RSP_REJECT: Reject the request to read the SIRK

BT_CSIS_READ_SIRK_REQ_RSP_OOB_ONLY: SIRK is available only via an OOB procedure

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

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

BT_CSIS_ERROR_LOCK_DENIED: Service is already locked

BT_CSIS_ERROR_LOCK_RELEASE_DENIED: Service is not locked

BT_CSIS_ERROR_LOCK_INVAL_VALUE: Invalid lock value

BT_CSIS_ERROR_SIRK_OOB_ONLY: SIRK only available out-of-band

BT_CSIS_ERROR_LOCK_ALREADY_GRANTED: Client is already owner of the lock

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.

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

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_csis_client_ordered_access_cb_t)(const struct bt_csis_client_set_info *set_info, int err, bool locked, struct bt_csis_client_set_member *member)

Callback for bt_csis_client_ordered_access()

If any of the set members supplied to bt_csis_client_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_csis_client_ordered_access_t)(const struct bt_csis_client_set_info *set_info, struct bt_csis_client_set_member *members[], size_t count)

Callback function definition for bt_csis_client_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_csis_svc_decl_get(const struct bt_csis *csis)

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.

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

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

Returns

0 if success, errno on failure.

void bt_csis_print_sirk(const struct bt_csis *csis)

Print the SIRK to the debug output.

Parameters

csis – Pointer to the Coordinated Set Identification Service.

int bt_csis_advertise(struct bt_csis *csis, bool enable)

Starts advertising the Resolvable 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.

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

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.

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.

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.

bool bt_csis_client_is_set_member(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

void bt_csis_client_register_cb(struct bt_csis_client_cb *cb)

Registers callbacks for csis_client.

Parameters

cb – Pointer to the callback structure.

int bt_csis_client_ordered_access(struct bt_csis_client_set_member *members[], uint8_t count, const struct bt_csis_client_set_info *set_info, bt_csis_client_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_csis_client_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_csis_client_lock(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.

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_csis_client_release(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.

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_csis_cb

#include <csis.h>

Callback structure for the Coordinated Set Identification Service

Public Members

void (*lock_changed)(struct bt_conn *conn, struct bt_csis *csis, 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_csis_lock() or by timeout.
Param csis: 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_csis *csis)

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 csis: Pointer to the Coordinated Set Identification Service.
Return: A BT_CSIS_READ_SIRK_REQ_RSP_* response code.

void (*rsi_changed)(const uint8_t rsi[6])

Callback whenever the RSI changes.

If this callback is not set, the stack will handle advertising of the RSI.

Param rsi: Pointer to the new 6-octet RSI data to be advertised.

struct bt_csis_register_param

#include <csis.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_csis_cb *cb: Pointer to the callback structure.

struct bt_csis_client_set_info

#include <csis.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_csis_client_csis_inst

#include <csis.h>

Struct representing a coordinated set instance on a remote device.

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

Public Members

struct bt_csis *csis: Internally used pointer value

struct bt_csis_client_set_member

#include <csis.h>

Struct representing a remote device as a set member

Public Members

struct bt_conn *conn: Connection pointer to the remote device, populated by the user

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

struct bt_csis_client_cb: #include <csis.h>