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 ST BLE-Mesh Application Note[1].
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 RGB LED of other Discovery kits.
| Project Overview |
|---|
To realize this project, we use 4 Discovery Kits[2] including temperature, time of flight sensors, and RGB LEDs. 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 in Thermometer mode.
The RGB LEDs of the boards set in Indicator mode change color regarding the temperature, blue for cold temperature, green for medium one and red for high temperature.
| BLE Mesh Vendor Project Description |
|---|
Each Discovery Kits[2] (either Thermometer and Indicator mode) implements a Vendor Server Model.
The Thermometer can be placed far from the user, for example in different rooms, the temperature is measured and sent to the Indicator nodes 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:
- 4 Discovery Kits[2] : 2 as temperature sensing boards and 2 as LED indicator.
- 1 or more USB Dongles (Optional) : As relay nodes. Can be bought in the ST Nucleo Pack[3].
- 1 Smartphone with Android or iOS
Click on component references to see resellers.
2.2. Software Setup
Thermometer Application for Discovery Kit[2] can be found on latest STM32CubeWB MCU Package[4] :
| Project BLE Mesh Thermometer - STM32WB5MM-DK |
|---|
By default, this project is setup to build the Thermometer Node solution, in project settings the THERMOMETER_NODE preprocessor definition is set.
| BLE Mesh Thermometer project setup |
|---|
In order to build the LED Indicator Node solution, user can replace the THERMOMETER_NODE definition by INDICATOR_NODE:
| BLE Mesh Indicator project setup |
|---|
Build the Vendor project using one of these preprocessor definition to define if the node have to be in Thermometer mode or LED Indicator mode.
3. Architecture
3.1. Firmware Architecture
| BLE Mesh Firmware architecture |
|---|
3.2. Vendor Model Code Architecture
| BLE Mesh Vendor Model Architecture |
|---|
4. Vendor Model Code Description
4.1. Setup your nodes and enable the Vendor Model
For both Nodes, here Thermometer and Indicator 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 1
/* Max Vendor Models per element */
#define USER_VENDOR_MODELS_MAX_COUNT 1
- Enable Models required for your demonstration, here Vendor Model Server:
#define ENABLE_VENDOR_MODEL_SERVER (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
4.2. Define your Vendor Command
In order to make the new vendor command to work, some modifications must be done in Middleware, vendor.h file:
- The following lines define the Vendor Command categories:
/*******************Commands Received from Android/IoS*************************/
#define APPLI_TEST_CMD 0x1U
#define APPLI_DEVICE_INFO_CMD 0x2U
#define APPLI_LED_CONTROL_STATUS_CMD 0x3U
#define APPLI_ELEMENT_TYPE_CMD 0x4U
#define APPLI_SENSOR_CNTRL_CMD 0X5U
#define APPLI_DATA_CNTRL_CMD 0xEU
//Add New Vendor Command here
/******************************************************************************/
If your new Vendor command doesn’t feet one of the defined categories, you can add your own category definition at this place.
- Add the new Vendor Sub Command definition in one of the previous categories, for example, for the APPLI_LED_CONTROL_STATUS_CMD category:
/*****************Sub Commands for APPLI_LED_CONTROL_STATUS_CMD***************/
#define APPLI_CMD_ON 0x01U
#define APPLI_CMD_OFF 0x02U
#define APPLI_CMD_TOGGLE 0x03U
#define APPLI_CMD_LED_BULB 0x05U
#define APPLI_CMD_LED_INTENSITY 0X06U
#define APPLI_CMD_LED_THERMOMETER 0X07U
//Add New LED Control Vendor Sub Command here
/******************************************************************************/
4.3. Publish a Vendor Command
In the demonstration case, the Thermometer Node must publish the vendor command to the Indicator Node, below is the code of the function sending the APPLI_LED_CONTROL_STATUS_CMD and APPLI_CMD_LED_THERMOMETER commands:
/**
* @brief Publish Temperature Command for Vendor Model
* @param srcAddress: Source Address of Node
* @param temperature: Temperature Measured
* @retval void
*/
void Appli_Vendor_Publish_Temperature(MOBLE_ADDRESS srcAddress, MOBLEUINT8 temperature)
{
MOBLE_RESULT result = MOBLE_RESULT_SUCCESS;
MOBLEUINT8 AppliBuff[2];
/* changes the LED status on other nodes in the network */
AppliBuff[0] = APPLI_CMD_LED_THERMOMETER;
AppliBuff[1] = temperature;
result = BLEMesh_SetRemotePublication(VENDORMODEL_STMICRO_ID1, srcAddress,
APPLI_LED_CONTROL_STATUS_CMD,
AppliBuff, sizeof(AppliBuff),
MOBLE_FALSE, MOBLE_TRUE);
if(result)
{
TRACE_I(TF_VENDOR_M, "Publication Error \r\n");
}
}
In the demonstration, the previous function is called in the application background task, if the temperature gap between the value recorded and the last value displayed is greater than a minimal value. For further project, you can define your own publication functions, and call them on different events, as button pressing, specific sensor measurements, interruption, etc.
4.4. Receive and manage a Vendor command
4.4.1. The new Vendor Command is included in an existing group
This is the case in the Thermometer demonstration, the APPLI_CMD_LED_THERMOMETER sub command is managed as a LED Control command (APPLI_LED_CONTROL_STATUS_CMD).
In this case, the Temperature Indicator Node must receive and manage the vendor command sent by the Thermometer Node. To perform that, identify the function processing the specific group of commands, here Appli_Vendor_LEDControl function. And, in the switch on the sub command identifiers, add a case corresponding to the new command defined:
MOBLE_RESULT Appli_Vendor_LEDControl( MOBLEUINT8 const *data, MOBLEUINT32 length,
MOBLEUINT8 elementIndex , MOBLE_ADDRESS dst_peer)
{
[…]
switch(subCommand)
{
[…]
/* Thermometer command */
#ifdef APPLI_CMD_LED_THERMOMETER
case APPLI_CMD_LED_THERMOMETER:
{
[ ACTION TO PERFORM ]
break;
}
#endif
[…]
}
}
4.4.2. The new Vendor Command is included in a new group
In this case, you must:
- Add your command into the Vendor_Opcodes_Table[], in vendor.c,
- Define the function processing the new group of commands, in appli_vendor.c/.h,
- Define the callback for this function into the Appli_Vendor_cb_t definition, in vendor.h,
- Associate the function to the corresponding callback into the VendorAppli_cb definition, in models_if.c,
- Call the callback into Vendor_WriteLocalDataCb or Vendor_ReadLocalDataCb, in vendor.c.
5. Demonstration Handle
1. Flash your boards with the different node projects.
Ensure your boards are un-provisioned by pressing RESET 
and SW1 
buttons simultaneously, release RESET and keep SW1 pressed until the LED1 
is blinking:
| Unprovisioning process |
|---|
2. Launch the Smartphone application and provision the different nodes.
LED Indicator Node:
| LED Indicator node provisioning |
|---|
Thermometer Node:
| Thermometer node provisioning |
|---|
3. Rename the different nodes.
| Node renaming |
|---|
4. Set the Publication address for the Thermometer nodes.
| Publication address setup |
|---|
5. Reproduce these steps for all Thermometer / LED Indicator Nodes.
You obtain the following publication address schematic:
| Subscription/Publication addresses summary |
|---|
After having followed the previous steps, the LED Indicator boards should reflect the temperature for their corresponding thermometer boards.
| Demonstration |
|---|
