STM_IoT_6: 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.

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 IoT7: BLE Beacon exercise is recommended.

• C/C++ Language Embedded Programming Fundamentals
• STM32
• SUT STM32 Laboratory Node Hardware Reference

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 simplest implementation to be extended in further scenarios.

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.

You can use the beacon and simple client programs from IoT7: BLE Beacon as the starting point.

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.

Let's begin with a simple program which advertises a single service. The code should start with including Arduino and BLE libraries.

#include <Arduino.h>
#include <STM32duinoBLE.h>

We need variables for the BLE device class object and data transport class object.

HCISharedMemTransportClass HCISharedMemTransport;
BLELocalDevice BLEObj(&HCISharedMemTransport);
BLELocalDevice& BLE = BLEObj;

Any service or characteristic is identified with a unique UUID. If you use the standard service, like eg. Health Thermometer or Binary Sensor Service you can use a 16-bit UUID defined by Bluetooth SIG in the document ^[2]. The same document defines the UUIDs for characteristics.

While none of the standard UUIDs fits your device you need to define your own UUID. It must be 128-bit long and can be randomly generated with the tool available on the website https://www.uuidgenerator.net/^[3]. The service UUID and characteristic UUID must differ. Although they can be completely different in many implementations the UUIDs of characteristics grouped under one service differ on one digit.

#define SERVICE_UUID        "6e9b7b26-ca96-4774-b056-8ec5b759fd86"
#define CHARACTERISTIC_UUID "6e9b7b27-ca96-4774-b056-8ec5b759fd86"

We create the service and characteristic objects with defined UUIDs

// BLE Service - custam 128-bit UUID
BLEService pService(SERVICE_UUID); 
 
// BLE Characteristic - custom 128-bit UUID, read and writable by central
BLECharacteristic pCharacteristic(CHARACTERISTIC_UUID, BLERead | BLEWrite, 16);

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 “SUT STM” text. All is done in the setup() function. The function creates and initialises the BLE device instance named “SUT STM BLE”. It creates a service with the characteristic, sets the characteristic's initial value and finally starts advertising.

void setup() {
 
  // begin initialization
  BLE.begin();
 
  // set advertised local name and service UUID:
  BLE.setLocalName("SUT STM BLE");
  BLE.setAdvertisedService(pService);
 
  // add the characteristic to the service
  pService.addCharacteristic(pCharacteristic);
 
  // add service
  BLE.addService(pService);
 
  // set the initial value for the characeristic:
  pCharacteristic.writeValue("SUT STM");
 
  // start advertising
  BLE.advertise();
}

In the loop function, we need to call a function waiting for the connection of the client (central device).

void loop() {
  // listen for BLE central device to connect:
  BLE.central();
}

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.

While we have analysed the client's behaviour we can start implementation. Let's begin with the libraries needed. Add the libraries to the platformio.ini.

lib_deps = 
  stm32duino/STM32duinoBLE @ 1.2.6
  arduino-libraries/LiquidCrystal@^1.0.7

And import libraries into the cpp file.

#include "Arduino.h"
#include "STM32duinoBLE.h"
#include "LiquidCrystal.h"

Next, we define the UUIDs for remote service and a characteristic. Notice they must match the ones defined in the server.

// The remote service we wish to connect to.
#define REMOTE_SERVICE_UUID "6e9b7b26-ca96-4774-b056-8ec5b759fd86"
// The characteristic of the remote service we are interested in.
#define REMOTE_CHARACTERISTIC_UUID "6e9b7b27-ca96-4774-b056-8ec5b759fd86"

Some global class objects and variables will be needed for our software.

// Variables
HCISharedMemTransportClass HCISharedMemTransport;
BLELocalDevice BLEObj(&HCISharedMemTransport);
BLELocalDevice& BLE = BLEObj;
BLECharacteristic remoteCharacteristic;

We need to add and configure the LCD to be able to observe the results.

// LCD class (Constructor uses STM port numbering)
const int rs = PC5, en = PB11, d4 = PB12, d5 = PB13, d6 = PB14, d7 = PB15;
LiquidCrystal lcd(rs, en, d4, d5, d6, d7);

In the setup() function we initialise LCD and Bluetooth and start scanning for the device having the service UUID we want to connect.

void setup() {
  // initialise LCD
  lcd.begin(16, 2);
  lcd.clear();
 
  // initialise the BLE hardware
  BLE.begin();
 
  // start scanning for peripherals
  int ret = 1;
  do
  {
    ret = BLE.scanForUuid(REMOTE_SERVICE_UUID);
    if (ret == 0)
    {
      BLE.end();
      BLE.begin();
    }
  } while(ret == 0);
}

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. While the function returns, we restart scanning.

void loop() {
  // check if a peripheral has been discovered
  BLEDevice peripheral = BLE.available();
 
  if (peripheral) {
    if (peripheral.localName() == "SUT STM BLE") {
 
      // display remote name  
      lcd.setCursor(0,0);
      lcd.print(peripheral.localName());
 
      // stop scanning
      int ret = 1;
      do
      {
        ret = BLE.stopScan();
        if (ret == 0)
        {
          BLE.end();
          BLE.begin();
        }
      } while(ret == 0);
 
      // display the characteristic value
      display_characteristic(peripheral);
    }
 
    // peripheral disconnected, start scanning again
    int ret = 1;
    do
    {
      ret = BLE.scanForUuid(REMOTE_SERVICE_UUID);
      if (ret == 0)
      {
        BLE.end();
        BLE.begin();
      }
    } while(ret == 0);
  }
}

The function reads the characteristic value in some steps:

1. Connects to the remote device.
2. Discovers attributes of the remote service.
3. Retrieves the characteristic with specified UUID.
4. Checks if the remote device is properly connected.
5. Checks if the remote characteristic can be read.
6. Reads the text and displays it on LCD.
7. Disconnects from the remote server.

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_CHARACTERISTIC_UUID);
      if (remoteCharacteristic) {
 
      // if the peripheral is connected display the value
        if (peripheral.connected()) {
 
          // check if the characteristic can be read
          if (remoteCharacteristic.canRead()){
            char char_text[16];
            remoteCharacteristic.readValue(char_text,16);
            int i=remoteCharacteristic.valueLength();
            lcd.setCursor(0,1);
            lcd.write(char_text,i);
          } // if (remoteCharacteristic.canRead())
        } // if (peripheral.connected())
      } // if (remoteCharacteristic)
      peripheral.disconnect();
    } // if (peripheral.discoverAttributes())
  } // if (peripheral.connect())
}

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.

What types of data can be sent with the characteristics?: The BLE characteristics can send any value as a single byte or a sequence of bytes. BLE does not interpret the data in characteristic in any way. Interpretation lies on the side of the application.
What if I need to read or write more data than a single text?: It is possible to implement many services in one device and add many characteristics to one service. Theoretically, the maximum number of characteristics in one service is 512, but the implementation and the memory available for the BLE library limit it.
What is the maximum length of the data in the characteristics?: The maximum length of the data in the characteristics in the BLE specification is 512 bytes.
Can I send data between SoCs coming from different vendors?: That's what the specifications of the network protocols are defined for. If devices are in their transmission range (i.e. in one physical laboratory site) you can implement a BLE server on one type of SoC and a BLE client on another.

Project information

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 Creative Commons Licence, free for Non-Commercial use.