1Bluetooth: Basic Audio Profile: Broadcast Assistant Shell
2#########################################################
3
4This document describes how to run the BAP Broadcast Assistant functionality.
5Note that in the examples below, some lines of debug have been
6removed to make this shorter and provide a better overview.
7
8The Broadcast Assistant is responsible for offloading scan for a resource
9restricted device, such that scanning does not drain the battery. The Broadcast
10Assistant shall support scanning for periodic advertisements and may optionally
11support the periodic advertisements synchronization transfer (PAST) protocol.
12
13The Broadcast Assistant will typically be phones or laptops.
14The Broadcast Assistant scans for periodic advertisements and transfer
15information to the server.
16
17It is necessary to have
18:kconfig:option:`CONFIG_BT_BAP_BROADCAST_ASSISTANT_LOG_LEVEL_DBG` enabled for
19using the Broadcast Assistant interactively.
20
21When the Bluetooth stack has been initialized (:code:`bt init`),
22and a device has been connected, the Broadcast Assistant can discover BASS on
23the connected device calling :code:`bap_broadcast_assistant discover`, which
24will start a discovery for the BASS UUIDs and store the handles, and
25subscribe to all notifications.
26
27.. code-block:: console
28
29   uart:~$ bap_broadcast_assistant --help
30   bap_broadcast_assistant - Bluetooth BAP broadcast assistant client shell
31                           commands
32   Subcommands:
33   discover          : Discover BASS on the server
34   scan_start        : Start scanning for broadcasters
35   scan_stop         : Stop scanning for BISs
36   add_src           : Add a source <address: XX:XX:XX:XX:XX:XX> <type:
37                        public/random> <adv_sid> <sync_pa> <broadcast_id>
38                        [<pa_interval>] [<sync_bis>] [<metadata>]
39   add_broadcast_id  : Add a source by broadcast ID <broadcast_id> <sync_pa>
40                        [<sync_bis>] [<metadata>]
41   add_pa_sync       : Add a PA sync as a source <sync_pa> <broadcast_id>
42                        [bis_index [bis_index [bix_index [...]]]]>
43   mod_src           : Set sync <src_id> <sync_pa> [<pa_interval> | "unknown"] [<sync_bis>]
44                        [<metadata>]
45   broadcast_code    : Send a string-based broadcast code of up to 16 bytes
46                        <src_id> <broadcast code>
47   rem_src           : Remove a source <src_id>
48   read_state        : Remove a source <index>
49
50Example usage
51*************
52
53Setup
54=====
55
56.. code-block:: console
57
58   uart:~$ bt init
59   uart:~$ bap init
60   uart:~$ bt connect xx:xx:xx:xx:xx:xx public
61
62When connected
63==============
64
65Start scanning for periodic advertisements for a server:
66--------------------------------------------------------
67
68.. note::
69   The Broadcast Assistant will not actually start scanning for periodic
70   advertisements, as that feature is still, at the time of writing, not
71   implemented.
72
73.. code-block:: console
74
75   uart:~$ bap_broadcast_assistant discover
76   BASS discover done with 1 recv states
77   uart:~$ bap_broadcast_assistant scan_start true
78   BASS scan start successful
79   Found broadcaster with ID 0x05BD38 and addr 1E:4D:0A:AA:6E:49 (random) and sid 0x00
80
81Adding a source to the receive state with add_src:
82--------------------------------------------------
83
84.. code-block:: console
85
86   uart:~$ bap_broadcast_assistant add_src 11:22:33:44:55:66 public 5 1 1
87   BASS recv state: src_id 0, addr 11:22:33:44:55:66 (public), sid 5, sync_state 1, encrypt_state 000000000000000000000000000000000
88        [0]: BIS sync 0, metadata_len 0
89
90
91Adding a source to the receive state with add_broadcast_id (recommended):
92-------------------------------------------------------------------------
93
94.. code-block:: console
95
96   uart:~$ bap_broadcast_assistant add_broadcast_id 0x05BD38 true
97   [DEVICE]: 1E:4D:0A:AA:6E:49 (random), AD evt type 5, RSSI -28 Broadcast Audio Source C:0 S:0 D:0 SR:0 E:1 Prim: LE 1M, Secn: LE 2M, Interval: 0x03c0 (1200000 us), SID: 0x0
98   Found BAP broadcast source with address 1E:4D:0A:AA:6E:49 (random) and ID 0x05BD38
99   BASS recv state: src_id 0, addr 1E:4D:0A:AA:6E:49 (random), sid 0, sync_state 0, encrypt_state 0
100         [0]: BIS sync 0x0000, metadata_len 0
101   BASS add source successful
102   BASS recv state: src_id 0, addr 1E:4D:0A:AA:6E:49 (random), sid 0, sync_state 2, encrypt_state 0
103         [0]: BIS sync 0x0000, metadata_len 0
104   BASS recv state: src_id 0, addr 1E:4D:0A:AA:6E:49 (random), sid 0, sync_state 2, encrypt_state 0
105         [0]: BIS sync 0x0000, metadata_len 4
106                  Metadata length 2, type 2, data: 0100
107
108
109Modifying a receive state:
110--------------------------
111
112.. code-block:: console
113
114   uart:~$ bap_broadcast_assistant mod_src 0 true 0x03c0 0x02
115   BASS modify source successful
116   BASS recv state: src_id 0, addr 1E:4D:0A:AA:6E:49 (random), sid 0, sync_state 2, encrypt_state 0
117         [0]: BIS sync 0x0001, metadata_len 4
118                  Metadata length 2, type 2, data: 0100
119
120Supplying a broadcast code:
121---------------------------
122
123.. code-block:: console
124
125   uart:~$ bap_broadcast_assistant broadcast_code 0 secretCode
126   Sending broadcast code:
127   00000000: 73 65 63 72 65 74 43 6f 64 65 00 00 00 00 00 00 |secretCo de....|
128   uart:~$ BASS broadcast code successful
129