BT serial: SSP improvements, added missing events (#8723)

* Renamed SerialToSerialBT_SSP_pairing

* Clarified useage of SPP example

* Added missing events

* Implemented dropCache() method to remove bonded devices

* Removed legacy pairing, enhaced SSP

* Minor updates to examples

* Updated README + asociated comments in source and example

* Implemented more methods to manipulate bonded devices + modified example

* Added SPP event

* Reordered event to match enum declaration; added missing events; added comments

* Re-implemented legacy pairing support

* Spelling fixes in README

* Removed unnecessary test in discover()

* Updates

---------

Co-authored-by: Tomas Pilny <[email protected]>
Co-authored-by: Tomáš Pilný <[email protected]>

Author: me-no-dev

libraries/BluetoothSerial/README.md

@@ -1,19 +1,78 @@
-### Bluetooth Serial Library
+## Bluetooth Serial Library
 
-A simple Serial compatible library using ESP32 classical bluetooth (SPP)
+A simple Serial compatible library using ESP32 classical Bluetooth Serial Port Profile (SPP)
 
+Note: Since version 3.0.0 this library does not support legacy pairing (using fixed PIN consisting of 4 digits).
 
+### How to use it?
 
-#### How to use it?
+There are 3 basic use cases: phone, other ESP32 or any MCU with a Bluetooth serial module
 
-- Download one bluetooth terminal app in your smartphone<br>
-For Android: https://play.google.com/store/apps/details?id=de.kai_morich.serial_bluetooth_terminal <br>
-For iOS: https://itunes.apple.com/us/app/hm10-bluetooth-serial-lite/id1030454675
+#### Phone
+
+- Download one of the Bluetooth terminal apps to your smartphone
+
+    - For [Android](https://play.google.com/store/apps/details?id=de.kai_morich.serial_bluetooth_terminal)
+    - For [iOS](https://itunes.apple.com/us/app/hm10-bluetooth-serial-lite/id1030454675)
 
 - Flash an example sketch to your ESP32
 
-- Scan and pair the device in your smartphone
+- Scan and pair the device to your smartphone
 
-- Open the bluetooth terminal app
+- Open the Bluetooth terminal app and connect
 
 - Enjoy
+
+#### ESP32
+
+You can flash one of the ESP32 with the example [`SerialToSerialBTM`](https://github.com/espressif/arduino-esp32/blob/master/libraries/BluetoothSerial/examples/SerialToSerialBTM/SerialToSerialBTM.ino) (the Master) and another ESP32 with [`SerialToSerialBT`](https://github.com/espressif/arduino-esp32/blob/master/libraries/BluetoothSerial/examples/SerialToSerialBT/SerialToSerialBT.ino) (the Slave).
+Those examples are preset to work out-of-the-box but they should be scalable to connect multiple Slaves to the Master.
+
+#### 3rd party Serial Bluetooth module
+
+Using a 3rd party Serial Bluetooth module will require to study the documentation of the particular module in order to make it work, however, one side can utilize the mentioned [`SerialToSerialBTM`](https://github.com/espressif/arduino-esp32/blob/master/libraries/BluetoothSerial/examples/SerialToSerialBTM/SerialToSerialBTM.ino) (the Master) or [`SerialToSerialBT`](https://github.com/espressif/arduino-esp32/blob/master/libraries/BluetoothSerial/examples/SerialToSerialBT/SerialToSerialBT.ino) (the Slave).
+
+### Pairing options
+
+There are two easy options and one difficult.
+
+The easy options can be used as usual. These offer pairing with and without Secure Simple Pairing (SSP).
+
+The difficult option offers legacy pairing (using fixed PIN) however this must be compiled with Arduino as an IDF component with disabled sdkconfig option `CONFIG_BT_SSP_ENABLED`.
+
+#### Without SSP
+
+This method will authenticate automatically any attempt to pair and should not be used if security is a concern! This option is used for the examples [`SerialToSerialBTM`](https://github.com/espressif/arduino-esp32/blob/master/libraries/BluetoothSerial/examples/SerialToSerialBTM/SerialToSerialBTM.ino) and [`SerialToSerialBT`](https://github.com/espressif/arduino-esp32/blob/master/libraries/BluetoothSerial/examples/SerialToSerialBT/SerialToSerialBT.ino).
+
+### With SSP
+
+The usage of SSP provides a secure connection. This option is demonstrated in the example `SerialToSerialBT_SSP``](https://github.com/espressif/arduino-esp32/blob/master/libraries/BluetoothSerial/examples/SerialToSerialBT_SSP/SerialToSerialBT_SSP.ino)
+
+The Secure Simple Pairing is enabled by calling method `enableSSP` which has two variants - one is backward compatible without parameter `enableSSP()` and second with parameters `enableSSP(bool inputCapability, bool outputCapability)`. Similarly, the SSP can be disabled by calling `disableSSP()`.
+
+Both options must be called before `begin()` or if it is called after `begin()` the driver needs to be restarted (call `end()` followed by `begin()`) in order to take in effect enabling or disabling the SSP.
+
+#### The parameters define the method of authentication:
+
+**inputCapability** - Defines if ESP32 device has input method (Serial terminal, keyboard or similar)
+
+**outputCapability** - Defines if ESP32 device has output method (Serial terminal, display or similar)
+
+* **inputCapability=true and outputCapability=true**
+    * Both devices display randomly generated code and if they match the user will authenticate pairing on both devices.
+    * This must be implemented by registering a callback via `onConfirmRequest()` and in this callback the user will input the response and call `confirmReply(true)` if the authenticated, otherwise call `confirmReply(false)` to reject the pairing.
+* **inputCapability=false and outputCapability=false**
+    * Only the other device authenticates pairing without any pin.
+* **inputCapability=false and outputCapability=true**
+    * Only the other device authenticates pairing without any pin.
+* **inputCapability=true and outputCapability=false**
+    * The user will be required to input the passkey to the ESP32 device to authenticate.
+    * This must be implemented by registering a callback via `onKeyRequest`()` and in this callback the entered passkey will be responded via `respondPasskey(passkey)`
+
+### Legacy Pairing (IDF component)
+
+To use Legacy pairing you will have to use [Arduino as an IDF component](https://espressif-docs.readthedocs-hosted.com/projects/arduino-esp32/en/latest/esp-idf_component.html) and disable option `CONFIG_BT_SSP_ENABLED`.
+Please refer to the documentation on how to setup Arduino as an IDF component and when you are done, run `idf.py menuconfig` navigate to `Component Config -> Bluetooth -> Bluedroid -> [ ] Secure Simple Pairing` and disable it.
+While in the menuconfig you will also need to change the partition scheme `Partition Table -> Partition Table -> (X) Single Factory app (large), no OTA`.
+After these changes save & quit menuconfig and you are ready to go: `idf.py  monitor flash`.
+Please note that to use the PIN in smartphones and computers you need to use characters `SerialBT.setPin("1234", 4);` not a number `SerialBT.setPin(1234, 4);` . Numbers CAN be used if the other side uses them too, but phones and computers use characters.

libraries/BluetoothSerial/examples/DiscoverConnect/DiscoverConnect.ino

@@ -19,19 +19,18 @@
 #include <BluetoothSerial.h>
 
 #if !defined(CONFIG_BT_ENABLED) || !defined(CONFIG_BLUEDROID_ENABLED)
-#error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
+  #error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
 #endif
 
 #if !defined(CONFIG_BT_SPP_ENABLED)
-#error Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.
+  #error Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.
 #endif
 
 BluetoothSerial SerialBT;
 
-
 #define BT_DISCOVER_TIME  10000
-esp_spp_sec_t sec_mask=ESP_SPP_SEC_NONE; // or ESP_SPP_SEC_ENCRYPT|ESP_SPP_SEC_AUTHENTICATE to request pincode confirmation
-esp_spp_role_t role=ESP_SPP_ROLE_SLAVE; // or ESP_SPP_ROLE_MASTER
+esp_spp_sec_t sec_mask = ESP_SPP_SEC_NONE; // or ESP_SPP_SEC_ENCRYPT|ESP_SPP_SEC_AUTHENTICATE to request pincode confirmation
+esp_spp_role_t role = ESP_SPP_ROLE_SLAVE; // or ESP_SPP_ROLE_MASTER
 
 // std::map<BTAddress, BTAdvertisedDeviceSet> btDeviceList;
 

libraries/BluetoothSerial/examples/GetLocalMAC/GetLocalMAC.ino

@@ -6,11 +6,11 @@
 String device_name = "ESP32-example";
 
 #if !defined(CONFIG_BT_ENABLED) || !defined(CONFIG_BLUEDROID_ENABLED)
-#error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
+  #error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
 #endif
 
 #if !defined(CONFIG_BT_SPP_ENABLED)
-#error Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.
+  #error Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.
 #endif
 
 BluetoothSerial SerialBT;

libraries/BluetoothSerial/examples/SerialToSerialBT/SerialToSerialBT.ino

@@ -1,35 +1,31 @@
-//This example code is in the Public Domain (or CC0 licensed, at your option.)
-//By Evandro Copercini - 2018
+// This example code is in the Public Domain (or CC0 licensed, at your option.)
+// By Evandro Copercini - 2018
 //
-//This example creates a bridge between Serial and Classical Bluetooth (SPP)
-//and also demonstrate that SerialBT have the same functionalities of a normal Serial
+// This example creates a bridge between Serial and Classical Bluetooth (SPP)
+// and also demonstrate that SerialBT have the same functionalities of a normal Serial
+// Note: Pairing is authenticated automatically by this device
 
 #include "BluetoothSerial.h"
 
-//#define USE_PIN // Uncomment this to use PIN during pairing. The pin is specified on the line below
-const char *pin = "1234"; // Change this to more secure PIN.
-
 String device_name = "ESP32-BT-Slave";
 
+// Check if Bluetooth is available
 #if !defined(CONFIG_BT_ENABLED) || !defined(CONFIG_BLUEDROID_ENABLED)
-#error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
+  #error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
 #endif
 
+// Check Serial Port Profile
 #if !defined(CONFIG_BT_SPP_ENABLED)
-#error Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.
+  #error Serial Port Profile for Bluetooth is not available or not enabled. It is only available for the ESP32 chip.
 #endif
 
 BluetoothSerial SerialBT;
 
 void setup() {
   Serial.begin(115200);
   SerialBT.begin(device_name); //Bluetooth device name
+  //SerialBT.deleteAllBondedDevices(); // Uncomment this to delete paired devices; Must be called after begin
   Serial.printf("The device with name \"%s\" is started.\nNow you can pair it with Bluetooth!\n", device_name.c_str());
-  //Serial.printf("The device with name \"%s\" and MAC address %s is started.\nNow you can pair it with Bluetooth!\n", device_name.c_str(), SerialBT.getMacString()); // Use this after the MAC method is implemented
-  #ifdef USE_PIN
-    SerialBT.setPin(pin);
-    Serial.println("Using PIN");
-  #endif
 }
 
 void loop() {

libraries/BluetoothSerial/examples/SerialToSerialBTM/SerialToSerialBTM.ino

@@ -1,27 +1,33 @@
 // This example code is in the Public Domain (or CC0 licensed, at your option.)
 // By Victor Tchistiak - 2019
 //
-// This example demonstrates master mode Bluetooth connection to a slave BT device using PIN (password)
-// defined either by String "slaveName" by default "OBDII" or by MAC address
+// This example demonstrates master mode Bluetooth connection to a slave BT device
+// defined either by String "slaveName" by default "ESP32-BT-Slave" or by MAC address
 //
 // This example creates a bridge between Serial and Classical Bluetooth (SPP)
 // This is an extension of the SerialToSerialBT example by Evandro Copercini - 2018
 //
 // DO NOT try to connect to phone or laptop - they are master
-// devices, same as the ESP using this code - it will NOT work!
+// devices, same as the ESP using this code - you will be able
+// to pair, but the serial communication will NOT work!
 //
 // You can try to flash a second ESP32 with the example SerialToSerialBT - it should
 // automatically pair with ESP32 running this code
+// Note: Pairing is authenticated automatically by this device
 
 #include "BluetoothSerial.h"
 
 #define USE_NAME // Comment this to use MAC address instead of a slaveName
-const char *pin = "1234"; // Change this to reflect the pin expected by the real slave BT device
 
-#if !defined(CONFIG_BT_SPP_ENABLED)
-#error Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.
+// Check if Bluetooth is available
+#if !defined(CONFIG_BT_ENABLED) || !defined(CONFIG_BLUEDROID_ENABLED)
+  #error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
 #endif
 
+// Check Serial Port Profile
+#if !defined(CONFIG_BT_SPP_ENABLED)
+  #error Serial Port Profile for Bluetooth is not available or not enabled. It is only available for the ESP32 chip.
+#endif
 BluetoothSerial SerialBT;
 
 #ifdef USE_NAME
@@ -38,6 +44,7 @@ void setup() {
   Serial.begin(115200);
 
   SerialBT.begin(myName, true);
+  //SerialBT.deleteAllBondedDevices(); // Uncomment this to delete paired devices; Must be called after begin
   Serial.printf("The device \"%s\" started in master mode, make sure slave BT device is on!\n", myName.c_str());
 
   #ifndef USE_NAME