1.. _bluetooth_shell_audio:
2
3Bluetooth: Basic Audio Profile Shell
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                   : [ase_sink_count, ase_source_count]
20      select_broadcast       : <stream>
21      create_broadcast       : [preset <preset_name>] [enc <broadcast_code>]
22      start_broadcast        :
23      stop_broadcast         :
24      delete_broadcast       :
25      create_broadcast_sink  : 0x<broadcast_id>
26      create_sink_by_name    : <broadcast_name>
27      sync_broadcast         : 0x<bis_index> [[[0x<bis_index>] 0x<bis_index>] ...]
28                              [bcode <broadcast code> || bcode_str <broadcast code
29                              as string>]
30      stop_broadcast_sink    : Stops broadcast sink
31      term_broadcast_sink    :
32      discover               : [dir: sink, source]
33      config                 : <direction: sink, source> <index> [loc <loc_bits>]
34                              [preset <preset_name>]
35      stream_qos             : interval [framing] [latency] [pd] [sdu] [phy] [rtn]
36      qos                    : Send QoS configure for Unicast Group
37      enable                 : [context]
38      connect                : Connect the CIS of the stream
39      stop
40      list
41      print_ase_info         : Print ASE info for default connection
42      metadata               : [context]
43      start
44      disable
45      release
46      select_unicast         : <stream>
47      preset                 : <sink, source, broadcast> [preset]
48                              [config
49                                    [freq <frequency>]
50                                    [dur <duration>]
51                                    [chan_alloc <location>]
52                                    [frame_len <frame length>]
53                                    [frame_blks <frame blocks>]]
54                              [meta
55                                    [pref_ctx <context>]
56                                    [stream_ctx <context>]
57                                    [program_info <program info>]
58                                    [lang <ISO 639-3 lang>]
59                                    [ccid_list <ccids>]
60                                    [parental_rating <rating>]
61                                    [program_info_uri <URI>]
62                                    [audio_active_state <state>]
63                                    [bcast_flag]
64                                    [extended <meta>]
65                                    [vendor <meta>]]
66      send                   : Send to Audio Stream [data]
67      bap_stats              : Sets or gets the statistics reporting interval in # of
68                              packets
69      set_location           : <direction: sink, source> <location bitmask>
70      set_context            : <direction: sink, source><context bitmask> <type:
71                              supported, available>
72
73
74.. csv-table:: State Machine Transitions
75   :header: "Command", "Depends", "Allowed States", "Next States"
76   :widths: auto
77
78   "init","none","any","none"
79   "discover","init","any","any"
80   "config","discover","idle/codec-configured/qos-configured","codec-configured"
81   "qos","config","codec-configured/qos-configured","qos-configured"
82   "enable","qos","qos-configured","enabling"
83   "connect","qos/enable","qos-configured/enabling","qos-configured/enabling"
84   "[start]","enable/connect","enabling","streaming"
85   "disable","enable", "enabling/streaming","disabling"
86   "[stop]","disable","disabling","qos-configure/idle"
87   "release","config","any","releasing/codec-configure/idle"
88   "list","none","any","none"
89   "select_unicast","none","any","none"
90   "send","enable","streaming","none"
91
92Example Central
93***************
94
95Connect and establish a sink stream:
96
97.. code-block:: console
98
99   uart:~$ bt init
100   uart:~$ bap init
101   uart:~$ bt connect <address>
102   uart:~$ gatt exchange-mtu
103   uart:~$ bap discover sink
104   uart:~$ bap config sink 0
105   uart:~$ bap qos
106   uart:~$ bap enable
107   uart:~$ bap connect
108
109Connect and establish a source stream:
110
111.. code-block:: console
112
113   uart:~$ bt init
114   uart:~$ bap init
115   uart:~$ bt connect <address>
116   uart:~$ gatt exchange-mtu
117   uart:~$ bap discover source
118   uart:~$ bap config source 0
119   uart:~$ bap qos
120   uart:~$ bap enable
121   uart:~$ bap connect
122   uart:~$ bap start
123
124Disconnect and release:
125
126.. code-block:: console
127
128   uart:~$ bap disable
129   uart:~$ bap release
130
131Example Peripheral
132******************
133
134Listen:
135
136.. code-block:: console
137
138   uart:~$ bt init
139   uart:~$ bap init
140   uart:~$ bt advertise on
141
142Server initiated disable and release:
143
144.. code-block:: console
145
146   uart:~$ bap disable
147   uart:~$ bap release
148
149Example Broadcast Source
150************************
151
152Create and establish a broadcast source stream:
153
154.. code-block:: console
155
156   uart:~$ bap init
157   uart:~$ bap create_broadcast
158   uart:~$ bap start_broadcast
159
160Stop and release a broadcast source stream:
161
162.. code-block:: console
163
164   uart:~$ bap stop_broadcast
165   uart:~$ bap delete_broadcast
166
167
168Example Broadcast Sink
169**********************
170
171Scan for and establish a broadcast sink stream.
172The command :code:`bap create_broadcast_sink` will either use existing periodic advertising
173sync (if exist) or start scanning and sync to the periodic advertising with the provided broadcast
174ID before syncing to the BIG.
175
176.. code-block:: console
177
178   uart:~$ bap init
179   uart:~$ bap create_broadcast_sink 0xEF6716
180   No PA sync available, starting scanning for broadcast_id
181   Found broadcaster with ID 0xEF6716 and addr 03:47:95:75:C0:08 (random) and sid 0x00
182   Attempting to PA sync to the broadcaster
183   PA synced to broadcast with broadcast ID 0xEF6716
184   Attempting to sync to the BIG
185   Received BASE from sink 0x20019080:
186   Presentation delay: 40000
187   Subgroup count: 1
188   Subgroup 0x20024182:
189      Codec Format: 0x06
190      Company ID  : 0x0000
191      Vendor ID   : 0x0000
192      codec cfg id 0x06 cid 0x0000 vid 0x0000 count 16
193         Codec specific configuration:
194         Sampling frequency: 16000 Hz (3)
195         Frame duration: 10000 us (1)
196         Channel allocation:
197                  Front left (0x00000001)
198                  Front right (0x00000002)
199         Octets per codec frame: 40
200         Codec specific metadata:
201         Streaming audio contexts:
202            Unspecified (0x0001)
203         BIS index: 0x01
204            codec cfg id 0x06 cid 0x0000 vid 0x0000 count 6
205            Codec specific configuration:
206               Channel allocation:
207                  Front left (0x00000001)
208            Codec specific metadata:
209               None
210         BIS index: 0x02
211            codec cfg id 0x06 cid 0x0000 vid 0x0000 count 6
212            Codec specific configuration:
213               Channel allocation:
214                  Front right (0x00000002)
215            Codec specific metadata:
216               None
217   Possible indexes: 0x01 0x02
218   Sink 0x20019110 is ready to sync without encryption
219   uart:~$ bap sync_broadcast 0x01
220
221
222Scan for and establish a broadcast sink stream by broadcast name
223----------------------------------------------------------------
224
225The command :code:`bap create_sink_by_name` will start scanning and sync to the periodic
226advertising with the provided broadcast name before syncing to the BIG.
227
228.. code-block:: console
229
230   uart:~$ bap init
231   uart:~$ bap create_sink_by_name "Test Broadcast"
232   Starting scanning for broadcast_name
233   Found matched broadcast name 'Test Broadcast' with address 03:47:95:75:C0:08 (random)
234   Found broadcaster with ID 0xEF6716 and addr 03:47:95:75:C0:08 (random) and sid 0x00
235   Attempting to PA sync to the broadcaster
236   PA synced to broadcast with broadcast ID 0xEF6716
237   Attempting to create the sink
238   Received BASE from sink 0x20019080:
239   Presentation delay: 40000
240   Subgroup count: 1
241   Subgroup 0x20024182:
242      Codec Format: 0x06
243      Company ID  : 0x0000
244      Vendor ID   : 0x0000
245      codec cfg id 0x06 cid 0x0000 vid 0x0000 count 16
246         Codec specific configuration:
247         Sampling frequency: 16000 Hz (3)
248         Frame duration: 10000 us (1)
249         Channel allocation:
250                  Front left (0x00000001)
251                  Front right (0x00000002)
252         Octets per codec frame: 40
253         Codec specific metadata:
254         Streaming audio contexts:
255            Unspecified (0x0001)
256         BIS index: 0x01
257            codec cfg id 0x06 cid 0x0000 vid 0x0000 count 6
258            Codec specific configuration:
259               Channel allocation:
260                  Front left (0x00000001)
261            Codec specific metadata:
262               None
263         BIS index: 0x02
264            codec cfg id 0x06 cid 0x0000 vid 0x0000 count 6
265            Codec specific configuration:
266               Channel allocation:
267                  Front right (0x00000002)
268            Codec specific metadata:
269               None
270   Possible indexes: 0x01 0x02
271   Sink 0x20019110 is ready to sync without encryption
272   uart:~$ bap sync_broadcast 0x01
273
274Syncing to encrypted broadcast
275------------------------------
276
277If the broadcast is encrypted, the broadcast code can be entered with the :code:`bap sync_broadcast`
278command as such:
279
280.. code-block:: console
281
282   Sink 0x20019110 is ready to sync with encryption
283   uart:~$ bap sync_broadcast 0x01 bcode 0102030405060708090a0b0c0d0e0f
284
285The broadcast code can be 1-16 values, either as a string or a hexadecimal value.
286
287.. code-block:: console
288
289   Sink 0x20019110 is ready to sync with encryption
290   uart:~$ bap sync_broadcast 0x01 bcode_str thisismycode
291
292Stop and release a broadcast sink stream:
293
294.. code-block:: console
295
296   uart:~$ bap stop_broadcast_sink
297   uart:~$ bap term_broadcast_sink
298
299Init
300****
301
302The :code:`init` command register local PAC records which are necessary to be
303able to configure stream and properly manage capabilities in use.
304
305.. csv-table:: State Machine Transitions
306   :header: "Depends", "Allowed States", "Next States"
307   :widths: auto
308
309   "none","any","none"
310
311.. code-block:: console
312
313   uart:~$ bap init
314
315Discover PAC(s) and ASE(s)
316**************************
317
318Once connected the :code:`discover` command discover PAC records and ASE
319characteristics representing remote endpoints.
320
321.. csv-table:: State Machine Transitions
322   :header: "Depends", "Allowed States", "Next States"
323   :widths: auto
324
325   "init","any","any"
326
327.. note::
328
329   Use command :code:`gatt exchange-mtu` to make sure the MTU is configured
330   properly.
331
332.. code-block:: console
333
334   uart:~$ gatt exchange-mtu
335   Exchange pending
336   Exchange successful
337   uart:~$ bap discover [type: sink, source]
338   uart:~$ bap discover sink
339   conn 0x2000b168: codec_cap 0x2001f8ec dir 0x02
340   codec cap id 0x06 cid 0x0000 vid 0x0000
341      Codec specific capabilities:
342         Supported sampling frequencies:
343            8000 Hz (0x0001)
344            11025 Hz (0x0002)
345            16000 Hz (0x0004)
346            22050 Hz (0x0008)
347            24000 Hz (0x0010)
348            32000 Hz (0x0020)
349            44100 Hz (0x0040)
350            48000 Hz (0x0080)
351            88200 Hz (0x0100)
352            96000 Hz (0x0200)
353            176400 Hz (0x0400)
354            192000 Hz (0x0800)
355            384000 Hz (0x1000)
356         Supported frame durations:
357            10 ms (0x02)
358         Supported channel counts:
359            1 channel (0x01)
360         Supported octets per codec frame counts:
361            Min: 40
362            Max: 120
363         Supported max codec frames per SDU: 1
364      Codec capabilities metadata:
365         Preferred audio contexts:
366            Conversational (0x0002)
367            Media (0x0004)
368   ep 0x81754e0
369   ep 0x81755d4
370   Discover complete: err 0
371
372Select preset
373*************
374
375The :code:`preset` command can be used to either print the default preset
376configuration or set a different one, it is worth noting that it doesn't change
377any stream previously configured.
378
379.. code-block:: console
380
381   uart:~$ bap preset
382   preset - <sink, source, broadcast> [preset]
383            [config
384                  [freq <frequency>]
385                  [dur <duration>]
386                  [chan_alloc <location>]
387                  [frame_len <frame length>]
388                  [frame_blks <frame blocks>]]
389            [meta
390                  [pref_ctx <context>]
391                  [stream_ctx <context>]
392                  [program_info <program info>]
393                  [lang <ISO 639-3 lang>]
394                  [ccid_list <ccids>]
395                  [parental_rating <rating>]
396                  [program_info_uri <URI>]
397                  [audio_active_state <state>]
398                  [bcast_flag]
399                  [extended <meta>]
400                  [vendor <meta>]]
401   uart:~$ bap preset sink
402   16_2_1
403   codec cfg id 0x06 cid 0x0000 vid 0x0000 count 16
404      Codec specific configuration:
405         Sampling frequency: 16000 Hz (3)
406         Frame duration: 10000 us (1)
407         Channel allocation:
408                     Front left (0x00000001)
409                     Front right (0x00000002)
410         Octets per codec frame: 40
411      Codec specific metadata:
412         Streaming audio contexts:
413            Game (0x0008)
414   QoS: interval 10000 framing 0x00 phy 0x02 sdu 40 rtn 2 latency 10 pd 40000
415
416   uart:~$ bap preset sink 32_2_1
417   32_2_1
418   codec cfg id 0x06 cid 0x0000 vid 0x0000 count 16
419      Codec specific configuration:
420         Sampling frequency: 32000 Hz (6)
421         Frame duration: 10000 us (1)
422         Channel allocation:
423                     Front left (0x00000001)
424                     Front right (0x00000002)
425         Octets per codec frame: 80
426      Codec specific metadata:
427         Streaming audio contexts:
428            Game (0x0008)
429      QoS: interval 10000 framing 0x00 phy 0x02 sdu 80 rtn 2 latency 10 pd 40000
430
431
432Configure preset
433****************
434
435The :code:`bap preset` command can also be used to configure the preset used for the subsequent
436commands. It is possible to add or set (or reset) any value. To reset the preset, the command can \
437simply be run without the :code:`config` or :code:`meta` parameter. The parameters are using the
438assigned numbers values.
439
440.. code-block:: console
441
442   uart:~$ bap preset sink 32_2_1
443   32_2_1
444   codec cfg id 0x06 cid 0x0000 vid 0x0000 count 16
445   data #0: type 0x01 value_len 1
446   00000000: 06                                               |.                |
447   data #1: type 0x02 value_len 1
448   00000000: 01                                               |.                |
449   data #2: type 0x03 value_len 4
450   00000000: 03 00 00 00                                      |....             |
451   data #3: type 0x04 value_len 2
452   00000000: 50 00                                            |P.               |
453   meta #0: type 0x02 value_len 2
454   00000000: 08 00                                            |..               |
455   QoS: interval 10000 framing 0x00 phy 0x02 sdu 80 rtn 2 latency 10 pd 40000
456
457   uart:~$ bap preset sink 32_2_1 config freq 10
458   32_2_1
459   codec cfg id 0x06 cid 0x0000 vid 0x0000 count 16
460   data #0: type 0x01 value_len 1
461   00000000: 0a                                               |.                |
462   data #1: type 0x02 value_len 1
463   00000000: 01                                               |.                |
464   data #2: type 0x03 value_len 4
465   00000000: 03 00 00 00                                      |....             |
466   data #3: type 0x04 value_len 2
467   00000000: 50 00                                            |P.               |
468   meta #0: type 0x02 value_len 2
469   00000000: 08 00                                            |..               |
470   QoS: interval 10000 framing 0x00 phy 0x02 sdu 80 rtn 2 latency 10 pd 40000
471
472   uart:~$ bap preset sink 32_2_1 config freq 10 meta lang "eng" stream_ctx 4
473   32_2_1
474   codec cfg id 0x06 cid 0x0000 vid 0x0000 count 16
475   data #0: type 0x01 value_len 1
476   00000000: 0a                                               |.                |
477   data #1: type 0x02 value_len 1
478   00000000: 01                                               |.                |
479   data #2: type 0x03 value_len 4
480   00000000: 03 00 00 00                                      |....             |
481   data #3: type 0x04 value_len 2
482   00000000: 50 00                                            |P.               |
483   meta #0: type 0x02 value_len 2
484   00000000: 04 00                                            |..               |
485   meta #1: type 0x04 value_len 3
486   00000000: 65 6e 67                                         |eng              |
487   QoS: interval 10000 framing 0x00 phy 0x02 sdu 80 rtn 2 latency 10 pd 40000
488
489Configure Codec
490***************
491
492The :code:`config` command attempts to configure a stream for the given
493direction using a preset codec configuration which can either be passed directly
494or in case it is omitted the default preset is used.
495
496.. csv-table:: State Machine Transitions
497   :header: "Depends", "Allowed States", "Next States"
498   :widths: auto
499
500   "discover","idle/codec-configured/qos-configured","codec-configured"
501
502.. code-block:: console
503
504   uart:~$ bap config <direction: sink, source> <index> [loc <loc_bits>] [preset <preset_name>]
505   uart:~$ bap config sink 0
506   Setting location to 0x00000000
507   ASE config: preset 16_2_1
508   stream 0x2000df70 config operation rsp_code 0 reason 0
509
510Configure Stream QoS
511********************
512
513The :code:`stream_qos` Sets a new stream QoS.
514
515.. code-block:: console
516
517   uart:~$ bap stream_qos <interval> [framing] [latency] [pd] [sdu] [phy] [rtn]
518   uart:~$ bap stream_qos 10
519
520Configure QoS
521*************
522
523The :code:`qos` command attempts to configure the stream QoS using the preset
524configuration, each individual QoS parameter can be set with use optional
525parameters.
526
527.. csv-table:: State Machine Transitions
528   :header: "Depends", "Allowed States", "Next States"
529   :widths: auto
530
531   "config","qos-configured/codec-configured","qos-configured"
532
533.. code-block:: console
534
535   uart:~$ bap qos
536
537Enable
538******
539
540The :code:`enable` command attempts to enable the stream previously configured.
541
542.. csv-table:: State Machine Transitions
543   :header: "Depends", "Allowed States", "Next States"
544   :widths: auto
545
546   "qos","qos-configured","enabling"
547
548.. code-block:: console
549
550   uart:~$ bap enable [context]
551   uart:~$ bap enable Media
552
553Connect
554*******
555
556The :code:`connect` command attempts to connect the stream previously configured.
557Sink streams will have to be started by the unicast server, and source streams will have to be
558started by the unicast client.
559
560.. csv-table:: State Machine Transitions
561   :header: "Depends", "Allowed States", "Next States"
562   :widths: auto
563
564   "qos/enable","qos-configured/enabling","qos-configured/enabling"
565
566.. code-block:: console
567
568   uart:~$ bap connect
569
570Start
571*****
572
573The :code:`start` command is only necessary when starting a source stream.
574
575.. csv-table:: State Machine Transitions
576   :header: "Depends", "Allowed States", "Next States"
577   :widths: auto
578
579   "enable/connect","enabling","streaming"
580
581.. code-block:: console
582
583   uart:~$ bap start
584
585Disable
586*******
587
588The :code:`disable` command attempts to disable the stream previously enabled,
589if the remote peer accepts then the ISO disconnection procedure is also
590initiated.
591
592.. csv-table:: State Machine Transitions
593   :header: "Depends", "Allowed States", "Next States"
594   :widths: auto
595
596   "enable","enabling/streaming","disabling"
597
598.. code-block:: console
599
600   uart:~$ bap disable
601
602Stop
603****
604
605The :code:`stop` command is only necessary when acting as a sink as it indicates
606to the source the stack is ready to stop receiving data.
607
608.. csv-table:: State Machine Transitions
609   :header: "Depends", "Allowed States", "Next States"
610   :widths: auto
611
612   "disable","disabling","qos-configure/idle"
613
614.. code-block:: console
615
616   uart:~$ bap stop
617
618Release
619*******
620
621The :code:`release` command releases the current stream and its configuration.
622
623.. csv-table:: State Machine Transitions
624   :header: "Depends", "Allowed States", "Next States"
625   :widths: auto
626
627   "config","any","releasing/codec-configure/idle"
628
629.. code-block:: console
630
631   uart:~$ bap release
632
633List
634****
635
636The :code:`list` command list the available streams.
637
638.. csv-table:: State Machine Transitions
639   :header: "Depends", "Allowed States", "Next States"
640   :widths: auto
641
642   "none","any","none"
643
644.. code-block:: console
645
646   uart:~$ bap list
647   *0: ase 0x01 dir 0x01 state 0x01
648
649Select Unicast
650**************
651
652The :code:`select_unicast` command set a unicast stream as default.
653
654.. csv-table:: State Machine Transitions
655   :header: "Depends", "Allowed States", "Next States"
656   :widths: auto
657
658   "none","any","none"
659
660.. code-block:: console
661
662   uart:~$ bap select <ase>
663   uart:~$ bap select 0x01
664   Default stream: 1
665
666To select a broadcast stream:
667
668.. code-block:: console
669
670   uart:~$ bap select 0x01 broadcast
671   Default stream: 1 (broadcast)
672
673Send
674****
675
676The :code:`send` command sends data over BAP Stream.
677
678.. csv-table:: State Machine Transitions
679   :header: "Depends", "Allowed States", "Next States"
680   :widths: auto
681
682   "enable","streaming","none"
683
684.. code-block:: console
685
686   uart:~$ bap send [count]
687   uart:~$ bap send
688   Audio sending...
689