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 `. 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 ` 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 ` 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 ` 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 `. 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 ` 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 ` or remove all paired devices with the command :code:`bt clear all`.