1Bluetooth: Coordinated Set Identification Profile
2#################################################
3
4This document describes how to run the coordinated set identification
5functionality, both as a client and as a server.
6Note that in the examples below, some lines of debug have been removed to make
7this shorter and provide a better overview.
8
9Set Coordinator (Client)
10************************
11
12The client will typically be a resource-rich device, such as a smartphone
13or a laptop. The client is able to lock and release members of a coordinated
14set. While the coordinated set is locked, no other clients may lock the set.
15
16To lock a set, the client must connect to each of the set members it wants to
17lock. This implementation will always try to connect to all the members of
18the set, and at the same time. Thus if the set size is 3, then
19:code:`BT_MAX_CONN` shall be at least 3.
20
21If the locks on set members shall persists through disconnects, it is
22necessary to bond with the set members. If you need to bond with multiple
23set members, make sure that :code:`BT_MAX_PAIRED` is correctly configured.
24
25Using the Set Coordinator
26=========================
27
28When the Bluetooth stack has been initialized (:code:`bt init`),
29and a set member device has been connected, the call control client can be
30initialized by calling :code:`csip_set_coordinator init`, which will start a discovery
31for the TBS uuids and store the handles, and optionally subscribe to all
32notifications (default is to subscribe to all).
33
34Once the client has connected and discovered the handles, then it can
35read the set information, which is needed to identify other set members.
36The client can then scan for and connect to the remaining set members, and once
37all the members has been connected to, it can lock and release the set.
38
39It is necessary to enable :code:`BT_DEBUG_CSIP_SET_COORDINATOR` to properly use the set
40coordinator.
41
42.. code-block:: console
43
44   csip_set_coordinator --help
45   csip_set_coordinator - Bluetooth CSIP_SET_COORDINATOR shell commands
46   Subcommands:
47      init              :Initialize CSIP_SET_COORDINATOR
48      discover          :Run discover for CSIS on peer device [member_index]
49      discover_members  :Scan for set members <set_pointer>
50      lock_set          :Lock set
51      release_set       :Release set
52      lock              :Lock specific member [member_index]
53      release           :Release specific member [member_index]
54      lock_get          :Get the lock value of the specific member and instance
55                        [member_index [inst_idx]]
56
57
58Example usage
59=============
60
61Setup
62-----
63
64.. code-block:: console
65
66   uart:~$ init
67   uart:~$ bt connect xx:xx:xx:xx:xx:xx public
68
69When connected
70--------------
71
72Discovering sets on a device:
73
74.. code-block:: console
75
76   uart:~$ csip_set_coordinator init
77   <dbg> bt_csip_set_coordinator.primary_discover_func: [ATTRIBUTE] handle 0x0048
78   <dbg> bt_csip_set_coordinator.primary_discover_func: Discover complete, found 1 instances
79   <dbg> bt_csip_set_coordinator.discover_func: Setup complete for 1 / 1
80   Found 1 sets on device
81   uart:~$ csip_set_coordinator discover_sets
82   <dbg> bt_csip_set_coordinator.Set SIRK
83   36 04 9a dc 66 3a a1 a1 |6...f:..
84   1d 9a 2f 41 01 73 3e 01 |../A.s>.
85   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_set_size_cb: 2
86   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_set_lock_cb: 1
87   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_rank_cb: 1
88   Set size 2 (pointer: 0x566fdfe8)
89
90Discover set members, based on the set pointer above:
91
92.. code-block:: console
93
94   uart:~$ csip_set_coordinator discover_members 0x566fdfe8
95   <dbg> bt_csip_set_coordinator.csip_found: Found CSIS advertiser with address 34:02:86:03:86:c0 (public)
96   <dbg> bt_csip_set_coordinator.is_set_member: hash: 0x33ccb1, prand 0x5bfe6a
97   <dbg> bt_csip_set_coordinator.is_discovered: 34:02:86:03:86:c0 (public)
98   <dbg> bt_csip_set_coordinator.is_discovered: 34:13:e8:b3:7f:9e (public)
99   <dbg> bt_csip_set_coordinator.csip_found: Found member (2 / 2)
100   Discovered 2/2 set members
101
102Lock set members:
103
104.. code-block:: console
105
106   uart:~$ csip_set_coordinator lock_set
107   <dbg> bt_csip_set_coordinator.bt_csip_set_coordinator_lock_set: Connecting to 34:02:86:03:86:c0 (public)
108   <dbg> bt_csip_set_coordinator.csip_set_coordinator_connected: Connected to 34:02:86:03:86:c0 (public)
109   <dbg> bt_csip_set_coordinator.discover_func: Setup complete for 1 / 1
110   <dbg> bt_csip_set_coordinator.csip_set_coordinator_lock_set_init_cb:
111   <dbg> bt_csip_set_coordinator.Set SIRK
112   36 04 9a dc 66 3a a1 a1 |6...f:..
113   1d 9a 2f 41 01 73 3e 01 |../A.s>.
114   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_set_size_cb: 2
115   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_set_lock_cb: 1
116   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_rank_cb: 2
117   <dbg> bt_csip_set_coordinator.csip_set_coordinator_write_lowest_rank: Locking member with rank 1
118   <dbg> bt_csip_set_coordinator.notify_func: Instance 0 lock was locked
119   <dbg> bt_csip_set_coordinator.csip_set_coordinator_write_lowest_rank: Locking member with rank 2
120   <dbg> bt_csip_set_coordinator.notify_func: Instance 0 lock was locked
121   Set locked
122
123Release set members:
124
125.. code-block:: console
126
127   uart:~$ csip_set_coordinator release_set
128   <dbg> bt_csip_set_coordinator.csip_set_coordinator_release_highest_rank: Releasing member with rank 2
129   <dbg> bt_csip_set_coordinator.notify_func: Instance 0 lock was released
130   <dbg> bt_csip_set_coordinator.csip_set_coordinator_release_highest_rank: Releasing member with rank 1
131   <dbg> bt_csip_set_coordinator.notify_func: Instance 0 lock was released
132   Set released
133
134Coordinated Set Member (Server)
135**********************************************
136The server on devices that are part of a set,
137consisting of at least two devices, e.g. a pair of earbuds.
138
139Using the Set Member
140=====================
141
142.. code-block:: console
143
144   csip_set_member --help
145   csip_set_member - Bluetooth CSIP set member shell commands
146   Subcommands:
147      register      :Initialize the service and register callbacks [size <int>]
148                     [rank <int>] [not-lockable] [sirk <data>]
149      update_psri   :Update the advertised PSRI
150      lock          :Lock the set
151      release       :Release the set [force]
152      print_sirk    :Print the currently used SIRK
153      set_sirk_rsp  :Set the response used in SIRK requests <accept, accept_enc,
154                     reject, oob>
155
156Example Usage
157=============
158
159Setup
160-----
161
162.. code-block:: console
163
164   uart:~$ bt init
165   uart:~$ csip_set_member register
166