1. Technical Description
This page describes the functioning of the BLE Mesh Vendor Model Project and how to handle it.
A quick description of the BLE Mesh Vendor Model is available in the following Application Note:
Further information about the Vendor Model are available in chapter 3 of this page.
This project demonstrates STM32WB application capabilities using BLE-Mesh solution and with a sensor module and using specific Vendor commands. The goal of the application is to indicate the temperature measured by the discovery kits using the STM32WB55 and a LED bar connected on it.
To realize this project, we use two Discovery Kits including temperature and time of flight sensors, and two STM32WB55 boards. In addition, we have the possibility to add USB dongles as relay nodes.
The temperature is sent periodically on the Mesh network by the discovery kits. The LED bar changes color regarding the temperature, from blue for cold temperature to red for high temperature.
Each Nucleo boards have a RGB LED bar connected to it, which reflect the temperature measured in their respective rooms, and implement a Vendor Server Model.
The Discovrery Kits include temperature sensors and can be placed far from the user, for example in different rooms, and implement a Vendor Server Model.
The temperature is measured and sent to the STM32WB through BLE-Mesh Vendor Commands to update the LEDs status periodically.
2. Demonstration Setup
2.1. Device Requirement
Required material to setup the demonstration is the following:
- 2 STM32WB55RG : as temperature information boards
- 2 Blinkt! LED: RGB LED bar
- 2 Discovery Kit : As temperature sensing boards
- 1 or more USB Dongles (Optional) : As relay nodes. Can be bought with the in the Nucleo boards in the ST Nucleo Pack
- 1 Smartphone with Android or iOS
Click on Component Hyperlink to see resellers.
2.2. Software
Sensor Model Application can be found on latest STM32CubeWB release [NOTE: this example will be included in next package: v1.13.0]:
| Project BLE Mesh Sensor - STM32WB5MM-DK |
|---|
2.3. Code Modification
Server/Client setup:
Modify the 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
Sensor Client-Server code architecture, from the action on user button to the sensor data display, can be summarized as follow:
Code sections specific to the Sensor Server/Client Demonstration is identified by the tag: SENSOR_EXAMPLE_CODE.
By launching a research on this keyword, you will quickly identify all code related to the example.
3.1. Node Setup
For both Nodes, here Sensor Client and Sensor Server nodes.
In mesh_cfg_usr.h file, setup your node:
- Number of Element, you can define up to 5 elements per nodes:
/* Max elements: 5 */
#define APPLICATION_NUMBER_OF_ELEMENTS 1
- Number of Models per elements, you can define up to 11 models per elements:
/* 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, here Sensor Model Server:
/* 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 (5) means the model is enabled on element 1 and element 3
3.2. Sensor Definition
In order to make the Sensor command to work with your sensors, some modifications must be done in 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, 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, 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 BLE Mesh lib function BLEMesh_ModelSendMessage() to send the data buffer through the BLE 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));
}
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 Handle
- Flash your boards with the different node projects.
Ensure your boards are un-provisioned by pressing RESET (1) and B1 (2) buttons simultaneously, release RESET and keep B1 pressed until the LED1 (3) is blinking:
- Launch the Smartphone application and add the different nodes to the network:
Sensor Server Node:
- Provision and Configure:
- Rename the node:
Sensor Client Node:
- Provision and Configure:
- Select the Client Subscription and Publication Addresses:
- Rename the node:
- Launch the Smartphone application and add the different nodes to the network:
- Pressing user button 1 of the Client board send a SENSOR_GET request to the Sensor Server
- The Sensor Server receive the request and Reply with the required sensor data
- The Client decode the data and displays it on his terminal
