STM32WB Bluetooth® LE Mesh Sensor Model application

1. Technical description

This page describes the functioning and handling of the Bluetooth® LE Mesh Sensor Client/Server project.

A quick description of the Bluetooth® LE Mesh Sensor Model is available in the ST Bluetooth® LE-Mesh Application Note[1].

This project demonstrates STM32WB application capabilities using Bluetooth® LE-Mesh solution with a sensor module and by using specific Sensor Client commands. The objective of the project is to send sensor data from the Sensor Server to the Sensor Client on Sensor Client request.

Project overview
Connectivity sensor-demo0.png

The project is based on the use of two STM32WB5MM-DK Discovery kits[2] including temperature and time of flight sensors.

One board implements a Bluetooth® LE Mesh Sensor Server node, and the second board a Sensor Client node. A short push on the sensor client user button 1 (B1) sends a Get temperature request to the Sensor Server. A long push sends a Get Distance request. The Server answers to the Client and the required data displays on the Client logs.

Bluetooth® LE Mesh sensor project description
Connectivity sensor-demo1.png

2. Demonstration setup

2.1. Device requirement

The required material to set up the demonstration is as follows:

  • two STM32WB5MM-DK Discovery kit[2]: temperature sensing boards
  • one smartphone with ST BLE Mesh application

2.2. Software

The Sensor Model application can be found on the latest STM32CubeWB MCU package[3]:

Project Bluetooth® LE Mesh Sensor - STM32WB5MM-DK
Connectivity sensor-demo1-bis.png

2.3. Code modification

Server/Client setup:
Modify mesh_cfg_usr.h file in order to chose between the Client or Server configuration:

  • Server:
/* Enable Sensor Model Server or Sensor Model Client */
#define ENABLE_SENSOR_MODEL_SERVER                                          (1)

//#define ENABLE_SENSOR_MODEL_CLIENT                                           (1)
  • Client:
/* Enable Sensor Model Server or Sensor Model Client */
//#define ENABLE_SENSOR_MODEL_SERVER                                        (1)

#define ENABLE_SENSOR_MODEL_CLIENT                                           (1)

After each modification, rebuild the project and flash the corresponding board.

3. Sensor Model code description

This defines the Sensor Client/Server code architecture. The action from the user button to the sensor data displayed is illustrated below:

Code architecture
Connectivity sensor-demo12.png

Code sections specific to the Sensor Server/Client demonstration are identified by the tag: MESH_MODEL_SENSOR_APP_CODE.
To identify all related code part to the Sensor Client/Server example launch a research on this keyword:

3.1. Node setup

For both nodes, namely Sensor Client and Sensor Server nodes.
In mesh_cfg_usr.h file, setup your node:

  • Number of element: you can define, up to five elements per node:
/* Max elements: 5 */
#define APPLICATION_NUMBER_OF_ELEMENTS                                         1
  • Number of models per element: you can define up to 11 models per element:
/* Max total Models per element = (SIG + Vendor) = 11 */
/* Max SIG Models per element */
#define USER_SIG_MODELS_MAX_COUNT                                              10
/* Max Vendor Models per element */
#define USER_VENDOR_MODELS_MAX_COUNT                                           1
  • Enable models required for your demonstration, Sensor Model server given below:
/* Enable Sensor Model Server or Sensor Model Client */
#define ENABLE_SENSOR_MODEL_SERVER                                           (1)
//#define ENABLE_SENSOR_MODEL_CLIENT                                           (1)
  • Or Sensor Model Client:
/* Enable Sensor Model Server or Sensor Model Client */
//#define ENABLE_SENSOR_MODEL_SERVER                                           (1)
#define ENABLE_SENSOR_MODEL_CLIENT                                           (1)

This number defines in which element the model is enable and works as a bitmap:

  • Bit 0 corresponds to element 1
  • Bit 1 corresponds to element 2
  • Bit 2 corresponds to element 3

For example #define ENABLE_SENSOR_MODEL_SERVER (5) means the model is enabled on element 1 and element 3 (as 5 = 0b0101).

3.2. Sensor definition

To have the sensor command working with your sensors, some modifications must be done in the sensor_cfg_usr.h file.

  • Define the maximum number of data series your sensors support:
#define SENSOR_MAX_SERIES_COUNT                                                2
  • Define the sum of sensors count on all the elements of your node:
#define TOTAL_SENSORS_COUNT                                                2
  • Define and Initialize your sensors settings:
#define SENSOR2_ELEMENT_IDX                    	 0
#define SENSOR2_PROPERTY_ID                    	TIME_OF_FLIGHT_PID
#define SENSOR2_POSITIVE_TOLERANCE              SENSOR_POSITIVE_TOLERANCE_UNSPECIFIED
#define SENSOR2_NEGATIVE_TOLERANCE            SENSOR_NEGATIVE_TOLERANCE_UNSPECIFIED
[]
#define SENSOR_SERVER_INIT_PARAMS \
{\
  TOTAL_SENSORS_COUNT,\
  {\
    SENSOR1_INIT_PARAMS,\
    SENSOR2_INIT_PARAMS,\
  }\
}

3.3. Sensor initialization (server side)

Add the functions to initialize your different sensors in Appli_Sensor_Init, appli_sensor.c.

In the example below, we initialize the time of flight sensor (VL53L0X) and the temperature sensor (STTS22H):

 /* Sensor Initialization */
  TRACE_M(TF_SENSOR, "VL53L0X init\r\n");
  VL53L0X_PROXIMITY_Init();
  TRACE_M(TF_SENSOR, "STTS22H init\r\n");
  STTS22H_Init_Sensor();


Then, launch the data measurement:

  /* Start measure of the distance */
  VL53L0X_Start_Measure();
  /* Start measure of the temperature */
  STTS22H_Start_Measure();

3.4. SENSOR_GET Request (client side)

On button push, call Appli_SensorsClient_API to send SENSOR_GET command to the publish address (defined by the smartphone application), this is done in appli_mesh.c file.
Appli_SensorsClient_API takes as parameter the element index, here 0, the command opcode and the property ID of the sensor targeted.

  /* PRESENT_AMBIENT_TEMPERATURE_PID */
  pPropertyId[0]= 0x4F;           // Property ID byte 0 : Property ID for the sensor
  pPropertyId[1]= 0x00;           // Property ID byte 1 : Property ID for the sensor

  /* Sensor Client Send SENSOR_GET request with PRESENT_AMBIENT_TEMPERATURE_PID */
  Appli_SensorsClient_API(0, SENSOR_GET, pPropertyId);

3.5. Sensor data reading (server side)

Appli_Sensor_ReadValue (appli_sensor.c) is a callback called by Sensor_Status in response of a Sensor Get request.
This gets the value measured by the sensor identified by the property ID received and copy it into a response buffer.
In the example below, we initialize the time of flight sensor (VL53L0X) and the temperature sensor (STTS22H):

switch(SensorServerInitParams.sensorInitParams[sensorOffset].propertyId)
  {
  case PRESENT_AMBIENT_TEMPERATURE_PID:
    {
      STTS22H_getTemperatureValue(&temp_val);
      pValueParams->data[0] = (MOBLEUINT8)round(temp_val*2);
     []
    }
    break;
case TIME_OF_FLIGHT_PID:
    {
      prox_value = VL53L0X_PROXIMITY_GetDistance();
      []
      pValueParams->data[0] = distance;
    }
    break;
   []

3.6. Sensor data answer (server side)

Once the data collected from sensor, the Sensor_Status() function calls the Bluetooth® LE Mesh lib function BLEMesh_ModelSendMessage() to send the data buffer through the Bluetooth® LE Mesh network, up to the Client node.

3.7. Sensor data reception (client side)

The Client node must decode the data buffer regarding the sensor data marshalling format.
This is done in Appli_Sensor_Status function, in appli_sensor_client.c.
The following code part decode the marshalled sensor data received regarding the sensor model specification, to retrieve the sensor PID and the data length:

 if((pStatus[0] & 0x01) == 0x01){
    sensorStatusFormat=0x01;
    receivedLenght=(MOBLEUINT32)(((pStatus[0] & 0xFE)>>1) + 1);
    receivedPID=(MOBLEUINT16)((pStatus[2] << 8)|(pStatus[1]));
  }

  else{
    sensorStatusFormat=0x00;
    receivedLenght=(MOBLEUINT32)(((pStatus[0] & 0x1E)>>1)+1);
    receivedPID=(MOBLEUINT16)(((pStatus[0] & 0xE0) >> 5)|(pStatus[1] << 3));
  }
Sensor data marshalling formats
Connectivity sensor-demo4.png

Once the sensor PID is retrieved, manage the sensor data depending on the sensor type.

  switch(receivedPID){
  case PRESENT_AMBIENT_TEMPERATURE_PID:
    TRACE_M(TF_SERIAL_CTRL,"Temperature = %d degrees \n\r", (pStatus[2]/2));
    break;

  case TIME_OF_FLIGHT_PID:  
    TRACE_M(TF_SERIAL_CTRL,"Distance = %d cm \n\r", ((pStatus[4]<<8)|(pStatus[3])));
    break;

    /* Add Sensor PID here */
  default:
    break;
  }

4. Demonstration handling

4.1. Flash the boards

Flash your boards with the different node projects.
Ensure your boards are un-provisioned by pressing RESET puce1violette.png and SW1 puce2violette.png buttons simultaneously, release RESET and keep SW1 pressed until the LED1 puce3violette.png blinks:

Unprovisioning process
Connectivity sensor-demo5.png


4.2. Network setup

Launch the smartphone application and add the different nodes to the network:
Sensor Server node:
- Provision and configure:

Sensor Server node provisioning
Connectivity sensor-demo6.png


- Rename the node:

Node renaming
Connectivity sensor-demo7.png


Sensor Client node:
- Provision and configure:

Sensor Client node provisioning
Connectivity sensor-demo8.png


- Select the Client subscription and publication addresses:

Subscription/Publication addresses setup
Connectivity sensor-demo9.png


- Rename the node:

Node renaming
Connectivity sensor-demo10.png


4.3. HyperTerminal setup

Open one HyperTerminal connected to each board.
You can find more information about the HyperTerminal settings and how to connect it to STM32WB platforms on the ST Bluetooth® LE Mesh Lighting example page.

4.4. Send sensor request and read measurements

puce1violette.png
Pressing user button 1 of the Client board sends a SENSOR_GET request to the Sensor Server
puce2violette.png
The Sensor Server receives the request and replies with the required sensor data
puce3violette.png
The Client decodes the data and displays it on his terminal


Demonstration summary
Connectivity sensor-demo11.png

5. References