Differences

This shows you the differences between two versions of the page.

--- en:iot-open:practical:hardware:sut:esp32:iot_8 [2024/04/15 17:36] – ktokarz
+++ en:iot-open:practical:hardware:sut:esp32:iot_8 [2025/04/12 08:37] (current) – [IoT8: BLE Communication with characteristics] ktokarz
@@ Line 1: / Line 1: @@
-====== IoT_8: BLE Communication with characteristics =====
+====== IoT8: BLE Communication with characteristics =====
-This scenario presents how to create the Bluetooth Low Energy server device and corresponding client device. The server can be the sensor device which responds to the client with the results of the measurements. This can also be the output device, which we can control writing the data to. The client connects to a server and reads the data. This scenario presents the use of the concept of services and characteristics.
+This scenario presents how to create the Bluetooth Low Energy server device and the corresponding client device. The server can be the sensor device which responds to the client with the results of the measurements. This can also be the output device, which we can control by writing the data to. The client connects to a server and reads the data. This scenario presents the use of the concept of services and characteristics.
 ===== Prerequisites =====
-It is necessary to understand the principles of the Bluetooth Low Energy protocol with concepts of services, characteristics and descriptors. We will use in this scenario the knowledge of the advertising process so making the IoT_7 exercise is recommended.
+It is necessary to understand the principles of the Bluetooth Low Energy protocol with concepts of services, characteristics and descriptors. We will use in this scenario the knowledge of the advertising process so making the [[en:iot-open:practical:hardware:sut:esp32:IoT_7]] exercise is recommended.
 ===== Suggested Readings and Knowledge Resources =====
@@ Line 16: / Line 16: @@
 ==== Task to be implemented ====
 **Task 1.** Implement a program that operates as the BLE server which advertises itself and allows us to connect to.
+\\
 **Task 2.** Implement a client device, to read the exemplary data from a server.
 ==== Start ====
-You can use the beacon and simple client programs from IoT_7 as the starting point.
+You can use the beacon and simple client programs from [[en:iot-open:practical:hardware:sut:esp32:IoT_7]] as the starting point.
 ==== Steps ====
-We will present the lab in a few steps. We begin with a simple program which advertises the device with a single service containing a single characteristic. It allows us to establish a connection with a client and, if successfully connected, responds with simple text data. In further steps, we will improve the program to make it more reliable, eg. by returning to the advertisement procedure after disconnecting.
+We will present the lab in a few steps. We begin with a simple program which advertises the device with a single service containing a single characteristic. It allows us to establish a connection with a client and, if successfully connected, responds with simple text data. The program returns automatically to the advertisement procedure after disconnecting.
 === Step 1 ===
@@ Line 57: / Line 58: @@
 #define CHARACTERISTIC_UUID "6e9b7b27-ca96-4774-b056-8ec5b759fd86"
 </code>
-The setup() function creates and initialises the BLE device instance with the name "SUT BLE device", and creates the server and the service within the server.
+Before we implement the setup() function, we have to create the callback function executed in case of connection and disconnection events. It allows us to control the advertising process with the deviceConnected flag.
+<code c>
+class MyServerCallbacks: public BLEServerCallbacks {
+    void onConnect(BLEServer* pServer) {
+      deviceConnected = true;
+    };
+    void onDisconnect(BLEServer* pServer) {
+      deviceConnected = false;
+    }
+};
+</code>
+The setup() function creates and initialises the BLE device instance with the name "SUT BLE device", and creates the server and sets the callback function. It also creates the service within the server.
 <code>
-BLEDevice::init("SUT BLE device");      //initialise the BLE device
+// Initialise the BLE device
-pServer = BLEDevice::createServer();
+BLEDevice::init("SUT BLE device");
+// Create BLE Server instance
+pServer = BLEDevice::createServer();
+// Set callback function for handling server events
+pServer->setCallbacks(new MyServerCallbacks());
+// Create the service in the server
 pService = pServer->createService(SERVICE_UUID);
 </code>
 Data for reading or writing is organised using characteristics. In this example, we create one characteristic with reading and writing enabled, and the initial data as the "BLE onboard" text.
 <code>
+// Create the characteristic in the service
 pCharacteristic = pService->createCharacteristic(
                                          CHARACTERISTIC_UUID,
@@ Line 70: / Line 97: @@
                                          BLECharacteristic::PROPERTY_WRITE
                                        );
+// Set the initial value of the characteristic.
+// We will be able to read it by client
 pCharacteristic->setValue("BLE onboard");
 </code>
 In the advertising packet, we can add the service UUID.
 <code>
+// Get the pointer to the advertising object
 pAdvertising = BLEDevice::getAdvertising();
+// Add the service UUID to the advertising
 pAdvertising->addServiceUUID(SERVICE_UUID);
+// Enable reading extended information with scan response packet
 pAdvertising->setScanResponse(true);
 </code>
@@ Line 83: / Line 118: @@
 After preparing all the elements we can close the setup() function by starting the service and beginning advertising.
 <code>
+// Starting the service and advertising process
 pService->start();
 pAdvertising->start();
 </code>
-The loop function can remain empty or call the delay function periodically.
+In the loop function, we need to handle the restarting of advertising in case of disconnection of the client.
 <code>
 void loop(){
-   delay(1000);
+    if (!deviceConnected && !advStarted) {
+        pServer->startAdvertising(); // restart advertising
+        advStarted = true;
+    }
+    if (deviceConnected){
+        advStarted = false;
+    }
+    delay(500);
 };
 </code>
@@ Line 95: / Line 139: @@
 === Step 2 ===
 In this step, we will analyse the behaviour of the client. The client software is much more complex than the server. It is because the server, called also the central device, in many circumstances is a more powerful device than the peripheral. Some parts of the software are implemented as callback functions because they handle reactions on the data coming asynchronously from the server. The diagram presents the algorithm of the client and data coming from the server.
-{{ en:iot-open:practical:hardware:sut:esp32:ble_client.drawio.svg?500 |The client algorithm}}
+{{ en:iot-open:practical:hardware:sut:esp32:ble_client_char.drawio.svg?500 |The client algorithm}}
 === Step 3 ===
@@ Line 102: / Line 146: @@
 #include "Arduino.h"
 #include "BLEDevice.h"
+#include "Adafruit_LiquidCrystal.h"
 </code>
 Next, we define the UUIDs for remote service and a characteristic. Notice they must match the ones defined in the server.
@@ Line 108: / Line 153: @@
 #define SERVICE_UUID "6e9b7b26-ca96-4774-b056-8ec5b759fd86"
 // The characteristic of the remote service we are interested in.
-#define REMOTE_CHARACTERISTIC_UUID "6e9b7b28-ca96-4774-b056-8ec5b759fd86"
+#define REMOTE_CHARACTERISTIC_UUID "6e9b7b27-ca96-4774-b056-8ec5b759fd86"
 </code>
@@ Line 119: / Line 164: @@
 static BLERemoteCharacteristic* pRemoteCharacteristic;
 static BLEAdvertisedDevice* myDevice;
+</code>
+We need to add and configure the LCD to be able to observe the results.
+<code c>
+// LCD display pins and class declaration
+#define LCD_RS 2
+#define LCD_ENABLE 1
+#define LCD_D4 39
+#define LCD_D5 40
+#define LCD_D6 41
+#define LCD_D7 42
+static Adafruit_LiquidCrystal lcd(LCD_RS, LCD_ENABLE, LCD_D4, LCD_D5, LCD_D6, LCD_D7);
 </code>
@@ Line 128: / Line 184: @@
 class MyAdvertisedDeviceCallbacks: public BLEAdvertisedDeviceCallbacks {
   void onResult(BLEAdvertisedDevice advertisedDevice) {
+    // We will print the asterix for every device found
+    lcd.print("*");
     // We have found a device, let's see if it contains the service we are looking for.
     if (advertisedDevice.haveServiceUUID() && advertisedDevice.isAdvertisingService(BLEUUID(SERVICE_UUID))) {
+      // Our device has the service we need. We can stop scanning.
       BLEDevice::getScan()->stop();
+      // Create the instance of remote device
       myDevice = new BLEAdvertisedDevice(advertisedDevice);
+      // Pass information to other part of the program to connect to the device
       doConnect = true;
       doScan = true;
     } // Found our server
@@ Line 141: / Line 207: @@
 </code>
-The second callback class helps to inform the other parts of the program about the connection close.
+The second callback class helps to inform the other parts of the program about the connection close. It will additionally inform us about the current state of the program.
 <code>
 class MyClientCallback : public BLEClientCallbacks {
   void onConnect(BLEClient* pclient) {
+      lcd.setCursor(0,0);
+      lcd.print("Connected       ");
   }
   void onDisconnect(BLEClient* pclient) {
+      lcd.setCursor(0,0);
+      lcd.print("Disconnected    ");
+      lcd.setCursor(0,1);
     connected = false;
   }
-};
+};</code>
-</code>
 The setup function initialises the Bluetooth, registers the advertising callback function, and starts the scan to look for nearby devices.
 <code>
 void setup() {
+  // Initialise the LCD and print the welcome message
+  lcd.begin(16, 2);
+  delay(1000);
+  lcd.setCursor(0,0);
+  lcd.print("BLE Client      ");
   // Initialise the Bluetooth
   BLEDevice::init("");
@@ Line 169: / Line 245: @@
   pBLEScan->setWindow(449);
   pBLEScan->setActiveScan(true);
+  // Print the message on the LCD
+  lcd.setCursor(0,0);
+  lcd.print("Scanning        ");
+  lcd.setCursor(0,1);
   // Start the scan for 30 seconds
@@ Line 175: / Line 256: @@
 </code>
-In the loop function, we wait for the information that the server with the service UUID we were interested in was found. It is signalled with the use of "doConnect" flag. If it's true we can connect to this server. Once we are connected the "connected" flag is set to be true in the connectToServer() function. We will show this function in a while.
+In the loop() function, we wait for the information that the server with the service UUID we were interested in was found. It is signalled with the use of "doConnect" flag. If it's true we can connect to this server. Once we are connected the "connected" flag is set to be true in the connectToServer() function. We will show this function in a while.
-<code>
+\\
+In a loop() function we will periodically read the characteristic value. It is a good practice to check if the characteristic is properly retrieved and readable before reading the value.
+<code c>
 void loop() {
   if (doConnect == true) {
-    connectToServer();     // Establish the connection to the server
+    // Establish the connection to the server
+    connectToServer();
     doConnect = false;
   }
@@ Line 185: / Line 269: @@
   if (!connected) {
     if(doScan){
-      BLEDevice::getScan()->start(0);  // Start scan again after disconnect
+      // Start scan again after disconnect
+      BLEDevice::getScan()->start(0);
     }
+  }
+  if (connected) {
+    lcd.setCursor(0,1);
+    // Is the characteristic properly retrieved?
+    if(pRemoteCharacteristic != nullptr)
+      // Is the characteristic readable?
+      if(pRemoteCharacteristic->canRead())
+        // We can safely read the value
+        lcd.print(pRemoteCharacteristic->readValue().c_str());
   }
   delay(1000); // Delay a second between loops.
@@ Line 220: / Line 318: @@
 </code>
-=== Step 4 ===
-BLE peripheral device stops advertising after establishing a connection. While the connection is closed or lost it should restart advertising to be able to accept further connections. Doing it is possible with the use of callback functions, executed in selected events occurrence. We need to add the callback functions called on the connection and disconnection events. We will use two global boolean variables, one to store the state of the device, and another to control the single advertising start.
-<code c>
-bool deviceConnected = false;
-bool advStarted = true;  //first advertise starts automatically
-class MyServerCallbacks: public BLEServerCallbacks {
-    void onConnect(BLEServer* pServer) {
-      deviceConnected = true;
-    };
-    void onDisconnect(BLEServer* pServer) {
-      deviceConnected = false;
-    }
-};
-</code>
-In the setup() function, just after the creation of the server we set up the callbacks.
-<code>
-pServer->setCallbacks(new MyServerCallbacks());
-</code>
-In the loop() function we have to program the starting of the advertising while the connection is ended. The startAdvertising() function should be called just once so the advStarted boolean variable helps us to control this process.
-<code>
-void loop(){
-    if (!deviceConnected && !advStarted) {
-        pServer->startAdvertising(); // restart advertising
-        advStarted = true;
-    }
-    if (deviceConnected){
-        advStarted = false;
-    }
-  }
-  delay(500);
-};
-</code>
 ==== Result validation ====
-You should be able to find the device in the BLE neighbourhood. It should allow us to establish connection, read the characteristic data and write a new value. Notice that the modified value remains unchanged until the new start of the device.
+You should be able to observe messages describing the process of searching for the server on the first line of LCD and during scanning asterisks appearing on the second line. After establishing the connection, the characteristic value should appear on the display's second line.
 ===== FAQ =====

en/iot-open/practical/hardware/sut/esp32/iot_8.1713202609.txt.gz · Last modified: 2024/04/15 17:36 by ktokarz