![\"Web](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2023\/09\/ESP32-Web-BLE-Getting-Started.jpg?resize=1200%2C675&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\nTable of Contents<\/h2>\n\n\n\n
Throughout this tutorial, we’ll cover the following:<\/p>\n\n\n\n
- \n
- Web Bluetooth Introduction<\/a><\/li>\n\n\n\n
- Bluetooth Low Energy Introduction – Basic Concepts<\/a>\n
- \n
- BLE Peripheral and Controller (Central Device)<\/a><\/li>\n\n\n\n
- BLE Server and Client<\/a><\/li>\n\n\n\n
- GATT<\/a><\/li>\n\n\n\n
- UUID<\/a><\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Project Overview<\/a><\/li>\n\n\n\n
- Part 1: ESP32 BLE Device – Arduino Code<\/a><\/li>\n\n\n\n
- Part 2: Creating the Web BLE App<\/a><\/li>\n\n\n\n
- Part 3: Hosting your Web BLE App<\/a><\/li>\n<\/ul>\n\n\n\n
Introducing Web Bluetooth<\/h2>\n\n\n\n
Web Bluetooth (also sometimes referred to as Web BLE) is a technology that allows you to connect and control BLE-enabled devices, like the ESP32, directly from your web browser using JavaScript.<\/p>\n\n\n\n
With Web BLE, you can create web applications that interact with your ESP32 devices via Bluetooth, enabling you to control GPIO pins, exchange data, and manage your devices remotely through a web interface (this means any device that supports a web browser like your computer or smartphone).<\/p>\n\n\n
\n![\"Explaining](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2023\/09\/Web-BLE-ESP32-Example.png?resize=1200%2C369&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\nOne of the key advantages of Web BLE is its cross-platform compatibility. Unlike traditional mobile apps developed for Android or iOS, Web BLE applications are web-based and can run on any device with a modern web browser that supports Web BLE. <\/p>\n\n\n\n
This cross-platform compatibility removes the need for users to download and install dedicated mobile apps, simplifying the user experience and reducing development efforts. <\/p>\n\n\n\n
This means you can use a smartphone, tablet, or desktop computer to connect and control ESP32 devices using a Web BLE application.<\/p>\n\n\n\n
The Web Bluetooth API is still under development, but it is generally considered to be stable and usable. It has been implemented in Chrome, Edge, Opera, and Firefox, and it is supported on Android and Windows. However, it is not yet supported on iOS<\/strong>.<\/p>\n\n\n\n
Note: <\/strong> At the time of writing this tutorial, Web BLE is not supported on iOS.<\/p>\n\n\n\n
Bluetooth Low Energy Introduction – Basic Concepts<\/h2>\n\n\n\n
Before proceeding, it’s important to get familiar with some basic BLE concepts. We also recommend that you take a quick look at our BLE getting started guides and tutorials:<\/p>\n\n\n\n
- \n
- Getting Started with ESP32 Bluetooth Low Energy (BLE) on Arduino IDE<\/a><\/li>\n\n\n\n
- ESP32 BLE Server and Client (Bluetooth Low Energy)<\/a><\/li>\n<\/ul>\n\n\n\n
BLE Peripheral and Controller (Central Device)<\/h3>\n\n\n\n
When using Bluetooth Low Energy (BLE), it’s important to understand the roles of BLE Peripheral and BLE Controller (also referred to as the Central Device).<\/p>\n\n\n
\n![\"BLE](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2023\/09\/BLE-Peripheral-Controller.png?resize=1200%2C736&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\nIn our particular example, the ESP32 takes the role of the BLE Peripheral, serving as the device that provides data or services. Your smartphone or computer acts as the BLE Controller, managing the connection and communication with the ESP32.<\/p>\n\n\n\n
BLE Server and Client<\/h3>\n\n\n\n
With Bluetooth Low Energy, there are two types of devices: the server and the client. The ESP32 can act either as a client or as a server. But, in our particular example, it will act as a server, exposing its GATT structure containing data. The BLE Server acts as a provider of data or services, while the BLE Client consumes or uses these services.<\/p>\n\n\n
\n![\"ESP32](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2023\/09\/BLE-Client-Server.png?resize=1024%2C421&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\nThe server advertises its existence, so it can be found by other devices and contains data that the client can read or interact with. The client scans the nearby devices, and when it finds the server it is looking for, it establishes a connection and can interact with that device by reading or writing on its characteristics<\/em>.<\/p>\n\n\n\n
GATT<\/h3>\n\n\n\n
GATT, which stands for Generic Attribute Profile, is a fundamental concept in Bluetooth Low Energy (BLE) technology. Essentially, it serves as a blueprint for how BLE devices communicate with each other. Think of it as a structured language that two BLE devices use to exchange information seamlessly.<\/p>\n\n\n
\n![\"GATT](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2023\/09\/BLE-basic-GATT.png?resize=1024%2C629&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n- \n
- Profile<\/strong>: standard collection of services for a specific use case;<\/li>\n\n\n\n
- Service<\/strong>: collection of related information, like sensor readings, battery level, heart rate, etc. ;<\/li>\n\n\n\n
- Characteristic<\/strong>: it is where the actual data is saved on the hierarchy (value<\/strong>);<\/li>\n\n\n\n
- Descriptor<\/strong>: metadata about the data;<\/li>\n\n\n\n
- Properties<\/strong>: describe how the characteristic value can be interacted with. For example: read, write, notify, broadcast, indicate, etc.<\/li>\n<\/ul>\n\n\n\n
For a more detailed introduction to these BLE concepts, read: Getting Started with ESP32 Bluetooth Low Energy (BLE) on Arduino IDE<\/a>.<\/p>\n\n\n\n
UUID<\/h3>\n\n\n\n
A UUID is a unique digital identifier used in BLE and GATT to distinguish and locate services, characteristics, and descriptors. It’s like a distinct label that ensures every component in a Bluetooth device has a unique name.<\/p>\n\n\n\n
Each service, characteristic, and descriptor has a UUID (Universally Unique Identifier). A UUID is a unique 128-bit (16 bytes) number. For example:<\/p>\n\n\n\n
55072829-bc9e-4c53-938a-74a6d4c78776<\/strong><\/pre>\n\n\n\n
There are shortened and default UUIDs for services, and characteristics specified in the SIG (Bluetooth Special Interest Group)<\/a>. This means, that if you have a BLE device that uses the default UUIDs for its services and characteristics, you’ll know exactly how to interact with that device to get or interact with the information you’re looking for.<\/p>\n\n\n\n
Most of the time, with the ESP32, you’ll use your custom UUIDs. You can generate them using this UUID generator website<\/a>.<\/p>\n\n\n\n
Project Overview<\/h2>\n\n\n\n
Now that you’re more familiar with BLE concepts, let’s go through a quick overview of the project we’ll build.<\/p>\n\n\n\n
The ESP32 will act as a BLE Peripheral\/BLE Server that advertises its existence. Your computer, smartphone, or tablet will act as a BLE Controller\/Client that interacts with the ESP32 device.<\/p>\n\n\n
\n![\"ESP32](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2023\/09\/Web-BLE-ESP32-Example-1024x315.png?resize=1024%2C315&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\nThe ESP32 GATT structure will have one service <\/em>with two characteristics<\/em>. One characteristic (let’s call it sensor characteristic<\/em>) will be the place to save a value <\/em>that changes over time (like sensor readings). The other characteristic (let’s call it LED characteristic<\/em>) will be the place to save the state of a GPIO. By changing the value<\/em> of that characteristic<\/em>, we’ll be able to control an LED connected to that GPIO.<\/p>\n\n\n
\n<\/figure><\/div>\n\n\nThe ESP32 will write a new value to the sensor characteristic periodically. Your browser will connect to the ESP32 Bluetooth device and will receive notifications whenever the value changes and will display the new value on the web page (see Fetched Value in the picture below).<\/p>\n\n\n
\n![\"ESP32](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2023\/09\/ESP32-Web-BLE-App-Smartphone.png?resize=369%2C735&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\nAdditionally, your browser will also connect to the LED characteristic<\/em> and will change its value (see the ON and OFF buttons above). The ESP32 checks that the value of that characteristic changed, and it will change the state of the GPIO accordingly, turning the LED either on or off.<\/p>\n\n\n\n
ESP32 BLE Device – Arduino Code<\/h2>\n\n\n\n
The following code turns the ESP32 into a BLE device with one service and two characteristics as we’ve mentioned previously. <\/p>\n\n\n\n
Upload the following code to your board, and it will work straight away.<\/p>\n\n\n
\/*\n Rui Santos & Sara Santos - Random Nerd Tutorials\n Complete project details at https:\/\/RandomNerdTutorials.com\/esp32-web-bluetooth\/\n Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files.\n The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n*\/\n#include <BLEDevice.h>\n#include <BLEServer.h>\n#include <BLEUtils.h>\n#include <BLE2902.h>\n\nBLEServer* pServer = NULL;\nBLECharacteristic* pSensorCharacteristic = NULL;\nBLECharacteristic* pLedCharacteristic = NULL;\nbool deviceConnected = false;\nbool oldDeviceConnected = false;\nuint32_t value = 0;\n\nconst int ledPin = 2; \/\/ Use the appropriate GPIO pin for your setup\n\n\/\/ See the following for generating UUIDs:\n\/\/ https:\/\/www.uuidgenerator.net\/\n#define SERVICE_UUID "19b10000-e8f2-537e-4f6c-d104768a1214"\n#define SENSOR_CHARACTERISTIC_UUID "19b10001-e8f2-537e-4f6c-d104768a1214"\n#define LED_CHARACTERISTIC_UUID "19b10002-e8f2-537e-4f6c-d104768a1214"\n\nclass MyServerCallbacks: public BLEServerCallbacks {\n void onConnect(BLEServer* pServer) {\n deviceConnected = true;\n };\n\n void onDisconnect(BLEServer* pServer) {\n deviceConnected = false;\n }\n};\n\nclass MyCharacteristicCallbacks : public BLECharacteristicCallbacks {\n void onWrite(BLECharacteristic* pLedCharacteristic) {\n String value = pLedCharacteristic->getValue();\n if (value.length() > 0) {\n Serial.print("Characteristic event, written: ");\n Serial.println(static_cast<int>(value[0])); \/\/ Print the integer value\n\n int receivedValue = static_cast<int>(value[0]);\n if (receivedValue == 1) {\n digitalWrite(ledPin, HIGH);\n } else {\n digitalWrite(ledPin, LOW);\n }\n }\n }\n};\n\nvoid setup() {\n Serial.begin(115200);\n pinMode(ledPin, OUTPUT);\n\n \/\/ Create the BLE Device\n BLEDevice::init("ESP32");\n\n \/\/ Create the BLE Server\n pServer = BLEDevice::createServer();\n pServer->setCallbacks(new MyServerCallbacks());\n\n \/\/ Create the BLE Service\n BLEService *pService = pServer->createService(SERVICE_UUID);\n\n \/\/ Create a BLE Characteristic\n pSensorCharacteristic = pService->createCharacteristic(\n SENSOR_CHARACTERISTIC_UUID,\n BLECharacteristic::PROPERTY_READ |\n BLECharacteristic::PROPERTY_WRITE |\n BLECharacteristic::PROPERTY_NOTIFY |\n BLECharacteristic::PROPERTY_INDICATE\n );\n\n \/\/ Create the ON button Characteristic\n pLedCharacteristic = pService->createCharacteristic(\n LED_CHARACTERISTIC_UUID,\n BLECharacteristic::PROPERTY_WRITE\n );\n\n \/\/ Register the callback for the ON button characteristic\n pLedCharacteristic->setCallbacks(new MyCharacteristicCallbacks());\n\n \/\/ https:\/\/www.bluetooth.com\/specifications\/gatt\/viewer?attributeXmlFile=org.bluetooth.descriptor.gatt.client_characteristic_configuration.xml\n \/\/ Create a BLE Descriptor\n pSensorCharacteristic->addDescriptor(new BLE2902());\n pLedCharacteristic->addDescriptor(new BLE2902());\n\n \/\/ Start the service\n pService->start();\n\n \/\/ Start advertising\n BLEAdvertising *pAdvertising = BLEDevice::getAdvertising();\n pAdvertising->addServiceUUID(SERVICE_UUID);\n pAdvertising->setScanResponse(false);\n pAdvertising->setMinPreferred(0x0); \/\/ set value to 0x00 to not advertise this parameter\n BLEDevice::startAdvertising();\n Serial.println("Waiting a client connection to notify...");\n}\n\nvoid loop() {\n \/\/ notify changed value\n if (deviceConnected) {\n pSensorCharacteristic->setValue(String(value).c_str());\n pSensorCharacteristic->notify();\n value++;\n Serial.print("New value notified: ");\n Serial.println(value);\n delay(3000); \/\/ bluetooth stack will go into congestion, if too many packets are sent, in 6 hours test i was able to go as low as 3ms\n }\n \/\/ disconnecting\n if (!deviceConnected && oldDeviceConnected) {\n Serial.println("Device disconnected.");\n delay(500); \/\/ give the bluetooth stack the chance to get things ready\n pServer->startAdvertising(); \/\/ restart advertising\n Serial.println("Start advertising");\n oldDeviceConnected = deviceConnected;\n }\n \/\/ connecting\n if (deviceConnected && !oldDeviceConnected) {\n \/\/ do stuff here on connecting\n oldDeviceConnected = deviceConnected;\n Serial.println("Device Connected");\n }\n}\n<\/code><\/pre>\n\tView raw code<\/a><\/p>\n\n\n\n
This is one of the simplest BLE code examples that turn the ESP32 into a BLE device that writes and listens to changes on characteristics. If you understand how this code works, you can easily modify it to serve more complex projects with more characteristics and services.<\/p>\n\n\n\n
We recommend continuing reading to learn how the code works.<\/p>\n\n\n\n
How the Code Works<\/h2>\n\n\n\n
In summary, this code sets up a BLE server with two characteristics\u2014one for reading sensor data and another for controlling an LED. When a BLE client connects, it can read sensor data and send commands (write on the characteristic) to turn the LED on or off. The code also handles device connection and disconnection events.<\/p>\n\n\n\n
Including Libraries<\/h3>\n\n\n\n
First, you need to import the following libraries to deal with Bluetooth.<\/p>\n\n\n\n
#include <BLEDevice.h>\n#include <BLEServer.h>\n#include <BLEUtils.h>\n#include <BLE2902.h><\/code><\/pre>\n\n\n\nCreating Global Variables<\/h3>\n\n\n\n
Then you create some global variables to use later in your code.<\/p>\n\n\n\n
BLEServer* pServer = NULL;\nBLECharacteristic* pSensorCharacteristic = NULL;\nBLECharacteristic* pLedCharacteristic = NULL;\nbool deviceConnected = false;\nbool oldDeviceConnected = false;\nuint32_t value = 0;\n\nconst int ledPin = 2; \/\/ Use the appropriate GPIO pin for your setup<\/code><\/pre>\n\n\n\n- \n
- pServer<\/span>: Pointer to the BLEServer<\/span> object.<\/li>\n\n\n\n
- pSensorCharacteristic<\/span>: Pointer to the BLECharacteristic<\/span> for reading the sensor value.<\/li>\n\n\n\n
- pLedCharacteristic<\/span>: Pointer to the BLECharacteristic<\/span> for controlling an LED.<\/li>\n\n\n\n
- deviceConnected<\/span>: A boolean variable to track whether a BLE device is connected.<\/li>\n\n\n\n
- oldDeviceConnected<\/span>: A boolean variable to track the previous connection status.<\/li>\n\n\n\n
- value<\/span>: An integer variable used to store and send sensor values.<\/li>\n\n\n\n
- ledPin<\/span>: The GPIO pin number to which an LED is connected.<\/li>\n<\/ul>\n\n\n\n
UUID Definitions<\/h3>\n\n\n\n
Then, you set the UUIDs for the Service and Characteristics. Those UUIDs were created using the uuidgenerator website<\/a>. You can generate your own UUIDs for your application, but for this example, we recommend using the same UUIDs we’re using.<\/p>\n\n\n\n
#define SERVICE_UUID \"19b10000-e8f2-537e-4f6c-d104768a1214\"\n#define SENSOR_CHARACTERISTIC_UUID \"19b10001-e8f2-537e-4f6c-d104768a1214\"\n#define LED_CHARACTERISTIC_UUID \"19b10002-e8f2-537e-4f6c-d104768a1214\"<\/code><\/pre>\n\n\n\nBLE Server and Callbacks<\/h3>\n\n\n\n
Then, you create several callback functions. The MyServerCallbacks<\/span> defines a callback function for device connection and disconnection events. In this case, we change the value of the deviceConnected<\/span> variable to true<\/span> or false<\/span> depending on the connection state.<\/p>\n\n\n\n
class MyServerCallbacks: public BLEServerCallbacks {\n void onConnect(BLEServer* pServer) {\n deviceConnected = true;\n };\n\n void onDisconnect(BLEServer* pServer) {\n deviceConnected = false;\n }\n};<\/code><\/pre>\n\n\n\nThe MyCharacteristicCallbacks<\/span> defines a callback function to read the value of a characteristic when it changes. In our code, we’ll set this callback function for the LED_CHARACTERISTIC<\/span> to detect when the value of the characteristic has changed. We’ll turn the LED on and off accordingly to the value of that characteristic.<\/p>\n\n\n\n
class MyCharacteristicCallbacks : public BLECharacteristicCallbacks {\n void onWrite(BLECharacteristic* onCharacteristic) {\n String value = onCharacteristic->getValue();\n if (value.length() > 0) {\n Serial.print(\"Characteristic event, written: \");\n Serial.println(static_cast<int>(value[0])); \/\/ Print the integer value\n\n int receivedValue = static_cast<int>(value[0]);\n if (receivedValue == 1) {\n digitalWrite(ledPin, HIGH);\n } else {\n digitalWrite(ledPin, LOW);\n }\n }\n }\n};<\/code><\/pre>\n\n\n\nsetup()<\/h3>\n\n\n\n
In the setup()<\/span>, initialize serial communication for debugging.<\/p>\n\n\n\n
Serial.begin(115200);<\/code><\/pre>\n\n\n\nSet the ledPin<\/span> as an output.<\/p>\n\n\n\n
pinMode(ledPin, OUTPUT);<\/code><\/pre>\n\n\n\nInitialize the ESP32 as BLE device called ESP32<\/span>. You can call it any other name, but for this project we recommend using this name to be compatible with the app we’ll build later on.<\/p>\n\n\n\n
Then, create a BLE server and set its callbacks for connection and disconnection.<\/p>\n\n\n\n
\/\/ Create the BLE Server\npServer = BLEDevice::createServer();\npServer->setCallbacks(new MyServerCallbacks());<\/code><\/pre>\n\n\n\nCreate a BLE service with the UUID we’ve defined earlier.<\/p>\n\n\n\n
\/\/ Create the BLE Service\nBLEService *pService = pServer->createService(SERVICE_UUID);<\/code><\/pre>\n\n\n\nCreate a BLE characteristic (inside the service we just created) for sensor values and set its properties (read, write, notify, indicate).<\/p>\n\n\n\n
\/\/ Create a BLE Characteristic\npSensorCharacteristic = pService->createCharacteristic(\n SENSOR_CHARACTERISTIC_UUID,\n BLECharacteristic::PROPERTY_READ |\n BLECharacteristic::PROPERTY_WRITE |\n BLECharacteristic::PROPERTY_NOTIFY |\n BLECharacteristic::PROPERTY_INDICATE\n );<\/code><\/pre>\n\n\n\nCreate a BLE characteristic for the LED characteristic and set its property (write).<\/p>\n\n\n\n
\/\/ Create the ON button Characteristic\npLedCharacteristic = pService->createCharacteristic(\n LED_CHARACTERISTIC_UUID,\n BLECharacteristic::PROPERTY_WRITE\n );<\/code><\/pre>\n\n\n\nRegister the callback for the LED characteristic, so that we detect when a new value was written on that characteristic.<\/p>\n\n\n\n
pLedCharacteristic->setCallbacks(new MyCharacteristicCallbacks());<\/code><\/pre>\n\n\n\nAdd BLE descriptors (BLE2902<\/span>) to both characteristics. <\/p>\n\n\n\n
\nNote:<\/strong> BLE2902 is a specific descriptor that is often used for Client Characteristic Configuration (CCC). CCC descriptors are used to configure how a client (the device connecting to the server) wants to be notified or indicated of changes in a characteristic’s value. In simpler terms, they control whether the client should receive notifications or indications when the value of the associated characteristic changes.<\/p>\n\n\n\n
By adding BLE2902 descriptors to both characteristics, you make it possible for clients to configure how they want to be notified or updated when the values of these characteristics change. Clients can use these descriptors to enable or disable notifications or indications, depending on their preferences or requirements for real-time updates from the ESP32 server.<\/p>\n<\/div><\/div>\n\n\n\n
Start the BLE service.<\/p>\n\n\n\n
\/\/ Start the service\npService->start();<\/code><\/pre>\n\n\n\nAnd finally, configure advertising settings and start advertising.<\/p>\n\n\n\n
\/\/ Start advertising\nBLEAdvertising *pAdvertising = BLEDevice::getAdvertising();\npAdvertising->addServiceUUID(SERVICE_UUID);\npAdvertising->setScanResponse(false);\npAdvertising->setMinPreferred(0x0); \/\/ set value to 0x00 to not advertise this parameter\nBLEDevice::startAdvertising();\nSerial.println(\"Waiting a client connection to notify...\");<\/code><\/pre>\n\n\n\nloop()<\/h3>\n\n\n\n
In the loop()<\/span>, if a BLE device is connected (deviceConnected<\/span> is true<\/span>), it updates the sensor value, notifies the client, and increments the value.<\/p>\n\n\n\n
if (deviceConnected) {\n pSensorCharacteristic->setValue(String(value).c_str());\n pSensorCharacteristic->notify();\n value++;\n Serial.print(\"New value notified: \");\n Serial.println(value);\n delay(3000); \/\/ bluetooth stack will go into congestion, if too many packets are sent, in 6 hours test i was able to go as low as 3ms\n}<\/code><\/pre>\n\n\n\nIf a device disconnects and oldDeviceConnected<\/span> is true<\/span>, it restarts advertising and logs a message.
If a device connects and oldDeviceConnected<\/span> is false<\/span>, it logs a message (you can add your own logic here for actions to be taken on connection).<\/p>\n\n\n\n\/\/ disconnecting\nif (!deviceConnected && oldDeviceConnected) {\n Serial.println(\"Device disconnected.\");\n delay(500); \/\/ give the bluetooth stack the chance to get things ready\n pServer->startAdvertising(); \/\/ restart advertising\n Serial.println(\"Start advertising\");\n oldDeviceConnected = deviceConnected;\n}\n\/\/ connecting\nif (deviceConnected && !oldDeviceConnected) {\n \/\/ do stuff here on connecting\n oldDeviceConnected = deviceConnected;\n Serial.println(\"Device Connected\");\n}<\/code><\/pre>\n\n\n\nUploading the Code<\/h2>\n\n\n\n
Upload the code to your ESP32 board. After uploading, open the Serial Monitor and restart your board.<\/p>\n\n\n\n
You’ll see that it initialized the BLE service and is waiting for a connection from a client.<\/p>\n\n\n
\n![\"ESP32](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2023\/09\/ESP32-BLE-Waiting-Client-Notify.png?resize=601%2C381&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\nNow that you’ve set the ESP32 as a BLE Client, we’ll create the web app so that we can interact with the ESP32 via Bluetooth using our web browser.<\/p>\n\n\n\n
Alternatively, you can use our web app by going to this URL:<\/p>\n\n\n\n
- \n
- <\/a>https:\/\/ruisantosdotme.github.io\/esp32-web-ble<\/a><\/li>\n<\/ul>\n\n\n\n<\/figure><\/div>\n\n\n
Connect to your ESP32 BLE device and see the values sent by the ESP32 being displayed on the interface and control the ESP32 on-board LED with the ON and OFF buttons. If you want to learn how to build the web app, continue reading.<\/p>\n\n\n\n
Creating the Web BLE App<\/h2>\n\n\n\n
Create an HTML file called index.html<\/em> with the following code (it contains both the HTML to build the web page and Javascript to handle Web Bluetooth).<\/p>\n\n\n
<!--\n Rui Santos\n Complete project details at https:\/\/RandomNerdTutorials.com\/esp32-web-bluetooth\/\n\n Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files.\n The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n-->\n\n<!DOCTYPE html>\n<html>\n<head>\n <title>ESP32 Web BLE App<\/title>\n <meta name="viewport" content="width=device-width, initial-scale=1">\n <link rel="icon" type="image\/png" href="">\n<\/head>\n<body>\n <h1>ESP32 Web BLE Application<\/h1>\n <button id="connectBleButton">Connect to BLE Device<\/button>\n <button id="disconnectBleButton">Disconnect BLE Device<\/button>\n <p>BLE state: <strong><span id="bleState" style="color:#d13a30;">Disconnected<\/span><\/strong><\/p>\n <h2>Fetched Value<\/h2>\n <p><span id="valueContainer">NaN<\/span><\/p>\n <p>Last reading: <span id="timestamp"><\/span><\/p>\n <h2>Control GPIO 2<\/h2>\n <button id="onButton">ON<\/button>\n <button id="offButton">OFF<\/button>\n <p>Last value sent: <span id="valueSent"><\/span><\/p>\n <p><a href="https:\/\/randomnerdtutorials.com\/">Created by RandomNerdTutorials.com<\/a><\/p>\n <p><a href="https:\/\/RandomNerdTutorials.com\/esp32-web-bluetooth\/">Read the full project here.<\/a><\/p>\n<\/body>\n<script>\n \/\/ DOM Elements\n const connectButton = document.getElementById('connectBleButton');\n const disconnectButton = document.getElementById('disconnectBleButton');\n const onButton = document.getElementById('onButton');\n const offButton = document.getElementById('offButton');\n const retrievedValue = document.getElementById('valueContainer');\n const latestValueSent = document.getElementById('valueSent');\n const bleStateContainer = document.getElementById('bleState');\n const timestampContainer = document.getElementById('timestamp');\n\n \/\/Define BLE Device Specs\n var deviceName ='ESP32';\n var bleService = '19b10000-e8f2-537e-4f6c-d104768a1214';\n var ledCharacteristic = '19b10002-e8f2-537e-4f6c-d104768a1214';\n var sensorCharacteristic= '19b10001-e8f2-537e-4f6c-d104768a1214';\n\n \/\/Global Variables to Handle Bluetooth\n var bleServer;\n var bleServiceFound;\n var sensorCharacteristicFound;\n\n \/\/ Connect Button (search for BLE Devices only if BLE is available)\n connectButton.addEventListener('click', (event) => {\n if (isWebBluetoothEnabled()){\n connectToDevice();\n }\n });\n\n \/\/ Disconnect Button\n disconnectButton.addEventListener('click', disconnectDevice);\n\n \/\/ Write to the ESP32 LED Characteristic\n onButton.addEventListener('click', () => writeOnCharacteristic(1));\n offButton.addEventListener('click', () => writeOnCharacteristic(0));\n\n \/\/ Check if BLE is available in your Browser\n function isWebBluetoothEnabled() {\n if (!navigator.bluetooth) {\n console.log("Web Bluetooth API is not available in this browser!");\n bleStateContainer.innerHTML = "Web Bluetooth API is not available in this browser!";\n return false\n }\n console.log('Web Bluetooth API supported in this browser.');\n return true\n }\n\n \/\/ Connect to BLE Device and Enable Notifications\n function connectToDevice(){\n console.log('Initializing Bluetooth...');\n navigator.bluetooth.requestDevice({\n filters: [{name: deviceName}],\n optionalServices: [bleService]\n })\n .then(device => {\n console.log('Device Selected:', device.name);\n bleStateContainer.innerHTML = 'Connected to device ' + device.name;\n bleStateContainer.style.color = "#24af37";\n device.addEventListener('gattservicedisconnected', onDisconnected);\n return device.gatt.connect();\n })\n .then(gattServer =>{\n bleServer = gattServer;\n console.log("Connected to GATT Server");\n return bleServer.getPrimaryService(bleService);\n })\n .then(service => {\n bleServiceFound = service;\n console.log("Service discovered:", service.uuid);\n return service.getCharacteristic(sensorCharacteristic);\n })\n .then(characteristic => {\n console.log("Characteristic discovered:", characteristic.uuid);\n sensorCharacteristicFound = characteristic;\n characteristic.addEventListener('characteristicvaluechanged', handleCharacteristicChange);\n characteristic.startNotifications();\n console.log("Notifications Started.");\n return characteristic.readValue();\n })\n .then(value => {\n console.log("Read value: ", value);\n const decodedValue = new TextDecoder().decode(value);\n console.log("Decoded value: ", decodedValue);\n retrievedValue.innerHTML = decodedValue;\n })\n .catch(error => {\n console.log('Error: ', error);\n })\n }\n\n function onDisconnected(event){\n console.log('Device Disconnected:', event.target.device.name);\n bleStateContainer.innerHTML = "Device disconnected";\n bleStateContainer.style.color = "#d13a30";\n\n connectToDevice();\n }\n\n function handleCharacteristicChange(event){\n const newValueReceived = new TextDecoder().decode(event.target.value);\n console.log("Characteristic value changed: ", newValueReceived);\n retrievedValue.innerHTML = newValueReceived;\n timestampContainer.innerHTML = getDateTime();\n }\n\n function writeOnCharacteristic(value){\n if (bleServer && bleServer.connected) {\n bleServiceFound.getCharacteristic(ledCharacteristic)\n .then(characteristic => {\n console.log("Found the LED characteristic: ", characteristic.uuid);\n const data = new Uint8Array([value]);\n return characteristic.writeValue(data);\n })\n .then(() => {\n latestValueSent.innerHTML = value;\n console.log("Value written to LEDcharacteristic:", value);\n })\n .catch(error => {\n console.error("Error writing to the LED characteristic: ", error);\n });\n } else {\n console.error ("Bluetooth is not connected. Cannot write to characteristic.")\n window.alert("Bluetooth is not connected. Cannot write to characteristic. \\n Connect to BLE first!")\n }\n }\n\n function disconnectDevice() {\n console.log("Disconnect Device.");\n if (bleServer && bleServer.connected) {\n if (sensorCharacteristicFound) {\n sensorCharacteristicFound.stopNotifications()\n .then(() => {\n console.log("Notifications Stopped");\n return bleServer.disconnect();\n })\n .then(() => {\n console.log("Device Disconnected");\n bleStateContainer.innerHTML = "Device Disconnected";\n bleStateContainer.style.color = "#d13a30";\n\n })\n .catch(error => {\n console.log("An error occurred:", error);\n });\n } else {\n console.log("No characteristic found to disconnect.");\n }\n } else {\n \/\/ Throw an error if Bluetooth is not connected\n console.error("Bluetooth is not connected.");\n window.alert("Bluetooth is not connected.")\n }\n }\n\n function getDateTime() {\n var currentdate = new Date();\n var day = ("00" + currentdate.getDate()).slice(-2); \/\/ Convert day to string and slice\n var month = ("00" + (currentdate.getMonth() + 1)).slice(-2);\n var year = currentdate.getFullYear();\n var hours = ("00" + currentdate.getHours()).slice(-2);\n var minutes = ("00" + currentdate.getMinutes()).slice(-2);\n var seconds = ("00" + currentdate.getSeconds()).slice(-2);\n\n var datetime = day + "\/" + month + "\/" + year + " at " + hours + ":" + minutes + ":" + seconds;\n return datetime;\n }\n\n\n<\/script>\n\n<\/html>\n<\/code><\/pre>\n\t
- pSensorCharacteristic<\/span>: Pointer to the BLECharacteristic<\/span> for reading the sensor value.<\/li>\n\n\n\n
- Service<\/strong>: collection of related information, like sensor readings, battery level, heart rate, etc. ;<\/li>\n\n\n\n
- ESP32 BLE Server and Client (Bluetooth Low Energy)<\/a><\/li>\n<\/ul>\n\n\n\n
- BLE Server and Client<\/a><\/li>\n\n\n\n
- Bluetooth Low Energy Introduction – Basic Concepts<\/a>\n
![\"ESP32](\"https:\/\/i2.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2023\/09\/Web-BLE-connected-ESP32.png?ssl=1\")
<\/figure><\/div>![\"ESP32](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2023\/09\/ESP32-BLE-application.png?ssl=1\")
<\/figure><\/div><\/div><\/div><\/div><\/div>\n\n\n\n