Bluetooth: Coordinated Set Identification Profile
#################################################

This document describes how to run the coordinated set identification
functionality, both as a client and as a server.
Note that in the examples below, some lines of debug have been removed to make
this shorter and provide a better overview.

Set Coordinator (Client)
************************

The client will typically be a resource-rich device, such as a smartphone
or a laptop. The client is able to lock and release members of a coordinated
set. While the coordinated set is locked, no other clients may lock the set.

To lock a set, the client must connect to each of the set members it wants to
lock. This implementation will always try to to connect to all the members of
the set, and at the same time. Thus if the set size is 3, then
:code:`BT_MAX_CONN` shall be at least 3.

If the locks on set members shall persists through disconnects, it is
necessary to bond with the set members. If you need to bond with multiple
set members, make sure that :code:`BT_MAX_PAIRED` is correctly configured.

Using the Set Coordinator
=========================

When the Bluetooth stack has been initialized (:code:`bt init`),
and a set member device has been connected, the call control client can be
initialized by calling :code:`csip_set_coordinator init`, which will start a discovery
for the TBS uuids and store the handles, and optionally subscribe to all
notifications (default is to subscribe to all).

Once the client has connected and discovered the handles, then it can
read the set information, which is needed to identify other set members.
The client can then scan for and connect to the remaining set members, and once
all the members has been connected to, it can lock and release the set.

It is necessary to enable :code:`BT_DEBUG_CSIP_SET_COORDINATOR` to properly use the set
coordinator.

.. code-block:: console

   csip_set_coordinator --help
   csip_set_coordinator - Bluetooth CSIP_SET_COORDINATOR shell commands
   Subcommands:
      init              :Initialize CSIP_SET_COORDINATOR
      discover          :Run discover for CSIS on peer device [member_index]
      discover_members  :Scan for set members <set_pointer>
      lock_set          :Lock set
      release_set       :Release set
      lock              :Lock specific member [member_index]
      release           :Release specific member [member_index]
      lock_get          :Get the lock value of the specific member and instance
                        [member_index [inst_idx]]


Example usage
=============

Setup
-----

.. code-block:: console

   uart:~$ init
   uart:~$ bt connect xx:xx:xx:xx:xx:xx public

When connected
--------------

Discovering sets on a device:

.. code-block:: console

   uart:~$ csip_set_coordinator init
   <dbg> bt_csip_set_coordinator.primary_discover_func: [ATTRIBUTE] handle 0x0048
   <dbg> bt_csip_set_coordinator.primary_discover_func: Discover complete, found 1 instances
   <dbg> bt_csip_set_coordinator.discover_func: Setup complete for 1 / 1
   Found 1 sets on device
   uart:~$ csip_set_coordinator discover_sets
   <dbg> bt_csip_set_coordinator.Set SIRK
   36 04 9a dc 66 3a a1 a1 |6...f:..
   1d 9a 2f 41 01 73 3e 01 |../A.s>.
   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_set_size_cb: 2
   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_set_lock_cb: 1
   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_rank_cb: 1
   Set size 2 (pointer: 0x566fdfe8)

Discover set members, based on the set pointer above:

.. code-block:: console

   uart:~$ csip_set_coordinator discover_members 0x566fdfe8
   <dbg> bt_csip_set_coordinator.csip_found: Found CSIS advertiser with address 34:02:86:03:86:c0 (public)
   <dbg> bt_csip_set_coordinator.is_set_member: hash: 0x33ccb1, prand 0x5bfe6a
   <dbg> bt_csip_set_coordinator.is_discovered: 34:02:86:03:86:c0 (public)
   <dbg> bt_csip_set_coordinator.is_discovered: 34:13:e8:b3:7f:9e (public)
   <dbg> bt_csip_set_coordinator.csip_found: Found member (2 / 2)
   Discovered 2/2 set members

Lock set members:

.. code-block:: console

   uart:~$ csip_set_coordinator lock_set
   <dbg> bt_csip_set_coordinator.bt_csip_set_coordinator_lock_set: Connecting to 34:02:86:03:86:c0 (public)
   <dbg> bt_csip_set_coordinator.csip_set_coordinator_connected: Connected to 34:02:86:03:86:c0 (public)
   <dbg> bt_csip_set_coordinator.discover_func: Setup complete for 1 / 1
   <dbg> bt_csip_set_coordinator.csip_set_coordinator_lock_set_init_cb:
   <dbg> bt_csip_set_coordinator.Set SIRK
   36 04 9a dc 66 3a a1 a1 |6...f:..
   1d 9a 2f 41 01 73 3e 01 |../A.s>.
   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_set_size_cb: 2
   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_set_lock_cb: 1
   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_rank_cb: 2
   <dbg> bt_csip_set_coordinator.csip_set_coordinator_write_lowest_rank: Locking member with rank 1
   <dbg> bt_csip_set_coordinator.notify_func: Instance 0 lock was locked
   <dbg> bt_csip_set_coordinator.csip_set_coordinator_write_lowest_rank: Locking member with rank 2
   <dbg> bt_csip_set_coordinator.notify_func: Instance 0 lock was locked
   Set locked

Release set members:

.. code-block:: console

   uart:~$ csip_set_coordinator release_set
   <dbg> bt_csip_set_coordinator.csip_set_coordinator_release_highest_rank: Releasing member with rank 2
   <dbg> bt_csip_set_coordinator.notify_func: Instance 0 lock was released
   <dbg> bt_csip_set_coordinator.csip_set_coordinator_release_highest_rank: Releasing member with rank 1
   <dbg> bt_csip_set_coordinator.notify_func: Instance 0 lock was released
   Set released

Coordinated Set Member (Server)
**********************************************
The server on devices that are part of a set,
consisting of at least two devices, e.g. a pair of earbuds.

Using the Set Member
=====================

.. code-block:: console

   csip --help
   csip - Bluetooth CSIP shell commands
   Subcommands:
      register      :Initialize the service and register callbacks [size <int>]
                     [rank <int>] [not-lockable] [sirk <data>]
      update_psri   :Update the advertised PSRI
      lock          :Lock the set
      release       :Release the set [force]
      print_sirk    :Print the currently used SIRK
      set_sirk_rsp  :Set the response used in SIRK requests <accept, accept_enc,
                     reject, oob>

Example Usage
=============

Setup
-----

.. code-block:: console

   uart:~$ bt init
   uart:~$ csip register