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 <int>]
149                     [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      get_sirk      :Get the currently used SIRK
154      sirk_rsp      :Set the response used in SIRK requests <accept, accept_enc,
155                     reject, oob>
156
157Example Usage
158=============
159
160Setup
161-----
162
163.. code-block:: console
164
165   uart:~$ bt init
166   uart:~$ csip_set_member register
167
168
169Setting a new SIRK
170------------------
171
172This command can modify the currently used SIRK. To get the new RSI to advertise on air,
173:code:`bt adv-data` or :code:`bt advertise` must be called again to set the new advertising data.
174If :code:`CONFIG_BT_CSIP_SET_MEMBER_NOTIFIABLE` is enabled, this will also notify connected
175clients.
176
177.. code-block:: console
178
179   uart:~$ csip_set_member sirk 00112233445566778899aabbccddeeff
180   SIRK updated
181
182Getting the current SIRK
183------------------------
184
185This command can get the currently used SIRK.
186
187.. code-block:: console
188
189   uart:~$ csip_set_member get_sirk
190   SIRK
191   36 04 9a dc 66 3a a1 a1 |6...f:..
192   1d 9a 2f 41 01 73 3e 01 |../A.s>.
193