STM32WB BLE MESH Vendor Model

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.

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.

Project Overview
File:vendor-demo0.png

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.

BLE Mesh Vendor Project Description
File:vendor-demo1.png

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 Discovery 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 Nucleo boards: as temperature information boards
• 2 RGB LED bar
• 2 Discovery Kits : 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 references to see resellers.

2.2. BLINKT LED Connection

Connect the LED bar to CN7 connector (left side of the board). The rounded edges of the LED bar must be placed towards the inside of the board. Let 7 Pins free from the beginning of CN7 connector, the LED are connected from PIN15.

LED bar connection
File:vendor-demo2.png

2.3. Software Patch

Thermometer Application for Discovery Kit can be found on latest STM32CubeWB MCU Package :

Project BLE Mesh Thermometer - STM32WB5MM-DK
File:vendor-demo3.png

The Nucleo LED Indicator project is not included in this package as it required external Drivers.

A patch is available to include the Nucleo LED Indicator project and his dependencies to the Firmware package.

Launch this .exe file and follow the instructions. In the Select Destination Location step, select the path to your Firmware Package.

Patch execution window
File:vendor-demo4.png

Warning

Be careful to remove the \New Folder added automatically at the end of the path you selected.

Path to remove
File:vendor-demo5.png

3. Architecture

3.1. Firmware Architecture

BLE Mesh Firmware architecture
File:vendor-demo6-bis.png

3.2. Vendor Model Code Architecture

BLE Mesh Vendor Model Architecture
File:vendor-demo7.png

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
File:vendor-demo8.png

2. Launch the Smartphone application and provision the different nodes.
LED Indicator Node:

LED Indicator node provisioning
File:vendor-demo9.png

Thermometer Node:

Thermometer node provisioning
File:vendor-demo10.png

3. Rename the different nodes.

Node renaming
File:vendor-demo11.png

4. Set the Publication address for the Thermometer nodes.

Publication address setup
File:vendor-demo12.png

5. Reproduce these steps for all Thermometer / LED Indicator Nodes.
You obtain the following publication address schematic:

Subscription/Publication addresses summary
File:vendor-demo13.png

After having followed the previous steps, the LED Indicator boards should reflect the temperature for their corresponding thermometer boards.

Demonstration
File:vendor-demo14.png