1Bluetooth: Coordinated Set Identification Profile Shell
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
40:kconfig:option:`CONFIG_BT_CSIP_SET_COORDINATOR_LOG_LEVEL_DBG` to properly use
41the set coordinator.
42
43.. code-block:: console
44
45   csip_set_coordinator --help
46   csip_set_coordinator - Bluetooth CSIP_SET_COORDINATOR shell commands
47   Subcommands:
48      init              :Initialize CSIP_SET_COORDINATOR
49      discover          :Run discover for CSIS on peer device [member_index]
50      discover_members  :Scan for set members <set_pointer>
51      lock_set          :Lock set
52      release_set       :Release set
53      lock              :Lock specific member [member_index]
54      release           :Release specific member [member_index]
55      lock_get          :Get the lock value of the specific member and instance
56                        [member_index [inst_idx]]
57
58
59Example usage
60=============
61
62Setup
63-----
64
65.. code-block:: console
66
67   uart:~$ init
68   uart:~$ bt connect xx:xx:xx:xx:xx:xx public
69
70When connected
71--------------
72
73Discovering sets on a device:
74
75.. code-block:: console
76
77   uart:~$ csip_set_coordinator init
78   <dbg> bt_csip_set_coordinator.primary_discover_func: [ATTRIBUTE] handle 0x0048
79   <dbg> bt_csip_set_coordinator.primary_discover_func: Discover complete, found 1 instances
80   <dbg> bt_csip_set_coordinator.discover_func: Setup complete for 1 / 1
81   Found 1 sets on device
82   uart:~$ csip_set_coordinator discover_sets
83   <dbg> bt_csip_set_coordinator.SIRK
84   36 04 9a dc 66 3a a1 a1 |6...f:..
85   1d 9a 2f 41 01 73 3e 01 |../A.s>.
86   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_set_size_cb: 2
87   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_set_lock_cb: 1
88   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_rank_cb: 1
89   Set size 2 (pointer: 0x566fdfe8)
90
91Discover set members, based on the set pointer above:
92
93.. code-block:: console
94
95   uart:~$ csip_set_coordinator discover_members 0x566fdfe8
96   <dbg> bt_csip_set_coordinator.csip_found: Found CSIS advertiser with address 34:02:86:03:86:c0 (public)
97   <dbg> bt_csip_set_coordinator.is_set_member: hash: 0x33ccb1, prand 0x5bfe6a
98   <dbg> bt_csip_set_coordinator.is_discovered: 34:02:86:03:86:c0 (public)
99   <dbg> bt_csip_set_coordinator.is_discovered: 34:13:e8:b3:7f:9e (public)
100   <dbg> bt_csip_set_coordinator.csip_found: Found member (2 / 2)
101   Discovered 2/2 set members
102
103Lock set members:
104
105.. code-block:: console
106
107   uart:~$ csip_set_coordinator lock_set
108   <dbg> bt_csip_set_coordinator.bt_csip_set_coordinator_lock_set: Connecting to 34:02:86:03:86:c0 (public)
109   <dbg> bt_csip_set_coordinator.csip_set_coordinator_connected: Connected to 34:02:86:03:86:c0 (public)
110   <dbg> bt_csip_set_coordinator.discover_func: Setup complete for 1 / 1
111   <dbg> bt_csip_set_coordinator.csip_set_coordinator_lock_set_init_cb:
112   <dbg> bt_csip_set_coordinator.SIRK
113   36 04 9a dc 66 3a a1 a1 |6...f:..
114   1d 9a 2f 41 01 73 3e 01 |../A.s>.
115   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_set_size_cb: 2
116   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_set_lock_cb: 1
117   <dbg> bt_csip_set_coordinator.csip_set_coordinator_discover_sets_read_rank_cb: 2
118   <dbg> bt_csip_set_coordinator.csip_set_coordinator_write_lowest_rank: Locking member with rank 1
119   <dbg> bt_csip_set_coordinator.notify_func: Instance 0 lock was locked
120   <dbg> bt_csip_set_coordinator.csip_set_coordinator_write_lowest_rank: Locking member with rank 2
121   <dbg> bt_csip_set_coordinator.notify_func: Instance 0 lock was locked
122   Set locked
123
124Release set members:
125
126.. code-block:: console
127
128   uart:~$ csip_set_coordinator release_set
129   <dbg> bt_csip_set_coordinator.csip_set_coordinator_release_highest_rank: Releasing member with rank 2
130   <dbg> bt_csip_set_coordinator.notify_func: Instance 0 lock was released
131   <dbg> bt_csip_set_coordinator.csip_set_coordinator_release_highest_rank: Releasing member with rank 1
132   <dbg> bt_csip_set_coordinator.notify_func: Instance 0 lock was released
133   Set released
134
135Coordinated Set Member (Server)
136**********************************************
137The server on devices that are part of a set,
138consisting of at least two devices, e.g. a pair of earbuds.
139
140Using the Set Member
141=====================
142
143.. code-block:: console
144
145   csip_set_member --help
146   csip_set_member - Bluetooth CSIP set member shell commands
147      Subcommands:
148      register           : Initialize the service and register callbacks [size
149                           <int>] [rank <int>] [not-lockable] [sirk <data>]
150      lock               : Lock the set
151      release            : Release the set [force]
152      sirk               : Set the currently used SIRK <sirk>
153      set_size_and_rank  : Set the currently used size and rank <size> <rank>
154      get_info           : Get service info
155      sirk_rsp           : Set the response used in SIRK requests <accept,
156                           accept_enc, reject, oob>
157
158
159
160Example Usage
161=============
162
163Setup
164-----
165
166.. code-block:: console
167
168   uart:~$ bt init
169   uart:~$ csip_set_member register
170
171
172Setting a new SIRK
173------------------
174
175This command can modify the currently used SIRK. To get the new RSI to advertise on air,
176:code:`bt adv-data` or :code:`bt advertise` must be called again to set the new advertising data.
177If :code:`CONFIG_BT_CSIP_SET_MEMBER_SIRK_NOTIFIABLE` is enabled, this will also notify connected
178clients.
179
180.. code-block:: console
181
182   uart:~$ csip_set_member sirk 00112233445566778899aabbccddeeff
183   SIRK updated
184
185Setting a new set size and rank
186-------------------------------
187
188This command can modify the set size and rank of a service instance.
189This shall be done for all device in the set at the same time,
190and all devices shall have the same set size.
191The rank will be ignored if the set is not lockable, else the rank shall be <= the set size,
192and shall be unique for this device in the set.
193
194.. code-block:: console
195
196   uart:~$ csip_set_member set_size_and_rank 1 1
197   Set size and rank updated to 1 and 1
198
199Getting the current info
200------------------------
201
202This command can get the currently used set info.
203
204.. code-block:: console
205
206   uart:~$ csip_set_member get_info
207   Info for 0x2003b0c8
208           SIRK
209   00000000: 20 37 0a 00 95 c4 04 20  00 00 00 00 f1 79 09 00 | 7.....  .....y..|
210           Set size: 2
211           Rank: 1
212           Lockable: true
213           Locked: false
214