Differences

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

--- en:edu:zmitac:s2:iotn:ble1 [2023/12/16 13:52] – [Description of the most important elements of the code] ktokarz
+++ en:edu:zmitac:s2:iotn:ble1 [2023/12/17 19:57] (current) – [Bluetooth Low Energy for STM32 - peripheral] ktokarz
@@ Line 1: / Line 1: @@
-====== Bluetooth Low Energy for STM32 - peripheral ======
+====== Bluetooth Low Energy for STM32 - peripheral write ======
 This laboratory shows the details of the example provided as part of the STM32duinoBLE library by Arduino.
 ===== Installing the library and importing the example =====
@@ Line 14: / Line 14: @@
 </figure>
 ===== Description of the most important elements of the code =====
+==== Variables and objects definition ====
 To use the BLE device you need to create the object of the BLELocalDevice class. This object can work using the SPI-connected Bluetooth module or the built-in unit in SoC. In the case of STM32WB55, the internal unit is used, so the HCISharedMemTransportClass is chosen as the connection to the BLE module.
 <code>
@@ Line 28: / Line 29: @@
 BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite);
 </code>
-The number of characteristics in one service is limited to 512 by BLE specification. You can experiment on how many characteristics can be used in Arduino implementation.\\
+The characteristic defined in the example allows remote devices to read or write byte values. It is also possible to define characteristics which contain the text string.
-The BLE subsystem must be initialized before use. It is possible to check if initialisation is successful.
+<code>
+BLECharacteristic textCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1215",  BLERead | BLEWrite, "sample text");
+</code>
+In the BLE specification, the maximal length of the characteristic's value is 512 bytes, the number of characteristics in one service is also limited to 512. You can experiment on how many characteristics can be used in Arduino implementation.\\
+The example program allows the remote device to control the state of the LED, so there is also a declaration of the "ledPin" variable.
+<code>
+const int ledPin = LED_BUILTIN; // pin to use for the LED
+</code>
+==== Initialization ====
+The BLE subsystem must be initialized before use. It is possible to check if initialisation is successful. This can be done once in the Arduino "setup()" function.
 <code>
  // begin initialization
@@ Line 53: / Line 63: @@
   BLE.addService(ledService);
 </code>
-The order is important, first, you need to add characteristic (or more characteristics) to the service, next add the service to the list of services.
+The order is important, first, you need to add a characteristic (or more characteristics) to the service, next, add the service to the list of services.
 <note>The number and list of services available after establishing the connection can differ from those advertised.</note>
+Before starting the advertising process it is possible to set the initial value of the characteristic.
+<code>
+  // set the initial value for the characeristic:
+  switchCharacteristic.writeValue(0);
+  // start advertising
+  BLE.advertise();
+</code>
+Also LED output is initialized in the setup() function.
+<code>
+  // set LED pin to output mode
+  pinMode(ledPin, OUTPUT);
+</code>
+==== Loop function ====
+As in all Arduino programs, after the initialization, the program starts to execute an infinite "loop()" function. First, it calls the "BLE.central()" function that specifies the role of our device as peripheral (server), and checks if there is any central (client) connected.
+<code>
+  BLEDevice central = BLE.central();
+</code>
+<note>BLE.central() function is non-blocking so you can execute other code if the connection is not established.</note>
+To check if there is an active connection the state of "central" variable can be checked. While it is not NULL the program prints the MAC address of the remote device and jumps into the while loop to handle write events requested by the central device. The while loop is executed until the remote device decides to close the connection. If the remote device writes a new value to the characteristic, the "written" property signals this situation. While it is TRUE we can read the value. In the example value "0" turns the LED off, while the other value sets the LED on.\\
+<code>
+// if a central is connected to peripheral:
+  if (central) {
+    Serial.print("Connected to central: ");
+    // print the central's MAC address:
+    Serial.println(central.address());
+    // while the central is still connected to peripheral:
+    while (central.connected()) {
+      // if the remote device wrote to the characteristic,
+      // use the value to control the LED:
+      if (switchCharacteristic.written()) {
+        if (switchCharacteristic.value()) {   // any value other than 0
+          Serial.println("LED on");
+          digitalWrite(ledPin, HIGH);         // will turn the LED on
+        } else {                              // a 0 value
+          Serial.println(F("LED off"));
+          digitalWrite(ledPin, LOW);          // will turn the LED off
+        }
+      }
+    }
+    // when the central disconnects, print it out:
+    Serial.print(F("Disconnected from central: "));
+    Serial.println(central.address());
+  }
+</code>
+<note>F("text") used in the Serial.print() function means that the text will be always taken directly from Flash memory. It frees some of the RAM during the program execution.</note>
+===== Tasks to do during the laboratory =====
+  - Import the Arduino blink example.
+  - Add STM32duinoBLE library to the project.
+  - Replace the original blink code with the LED example, compile and execute.
+  - Add characteristics to existing service for controlling other LEDs on the Nucleo board.
+  - Add service and the characteristic to display texts (using serial port).
+Reading text value can be done with memcpy() function.
+<code>
+char buffer[10];
+memcpy(buffer, textcharacteristic.value(), textcharacteristic.valueLength());
+</code>
+<note>Nucleo board has three LEDs: red, green, and blue named LED_RED, LED_GREEN, and LED_BLUE. The blue LED is also named LED_BUILTIN or LED1, the green LED is also named LED2, and the red LED is also named LED3.</note>