ESP32 Bluetooth Networking User Guide fersion Espre: or Syste ms Copyright © 2019 BY |:About This Guide This document provides a guide with examples to using ESP32 to establish Bluetooth® networks for loT devices. Release Note Date Version Release notes 2017.03 vio First ola. 2019.05 via Updated figures. 2010.11 vie Undated the download lnk of EspB Documentation Change Notification Espressif provides email notifications to keep customers updated on changes to technical documentation. Please subscribe at hits.//www.espressif. com/en/subsoribe, Certification Download certi ates for Espressif products from /itps://www espressif com/en/Content 1. Introduction. 4.4. Overview 1 1.2, EspBlufi 2. APIs for Networking Development 2.1. BluFi Protocol. 22, APIs on ESP32 End.. 2.3. APIs on the EspBlufi APK End... Rob & 3. ESP32 Bluetooth Networking Examples 3.1. Hardware and Software Preparation 3.2, Setting ESP32 to Station Mode... 3.3. Setting ESP32 as a SoftAP1. Introduction Introduction 1.1. Overview ‘The ESP32, as a single 2.4 GHz Wi-Fi and Bluetooth combo chip, supports Wi-Fi setups via both SmartConfig and Bluetooth. Users can use ESP32 for secure configuration of Wi- Fi networking for loT devices. Using Bluetooth for configuring Wi-Fi network presents the following advantages: The Bluetooth protocol is open and scalable. By using Bluetooth protocol, users can easily discover nearby devices via Bluetooth beacons. The Bluetooth protocol is secure, because the authentication of the device is done over a secure Bluetooth connection before the password is sent to the device. Users can also transmit data over Bluetooth to a smartphone, even when the router is not working, The phone can then uploads the data to the Internet, ‘The phone can now also connect to the Bluetooth device and send commands directly to control the device if the Wi-Fi network is down, 1.2. EspBlufi ESP32 is compliant with Bluetooth v4.2 BR/EDR and BLE specifications. Espressif has developed the app EspBlufi specifically for Bluetooth networking of IoT devices. The app is supported on Android 4.3 and above. For smartphones of Android 6.0 or above, because of Google's modification to the Android API, users must give their permission for access to their current location and enable the location information module to start the Bluetooth scanning, © EspBlufi can be downloaded via: httos://aithub.com/EspressifApp/EspBlufiForAndroid/ releases + Open EspBlufi after downloading it. In the user interface as shown in Figure 1-1, click on the [Ell icon in the upper right corner. Espressit 113 2019.111. Introduction Figure 1-1. EspBlufi User Interface * The Configure button will be shown in the interface and click this button. ‘BLUFI_DEVICE Figure 1-2, CONFIGURE Button * Configure the length of BLE mtu, BLE device fitering, and check the version of the app and Blufi repository. 8m mu deme BLE ene vs APP Hc Blu eas Figure 1-3. CONFIGURE Interface Espressit 23 2019.112, APIs for Networking Development APIs for Networking Development 2.1. BluFi Protocol Protocol documentation: hitps://docs.es if. -idt/erviates in jes blufi.htm! 2.2. APIs on ESP32 End In the program of ESP32, security-related processes such as key establishment are determined and developed by the users. The app sends the “negotiate data” to ESP32 and the data packets will be sent to the application layer. If the data is not handled by the application layer, DH algorithm provided by BIuFi can be used to exchange the key. The application layer needs to register relevant callback functions to BIuFi, Table 2-1 provides description of those functions. Table 2-1. Security-Related Functions, Function typedef void (tesp_blufi_negotiate_data_handler_t) (uinté_t “data, int len, uinte_t sroutput_data, int *output_len, Bool *need_free): typedef int (* esp_blufi_encrypt_func_t) (wint8_t ive. uint@_t Fcrypt_data, int cyprt_len) typedef int (* esp_blufi_decrypt_func_t) (wint8_t iv8, uinte_t =crypt_data, Int crypt_len) typedef uintie_t (*esp_bluti_checksum_func_t) (uint8_t ivB, uint@_t ‘data, int Len) Espressit ang Description *+ This tunction is used to re data” during key exchange should be output by passing the parameters output_data anc output_len to Blu + Alter BluFi calls negotiate_data_handler, output_data output oy negotiate_data_handler is sont + Since the length of data to be sent is not definite, **output_data has tomal loc a part of memory or use global variables to release memory via need_free The length of the encoded and decoded data must be the same, #8 inthis function means the B-bit sequence ofthe packets. It can be used for eight bits ofthe initialization vector. “The length of the encoded and decoded data must be the same, {v8 inthis function means the 8-it sequonce of the packets. It can be used for eight bits ofthe initialization vector The function is used to calculate the checksum, Calling this function returns the value of checksum. The returned value will be compared with the um at the end of the packet by Bl 2019.112, APIs for Networking Development 2.3. APIs on the EspBlufi APK End * Source code of EspBlufi for Android: https://github.com/EspressifApp/ EspBlufiForAndroid * Documentation of EspBIufi for Android: htins://github.com/EspressifAop/ EspBlufiForAndroid/biob/master/doc/ Introduction to the EspBiufi API Interface for Android cn.md © Source code of EspBlufi for iOS: hitos://aithub.com/EspressifApp/EsoBlufiForiOS ‘* Documentation of EspBlufi for iOS: hitos://ithub.com/EspressitAop/EspBlufiForiOS/ blob/master/doc/Blufi APP API for iOS CN.md Espressit ang 2019.118, ESP2 Bluetooth Networking Examples ESP32 Bluetooth Networking Examples 3.1. Hardware and Software Preparation * 1 x ESP32 module * 1x PC, connected to the module to supply power and print log for ESP32, ‘+1 x smartphone (Android 4.3 or above) ‘* Download and install EspBlufi on the smartphone, Tum on the Wi-Fi and Bluetooth capabilities on the phone. The link for downloading EspBluf is httos.//github.com/Espres /EspBlufiForAndroid/ 3.2. Setting ESP32 to Station Mode 1. Power on the module. The following log will be output to the serial port tool: J 3155) er: Startup ery lg (3165) oT: GarTscreateservice: handle of service handlet (5175) et: Bracdaco-ble-load-local-keys? func not ported 1 (3185) BLUFT_pEMO: 60 ADDR: 24:0a:c4:01 4dzbe 1 G15) BLUFI_DEMO: BLUFT VERSION 0100 1 185) BLUFI_DEMO: BLUFT Init Finish 2. Open the EspBlufi app, and refresh the interface by swiping down from the top of the screen. The nearby Bluetooth-enabled devices will be shown on the screen. Figure 3-1. EspBilufi interface Espressit 8/13 2019.118, ESP2 Bluetooth Networking Examples 3. Click on the ESP32 device in the interface as Figure 3-1 shows, and click Connect button [= ]to establish Btuetooth connection to it. Successful connection will yield the interface shown in Figure 3-2. CMa Conested 0AE-MT:56 Discover sence and characteristics Set mtu 128 complete we] eee Figure 3-2. Interface Showing Successful Connection Meanwhile, the following log will be output to the serial port tool: e 37875) E (e143) er: device 12 connected 48:63:0F:4 bbem_ble_resolve_random_addr_on_conn_cmp! unable to match and resol 186, server_ifad reasone0x0,connect_idea (38145) ‘smp_br_connect_caTTback 1s called on unexpected transport 2 (G8145)[BLUFT_peM0? BLUFT ble connect (38285) eT: MTU request POU with MTU size 64 Ir e (38285) E (38285) Tr C0188: em sereleoataLength fa'led, peer does nor support request EniT back not found for application comida BLUFT-Dewo: BLUFT get wift status from AP LW Note: Ifthe Networking bution isnot shown or can not be clicked in the interlace of Figure 3-2, it means that Blustooth connection has failed. 4. Click on the Networking button E8 to configure the network, get the dropdown menu for network configuration, as Figure 3-3 shows: Espressit wis 2019.118, ESP2 Bluetooth Networking Examples station NETGEAR a Figure 3-8. Network Configuration interface 5, Select the device mode from the dropdown menu, as Figure 3-4 shows, (BIUFi networking supports the following three mod. Station, SoftAP, and Station+SottAP}) ssaten rc u ° < Figure 3-4. Selecting Device Mode Espressit 73 2019.118, ESP2 Bluetooth Networking Examples 8. Select Station mode as an instance, click on the refresh button FISSID. Then, enter the password. . and choose the Wi- a moo Figure 3-5. Configuring the Station Mode 7. Click on the ™® button to complete the configuration. Successful configuration wil lead to the interface as Figure 3-6 shows. The information marked in red in Figure 3-6 shows the Wi-Fi mode (which is Station mode in this example) and the connection information (such as the AP's BSSID and SSID, as well as the connection status). Figure 3-6, Station Connection Information Espressit aig 2019.118, ESP2 Bluetooth Networking Examples Meanwhile, the following log will be output to the serial port tool: TF (421745) BLUFT_pEMO: BLUFY Set WIFI opmode 1 T (421845) BLUFT_DEMO: Recv STA SSID OVES_HOME 1 (421945) BLUFT_DEMO: Recv STA PASSWORD 12345678 1 (422085) eLUFT_DEMO: BLUFT requset wif connect to AP 122055) wit: n26 2, 9:2. 0, ap:255 255, stas 123615) Wiel: eave! Ini 2> uth ce 2, pre 123605) Wifl: State: auth —> assoc (0) 123645) wifl: state! assoc —> run (10. 123675) WiFl: connected with ovES_FeNe, channel 6 (124305) event: ip: 192-168.1.105, mask! 255.255.255.0, gw: 192.168.2.1 33685) WIFl: pa start, type 3.3. Setting ESP32 as a SoftAP. 1, Power up the module, Connect the EsoBluti app to ESP32 via Bluetooth, Set the device mode as SoftAP in the network configuration interface, as Figure 3-7 shows. For details, of doing so, please refer to Steps 1 to 4 in Section 3.2. id SoftAP . Open : Sonar SonaP meet AP ssid Figure 3-7. Selecting SoftAP Mode 2. Configure the SoftAP mode, as Figure 3-8 shows, Select the security encryption mode, channel, and maximum number of Stations to be connected. Enter the SoftAP's SSID and password, Click on the | ##® button to complete the configuration. Espressit ang 2019.118, ESP2 Bluetooth Networking Examples “SofAP - WPA PSK - sana sone meni 10 - 2 . bluf soften 12345678, 2 Figure 3-8. Configuring the SoftAP Mode 3, Success of the SoftAP configuration will lead to the interface as Figure 3-9 shows, The current Wi-Fi mode and the connection status are shown in the interface. BLUFL_DEVICE ‘SoRAPcurent conection: 0 Receive device status responce: op made SOFTAP Stachoconnect wifi now SoAPcurent connection: 0 Receive device status response: op made SOFTAP Stecleconnect wifi now SoRAP caren conection: 0 Receive device status response: (ep modeSOFTAP ‘Stacconnect wifi now 'SoRAP curent conection: Post configure params complete Receive device status response: cp mode SOFTAP ‘Staeconnect wifi now ‘SoRAP curent conection: mee me eX Figure 3-9. SoftAP Connection Information Espressit 10/13 2019.118, ESP2 Bluetooth Networking Examples Meanwhile, the following log will be outpu! the serial port too: I (141967) wifi: mode : softAP (24:0a:c4:01:4d:bd) 1 @42067) BLUFT_DEMO: Recy SOFTAP S510 bluti_softap , ssid Ten 13 1 (142167) BLUFT_DEMO: Rec SOFTAP PASSWORD 12345678 1 (142267) BLUFI_DEMO: Recy SOFTAP CHANNEL 10 1 (142357) BLUFI_DEMO: Recy SOFTAP MAX CONN NUM 2 1 (243107) BLUFT_DEMO: Recy SOFTAP AUTH MODE 4 4, Turn on the smartphone’s Wi-Fi capability. The SoftAP connected can be found in the WLAN interface, as Figure 3-10 shows, ‘enda_108858 7 om Om, EKA esp.020021 VES HOME TLWROaIN ‘lt softap TPUNK.842N 3P.A49090 a a alae ae wie Figure 3-10. The Configured ESP32 SoftAP 5. Connect the smartphone to the ESP32 SoftAP. As shown in Figure 3-11, the prompt fl wil appear, indicating that the Wi-Fi is connected. Espressit 113 2019.118, ESP2 Bluetooth Networking Examples eer) amTeU) ‘uso ves HOME sp.020c21 TUN 2420 Figure 3-11, WiFi Connection Prompt the serial port tool: nwhile, the following log will be outpu I (293557) wif: + ap:10 2, sta:255 255, prof:10 1 (293557) wif, 98:d6!F7:64:13!08 join, AID=1, n, 20 ‘The ESP32 device is successfully connected to Wi-Fi via Bluetooth networking, LW Note: Jues of connection time shown on the Espé examples. Connection time is subject to the. 209 screenshots in this document are provided only al situations Espressit 12/18 2019.11Disclaimer and Copyright Notice Information inthis document, including URL references, f subject to change without rote, THIS DOCUMENT IS PROVIDED AS IS WITH NO WARRANTIES WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY, NON-INFRINGEMENT, FITNESS FOR ANY PARTICULAR PURPOSE, OR ANY WARRANTY OTHEAWISE ARISING OUT OF ANY PROPOSAL, SPECIFICATION OF SAMPLE Alii nciding abit fr inkingement of ary proprietary rights, relating to tho use of irormatton n Bis documents dscamed. No Keansos enotes or ipl, by estoppel or ctherwise, to ary inelectual propary rights ae granted herein The WEF Aiance Member logos a trademark ofthe Wii ance, The Bletoth fgo is 2 rogetorod trademark of Btooth SIS : (rad rare, radars ad registred wairark rentioned inthis document are See ORCSLM opory of na reapoctve mors, ard ao hereby accrowodyed Cee ae LAC OUm| CoPytight © 2019 Espressif Inc. All rights reserved.