8000 BT serial: SSP improvements, added missing events (#8723) · gokhansari/arduino-esp32@02e7fd8 · GitHub
[go: up one dir, main page]
Skip to content

Commit 02e7fd8

Browse files
me-no-devPilnyTomas
me-no-dev
and
PilnyTomas
authored
BT serial: SSP improvements, added missing events (espressif#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 <tomas.pilny@espressif.com> Co-authored-by: Tomáš Pilný <pilnyt@seznam.cz>
1 parent 6603b6e commit 02e7fd8

File tree

23 files changed

+753
-389
lines changed
  • .skip.esp32s2
  • .skip.esp32s3
  • SerialToSerialBT_SSP.ino
  • SerialToSerialBT
  • bt_classic_device_discovery
  • bt_remove_paired_devices
  • src

    • 23 files changed

    +753
    -389
    lines changed

    ‎libraries/BluetoothSerial/README.md

    Lines changed: 67 additions & 8 deletions
    Original file line numberDiff line numberDiff line change
    @@ -1,19 +1,78 @@
    1-
    ### Bluetooth Serial Library
    1+
    ## Bluetooth Serial Library
    22

    3-
    A simple Serial compatible library using ESP32 classical bluetooth (SPP)
    3+
    A simple Serial compatible library using ESP32 classical Bluetooth Serial Port Profile (SPP)
    44

    5+
    Note: Since version 3.0.0 this library does not support legacy pairing (using fixed PIN consisting of 4 digits).
    56

    7+
    ### How to use it?
    68

    7-
    #### How to use it?
    9+
    There are 3 basic use cases: phone, other ESP32 or any MCU with a Bluetooth serial module
    810

    9-
    - Download one bluetooth terminal app in your smartphone<br>
    10-
    For Android 10000 : https://play.google.com/store/apps/details?id=de.kai_morich.serial_bluetooth_terminal <br>
    11-
    For iOS: https://itunes.apple.com/us/app/hm10-bluetooth-serial-lite/id1030454675
    11+
    #### Phone
    12+
    13+
    - Download one of the Bluetooth terminal apps to your smartphone
    14+
    15+
    - For [Android](https://play.google.com/store/apps/details?id=de.kai_morich.serial_bluetooth_terminal)
    16+
    - For [iOS](https://itunes.apple.com/us/app/hm10-bluetooth-serial-lite/id1030454675)
    1217

    1318
    - Flash an example sketch to your ESP32
    1419

    15-
    - Scan and pair the device in your smartphone
    20+
    - Scan and pair the device to your smartphone
    1621

    17-
    - Open the bluetooth terminal app
    22+
    - Open the Bluetooth terminal app and connect
    1823

    1924
    - Enjoy
    25+
    26+
    #### ESP32
    27+
    28+
    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).
    29+
    Those examples are preset to work out-of-the-box but they should be scalable to connect multiple Slaves to the Master.
    30+
    31+
    #### 3rd party Serial Bluetooth module
    32+
    33+
    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).
    34+
    35+
    ### Pairing options
    36+
    37+
    There are two easy options and one difficult.
    38+
    39+
    The easy options can be used as usual. These offer pairing with and without Secure Simple Pairing (SSP).
    40+
    41+
    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`.
    42+
    43+
    #### Without SSP
    44+
    45+
    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).
    46+
    47+
    ### With SSP
    48+
    49+
    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)
    50+
    51+
    The Secure Simple Pairing is enabled by calling method `enableSSP` which has two variants - one is backward compatible without parameter ` 10000 enableSSP()` and second with parameters `enableSSP(bool inputCapability, bool outputCapability)`. Similarly, the SSP can be disabled by calling `disableSSP()`.
    52+
    53+
    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.
    54+
    55+
    #### The parameters define the method of authentication:
    56+
    57+
    **inputCapability** - Defines if ESP32 device has input method (Serial terminal, keyboard or similar)
    58+
    59+
    **outputCapability** - Defines if ESP32 device has output method (Serial terminal, display or similar)
    60+
    61+
    * **inputCapability=true and outputCapability=true**
    62+
    * Both devices display randomly generated code and if they match the user will authenticate pairing on both devices.
    63+
    * 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.
    64+
    * **inputCapability=false and outputCapability=false**
    65+
    * Only the other device authenticates pairing without any pin.
    66+
    * **inputCapability=false and outputCapability=true**
    67+
    * Only the other device authenticates pairing without any pin.
    68+
    * **inputCapability=true and outputCapability=false**
    69+
    * The user will be required to input the passkey to the ESP32 device to authenticate.
    70+
    * This must be implemented by registering a callback via `onKeyRequest`()` and in this callback the entered passkey will be responded via `respondPasskey(passkey)`
    71+
    72+
    ### Legacy Pairing (IDF component)
    73+
    74+
    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`.
    75+
    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.
    76+
    While in the menuconfig you will also need to change the partition scheme `Partition Table -> Partition Table -> (X) Single Factory app (large), no OTA`.
    77+
    After these changes save & quit menuconfig and you are ready to go: `idf.py monitor flash`.
    78+
    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

    Lines changed: 4 additions & 5 deletions
    Original file line numberDiff line numberDiff line change
    @@ -19,19 +19,18 @@
    1919
    #include <BluetoothSerial.h>
    2020

    2121
    #if !defined(CONFIG_BT_ENABLED) || !defined(CONFIG_BLUEDROID_ENABLED)
    22-
    #error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
    22+
    #error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
    2323
    #endif
    2424

    2525
    #if !defined(CONFIG_BT_SPP_ENABLED)
    26-
    #error Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.
    26+
    #error Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.
    2727
    #endif
    2828

    2929
    BluetoothSerial SerialBT;
    3030

    31-
    3231
    #define BT_DISCOVER_TIME 10000
    33-
    esp_spp_sec_t sec_mask=ESP_SPP_SEC_NONE; // or ESP_SPP_SEC_ENCRYPT|ESP_SPP_SEC_AUTHENTICATE to request pincode confirmation
    34-
    esp_spp_role_t role=ESP_SPP_ROLE_SLAVE; // or ESP_SPP_ROLE_MASTER
    32+
    esp_spp_sec_t sec_mask = ESP_SPP_SEC_NONE; // or ESP_SPP_SEC_ENCRYPT|ESP_SPP_SEC_AUTHENTICATE to request pincode confirmation
    33+
    esp_spp_role_t role = ESP_SPP_ROLE_SLAVE; // or ESP_SPP_ROLE_MASTER
    3534

    3635
    // std::map<BTAddress, BTAdvertisedDeviceSet> btDeviceList;
    3736

    ‎libraries/BluetoothSerial/examples/GetLocalMAC/GetLocalMAC.ino

    Lines changed: 2 additions & 2 deletions
    Original file line numberDiff line numberDiff line change
    @@ -6,11 +6,11 @@
    66
    String device_name = "ESP32-example";
    77

    88
    #if !defined(CONFIG_BT_ENABLED) || !defined(CONFIG_BLUEDROID_ENABLED)
    9-
    #error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
    9+
    #error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
    1010
    #endif
    1111

    1212
    #if !defined(CONFIG_BT_SPP_ENABLED)
    13-
    #error Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.
    13+
    #error Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.
    1414
    #endif
    1515

    1616
    BluetoothSerial SerialBT;

    ‎libraries/BluetoothSerial/examples/SerialToSerialBT/SerialToSerialBT.ino

    Lines changed: 10 additions & 14 deletions
    Original file line numberDiff line numberDiff line change
    @@ -1,35 +1,31 @@
    1-
    //This example code is in the Public Domain (or CC0 licensed, at your option.)
    2-
    //By Evandro Copercini - 2018
    1+
    // This example code is in the Public Domain (or CC0 licensed, at your option.)
    2+
    // By Evandro Copercini - 2018
    33
    //
    4-
    //This example creates a bridge between Serial and Classical Bluetooth (SPP)
    5-
    //and also demonstrate that SerialBT have the same functionalities of a normal Serial
    4+
    // This example creates a bridge between Serial and Classical Bluetooth (SPP)
    5+
    // and also demonstrate that SerialBT have the same functionalities of a normal Serial
    6+
    // Note: Pairing is authenticated automatically by this device
    67

    78
    #include "BluetoothSerial.h"
    89

    9-
    //#define USE_PIN // Uncomment this to use PIN during pairing. The pin is specified on the line below
    10-
    const char *pin = "1234"; // Change this to more secure PIN.
    11-
    1210
    String device_name = "ESP32-BT-Slave";
    1311

    12+
    // Check if Bluetooth is available
    1413
    #if !defined(CONFIG_BT_ENABLED) || !defined(CONFIG_BLUEDROID_ENABLED)
    15-
    #error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
    14+
    #error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
    1615
    #endif
    1716

    17+
    // Check Serial Port Profile
    1818
    #if !defined(CONFIG_BT_SPP_ENABLED)
    19-
    #error Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.
    19+
    #error Serial Port Profile for Bluetooth is not available or not enabled. It is only available for the ESP32 chip.
    2020
    #endif
    2121

    2222
    BluetoothSerial SerialBT;
    2323

    2424
    void setup() {
    2525
    Serial.begin(115200);
    2626
    SerialBT.begin(device_name); //Bluetooth device name
    27+
    //SerialBT.deleteAllBondedDevices(); // Uncomment this to delete paired devices; Must be called after begin
    2728
    Serial.printf("The device with name \"%s\" is started.\nNow you can pair it with Bluetooth!\n", device_name.c_str());
    28-
    //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
    29-
    #ifdef USE_PIN
    30-
    SerialBT.setPin(pin);
    31-
    Serial.println("Using PIN");
    32-
    #endif
    3329
    }
    3430

    3531
    void loop() {

    ‎libraries/BluetoothSerial/examples/SerialToSerialBTM/SerialToSerialBTM.ino

    Lines changed: 13 additions & 6 deletions
    Original file line numberDiff line numberDiff line change
    @@ -1,27 +1,33 @@
    11
    // This example code is in the Public Domain (or CC0 licensed, at your option.)
    22
    // By Victor Tchistiak - 2019
    33
    //
    4-
    // This example demonstrates master mode Bluetooth connection to a slave BT device using PIN (password)
    5-
    // defined either by String "slaveName" by default "OBDII" or by MAC address
    4+
    // This example demonstrates master mode Bluetooth connection to a slave BT device
    5+
    // defined either by String "slaveName" by default "ESP32-BT-Slave" or by MAC address
    66
    //
    77
    // This example creates a bridge between Serial and Classical Bluetooth (SPP)
    88
    // This is an extension of the SerialToSerialBT example by Evandro Copercini - 2018
    99
    //
    1010
    // DO NOT try to connect to phone or laptop - they are master
    11-
    // devices, same as the ESP using this code - it will NOT work!
    11+
    // devices, same as the ESP using this code - you will be able
    12+
    // to pair, but the serial communication will NOT work!
    1213
    //
    1314
    // You can try to flash a second ESP32 with the example SerialToSerialBT - it should
    1415
    // automatically pair with ESP32 running this code
    16+
    // Note: Pairing is authenticated automatically by this device
    1517

    1618
    #include "BluetoothSerial.h"
    1719

    1820
    #define USE_NAME // Comment this to use MAC address instead of a slaveName
    19-
    const char *pin = "1234"; // Change this to reflect the pin expected by the real slave BT device
    2021

    21-
    #if !defined(CONFIG_BT_SPP_ENABLED)
    22-
    #error Serial Bluetooth not available or not enabled. It is only available for the ESP32 chip.
    22+
    // Check if Bluetooth is available
    23+
    #if !defined(CONFIG_BT_ENABLED) || !defined(CONFIG_BLUEDROID_ENABLED)
    24+
    #error Bluetooth is not enabled! Please run `make menuconfig` to and enable it
    2325
    #endif
    2426

    27+
    // Check Serial Port Profile
    28+
    #if !defined(CONFIG_BT_SPP_ENABLED)
    29+
    #error Serial Port Profile for Bluetooth is not available or not enabled. It is only available for the ESP32 chip.
    30+
    #endif
    2531
    BluetoothSerial SerialBT;
    2632

    2733
    #ifdef USE_NAME
    @@ -38,6 +44,7 @@ void setup() {
    3844
    Serial.begin(115200);
    3945

    4046
    SerialBT.begin(myName, true);
    47+
    //SerialBT.deleteAllBondedDevices(); // Uncomment this to delete paired devices; Must be called after begin
    4148
    Serial.printf("The device \"%s\" started in master mode, make sure slave BT device is on!\n", myName.c_str());
    4249

    4350
    #ifndef USE_NAME

    ‎libraries/BluetoothSerial/examples/SerialToSerialBT_SSP_pairing/.skip.esp32c3 renamed to ‎libraries/BluetoothSerial/examples/SerialToSerialBT_Legacy/.skip.esp32c3

    File renamed without changes.

    ‎libraries/BluetoothSerial/examples/SerialToSerialBT_SSP_pairing/.skip.esp32c6 renamed to ‎libraries/BluetoothSerial/examples/SerialToSerialBT_Legacy/.skip.esp32c6

    File renamed without changes.

    ‎libraries/BluetoothSerial/examples/SerialToSerialBT_SSP_pairing/.skip.esp32h2 renamed to ‎libraries/BluetoothSerial/examples/SerialToSerialBT_Legacy/.skip.esp32h2

    File renamed without changes.

    ‎libraries/BluetoothSerial/examples/SerialToSerialBT_SSP_pairing/.skip.esp32s2 renamed to ‎libraries/BluetoothSerial/examples/SerialToSerialBT_Legacy/.skip.esp32s2

    File renamed without changes.

    ‎libraries/BluetoothSerial/examples/SerialToSerialBT_SSP_pairing/.skip.esp32s3 renamed to ‎libraries/BluetoothSerial/examples/SerialToSerialBT_Legacy/.skip.esp32s3

    File renamed without changes.

    0 commit comments

    Comments
     (0)
    0