Differences

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

--- en:iot-open:practical:hardware:sut:stm32:iot_7 [2024/05/04 12:18] – created ktokarz
+++ en:iot-open:practical:hardware:sut:stm32:iot_7 [2024/05/04 14:03] (current) – [STM_IoT_7: BLE Communication with notifications] ktokarz
@@ Line 1: / Line 1: @@
+====== STM_IoT_7: BLE Communication with indications =====
+This scenario presents how to extend the Bluetooth Low Energy server and client devices with a notification or indication mechanism for sending data automatically. If enabled, notifications or indications are sent at any time while the data in the server is updated. A difference between them is that a notification is an unacknowledged message while an indication is an acknowledged message. While one of them is enabled by the client, the server decides on the time of the message sent.
+===== 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 [[en:iot-open:practical:hardware:sut:stm32:IoT_6]] exercise is recommended.
+===== Suggested Readings and Knowledge Resources =====
+  * [[en:iot-open:introductiontoembeddedprogramming2:cppfundamentals]]
+  * [[en:iot-open:hardware2:stm32|]]
+  * [[en:iot-open:practical:hardware:sut:stm32|]]
+===== Hands-on Lab Scenario =====
+This scenario is intended to be implemented using two BLE laboratory nodes. One of them is a server, while the second is a client. Here we will present the extension of the scenario implemented in [[en:iot-open:practical:hardware:sut:stm32:IoT_6]]
+<note>
+The Nucleo STM32WB55 development boards which are used in our STM laboratory don't have the BLE firmware flashed by default. If you would like to test this scenario on your own board please refer to the STM documentation on the flashing process ((https://wiki.stmicroelectronics.cn/stm32mcu/wiki/Connectivity:STM32WB_FUS)). Read and follow the documentation carefully because of the danger of "bricking" your device.
+</note>
+==== Task to be implemented ====
+**Task 1.** Implement a program that operates as the BLE server which advertises itself and allows us to connect to. We should be able to subscribe to indications of the characteristic.
+\\
+**Task 2.** Implement a client device, capable of subscribing to the characteristic and reading the exemplary data from a server with a indication mechanism.
+==== Start ====
+It is advised to use the server and client programs from [[en:iot-open:practical:hardware:sut:stm32:IoT_6]] as the starting point.
+==== Steps ====
+We will pass through the lab in a few steps. We will add the second characteristic to the example from lab [[en:iot-open:practical:hardware:sut:stm32:IoT_6]]. We will configure this characteristic as capable of transmitting data with indication. It allows us to establish a connection and, if successfully connected, enable the indication feature. With this feature enabled, the peripheral device initiates data transmission. It can be used for periodic measurement reading or updating information on value change.
+=== Step 1 ===
+We start with the program written during the laboratory [[en:iot-open:practical:hardware:sut:stm32:IoT_6]] by adding another characteristic to the service and variable required to hold the pointer to the characteristic class. We need to define the UUID for this characteristic.
+<code c>
+#define INDICATE_CHARACTERISTIC_UUID "6e9b7b28-ca96-4774-b056-8ec5b759fd86"
+// BLE Characteristic - custom 128-bit UUID, read and notify enabled
+BLEByteCharacteristic pIndicateCharacteristic(INDICATE_CHARACTERISTIC_UUID, BLERead | BLEWrite | BLEIndicate);
+</code>
+In the setup() function we add a new characteristic to the service and set its initial value.
+<code>
+// add the characteristic to the service
+pService.addCharacteristic(pIndicateCharacteristic);
+// set the initial value for the characteristic:
+pIndicateCharacteristic.setValue(1);
+</code>
+After these modifications, it would be possible to observe an additional characteristic in the service with the possibility of reading, writing, and enabling notifications.
+=== Step 2 ===
+At this step, we implement periodical data sending. We add the counter variable, an integer for holding the value incremented every loop pass. We will increment this counter with use of millis() function to do not block the loop() with delay();
+<code c>
+int counter = 1;
+int delay_millis;
+</code>
+In the main loop() we implement the incrementation of the counter and updating of the characteristic.
+<code c>
+void loop() {
+  // listen for BLE peripherals to connect:
+  BLE.central();
+  if (millis() > delay_millis +1000){
+    delay_millis = millis();
+    pIndicateCharacteristic.setValue(counter);
+    counter++;
+  }
+}
+</code>
+=== Step 3 ===
+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}}
+=== Step 4 ===
+While we have analysed the client's behaviour we can start implementation. Let's begin with modifying the remote characteristic for receiving notifications. Notice its UUID they must match the one defined in the server.
+<code c>
+#define REMOTE_NOTIFY_CHARACTERISTIC_UUID "6e9b7b28-ca96-4774-b056-8ec5b759fd86"
+</code>
+<note>
+We intentionally specified here the same UUIDs as in ESP32 BLE scenarios. If both platforms are physically available in the same laboratory, you can try to connect different hardware platforms with BLE.
+</note>
+In a loop() function we check if a peripheral with UUID we are interested in was discovered. If so we check its name. If the remote device's name is as we expect we print its name, stop scanning, and call the function which reads and displays the value of the characteristic. This function uses the polling method of reading the updated characteristic value. While the function returns, we restart scanning.
+<note>
+At the time of writing this book the mechanism available for automatic update of the characteristic value was indication only. Notifications couldn't be subscribed.
+</note>
+We will present the full code of the function to subscribe and receive the indications. The function reads the characteristic value in some steps:
+  - Connects to the remote device.
+  - Discovers attributes of the remote service.
+  - Retrieves the characteristic with specified UUID.
+  - Checks if the remote device is properly connected.
+  - Checks if the remote characteristic can be subscribed.
+  - Subscribes to the characteristic with indication mechanism.
+  - Waits for the characteristic value update.
+  - Reads the value and displays it on LCD.
+<code c>
+void display_characteristic(BLEDevice peripheral) {
+  // connect to the peripheral
+  if (peripheral.connect()) {
+    // discover peripheral attributes
+    if (peripheral.discoverAttributes()) {
+      // retrieve the remote characteristic to read
+      remoteCharacteristic = peripheral.characteristic(REMOTE_NOTIFY_CHARACTERISTIC_UUID);
+      if (remoteCharacteristic) {
+        // check if the characteristic can be read
+        if (remoteCharacteristic.canSubscribe()){
+          remoteCharacteristic.subscribe();
+          // if the peripheral is connected display the value
+          while (peripheral.connected()) {
+            // check if the value was updated
+            if (remoteCharacteristic.valueUpdated()) {
+              // yes, get the value, characteristic is 1 byte so use byte value
+              byte value = 0;
+              remoteCharacteristic.readValue(value);
+              lcd.setCursor(0,1);
+              lcd.print(value);
+            } // if (remoteCharacteristic.valueUpdated())
+          } // while (peripheral.connected())
+        } // if (remoteCharacteristic.canSubscribe())
+      } // if (remoteCharacteristic)
+      peripheral.disconnect();
+    } // if (peripheral.discoverAttributes())
+  } // if (peripheral.connect())
+}
+</code>
+==== Result validation ====
+You should be able to read the name of the remote device in the first line of the LCD. After establishing the connection, the characteristic value should appear on the display's second line.
+===== FAQ =====
+**What is the difference between notification and indication?**: As it was mentioned in the beginning the notification is an unacknowledged message while an indication is an acknowledged message. It means that if the indication message remains unacknowledged, the peripheral device won't send another message for this characteristic.
+\\
+**Is the notification/indication mechanism similar to interrupts?**: You are right. They work in a similar manner as interrupts in the microprocessor. They allow sending the data asynchronously, and the peripheral decides about the time of the message sent like the peripheral decides on the time of signalling interrupt. Data transmission when the central device sends the packet with a characteristic read command is similar to the polling method used in microprocessors.
+<WRAP noprint>
+===== Project information =====
+{{:en:iot-open:logo_iot_200_px.png?200|}}\\
+This Intellectual Output was implemented under the Erasmus+ KA2.\\
+Project IOT-OPEN.EU Reloaded – Education-based strengthening of the European universities, companies and labour force in the global IoT market.\\
+Project number: 2022-1-PL01-KA220-HED-000085090.
+**__Erasmus+ Disclaimer__**\\
+This project has been funded with support from the European Commission. \\
+This publication reflects the views of only the author, and the Commission cannot be held responsible for any use that may be made of the information contained therein.
+**__Copyright Notice__**\\
+This content was created by the IOT-OPEN.EU Reloaded consortium, 2022,2024.\\
+The content is Copyrighted and distributed under CC BY-NC [[https://en.wikipedia.org/wiki/Creative_Commons_license|Creative Commons Licence]], free for Non-Commercial use.
+<figure label>
+{{:en:iot-open:ccbync.png?100|}}
+</figure>
+</WRAP>