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