michaelh/zephyr
1
0
Fork 0
Code Releases Activity

docs: Bluetooth: Move documentating for shell out of API

Browse source 
The API directory really isn't the best place for shell
documentation, which isn't API.

Created a new directory for Bluetooth shell documentation
and moved the ISO and LE Audio docs in there.

The existing bluetooth-shell.rst file was also split into
several new files, so that it follows the same structure.

Signed-off-by: Emil Gydesen <emil.gydesen@nordicsemi.no>
This commit is contained in:
Emil Gydesen 2024-11-19 12:00:27 +01:00 • committed by Henrik Brix Andersen
commit b20784dfbb
19 changed files with 537 additions and 507 deletions
Download patch file Download diff file Expand all files Collapse all files

8
MAINTAINERS.yml
View file

@ -390,8 +390,10 @@ Bluetooth Host:
- doc/connectivity/bluetooth/img/ctlr*
- doc/connectivity/bluetooth/api/audio/
- doc/connectivity/bluetooth/api/mesh/
- doc/connectivity/bluetooth/api/shell/iso.rst
- doc/connectivity/bluetooth/api/controller.rst
- doc/connectivity/bluetooth/shell/classic/a2dp.rst
- doc/connectivity/bluetooth/shell/host/iso.rst
- doc/connectivity/bluetooth/shell/audio/
- samples/bluetooth/bap*/
- samples/bluetooth/cap*/
- samples/bluetooth/hap*/
@ -475,6 +477,7 @@ Bluetooth Audio:
- tests/bluetooth/tester/overlay-le-audio.conf
- tests/bluetooth/tester/src/audio/
- doc/connectivity/bluetooth/api/audio/
- doc/connectivity/bluetooth/shell/audio/
- samples/bluetooth/bap*/
- samples/bluetooth/cap*/
- samples/bluetooth/hap*/
@ -493,6 +496,7 @@ Bluetooth Classic:
collaborators:
- jhedberg
files:
- doc/connectivity/bluetooth/shell/classic/a2dp.rst
- subsys/bluetooth/common/
- subsys/bluetooth/host/classic/
- include/zephyr/bluetooth/classic/
@ -512,7 +516,7 @@ Bluetooth ISO:
- rugeGerritsen
files:
- include/zephyr/bluetooth/iso.h
- doc/connectivity/bluetooth/api/shell/iso.rst
- doc/connectivity/bluetooth/shell/host/iso.rst
- samples/bluetooth/iso_*/
- subsys/bluetooth/Kconfig.iso
- subsys/bluetooth/host/iso.c

12
doc/_scripts/redirects.py
View file

@ -26,6 +26,18 @@ REDIRECTS = [
('boards/x86/intel_ehl/doc/index', 'boards/intel/ehl/doc/index'),
('boards/x86/intel_rpl/doc/index', 'boards/intel/rpl/doc/index'),
('boards/x86/rpl_crb/doc/index', 'boards/x86/intel_rpl/doc/index'),
('connectivity/bluetooth/api/audio/shell/bap', 'connectivity/bluetooth/shell/audio/bap'),
('connectivity/bluetooth/api/audio/shell/bap_broadcast_assistant', 'connectivity/bluetooth/shell/audio/bap_broadcast_assistant'),
('connectivity/bluetooth/api/audio/shell/bap_scan_delegator', 'connectivity/bluetooth/shell/audio/bap_scan_delegator'),
('connectivity/bluetooth/api/audio/shell/cap', 'connectivity/bluetooth/shell/audio/cap'),
('connectivity/bluetooth/api/audio/shell/ccp', 'connectivity/bluetooth/shell/audio/ccp'),
('connectivity/bluetooth/api/audio/shell/csip', 'connectivity/bluetooth/shell/audio/csip'),
('connectivity/bluetooth/api/audio/shell/gmap', 'connectivity/bluetooth/shell/audio/gmap'),
('connectivity/bluetooth/api/audio/shell/mcp', 'connectivity/bluetooth/shell/audio/mcp'),
('connectivity/bluetooth/api/audio/shell/pbp', 'connectivity/bluetooth/shell/audio/pbp'),
('connectivity/bluetooth/api/audio/shell/tmap', 'connectivity/bluetooth/shell/audio/tmap'),
('connectivity/bluetooth/api/shell/iso', 'connectivity/bluetooth/shell/host/iso'),
('connectivity/bluetooth/audio', 'connectivity/bluetooth/api/audio/audio'),
('connectivity/bluetooth/bap', 'connectivity/bluetooth/api/audio/bap'),
('connectivity/bluetooth/bluetooth-audio-arch', 'connectivity/bluetooth/bluetooth-le-audio-arch'),

11
doc/connectivity/bluetooth/api/index.rst
View file

@ -26,16 +26,6 @@ Bluetooth LE Audio
audio/media.rst
audio/microphone.rst
audio/volume.rst
audio/shell/bap.rst
audio/shell/bap_broadcast_assistant.rst
audio/shell/bap_scan_delegator.rst
audio/shell/cap.rst
audio/shell/ccp.rst
audio/shell/csip.rst
audio/shell/gmap.rst
audio/shell/mcp.rst
audio/shell/tmap.rst
audio/shell/pbp.rst
Bluetooth LE Host
=================
@ -45,7 +35,6 @@ Bluetooth LE Host
services.rst
gap.rst
shell/iso.rst
gatt.rst
att.rst

513
doc/connectivity/bluetooth/bluetooth-shell.rst
View file

@ -6,6 +6,27 @@ Shell
The Bluetooth Shell is an application based on the :ref:`shell_api` module. It offer a collection of
commands made to easily interact with the Bluetooth stack.
For specific Bluetooth functionality see also the following shell documentation
.. toctree::
:maxdepth: 1
shell/audio/bap.rst
shell/audio/bap_broadcast_assistant.rst
shell/audio/bap_scan_delegator.rst
shell/audio/cap.rst
shell/audio/ccp.rst
shell/audio/csip.rst
shell/audio/gmap.rst
shell/audio/mcp.rst
shell/audio/tmap.rst
shell/audio/pbp.rst
shell/classic/a2dp.rst
shell/host/gap.rst
shell/host/gatt.rst
shell/host/iso.rst
shell/host/l2cap.rst
Bluetooth Shell Setup and Usage
*******************************
@ -42,498 +63,6 @@ message is printed to confirm Bluetooth has been initialized.
[00:02:26.794,799] <inf> bt_hci_core: bt_dev_show_info: LMP: version 5.3 (0x0c) subver 0xffff
Identities
**********
Identities are a Zephyr host concept, allowing a single physical device to behave like multiple
logical Bluetooth devices.
The shell allows the creation of multiple identities, to a maximum that is set by the Kconfig symbol
:kconfig:option:`CONFIG_BT_ID_MAX`. To create a new identity, use :code:`bt id-create` command. You
can then use it by selecting it with its ID :code:`bt id-select <id>`. Finally, you can list all the
available identities with :code:`id-show`.
Scan for devices
****************
Start scanning by using the :code:`bt scan on` command. Depending on the environment you're in, you
may see a lot of lines printed on the shell. To stop the scan, run :code:`bt scan off`, the
scrolling should stop.
Here is an example of what you can expect:
.. code-block:: console
uart:~$ bt scan on
Bluetooth active scan enabled
[DEVICE]: CB:01:1A:2D:6E:AE (random), AD evt type 0, RSSI -78 C:1 S:1 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: 20:C2:EE:59:85:5B (random), AD evt type 3, RSSI -62 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: E3:72:76:87:2F:E8 (random), AD evt type 3, RSSI -74 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: 1E:19:25:8A:CB:84 (random), AD evt type 3, RSSI -67 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: 26:42:F3:D5:A0:86 (random), AD evt type 3, RSSI -73 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: 0C:61:D1:B9:5D:9E (random), AD evt type 3, RSSI -87 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: 20:C2:EE:59:85:5B (random), AD evt type 3, RSSI -66 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: 25:3F:7A:EE:0F:55 (random), AD evt type 3, RSSI -83 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
uart:~$ bt scan off
Scan successfully stopped
As you can see, this can lead to a high number of results. To reduce that number and easily find a
specific device, you can enable scan filters. There are four types of filters: by name, by RSSI, by
address and by periodic advertising interval. To apply a filter, use the :code:`bt scan-set-filter`
command followed by the type of filters. You can add multiple filters by using the commands again.
For example, if you want to look only for devices with the name *test shell*:
.. code-block:: console
uart:~$ bt scan-filter-set name "test shell"
Or if you want to look for devices at a very close range:
.. code-block:: console
uart:~$ bt scan-filter-set rssi -40
RSSI cutoff set at -40 dB
Finally, if you want to remove all filters:
.. code-block:: console
uart:~$ bt scan-filter-clear all
You can use the command :code:`bt scan on` to create an *active* scanner, meaning that the scanner
will ask the advertisers for more information by sending a *scan request* packet. Alternatively, you
can create a *passive scanner* by using the :code:`bt scan passive` command, so the scanner will not
ask the advertiser for more information.
Connecting to a device
**********************
To connect to a device, you need to know its address and type of address and use the
:code:`bt connect` command with the address and the type as arguments.
Here is an example:
.. code-block:: console
uart:~$ bt connect 52:84:F6:BD:CE:48 random
Connection pending
Connected: 52:84:F6:BD:CE:48 (random)
Remote LMP version 5.3 (0x0c) subversion 0xffff manufacturer 0x05f1
LE Features: 0x000000000001412f
LE PHY updated: TX PHY LE 2M, RX PHY LE 2M
LE conn param req: int (0x0018, 0x0028) lat 0 to 42
LE conn param updated: int 0x0028 lat 0 to 42
You can list the active connections of the shell using the :code:`bt connections` command. The shell
maximum number of connections is defined by :kconfig:option:`CONFIG_BT_MAX_CONN`. You can disconnect
from a connection with the
:code:`bt disconnect <address: XX:XX:XX:XX:XX:XX> <type: (public|random)>` command.
.. note::
If you were scanning just before, you can connect to the last scanned device by
simply running the :code:`bt connect` command.
Alternatively, you can use the :code:`bt connect-name <name>` command to automatically
enable scanning with a name filter and connect to the first match.
Advertising
***********
Begin advertising by using the :code:`bt advertise on` command. This will use the default parameters
and advertise a resolvable private address with the name of the device. You can choose to use the
identity address instead by running the :code:`bt advertise on identity` command. To stop
advertising use the :code:`bt advertise off` command.
To enable more advanced features of advertising, you should create an advertiser using the
:code:`bt adv-create` command. Parameters for the advertiser can be passed either at the creation of
it or by using the :code:`bt adv-param` command. To begin advertising with this newly created
advertiser, use the :code:`bt adv-start` command, and then the :code:`bt adv-stop` command to stop
advertising.
When using the custom advertisers, you can choose if it will be connectable or scannable. This leads
to four options: :code:`conn-scan`, :code:`conn-nscan`, :code:`nconn-scan` and :code:`nconn-nscan`.
Those parameters are mandatory when creating an advertiser or updating its parameters.
For example, if you want to create a connectable and scannable advertiser and start it:
.. code-block:: console
uart:~$ bt adv-create conn-scan
Created adv id: 0, adv: 0x200022f0
uart:~$ bt adv-start
Advertiser[0] 0x200022f0 set started
You may notice that with this, the custom advertiser does not advertise the device name; you need to
add it. Continuing from the previous example:
.. code-block:: console
uart:~$ bt adv-stop
Advertiser set stopped
uart:~$ bt adv-data dev-name
uart:~$ bt adv-start
Advertiser[0] 0x200022f0 set started
You should now see the name of the device in the advertising data. You can also set a custom name by
using :code:`name <custom name>` instead of :code:`dev-name`. It is also possible to set the
advertising data manually with the :code:`bt adv-data` command. The following example shows how
to set the advertiser name with it using raw advertising data:
.. code-block:: console
uart:~$ bt adv-create conn-scan
Created adv id: 0, adv: 0x20002348
uart:~$ bt adv-data 1009426C7565746F6F74682D5368656C6C
uart:~$ bt adv-start
Advertiser[0] 0x20002348 set started
The data must be formatted according to the Bluetooth Core Specification (see version 5.3, vol. 3,
part C, 11). In this example, the first octet is the size of the data (the data and one octet for
the data type), the second one is the type of data, ``0x09`` is the Complete Local Name and the
remaining data are the name in ASCII. So, on the other device you should see the name
*Bluetooth-Shell*.
When advertising, if others devices use an *active* scanner, you may receive *scan request* packets.
To visualize those packets, you can add :code:`scan-reports` to the parameters of your advertiser.
Directed Advertising
====================
It is possible to use directed advertising on the shell if you want to reconnect to a device. The
following example demonstrates how to create a directed advertiser with the address specified right
after the parameter :code:`directed`. The :code:`low` parameter indicates that we want to use the
low duty cycle mode, and the :code:`dir-rpa` parameter is required if the remote device is
privacy-enabled and supports address resolution of the target address in directed advertisement.
.. code-block:: console
uart:~$ bt adv-create conn-scan directed D7:54:03:CE:F3:B4 random low dir-rpa
Created adv id: 0, adv: 0x20002348
After that, you can start the advertiser and then the target device will be able to reconnect.
Extended Advertising
====================
Let's now have a look at some extended advertising features. To enable extended advertising, use the
``ext-adv`` parameter.
.. code-block:: console
uart:~$ bt adv-create conn-nscan ext-adv name-ad
Created adv id: 0, adv: 0x200022f0
uart:~$ bt adv-start
Advertiser[0] 0x200022f0 set started
This will create an extended advertiser, that is connectable and non-scannable.
Encrypted Advertising Data
==========================
Zephyr has support for the Encrypted Advertising Data feature. The :code:`bt encrypted-ad`
sub-commands allow managing the advertising data of a given advertiser.
To encrypt the advertising data, key materials need to be provided, that can be done with :code:`bt
encrypted-ad set-keys <session key> <init vector>`. The session key is 16 bytes long and the
initialisation vector is 8 bytes long.
You can add advertising data by using :code:`bt encrypted-ad add-ad` and :code:`bt encrypted-ad
add-ead`. The former will take add one advertising data structure (as defined in the Core
Specification), when the later will read the given data, encrypt them and then add the generated
encrypted advertising data structure. It's possible to mix encrypted and non-encrypted data, when
done adding advertising data, :code:`bt encrypted-ad commit-ad` can be used to apply the change to
the data to the selected advertiser. After that the advertiser can be started as described
previously. It's possible to clear the advertising data by using :code:`bt encrypted-ad clear-ad`.
On the Central side, it's possible to decrypt the received encrypted advertising data by setting the
correct keys material as described earlier and then enabling the decrypting of the data with
:code:`bt encrypted-ad decrypt-scan on`.
.. note::
To see the advertising data in the scan report :code:`bt scan-verbose-output` need to be
enabled.
.. note::
It's possible to increase the length of the advertising data by increasing the value of
:kconfig:option:`CONFIG_BT_CTLR_ADV_DATA_LEN_MAX` and
:kconfig:option:`CONFIG_BT_CTLR_SCAN_DATA_LEN_MAX`.
Here is a simple example demonstrating the usage of EAD:
.. tabs::
.. group-tab:: Peripheral
.. code-block:: console
uart:~$ bt init
...
uart:~$ bt adv-create conn-nscan ext-adv
Created adv id: 0, adv: 0x81769a0
uart:~$ bt encrypted-ad set-keys 9ba22d3824efc70feb800c80294cba38 2e83f3d4d47695b6
session key set to:
00000000: 9b a2 2d 38 24 ef c7 0f eb 80 0c 80 29 4c ba 38 |..-8$... ....)L.8|
initialisation vector set to:
00000000: 2e 83 f3 d4 d4 76 95 b6 |.....v.. |
uart:~$ bt encrypted-ad add-ad 06097368656C6C
uart:~$ bt encrypted-ad add-ead 03ffdead03ffbeef
uart:~$ bt encrypted-ad commit-ad
Advertising data for Advertiser[0] 0x81769a0 updated.
uart:~$ bt adv-start
Advertiser[0] 0x81769a0 set started
.. group-tab:: Central
.. code-block:: console
uart:~$ bt init
...
uart:~$ bt scan-verbose-output on
uart:~$ bt encrypted-ad set-keys 9ba22d3824efc70feb800c80294cba38 2e83f3d4d47695b6
session key set to:
00000000: 9b a2 2d 38 24 ef c7 0f eb 80 0c 80 29 4c ba 38 |..-8$... ....)L.8|
initialisation vector set to:
00000000: 2e 83 f3 d4 d4 76 95 b6 |.....v.. |
uart:~$ bt encrypted-ad decrypt-scan on
Received encrypted advertising data will now be decrypted using provided key materials.
uart:~$ bt scan on
Bluetooth active scan enabled
[DEVICE]: 68:49:30:68:49:30 (random), AD evt type 5, RSSI -59 shell C:1 S:0 D:0 SR:0 E:1 Prim: LE 1M, Secn: LE 2M, Interval: 0x0000 (0 us), SID: 0x0
[SCAN DATA START - EXT_ADV]
Type 0x09: shell
Type 0x31: Encrypted Advertising Data: 0xe2, 0x17, 0xed, 0x04, 0xe7, 0x02, 0x1d, 0xc9, 0x40, 0x07, uart:~0x18, 0x90, 0x6c, 0x4b, 0xfe, 0x34, 0xad
[START DECRYPTED DATA]
Type 0xff: 0xde, 0xad
Type 0xff: 0xbe, 0xef
[END DECRYPTED DATA]
[SCAN DATA END]
...
Filter Accept List
******************
It's possible to create a list of allowed addresses that can be used to
connect to those addresses automatically. Here is how to do it:
.. code-block:: console
uart:~$ bt fal-add 47:38:76:EA:29:36 random
uart:~$ bt fal-add 66:C8:80:2A:05:73 random
uart:~$ bt fal-connect on
The shell will then connect to the first available device. In the example, if both devices are
advertising at the same time, we will connect to the first address added to the list.
The Filter Accept List can also be used for scanning or advertising by using the option :code:`fal`.
For example, if we want to scan for a bunch of selected addresses, we can set up a Filter Accept
List:
.. code-block:: console
uart:~$ bt fal-add 65:4B:9E:83:AF:73 random
uart:~$ bt fal-add 73:72:82:B4:8F:B9 random
uart:~$ bt fal-add 5D:85:50:1C:72:64 random
uart:~$ bt scan on fal
You should see only those three addresses reported by the scanner.
Enabling security
*****************
When connected to a device, you can enable multiple levels of security, here is the list for
Bluetooth LE:
* **1** No encryption and no authentication;
* **2** Encryption and no authentication;
* **3** Encryption and authentication;
* **4** Bluetooth LE Secure Connection.
To enable security, use the :code:`bt security <level>` command. For levels requiring authentication
(level 3 and above), you must first set the authentication method. To do it, you can use the
:code:`bt auth all` command. After that, when you will set the security level, you will be asked to
confirm the passkey on both devices. On the shell side, do it with the command
:code:`bt auth-passkey-confirm`.
Pairing
=======
Enabling authentication requires the devices to be bondable. By default the shell is bondable. You
can make the shell not bondable using :code:`bt bondable off`. You can list all the devices you are
paired with using the command :code:`bt bonds`.
The maximum number of paired devices is set using :kconfig:option:`CONFIG_BT_MAX_PAIRED`. You can
remove a paired device using :code:`bt clear <address: XX:XX:XX:XX:XX:XX> <type: (public|random)>`
or remove all paired devices with the command :code:`bt clear all`.
GATT
****
The following examples assume that you have two devices already connected.
To perform service discovery on the client side, use the :code:`gatt discover` command. This should
print all the services that are available on the GATT server.
On the server side, you can register pre-defined test services using the :code:`gatt register`
command. When done, you should see the newly added services on the client side when running the
discovery command.
You can now subscribe to those new services on the client side. Here is an example on how to
subscribe to the test service:
.. code-block:: console
uart:~$ gatt subscribe 26 25
Subscribed
The server can now notify the client with the command :code:`gatt notify`.
Another option available through the GATT command is initiating the MTU exchange. To do it, use the
:code:`gatt exchange-mtu` command. To update the shell maximum MTU, you need to update Kconfig
symbols in the configuration file of the shell. For more details, see
:zephyr:code-sample:`bluetooth_mtu_update`.
L2CAP
*****
The :code:`l2cap` command exposes parts of the L2CAP API. The following example shows how to
register a LE PSM, connect to it from another device and send 3 packets of 14 octets each.
The example assumes that the two devices are already connected.
On device A, register the LE PSM:
.. code-block:: console
uart:~$ l2cap register 29
L2CAP psm 41 sec_level 1 registered
On device B, connect to the registered LE PSM and send data:
.. code-block:: console
uart:~$ l2cap connect 29
Chan sec: 1
L2CAP connection pending
Channel 0x20000210 connected
Channel 0x20000210 status 1
uart:~$ l2cap send 3 14
Rem 2
Rem 1
Rem 0
Outgoing data channel 0x20000210 transmitted
Outgoing data channel 0x20000210 transmitted
Outgoing data channel 0x20000210 transmitted
On device A, you should have received the data:
.. code-block:: console
Incoming conn 0x20002398
Channel 0x20000210 status 1
Channel 0x20000210 connected
Channel 0x20000210 requires buffer
Incoming data channel 0x20000210 len 14
00000000: ff ff ff ff ff ff ff ff ff ff ff ff ff ff |........ ...... |
Channel 0x20000210 requires buffer
Incoming data channel 0x20000210 len 14
00000000: ff ff ff ff ff ff ff ff ff ff ff ff ff ff |........ ...... |
Channel 0x20000210 requires buffer
Incoming data channel 0x20000210 len 14
00000000: ff ff ff ff ff ff ff ff ff ff ff ff ff ff |........ ...... |
A2DP
*****
The :code:`a2dp` command exposes parts of the A2DP API.
The following examples assume that you have two devices already connected.
Here is a example connecting two devices:
* Source and Sink sides register a2dp callbacks. using :code:`a2dp register_cb`.
* Source and Sink sides register stream endpoints. using :code:`a2dp register_ep source sbc` and :code:`a2dp register_ep sink sbc`.
* Source establish A2dp connection. It will create the AVDTP Signaling and Media L2CAP channels. using :code:`a2dp connect`.
* Source and Sink side can discover remote device's stream endpoints. using :code:`a2dp discover_peer_eps`
* Source or Sink configure the stream to create the stream after discover remote's endpoints. using :code:`a2dp configure`.
* Source or Sink establish the stream. using :code:`a2dp establish`.
* Source or Sink start the media. using :code:`a2dp start`.
* Source test the media sending. using :code:`a2dp send_media` to send one test packet data.
.. tabs::
.. group-tab:: Device A (Audio Source Side)
.. code-block:: console
uart:~$ a2dp register_cb
success
uart:~$ a2dp register_ep source sbc
SBC source endpoint is registered
uart:~$ a2dp connect
Bonded with XX:XX:XX:XX:XX:XX
Security changed: XX:XX:XX:XX:XX:XX level 2
a2dp connected
uart:~$ a2dp discover_peer_eps
endpoint id: 1, (sink), (idle):
codec type: SBC
sample frequency:
44100
48000
channel mode:
Mono
Stereo
Joint-Stereo
Block Length:
16
Subbands:
8
Allocation Method:
Loudness
Bitpool Range: 18 - 35
uart:~$ a2dp configure
success to configure
stream configured
uart:~$ a2dp establish
success to establish
stream established
uart:~$ a2dp start
success to start
stream started
uart:~$ a2dp send_media
frames num: 1, data length: 160
data: 1, 2, 3, 4, 5, 6 ......
.. group-tab:: Device B (Audio Sink Side)
.. code-block:: console
uart:~$ a2dp register_cb
success
uart:~$ a2dp register_ep sink sbc
SBC sink endpoint is registered
<after a2dp connect>
Connected: XX:XX:XX:XX:XX:XX
Bonded with XX:XX:XX:XX:XX:XX
Security changed: XX:XX:XX:XX:XX:XX level 2
a2dp connected
<after a2dp configure of source side>
receive requesting config and accept
SBC configure success
sample rate 44100Hz
stream configured
<after a2dp establish of source side>
receive requesting establishment and accept
stream established
<after a2dp start of source side>
receive requesting start and accept
stream started
<after a2dp send_media of source side>
received, num of frames: 1, data length: 160
data: 1, 2, 3, 4, 5, 6 ......
...
Logging
*******

0
doc/connectivity/bluetooth/api/audio/shell/bap.rst → doc/connectivity/bluetooth/shell/audio/bap.rst
View file

0
doc/connectivity/bluetooth/api/audio/shell/bap_broadcast_assistant.rst → doc/connectivity/bluetooth/shell/audio/bap_broadcast_assistant.rst
View file

0
doc/connectivity/bluetooth/api/audio/shell/bap_scan_delegator.rst → doc/connectivity/bluetooth/shell/audio/bap_scan_delegator.rst
View file

0
doc/connectivity/bluetooth/api/audio/shell/cap.rst → doc/connectivity/bluetooth/shell/audio/cap.rst
View file

0
doc/connectivity/bluetooth/api/audio/shell/ccp.rst → doc/connectivity/bluetooth/shell/audio/ccp.rst
View file

0
doc/connectivity/bluetooth/api/audio/shell/csip.rst → doc/connectivity/bluetooth/shell/audio/csip.rst
View file

0
doc/connectivity/bluetooth/api/audio/shell/gmap.rst → doc/connectivity/bluetooth/shell/audio/gmap.rst
View file

0
doc/connectivity/bluetooth/api/audio/shell/mcp.rst → doc/connectivity/bluetooth/shell/audio/mcp.rst
View file

0
doc/connectivity/bluetooth/api/audio/shell/pbp.rst → doc/connectivity/bluetooth/shell/audio/pbp.rst
View file

0
doc/connectivity/bluetooth/api/audio/shell/tmap.rst → doc/connectivity/bluetooth/shell/audio/tmap.rst
View file

89
doc/connectivity/bluetooth/shell/classic/a2dp.rst Normal file
View file

@ -0,0 +1,89 @@
Bluetooth: A2DP Shell
#####################
The :code:`a2dp` command exposes parts of the A2DP API.
The following examples assume that you have two devices already connected.
Here is a example connecting two devices:
* Source and Sink sides register a2dp callbacks. using :code:`a2dp register_cb`.
* Source and Sink sides register stream endpoints. using :code:`a2dp register_ep source sbc` and :code:`a2dp register_ep sink sbc`.
* Source establish A2dp connection. It will create the AVDTP Signaling and Media L2CAP channels. using :code:`a2dp connect`.
* Source and Sink side can discover remote device's stream endpoints. using :code:`a2dp discover_peer_eps`
* Source or Sink configure the stream to create the stream after discover remote's endpoints. using :code:`a2dp configure`.
* Source or Sink establish the stream. using :code:`a2dp establish`.
* Source or Sink start the media. using :code:`a2dp start`.
* Source test the media sending. using :code:`a2dp send_media` to send one test packet data.
.. tabs::
.. group-tab:: Device A (Audio Source Side)
.. code-block:: console
uart:~$ a2dp register_cb
success
uart:~$ a2dp register_ep source sbc
SBC source endpoint is registered
uart:~$ a2dp connect
Bonded with XX:XX:XX:XX:XX:XX
Security changed: XX:XX:XX:XX:XX:XX level 2
a2dp connected
uart:~$ a2dp discover_peer_eps
endpoint id: 1, (sink), (idle):
codec type: SBC
sample frequency:
44100
48000
channel mode:
Mono
Stereo
Joint-Stereo
Block Length:
16
Subbands:
8
Allocation Method:
Loudness
Bitpool Range: 18 - 35
uart:~$ a2dp configure
success to configure
stream configured
uart:~$ a2dp establish
success to establish
stream established
uart:~$ a2dp start
success to start
stream started
uart:~$ a2dp send_media
frames num: 1, data length: 160
data: 1, 2, 3, 4, 5, 6 ......
.. group-tab:: Device B (Audio Sink Side)
.. code-block:: console
uart:~$ a2dp register_cb
success
uart:~$ a2dp register_ep sink sbc
SBC sink endpoint is registered
<after a2dp connect>
Connected: XX:XX:XX:XX:XX:XX
Bonded with XX:XX:XX:XX:XX:XX
Security changed: XX:XX:XX:XX:XX:XX level 2
a2dp connected
<after a2dp configure of source side>
receive requesting config and accept
SBC configure success
sample rate 44100Hz
stream configured
<after a2dp establish of source side>
receive requesting establishment and accept
stream established
<after a2dp start of source side>
receive requesting start and accept
stream started
<after a2dp send_media of source side>
received, num of frames: 1, data length: 160
data: 1, 2, 3, 4, 5, 6 ......
...

333
doc/connectivity/bluetooth/shell/host/gap.rst Normal file
View file

@ -0,0 +1,333 @@
Bluetooth: GAP Shell
####################
The GAP shell is the "main" shell of Bluetooth and handles connection management, scanning,
advertising, and more.
Identities
**********
Identities are a Zephyr host concept, allowing a single physical device to behave like multiple
logical Bluetooth devices.
The shell allows the creation of multiple identities, to a maximum that is set by the Kconfig symbol
:kconfig:option:`CONFIG_BT_ID_MAX`. To create a new identity, use :code:`bt id-create` command. You
can then use it by selecting it with its ID :code:`bt id-select <id>`. Finally, you can list all the
available identities with :code:`id-show`.
Scan for devices
****************
Start scanning by using the :code:`bt scan on` command. Depending on the environment you're in, you
may see a lot of lines printed on the shell. To stop the scan, run :code:`bt scan off`, the
scrolling should stop.
Here is an example of what you can expect:
.. code-block:: console
uart:~$ bt scan on
Bluetooth active scan enabled
[DEVICE]: CB:01:1A:2D:6E:AE (random), AD evt type 0, RSSI -78 C:1 S:1 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: 20:C2:EE:59:85:5B (random), AD evt type 3, RSSI -62 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: E3:72:76:87:2F:E8 (random), AD evt type 3, RSSI -74 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: 1E:19:25:8A:CB:84 (random), AD evt type 3, RSSI -67 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: 26:42:F3:D5:A0:86 (random), AD evt type 3, RSSI -73 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: 0C:61:D1:B9:5D:9E (random), AD evt type 3, RSSI -87 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: 20:C2:EE:59:85:5B (random), AD evt type 3, RSSI -66 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
[DEVICE]: 25:3F:7A:EE:0F:55 (random), AD evt type 3, RSSI -83 C:0 S:0 D:0 SR:0 E:0 Prim: LE 1M, Secn: No packets, Interval: 0x0000 (0 us), SID: 0xff
uart:~$ bt scan off
Scan successfully stopped
As you can see, this can lead to a high number of results. To reduce that number and easily find a
specific device, you can enable scan filters. There are four types of filters: by name, by RSSI, by
address and by periodic advertising interval. To apply a filter, use the :code:`bt scan-set-filter`
command followed by the type of filters. You can add multiple filters by using the commands again.
For example, if you want to look only for devices with the name *test shell*:
.. code-block:: console
uart:~$ bt scan-filter-set name "test shell"
Or if you want to look for devices at a very close range:
.. code-block:: console
uart:~$ bt scan-filter-set rssi -40
RSSI cutoff set at -40 dB
Finally, if you want to remove all filters:
.. code-block:: console
uart:~$ bt scan-filter-clear all
You can use the command :code:`bt scan on` to create an *active* scanner, meaning that the scanner
will ask the advertisers for more information by sending a *scan request* packet. Alternatively, you
can create a *passive scanner* by using the :code:`bt scan passive` command, so the scanner will not
ask the advertiser for more information.
Connecting to a device
**********************
To connect to a device, you need to know its address and type of address and use the
:code:`bt connect` command with the address and the type as arguments.
Here is an example:
.. code-block:: console
uart:~$ bt connect 52:84:F6:BD:CE:48 random
Connection pending
Connected: 52:84:F6:BD:CE:48 (random)
Remote LMP version 5.3 (0x0c) subversion 0xffff manufacturer 0x05f1
LE Features: 0x000000000001412f
LE PHY updated: TX PHY LE 2M, RX PHY LE 2M
LE conn param req: int (0x0018, 0x0028) lat 0 to 42
LE conn param updated: int 0x0028 lat 0 to 42
You can list the active connections of the shell using the :code:`bt connections` command. The shell
maximum number of connections is defined by :kconfig:option:`CONFIG_BT_MAX_CONN`. You can disconnect
from a connection with the
:code:`bt disconnect <address: XX:XX:XX:XX:XX:XX> <type: (public|random)>` command.
.. note::
If you were scanning just before, you can connect to the last scanned device by
simply running the :code:`bt connect` command.
Alternatively, you can use the :code:`bt connect-name <name>` command to automatically
enable scanning with a name filter and connect to the first match.
Advertising
***********
Begin advertising by using the :code:`bt advertise on` command. This will use the default parameters
and advertise a resolvable private address with the name of the device. You can choose to use the
identity address instead by running the :code:`bt advertise on identity` command. To stop
advertising use the :code:`bt advertise off` command.
To enable more advanced features of advertising, you should create an advertiser using the
:code:`bt adv-create` command. Parameters for the advertiser can be passed either at the creation of
it or by using the :code:`bt adv-param` command. To begin advertising with this newly created
advertiser, use the :code:`bt adv-start` command, and then the :code:`bt adv-stop` command to stop
advertising.
When using the custom advertisers, you can choose if it will be connectable or scannable. This leads
to four options: :code:`conn-scan`, :code:`conn-nscan`, :code:`nconn-scan` and :code:`nconn-nscan`.
Those parameters are mandatory when creating an advertiser or updating its parameters.
For example, if you want to create a connectable and scannable advertiser and start it:
.. code-block:: console
uart:~$ bt adv-create conn-scan
Created adv id: 0, adv: 0x200022f0
uart:~$ bt adv-start
Advertiser[0] 0x200022f0 set started
You may notice that with this, the custom advertiser does not advertise the device name; you need to
add it. Continuing from the previous example:
.. code-block:: console
uart:~$ bt adv-stop
Advertiser set stopped
uart:~$ bt adv-data dev-name
uart:~$ bt adv-start
Advertiser[0] 0x200022f0 set started
You should now see the name of the device in the advertising data. You can also set a custom name by
using :code:`name <custom name>` instead of :code:`dev-name`. It is also possible to set the
advertising data manually with the :code:`bt adv-data` command. The following example shows how
to set the advertiser name with it using raw advertising data:
.. code-block:: console
uart:~$ bt adv-create conn-scan
Created adv id: 0, adv: 0x20002348
uart:~$ bt adv-data 1009426C7565746F6F74682D5368656C6C
uart:~$ bt adv-start
Advertiser[0] 0x20002348 set started
The data must be formatted according to the Bluetooth Core Specification (see version 5.3, vol. 3,
part C, 11). In this example, the first octet is the size of the data (the data and one octet for
the data type), the second one is the type of data, ``0x09`` is the Complete Local Name and the
remaining data are the name in ASCII. So, on the other device you should see the name
*Bluetooth-Shell*.
When advertising, if others devices use an *active* scanner, you may receive *scan request* packets.
To visualize those packets, you can add :code:`scan-reports` to the parameters of your advertiser.
Directed Advertising
====================
It is possible to use directed advertising on the shell if you want to reconnect to a device. The
following example demonstrates how to create a directed advertiser with the address specified right
after the parameter :code:`directed`. The :code:`low` parameter indicates that we want to use the
low duty cycle mode, and the :code:`dir-rpa` parameter is required if the remote device is
privacy-enabled and supports address resolution of the target address in directed advertisement.
.. code-block:: console
uart:~$ bt adv-create conn-scan directed D7:54:03:CE:F3:B4 random low dir-rpa
Created adv id: 0, adv: 0x20002348
After that, you can start the advertiser and then the target device will be able to reconnect.
Extended Advertising
====================
Let's now have a look at some extended advertising features. To enable extended advertising, use the
``ext-adv`` parameter.
.. code-block:: console
uart:~$ bt adv-create conn-nscan ext-adv name-ad
Created adv id: 0, adv: 0x200022f0
uart:~$ bt adv-start
Advertiser[0] 0x200022f0 set started
This will create an extended advertiser, that is connectable and non-scannable.
Encrypted Advertising Data
==========================
Zephyr has support for the Encrypted Advertising Data feature. The :code:`bt encrypted-ad`
sub-commands allow managing the advertising data of a given advertiser.
To encrypt the advertising data, key materials need to be provided, that can be done with :code:`bt
encrypted-ad set-keys <session key> <init vector>`. The session key is 16 bytes long and the
initialisation vector is 8 bytes long.
You can add advertising data by using :code:`bt encrypted-ad add-ad` and :code:`bt encrypted-ad
add-ead`. The former will take add one advertising data structure (as defined in the Core
Specification), when the later will read the given data, encrypt them and then add the generated
encrypted advertising data structure. It's possible to mix encrypted and non-encrypted data, when
done adding advertising data, :code:`bt encrypted-ad commit-ad` can be used to apply the change to
the data to the selected advertiser. After that the advertiser can be started as described
previously. It's possible to clear the advertising data by using :code:`bt encrypted-ad clear-ad`.
On the Central side, it's possible to decrypt the received encrypted advertising data by setting the
correct keys material as described earlier and then enabling the decrypting of the data with
:code:`bt encrypted-ad decrypt-scan on`.
.. note::
To see the advertising data in the scan report :code:`bt scan-verbose-output` need to be
enabled.
.. note::
It's possible to increase the length of the advertising data by increasing the value of
:kconfig:option:`CONFIG_BT_CTLR_ADV_DATA_LEN_MAX` and
:kconfig:option:`CONFIG_BT_CTLR_SCAN_DATA_LEN_MAX`.
Here is a simple example demonstrating the usage of EAD:
.. tabs::
.. group-tab:: Peripheral
.. code-block:: console
uart:~$ bt init
...
uart:~$ bt adv-create conn-nscan ext-adv
Created adv id: 0, adv: 0x81769a0
uart:~$ bt encrypted-ad set-keys 9ba22d3824efc70feb800c80294cba38 2e83f3d4d47695b6
session key set to:
00000000: 9b a2 2d 38 24 ef c7 0f eb 80 0c 80 29 4c ba 38 |..-8$... ....)L.8|
initialisation vector set to:
00000000: 2e 83 f3 d4 d4 76 95 b6 |.....v.. |
uart:~$ bt encrypted-ad add-ad 06097368656C6C
uart:~$ bt encrypted-ad add-ead 03ffdead03ffbeef
uart:~$ bt encrypted-ad commit-ad
Advertising data for Advertiser[0] 0x81769a0 updated.
uart:~$ bt adv-start
Advertiser[0] 0x81769a0 set started
.. group-tab:: Central
.. code-block:: console
uart:~$ bt init
...
uart:~$ bt scan-verbose-output on
uart:~$ bt encrypted-ad set-keys 9ba22d3824efc70feb800c80294cba38 2e83f3d4d47695b6
session key set to:
00000000: 9b a2 2d 38 24 ef c7 0f eb 80 0c 80 29 4c ba 38 |..-8$... ....)L.8|
initialisation vector set to:
00000000: 2e 83 f3 d4 d4 76 95 b6 |.....v.. |
uart:~$ bt encrypted-ad decrypt-scan on
Received encrypted advertising data will now be decrypted using provided key materials.
uart:~$ bt scan on
Bluetooth active scan enabled
[DEVICE]: 68:49:30:68:49:30 (random), AD evt type 5, RSSI -59 shell C:1 S:0 D:0 SR:0 E:1 Prim: LE 1M, Secn: LE 2M, Interval: 0x0000 (0 us), SID: 0x0
[SCAN DATA START - EXT_ADV]
Type 0x09: shell
Type 0x31: Encrypted Advertising Data: 0xe2, 0x17, 0xed, 0x04, 0xe7, 0x02, 0x1d, 0xc9, 0x40, 0x07, uart:~0x18, 0x90, 0x6c, 0x4b, 0xfe, 0x34, 0xad
[START DECRYPTED DATA]
Type 0xff: 0xde, 0xad
Type 0xff: 0xbe, 0xef
[END DECRYPTED DATA]
[SCAN DATA END]
...
Filter Accept List
******************
It's possible to create a list of allowed addresses that can be used to
connect to those addresses automatically. Here is how to do it:
.. code-block:: console
uart:~$ bt fal-add 47:38:76:EA:29:36 random
uart:~$ bt fal-add 66:C8:80:2A:05:73 random
uart:~$ bt fal-connect on
The shell will then connect to the first available device. In the example, if both devices are
advertising at the same time, we will connect to the first address added to the list.
The Filter Accept List can also be used for scanning or advertising by using the option :code:`fal`.
For example, if we want to scan for a bunch of selected addresses, we can set up a Filter Accept
List:
.. code-block:: console
uart:~$ bt fal-add 65:4B:9E:83:AF:73 random
uart:~$ bt fal-add 73:72:82:B4:8F:B9 random
uart:~$ bt fal-add 5D:85:50:1C:72:64 random
uart:~$ bt scan on fal
You should see only those three addresses reported by the scanner.
Enabling security
*****************
When connected to a device, you can enable multiple levels of security, here is the list for
Bluetooth LE:
* **1** No encryption and no authentication;
* **2** Encryption and no authentication;
* **3** Encryption and authentication;
* **4** Bluetooth LE Secure Connection.
To enable security, use the :code:`bt security <level>` command. For levels requiring authentication
(level 3 and above), you must first set the authentication method. To do it, you can use the
:code:`bt auth all` command. After that, when you will set the security level, you will be asked to
confirm the passkey on both devices. On the shell side, do it with the command
:code:`bt auth-passkey-confirm`.
Pairing
=======
Enabling authentication requires the devices to be bondable. By default the shell is bondable. You
can make the shell not bondable using :code:`bt bondable off`. You can list all the devices you are
paired with using the command :code:`bt bonds`.
The maximum number of paired devices is set using :kconfig:option:`CONFIG_BT_MAX_PAIRED`. You can
remove a paired device using :code:`bt clear <address: XX:XX:XX:XX:XX:XX> <type: (public|random)>`
or remove all paired devices with the command :code:`bt clear all`.

26
doc/connectivity/bluetooth/shell/host/gatt.rst Normal file
View file

@ -0,0 +1,26 @@
Bluetooth: GATT Shell
#####################
The following examples assume that you have two devices already connected.
To perform service discovery on the client side, use the :code:`gatt discover` command. This should
print all the services that are available on the GATT server.
On the server side, you can register pre-defined test services using the :code:`gatt register`
command. When done, you should see the newly added services on the client side when running the
discovery command.
You can now subscribe to those new services on the client side. Here is an example on how to
subscribe to the test service:
.. code-block:: console
uart:~$ gatt subscribe 26 25
Subscribed
The server can now notify the client with the command :code:`gatt notify`.
Another option available through the GATT command is initiating the MTU exchange. To do it, use the
:code:`gatt exchange-mtu` command. To update the shell maximum MTU, you need to update Kconfig
symbols in the configuration file of the shell. For more details, see
:zephyr:code-sample:`bluetooth_mtu_update`.

4
doc/connectivity/bluetooth/api/shell/iso.rst → doc/connectivity/bluetooth/shell/host/iso.rst
View file

@ -1,5 +1,5 @@
Bluetooth: Isochronous Channels
################################
Bluetooth: Isochronous Channels Shell
#####################################
Commands
********

48
doc/connectivity/bluetooth/shell/host/l2cap.rst Normal file
View file

@ -0,0 +1,48 @@
Bluetooth: L2CAP Shell
######################
The :code:`l2cap` command exposes parts of the L2CAP API. The following example shows how to
register a LE PSM, connect to it from another device and send 3 packets of 14 octets each.
The example assumes that the two devices are already connected.
On device A, register the LE PSM:
.. code-block:: console
uart:~$ l2cap register 29
L2CAP psm 41 sec_level 1 registered
On device B, connect to the registered LE PSM and send data:
.. code-block:: console
uart:~$ l2cap connect 29
Chan sec: 1
L2CAP connection pending
Channel 0x20000210 connected
Channel 0x20000210 status 1
uart:~$ l2cap send 3 14
Rem 2
Rem 1
Rem 0
Outgoing data channel 0x20000210 transmitted
Outgoing data channel 0x20000210 transmitted
Outgoing data channel 0x20000210 transmitted
On device A, you should have received the data:
.. code-block:: console
Incoming conn 0x20002398
Channel 0x20000210 status 1
Channel 0x20000210 connected
Channel 0x20000210 requires buffer
Incoming data channel 0x20000210 len 14
00000000: ff ff ff ff ff ff ff ff ff ff ff ff ff ff |........ ...... |
Channel 0x20000210 requires buffer
Incoming data channel 0x20000210 len 14
00000000: ff ff ff ff ff ff ff ff ff ff ff ff ff ff |........ ...... |
Channel 0x20000210 requires buffer
Incoming data channel 0x20000210 len 14
00000000: ff ff ff ff ff ff ff ff ff ff ff ff ff ff |........ ...... |