d19abff476
The set size can now be dynamically set and notified. The rank is added as a argument in the case that changing the set size, also affects the device's rank, as ranks in a coordinated set needs to be continuous. The set coordinator implementation has been updated to support receiving the new set size, and providing this information to the upper layers. This commit adds a babblesim test for the new API, as well as a shell command. Signed-off-by: Emil Gydesen <emil.gydesen@nordicsemi.no>
214 lines
8.0 KiB
ReStructuredText
214 lines
8.0 KiB
ReStructuredText
Bluetooth: Coordinated Set Identification Profile Shell
|
|
#######################################################
|
|
|
|
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 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
|
|
:kconfig:option:`CONFIG_BT_CSIP_SET_COORDINATOR_LOG_LEVEL_DBG` 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.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.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_set_member --help
|
|
csip_set_member - Bluetooth CSIP set member shell commands
|
|
Subcommands:
|
|
register : Initialize the service and register callbacks [size
|
|
<int>] [rank <int>] [not-lockable] [sirk <data>]
|
|
lock : Lock the set
|
|
release : Release the set [force]
|
|
sirk : Set the currently used SIRK <sirk>
|
|
set_size_and_rank : Set the currently used size and rank <size> <rank>
|
|
get_info : Get service info
|
|
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_set_member register
|
|
|
|
|
|
Setting a new SIRK
|
|
------------------
|
|
|
|
This command can modify the currently used SIRK. To get the new RSI to advertise on air,
|
|
:code:`bt adv-data` or :code:`bt advertise` must be called again to set the new advertising data.
|
|
If :code:`CONFIG_BT_CSIP_SET_MEMBER_SIRK_NOTIFIABLE` is enabled, this will also notify connected
|
|
clients.
|
|
|
|
.. code-block:: console
|
|
|
|
uart:~$ csip_set_member sirk 00112233445566778899aabbccddeeff
|
|
SIRK updated
|
|
|
|
Setting a new set size and rank
|
|
-------------------------------
|
|
|
|
This command can modify the set size and rank of a service instance.
|
|
This shall be done for all device in the set at the same time,
|
|
and all devices shall have the same set size.
|
|
The rank will be ignored if the set is not lockable, else the rank shall be <= the set size,
|
|
and shall be unique for this device in the set.
|
|
|
|
.. code-block:: console
|
|
|
|
uart:~$ csip_set_member set_size_and_rank 1 1
|
|
Set size and rank updated to 1 and 1
|
|
|
|
Getting the current info
|
|
------------------------
|
|
|
|
This command can get the currently used set info.
|
|
|
|
.. code-block:: console
|
|
|
|
uart:~$ csip_set_member get_info
|
|
Info for 0x2003b0c8
|
|
SIRK
|
|
00000000: 20 37 0a 00 95 c4 04 20 00 00 00 00 f1 79 09 00 | 7..... .....y..|
|
|
Set size: 2
|
|
Rank: 1
|
|
Lockable: true
|
|
Locked: false
|