docs/bluetooth.md

   1 ## Bluetooth/BLE Setup and Test Procedure
   2
   3 * Ensure that bluez is installed on Raspberry Pi and it is downloaded in source format as well.
   4 * In following test, Android device was used as a BT/BLE test device. For BLE testing, [nRF connect for mobile APP](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp&hl=en_IN) was used.
   5 * Ensure that `hci0` interface is visible. To check that, run `hciconfig`.
   6 ```
   7 hci0:   Type: Primary  Bus: SDIO
   8         BD Address: 3C:71:BF:9A:C2:46  ACL MTU: 1021:9  SCO MTU: 255:4
   9         UP RUNNING PSCAN
  10         RX bytes:8801 acl:1000 sco:0 events:406 errors:0
  11         TX bytes:5097 acl:147 sco:0 commands:52 errors:0
  12 ```
  13 * This interface supports all standard HCI commands. Use standard hci tools to control and configure this interface.
  14
  15 ### BT/BLE Test procedure
  16
  17 * ESP-Hosted related BR/EDR 4.2 and BLE 4.2 functionalities are tested with `bluez` 5.50+.
  18 Whereas BLE 5.0 functionalities are tested with `bluez` 5.45+.
  19 * We suggest latest stable `bluez` version to be used. Any other bluetooth stack instead of `bluez` also could be used.
  20 * To upgrade `bluez` for particular version, follow this [link](https://scribles.net/updating-bluez-on-raspberry-pi-from-5-43-to-5-50/). Replace bluez `older version` to `expected version` while following mentioned link.
  21
  22 ##### GATT server
  23 Steps:
  24 1. Run `sudo bluetoothctl`.
  25 2. Run `list` to get MAC address of ESP.
  26 3. To set device name, run `menu advertise`. Then `name <enter_any_name>`.
  27 4. To come back to main menu, run `back`.
  28 5. To start advertising, run `advertise on`.
  29 Perform below steps on Mobile Phone:
  30 6. Turn on mobile phone's bluetooth. Open nRF connect application, ESP's MAC address will be displayed under `SCANNER` tab as a result of scan.
  31 7. Click on connect. Client tab will be open. Click on `Generic Attribute` option.
  32 8. Perform read/write on listed characteristics fields in `Generic Attribute` service.
  33 To disconnet:
  34 9. Run `disconnect <MAC_ADDRESS_of_gatt_client>` on linux host's `bluetoothctrl` OR click on `DISCONNECT` in nRF connect application's `GATT client` screen.
  35
  36 ##### GATT Client
  37
  38 1. Run `sudo bluetoothctl`.
  39 2. To Turn on power, run `power on`.
  40 3. Make device discoverable, run `discoverable on`.
  41 4. Make device pairable, run `pairable on`.
  42 5. Set current agent to default, run `default-agent`.
  43 6. Turn on bluetooth support, run `agent on`.
  44 7. Turn on mobile phone's bluetooth so that linux host can detect it.
  45 8. Start scanning, run `scan on`.
  46 9. Once mobile phone's MAC address is listed in scan list, stop scanning, run `scan off`.
  47 10. Start btmon to collect log in separate terminal window, run `sudo btmon &`.
  48 11. To trust, run `trust <MAC address of mobile phone>`.
  49 12. To pair, run `pair <MAC address of mobile phone>`.
  50 13. To connect, run `connect <MAC address of mobile phone>`.
  51 14. Once connected, please run `discoverable off`.
  52 15. Go to gatt menu, run `menu gatt`.
  53 16. list available attributes, run `list-attributes`.
  54 17. select characteristic of service, run `select-attribute <characteristic_of_service>`.
  55 18. perform read/write operation on selected characteristic.
  56 19. To disconnect, run `disconnect <MAC_ADDRESS_of_gatt_server>`.
  57
  58 ##### BT scan
  59
  60 Run `hcitool scan` for BT device scanning.
  61
  62 ##### BLE scan
  63
  64 Run `hcitool lescan` for BLE device scanning.
  65
  66 ## BLE 5.0 testing
  67
  68 Only ESP32-C3 HCI controller supports BLE 5.0. Several new features are introduced in BLE 5.0. The major areas of improvement are:
  69 1. Slot Availability Mask (SAM)
  70 2. 2 Msym/s PHY for LE
  71 3. LE Long Range
  72 4. High Duty Cycle Non-Connectable Advertising
  73 5. LE Advertising Extensions
  74 6. LE Channel Selection Algorithm #2
  75
  76 To test BLE 5.0 on Raspberry Pi, minimum `bluez` version `5.45` and above required. If `bluez` version is less than 5.45 ,then upgrade `bluez` version.
  77
  78 Check current `bluez` version by running following command on Raspberry Pi:
  79
  80 ```
  81 $ bluetoothctl -v
  82 ```
  83 :warning: `hcitool lescan` is deprecated. Please dont use it.
  84
  85 ##### Basic scan, pair, connect
  86
  87 Execute following steps on linux host.
  88 Steps:
  89 1. Run `sudo bluetoothctl`.
  90 2. To Turn on power, run `power on`.
  91 3. Make device discoverable, run `discoverable on`.
  92 4. Make device pairable on, run `pairable on`.
  93 5. Set current agent to default, run `default-agent`.
  94 6. Turn on bluetooth support, run `agent on`.
  95 7. Start btmon to collect log in separate terminal window, run `sudo btmon &`.
  96 8. Turn on mobile phone's bluetooth so that linux host can detect it.
  97 9. Start scanning, run `scan on` in bluetoothctl window.
  98 10. Once mobile phone's MAC address is listed in scan list, stop scanning, run `scan off`.
  99 11. To trust, run `trust <MAC address of your device>`.
 100 12. To pair, run `pair <MAC address of your device>`.
 101 13. To connect, run `connect <MAC address of your device>`.
 102 14. Once connected, please run `discoverable off`.
 103
 104 ##### GATT Server
 105
 106 BLE 5.0 has backword compability. It can connect with BLE4.2 devices.
 107 Below example demonstrate linux host as GATT server and mobile phone as GATT client. We are using `nRF connect` application for GATT client operartion.
 108
 109 Follow section [2.1.1](#211-gatt-server) for GATT server connections.
 110
 111 ##### GATT client
 112
 113 BLE 5.0 has backword compability. It can connect with BLE4.2 devices.
 114 Below example demonstrate linux host as GATT client and mobile phone as GATT server. We are using `nRF connect` application for GATT server operartion.
 115
 116 Follow section [2.1.2](#212-gatt-client) for GATT client connections.
 117
 118 ##### 1M, 2M, CODED phy for LE
 119
 120 BLE5.0 supports 1M, 2M and CODED phy. To use 2M and CODED phy for gatt read/write procedure as follow:
 121
 122 Note:
 123 * Default selected phy is 1M. To perform gatt read/write with BLE5.0 peripheral, both host and peripheral must have same phy configuration.
 124
 125 * 'PHY' feature in BLE 5.0 is verified with btmgmt tool from bluez version 5.56+.
 126
 127 * If `bluez` version is less than 5.56 ,then upgrade `bluez` version.
 128
 129 ######  Using 1M phy:
 130 1M phy is default phy for BLE5.0. Follow above mentioned steps in section 2.2.1
 131 for connection. After connection follow gatt read/write from gatt menu in bluetoothctl.
 132
 133 ###### Using 2M phy:
 134 2M phy can not use for connection in BLE5.0 . So configure phy as 1M and 2M both, make connection with other BLE5.0 device and then set phy as 2M. On peripheral side make primary phy as 1M and secondary phy as 2M.
 135
 136 Steps:
 137 1. To configure phy as 1M and 2M both, run `sudo hcitool cmd 08 31 03 03 03`.
 138 2. To check selected phy, Go to `bluez-5.56` directory. Run `sudo ./tools/btmgmt --index hci0` and run `phy`.
 139 3. Connect to BLE5.0 device using above mentioned steps in section 2.2.1.
 140 4. while executing connect command, there is `LE Enhanced Connection Complete` event in `btmon` log. Note down `handle` value.
 141 5. After connection, exit form bluetoothctl. Run `exit` in bluetoothctl.
 142 6. Now configure phy into 2M. Run `sudo hcitool cmd 08 32 <handle value in two bytes in little endian format > 03 02 02 00 00`.
 143 ex. For handle 1 -> `sudo hcitool cmd 08 32 01 00 03 02 02 00 00`
 144 7. Follow gatt read/write from `menu gatt` in bluetoothctl.
 145
 146 ###### Using CODED phy:
 147 Configure CODED phy on host and peripheral side.
 148
 149 Steps:
 150 1. To configure phy as CODED phy, run `sudo hcitool cmd 08 31 03 04 04`.
 151 2. To check selected phy, Go to `bluez-5.56` directory. Run `sudo ./tools/btmgmt --index hci0` and run `phy`.
 152 3. Connect to BLE5.0 device using above mentioned steps in section 2.2.1.
 153 4. Follow gatt read/write from `menu gatt` in bluetoothctl.
 154