1.. _bluetooth_shell_audio:
2
3Bluetooth: Basic Audio Profile
4##############################
5
6This document describes how to run Basic Audio Profile functionality which
7includes:
8
9  - Capabilities and Endpoint discovery
10  - Audio Stream Endpoint procedures
11
12Commands
13********
14
15.. code-block:: console
16
17   bap --help
18   Subcommands:
19      init
20      select_broadcast      :<stream>
21      create_broadcast      :[preset <preset_name>] [enc <broadcast_code>]
22      start_broadcast       :
23      stop_broadcast        :
24      delete_broadcast      :
25      broadcast_scan        :<on, off>
26      create_broadcast_sink :0x<broadcast_id>
27      sync_broadcast        :0x<bis_index> [[[0x<bis_index>] 0x<bis_index>] ...]
28      stop_broadcast_sink   :Stops broadcast sink
29      term_broadcast_sink   :
30      discover              :[dir: sink, source]
31      config                :<direction: sink, source> <index> [loc <loc_bits>] [preset <preset_name>]
32      stream_qos            :interval [framing] [latency] [pd] [sdu] [phy] [rtn]
33      qos                   :Send QoS configure for Unicast Group
34      enable                :[context]
35      stop
36      print_ase_info        :Print ASE info for default connection
37      metadata              :[context]
38      start
39      disable
40      release
41      list
42      select_unicast        :<stream>
43      preset                :<sink, source, broadcast> [preset]
44      send                  :Send to Audio Stream [data]
45      start_sine            :Start sending a LC3 encoded sine wave
46      stop_sine             :Stop sending a LC3 encoded sine wave
47      set_location          :<direction: sink, source> <location bitmask>
48      set_context           :<direction: sink, source><context bitmask> <type:
49                             supported, available>
50
51
52.. csv-table:: State Machine Transitions
53   :header: "Command", "Depends", "Allowed States", "Next States"
54   :widths: auto
55
56   "init","none","any","none"
57   "discover","init","any","any"
58   "config","discover","idle/codec-configured/qos-configured","codec-configured"
59   "qos","config","codec-configured/qos-configured","qos-configured"
60   "enable","qos","qos-configured","enabling"
61   "[start]","enable","enabling","streaming"
62   "disable","enable", "enabling/streaming","disabling"
63   "[stop]","disable","disabling","qos-configure/idle"
64   "release","config","any","releasing/codec-configure/idle"
65   "list","none","any","none"
66   "select_unicast","none","any","none"
67   "connect","discover","idle/codec-configured/qos-configured","codec-configured"
68   "send","enable","streaming","none"
69
70Example Central
71***************
72
73Connect and establish a stream:
74
75.. code-block:: console
76
77   uart:~$ bt init
78   uart:~$ bap init
79   uart:~$ bt connect <address>
80   uart:~$ gatt exchange-mtu
81   uart:~$ bap discover sink
82   uart:~$ bap config sink 0
83   uart:~$ bap qos
84   uart:~$ bap enable
85
86Or using connect command:
87
88.. code-block:: console
89
90   uart:~$ bt init
91   uart:~$ bap init
92   uart:~$ bt connect <address>
93   uart:~$ gatt exchange-mtu
94   uart:~$ bap discover sink
95   uart:~$ bap connect sink 0
96
97Disconnect and release:
98
99.. code-block:: console
100
101   uart:~$ bap disable
102   uart:~$ bap release
103
104Example Peripheral
105******************
106
107Listen:
108
109.. code-block:: console
110
111   uart:~$ bt init
112   uart:~$ bap init
113   uart:~$ bt advertise on
114
115Server initiated disable and release:
116
117.. code-block:: console
118
119   uart:~$ bap disable
120   uart:~$ bap release
121
122Example Broadcast Source
123************************
124
125Create and establish a broadcast source stream:
126
127.. code-block:: console
128
129   uart:~$ bap init
130   uart:~$ bap create_broadcast
131   uart:~$ bap start_broadcast
132
133Stop and release a broadcast source stream:
134
135.. code-block:: console
136
137   uart:~$ bap stop_broadcast
138   uart:~$ bap delete_broadcast
139
140
141Example Broadcast Sink
142**********************
143
144Scan for and establish a broadcast sink stream.
145The command :code:`bap create_broadcast_sink 0xEF6716` will either use existing periodic advertising
146sync (if exist) or start scanning and sync to the periodic advertising before syncing to the BIG.
147
148.. code-block:: console
149
150   uart:~$ bap init
151   uart:~$ bap broadcast_scan on
152   Found broadcaster with ID 0xEF6716 and addr 3D:A5:F9:35:0B:19 (random) and sid 0x00
153   uart:~$ bap create_broadcast_sink 0xEF6716
154   Attempting to PA sync to the broadcaster
155   PA synced to broadcast with broadcast ID 0xEF6716
156   Attempting to sync to the BIG
157   Received BASE from sink 0x20031fac:
158   Presentation delay: 40000
159   Subgroup count: 2
160   Subgroup[0]:
161   codec cfg id 0x06 cid 0x0000 vid 0x0000
162   data_count 4
163   data #0: type 0x01 len 1
164   00000000: 03                                               |.                |
165   data #1: type 0x02 len 1
166   00000000: 01                                               |.                |
167   data #2: type 0x03 len 4
168   00000000: 01 00 00 00                                      |....             |
169   data #3: type 0x04 len 2
170   00000000: 28 00                                            |(.               |
171   meta_count 4
172   meta #0: type 0x02 len 2
173   00000000: 01 00                                            |..               |
174      BIS[0] index 0x01
175   Subgroup[1]:
176   codec cfg id 0x06 cid 0x0000 vid 0x0000
177   data_count 4
178   data #0: type 0x01 len 1
179   00000000: 03                                               |.                |
180   data #1: type 0x02 len 1
181   00000000: 01                                               |.                |
182   data #2: type 0x03 len 4
183   00000000: 01 00 00 00                                      |....             |
184   data #3: type 0x04 len 2
185   00000000: 28 00                                            |(.               |
186   meta_count 4
187   meta #0: type 0x02 len 2
188   00000000: 01 00                                            |..               |
189      BIS[1] index 0x01
190   [0]: 0x01
191   [1]: 0x01
192   Possible indexes: 0x01 0x01
193   uart:~$ bap sync_broadcast 0x01
194
195Stop and release a broadcast sink stream:
196
197.. code-block:: console
198
199   uart:~$ bap stop_broadcast_sink
200   uart:~$ bap term_broadcast_sink
201
202Init
203****
204
205The :code:`init` command register local PAC records which are necessary to be
206able to configure stream and properly manage capabilities in use.
207
208.. csv-table:: State Machine Transitions
209   :header: "Depends", "Allowed States", "Next States"
210   :widths: auto
211
212   "none","any","none"
213
214.. code-block:: console
215
216   uart:~$ bap init
217
218Discover PAC(s) and ASE(s)
219**************************
220
221Once connected the :code:`discover` command discover PAC records and ASE
222characteristics representing remote endpoints.
223
224.. csv-table:: State Machine Transitions
225   :header: "Depends", "Allowed States", "Next States"
226   :widths: auto
227
228   "init","any","any"
229
230.. note::
231
232   Use command :code:`gatt exchange-mtu` to make sure the MTU is configured
233   properly.
234
235.. code-block:: console
236
237   uart:~$ gatt exchange-mtu
238   Exchange pending
239   Exchange successful
240   uart:~$ bap discover [type: sink, source]
241   uart:~$ bap discover sink
242   cap 0x8175940 type 0x01
243   codec 0x06 cid 0x0000 vid 0x0000 count 4
244   data #0: type 0x01 len 1
245   00000000: 3f                                             |?                |
246   data #1: type 0x02 len 1
247   00000000: 03                                             |.                |
248   data #2: type 0x03 len 1
249   00000000: 03                                             |.                |
250   data #3: type 0x04 len 4
251   00000000: 1e 00 f0 00                                    |....             |
252   meta #0: type 0x01 len 2
253   00000000: 06 00                                          |..               |
254   meta #1: type 0x02 len 2
255   00000000: ff 03                                          |..               |
256   ep 0x81754e0
257   ep 0x81755d4
258   Discover complete: err 0
259
260Select preset
261*************
262
263The :code:`preset` command can be used to either print the default preset
264configuration or set a different one, it is worth noting that it doesn't change
265any stream previously configured.
266
267.. code-block:: console
268
269   uart:~$ bap preset <sink, source, broadcast> [preset]
270   uart:~$ bap preset sink
271   16_2_1
272   codec 0x06 cid 0x0000 vid 0x0000 count 4
273   data #0: type 0x01 len 1
274   data #1: type 0x02 len 1
275   data #2: type 0x03 len 4
276   00000000: 01 00 00                                         |...              |
277   data #3: type 0x04 len 2
278   00000000: 28                                               |(                |
279   meta #0: type 0x02 len 2
280   00000000: 06                                               |.                |
281   QoS: interval 10000 framing 0x00 phy 0x02 sdu 40 rtn 2 latency 10 pd 40000
282
283   uart:~$ bap preset sink 32_2_1
284   32_2_1
285   codec 0x06 cid 0x0000 vid 0x0000 count 4
286   data #0: type 0x01 len 1
287   data #1: type 0x02 len 1
288   data #2: type 0x03 len 4
289   00000000: 01 00 00                                         |...              |
290   data #3: type 0x04 len 2
291   00000000: 50                                               |P                |
292   meta #0: type 0x02 len 2
293   00000000: 06                                               |.                |
294   QoS: interval 10000 framing 0x00 phy 0x02 sdu 80 rtn 2 latency 10 pd 40000
295
296
297Configure Codec
298***************
299
300The :code:`config` command attempts to configure a stream for the given
301direction using a preset codec configuration which can either be passed directly
302or in case it is omitted the default preset is used.
303
304.. csv-table:: State Machine Transitions
305   :header: "Depends", "Allowed States", "Next States"
306   :widths: auto
307
308   "discover","idle/codec-configured/qos-configured","codec-configured"
309
310.. code-block:: console
311
312   uart:~$ bap config <direction: sink, source> <index> [loc <loc_bits>] [preset <preset_name>]
313   uart:~$ bap config sink 0
314   ASE Codec Config: conn 0x8173800 ep 0x81754e0 cap 0x816a360
315   codec 0x06 cid 0x0000 vid 0x0000 count 3
316   data #0: type 0x01 len 1
317   00000000: 02                                             |.                |
318   data #1: type 0x02 len 1
319   00000000: 01                                             |.                |
320   data #2: type 0x04 len 2
321   00000000: 28 00                                          |(.               |
322   meta #0: type 0x02 len 2
323   00000000: 02 00                                          |..               |
324   ASE Codec Config stream 0x8179e60
325   Default ase: 1
326   ASE config: preset 16_2_1
327
328Configure Stream QoS
329********************
330
331The :code:`stream_qos` Sets a new stream QoS.
332
333.. code-block:: console
334
335   uart:~$ bap stream_qos <interval> [framing] [latency] [pd] [sdu] [phy] [rtn]
336   uart:~$ bap stream_qos 10
337
338Configure QoS
339*************
340
341The :code:`qos` command attempts to configure the stream QoS using the preset
342configuration, each individual QoS parameter can be set with use optional
343parameters.
344
345.. csv-table:: State Machine Transitions
346   :header: "Depends", "Allowed States", "Next States"
347   :widths: auto
348
349   "config","qos-configured/codec-configured","qos-configured"
350
351.. code-block:: console
352
353   uart:~$ bap qos
354
355Enable
356******
357
358The :code:`enable` command attempts to enable the stream previously configured,
359if the remote peer accepts then the ISO connection procedure is also initiated.
360
361.. csv-table:: State Machine Transitions
362   :header: "Depends", "Allowed States", "Next States"
363   :widths: auto
364
365   "qos","qos-configured","enabling"
366
367.. code-block:: console
368
369   uart:~$ bap enable [context]
370   uart:~$ bap enable Media
371
372Start
373*****
374
375The :code:`start` command is only necessary when acting as a sink as it
376indicates to the source the stack is ready to start receiving data.
377
378.. csv-table:: State Machine Transitions
379   :header: "Depends", "Allowed States", "Next States"
380   :widths: auto
381
382   "enable","enabling","streaming"
383
384.. code-block:: console
385
386   uart:~$ bap start
387
388Disable
389*******
390
391The :code:`disable` command attempts to disable the stream previously enabled,
392if the remote peer accepts then the ISO disconnection procedure is also
393initiated.
394
395.. csv-table:: State Machine Transitions
396   :header: "Depends", "Allowed States", "Next States"
397   :widths: auto
398
399   "enable","enabling/streaming","disabling"
400
401.. code-block:: console
402
403   uart:~$ bap disable
404
405Stop
406****
407
408The :code:`stop` command is only necessary when acting as a sink as it indicates
409to the source the stack is ready to stop receiving data.
410
411.. csv-table:: State Machine Transitions
412   :header: "Depends", "Allowed States", "Next States"
413   :widths: auto
414
415   "disable","disabling","qos-configure/idle"
416
417.. code-block:: console
418
419   uart:~$ bap stop
420
421Release
422*******
423
424The :code:`release` command releases the current stream and its configuration.
425
426.. csv-table:: State Machine Transitions
427   :header: "Depends", "Allowed States", "Next States"
428   :widths: auto
429
430   "config","any","releasing/codec-configure/idle"
431
432.. code-block:: console
433
434   uart:~$ bap release
435
436List
437****
438
439The :code:`list` command list the available streams.
440
441.. csv-table:: State Machine Transitions
442   :header: "Depends", "Allowed States", "Next States"
443   :widths: auto
444
445   "none","any","none"
446
447.. code-block:: console
448
449   uart:~$ bap list
450   *0: ase 0x01 dir 0x01 state 0x01
451
452Select Unicast
453**************
454
455The :code:`select_unicast` command set a unicast stream as default.
456
457.. csv-table:: State Machine Transitions
458   :header: "Depends", "Allowed States", "Next States"
459   :widths: auto
460
461   "none","any","none"
462
463.. code-block:: console
464
465   uart:~$ bap select <ase>
466   uart:~$ bap select 0x01
467   Default stream: 1
468
469To select a broadcast stream:
470
471.. code-block:: console
472
473   uart:~$ bap select 0x01 broadcast
474   Default stream: 1 (broadcast)
475
476Send
477****
478
479The :code:`send` command sends data over BAP Stream.
480
481.. csv-table:: State Machine Transitions
482   :header: "Depends", "Allowed States", "Next States"
483   :widths: auto
484
485   "enable","streaming","none"
486
487.. code-block:: console
488
489   uart:~$ bap send [count]
490   uart:~$ bap send
491   Audio sending...
492