STMicroelectronics STSW-BNRG-Mesh User Manual
Oglas
Oglas
UM2295
User manual
Getting started with the ST BlueNRG-Mesh embedded firmware
Introduction
BlueNRG-Mesh connects multiple BLE (Bluetooth Low Energy) devices in Mesh networking for IoT (Internet of Things) solutions. It integrates BlueNRG products with embedded Bluetooth Low Energy communication in a powerful, range-extending
Mesh network with true full-duplex communication.
The solution contains the core functionality for secure communication and provides the flexibility you need to build applications.
It uses BlueNRG-2 , BlueNRG-1 , BlueNRG-MS devices with Mesh stack APIs and related event callbacks. The SDK provides the Mesh stack in library form and a sample application in source code to demonstrate how to use the library.
BlueNRG-Mesh can be used in several applications requiring infrequent data transfer in a mesh network over Bluetooth Low
Energy, to create distributed control systems such as:
• smart lighting
• home and building automation
• industrial automation
A demo example is available for the device evaluation boards. You can use it to change the application interface and use the library for the required hardware and software functionalities. The demo application is available for the following evaluation boards:
• STEVAL-IDB008V1 and STEVAL-IDB008V2 for BlueNRG-2
• STEVAL-IDB007V1 and STEVAL-IDB007V2 for BlueNRG-1
• X-NUCLEO-IDB05A1 and NUCLEO-L152RE for BlueNRG-MS
The sample application implements Smart Light control scenario, which you may modify according to your requirements.
UM2295 - Rev 2 - September 2018
For further information contact your local STMicroelectronics sales office.
www.st.com
1
1.1
1.2
1.3
UM2295
Getting started
Getting started
The sample application implements a smart lighting control scenario. To modify the application, you need to follow the sequence below.
Step 1.
Connect the board to the PC
Step 2.
Compile the firmware in IDE
Step 3.
Flash the firmware to the board
Step 4.
Provision the board in the BlueNRG-Mesh App
Step 5.
Toggle LED on board using the app
Hardware requirements
The following boards can be used for evaluation of the ST BlueNRG-Mesh solution.
Devices
BlueNRG-2
BlueNRG-1
BlueNRG-MS
Table 1. Hardware requirements
Evaluation boards
STEVAL-IDB008V1 and STEVAL-
IDB008V2
STEVAL-IDB007V1 and STEVAL-
IDB007V2
Description
Evaluation platform based on the BlueNRG-2
Evaluation platform based on the BlueNRG-1
X-NUCLEO-IDB05A1
NUCLEO-L152RE
Bluetooth Low Energy expansion board based on the SPBTLE-RF module for STM32 Nucleo
STM32 Nucleo-64 development board with the STM32L152RE MCU, supports Arduino™ and ST morpho connectivity
Board interfaces
The following table explains the details of the evaluation boards for the power requirement, programming and user interface, for example LEDs and buttons.
Table 2. Evaluation board details
Devices
Evaluation boards
BlueNRG-2
BlueNRG-1
STEVAL-
IDB008V1 and
STEVAL-
IDB008V2
STEVAL-
IDB007V1 and
STEVAL-
IDB007V2
BlueNRG-MS
X-NUCLEO-
IDB05A1
NUCLEO-L152RE
Powered by
Micro-B
USB Cable
Or AAA x 2 battery
Micro-B USB cable or AAA x 2 battery
Mini-USB cable
Programmed by
External ST-LINK/V2 or
USB port
External ST-LINK/V2 or
USB port
In-Built STLINK on the
STM32 Nucleo board
LEDs
3x user LEDs +1 power indication
3x user LEDs +1 power indication
1 user LED +1 power indication
Buttons
Reset button + 2 x user buttons
Reset button +2 x user buttons
Reset button + 1 x user buttons
STEVAL-IDB008V1 or STEVAL-IDB008V2 BlueNRG2 board setup
To connect the STEVAL-IDB008V1 or STEVAL-IDB008V2 ( BlueNRG-2 evaluation board) and PC, a USB port is required to provide power supply to the board. To connect the ST-Link/V2 debugger, an additional USB port is needed.
UM2295 - Rev 2 page 2/37
UM2295
STEVAL-IDB007V1 or STEVAL-IDB007V2 BlueNRG1 board setup
Note: The BlueNRG-2 device on these boards is clocked at 32 MHz XTAL. These settings are performed in project configurations.
Figure 1. Connection between the STEVAL-IDB008V1 or STEVAL-IDB008V2 and PC
1.4
Note:
RELATED LINKS
4.1 BlueNRG cold start configuration on page 12
STEVAL-IDB007V1 or STEVAL-IDB007V2 BlueNRG1 board setup
To connect the STEVAL-IDB007V1 or STEVAL-IDB007V2 ( BlueNRG-1 evaluation board) and PC, one USB port is required to provide power supply to the board. To connect the ST-Link/V2 debugger, an additional USB port is needed.
Please note that the BlueNRG-1 on this evaluation board is clocked by 16 MHz XTAL. These settings are performed in project configurations.
UM2295 - Rev 2 page 3/37
UM2295
NUCLEO-L152RE plus X-NUCLEO-IDB05A1 board setup
Figure 2. Connection between the STEVAL-IDB007V1 and PC
1.5
Note:
RELATED LINKS
4.1 BlueNRG cold start configuration on page 12
NUCLEO-L152RE plus X-NUCLEO-IDB05A1 board setup
Connect the STM32 NUCLEO-L152RE + X-NUCLEO-IDB05A1 ( BlueNRG-MS board) thanks to a USB cable. The
USB cable is used for two purposes:
1.
Providing power supply to the NUCLEO-L152RE + X-NUCLEO-IDB05A1 board
2.
Helping in serial communication of data between the PC and the boards NUCLEO-L152RE + X-NUCLEO-
IDB05A1
The STM32 NUCLEO-L152RE board integrates the ST-LINK/V2-1 debugger/ programmer. You can download the relevant version of the STSW-LINK009 ST-LINK/V2-1 USB driver (according to your version of Windows).
Ensure that BlueNRG-MS is updated with BLE stack version 7.2 c or higher. You can use BlueNRG GUI to manage the update.
UM2295 - Rev 2 page 4/37
UM2295
System requirements
Figure 3. STM32 NUCLEO-L152RE plus X-NUCLEO-IDB05A1 connection with PC
1.6
System requirements
The minimum requirements to set up the software environment and run the BlueNRG-Mesh smart lighting application are:
• PC with Intel or AMD processor running one of the following Microsoft operating systems: Windows XP or
Vista/Windows 7/Windows 10
– At least 128 MB of RAM
– 2 x USB ports
– 40 MB of hard disk space
UM2295 - Rev 2 page 5/37
1.7
UM2295
Installing STSW-BNRG-Mesh
• Development toolchains and compilers:
– Keil µVision v5.23
– IAR Embedded Workbench v7.80.4
Please read the system requirements and setup information provided by the IDE provider.
Installing STSW-BNRG-Mesh
1.
Extract the contents of the package in a temporary directory
2.
Launch the installer and follow the on-screen instructions
3.
Install in suitable folder in your disk-drive
UM2295 - Rev 2 page 6/37
2
UM2295
Firmware structure
Firmware structure
Applications
Figure 4. Firmware architecture
LED light demo Custom applications
Middleware
BlueNRG-Mesh library
BlueNRG-Core stack
Cryptographic library
Drivers
Hardware Abstraction
Layer API
Board Support
Packages
H a r d w a r e
BlueNRG-1 BlueNRG-2
STEVAL-IDB007V1/V2 STEVAL-IDB008V1/V2
BlueNRG-MS
X-NUCLEO-IDB05A1
NUCLEO-L152RE
The following folders are included in the package firmware folder:
• A Documentation folder with a compiled HTML file generated from the source code and detailed documentation of the software components and APIs.
•
•
•
A Drivers folder with HAL drivers and specific drivers for supported boards, hardware platforms, and components, and the CMSIS vendor-independent hardware abstraction layer for the Cortex-M processor series.
A Middleware folder with libraries for Mesh and BLE communication.
Horizontal interaction between layer components is handled directly by calling the feature APIs, while vertical interaction with the low level drivers is managed through specific callbacks and static macros implemented in the library system call interface.
A Projects folder contains the workspaces for IAR Embedded Workbench and Keil µVision integrated development environments for the STEVAL-IDB008V1 / STEVAL-IDB008V2 , STEVAL-IDB007V1 / STEVAL-
IDB007V2 board and NUCLEO-L152RE plus X-NUCLEO-IDB05A1 board.
The EWARM folder contains the workspace for IAR Embedded Workbench and MDK-ARM folder contains the workspace for Keil µVision.
The source files in the folder bind the firmware layers to implement the functions that demonstrate Mesh over BLE functionality.
UM2295 - Rev 2 page 7/37
Figure 5. Folders, sub-folders and contents of the package
UM2295
Root folder
2.1
Root folder
The figure below shows the root folder structure of the firmware package.
Figure 6. Root folder structure
2.2
Driver folder
This folder contains all low level drivers including peripheral drivers and HAL drivers corresponding to the hardware.
Figure 7. Driver folder
2.3
Project folder
This folder contains the projects for IAR and Keil.
UM2295 - Rev 2 page 8/37
Figure 8. Project folder
UM2295
Middleware folder
2.4
Middleware folder
This folder contains the middleware for the project including pre-compiled Mesh library for the BlueNRG-2 ,
BlueNRG-1 and BlueNRG-MS + STM32L1.
Figure 9. Middleware folder
UM2295 - Rev 2 page 9/37
3
3.1
UM2295
Using the BlueNRG-Mesh demo
Using the BlueNRG-Mesh demo
IAR Embedded Workbench and Keil µVision are used to debug and burn the firmware into the flash memory of the STEVAL-IDB008V1 / STEVAL-IDB008V2 , STEVAL-IDB007V1 / STEVAL-IDB007V2 and NUCLEO-L152RE plus
X-NUCLEO-IDB05A1 boards.
Using binaries for BlueNRG-1 and BlueNRG-2
1.
The pre-compiled binaries are available in Project\<Platform>\Application\<Demo>\Binary folder.
For example for BlueNRG-1 , the path is “Projects\BlueNRG-1\Applications\Lighting_Demo\Binary”
2.
These can be programmed in the device using different utilities available for the devices, such as the
BlueNRG-1 Flasher tool or ST-LINK Utility
3.
Use "BlueNRG-1 Flasher" tool to program the ( STEVAL-IDB007V1 / STEVAL-IDB007V2 or STEVAL-
IDB008V1 / STEVAL-IDB008V2 ) boards connected via micro-USB cable
4.
Use "STSW-BNRG1STLINK: BlueNRG-1 ST-LINK utility for BlueNRG-1, BlueNRG-2 MCU” utility to program boards via ST-LINK
Figure 10. Binaries for BlueNRG-1 and BlueNRG-2
3.2
Using binaries for the STM32L152 used with the BlueNRG-MS
1.
The pre-compiled binaries are available in Project\<Platform>\Application\<Demo>\Binary folder
– For example, for BlueNRG-MS , the path is “Projects\BlueNRG-MS\Applications\Lighting_Demo\Binary
\STM32L152RE-Nucleo”
2.
These can be programmed in the device using different utilities
3.
Use “ST-LINK Utility” tool to program the boards ( NUCLEO-L152RE ) connected via mini-USB cable
4.
Or, simply drag and drop the .bin file in the drive created by ST-LINK on the STM32 Nucleo board. The binary will be programmed in the STM32L152 device on the Nucleo board
UM2295 - Rev 2 page 10/37
UM2295
Using the IAR and Keil projects
Figure 11. Overview of how to program the binary in the STM32L152RE MCU
3.3
Using the IAR and Keil projects
Figure 12. Overview
3.3.1
3.3.2
Using IAR project
1.
Choose file→open→workspace. Select the project.eww file from the appropriate location. For example, for the BlueNRG-1 , the location is as follows:
– Embedded\Projects\BlueNRG-1\Applications\Lighting_Demo\EWARM\STEVAL-IDB007V1.
2.
A project opens in the workspace. This project contains the information regarding your project files and folders (driver files, application files, middleware, output files, etc.).
3.
Build the program with Project→Make Option.
4.
Press (download and debug) button to debug the code and flash it to the board.
5.
Press go button to run the program.
Similarly, to use the BlueNRG-MS with boards X-NUCLEO-IDB05A1 and NUCLEO-L152RE , select the project.eww from: Embedded\Projects\ BlueNRG-MS\Applications\Lighting_Demo\EWARM\STM32L152RE-
Nucleo.
Using Keil project
1.
Click on File→Open. Select the project.uvprojx file from: Embedded\Projects\BlueNRG-1\Applications
\Lighting_Demo\MDK-ARM\STEVAL-IDB007V1.
2.
To build the program, select Project→Build Target or simply click on the Build Target icon.
To debug the program, select Debug→Start/Stop Debug Session or click on the Start/Stop Debug Session icon.
To flash the program to the flash memory on the board click on the icon.
UM2295 - Rev 2 page 11/37
4
4.1
4.2
UM2295
Firmware initialization and configuration
Firmware initialization and configuration
•
•
•
•
•
This section describes the available function APIs for application development based on Mesh network over
Bluetooth Low Energy devices.
The Mesh over BLE library manages the following features:
Creates the Mesh network between nodes
Handles the unicast, broadcast addressing
Manages the relay feature: all the packets whose destination address is for another node are re-transmitted
Communication with devices for advanced features, such as provisioning and proxy service
Handles the platform specific communication
The user application handles the following
•
•
•
Initialization of the Mesh stack
User callbacks required for the application
Application handling
The following sections describe the requirements for initialization and configuration of the firmware.
BlueNRG cold start configuration
•
•
Concerning the BlueNRG-1 and BlueNRG-2 devices, certain parameters must be defined on BLE device controller registers during the device initialization phase, after the device powers on:
High speed crystal configuration: 32 or 16 MHz
Low speed crystal source: external 32 kHz oscillator or internal RO
• SMPS: on or off (if on: 4.7 μH or 10 μH SMPS inductor)
•
•
The BlueNRG-1 , BlueNRG-2 controllers are configured in the project C/C++ Preprocessor settings.
For example: for IAR, go to Project → Options → C/C++ Compiler → Preprocessor → Defined Symbols
For Keil, go to Project → Options → C/C++ → Preprocessor Symbols → Define
•
•
The following symbols are used in the project: USER_DEFINED_PLATFORM=STEVAL_IDB007V1:
• HS_SPEED_XTAL=HS_SPEED_XTAL_16MHZ
LS_SOURCE=LS_SOURCE_EXTERNAL_32KHZ
SMPS_INDUCTOR=SMPS_INDUCTOR_10 uH.
These can be changed to suit your hardware design.
RELATED LINKS
1.3 STEVAL-IDB008V1 or STEVAL-IDB008V2 BlueNRG2 board setup on page 2
1.4 STEVAL-IDB007V1 or STEVAL-IDB007V2 BlueNRG1 board setup on page 3
Setting the transmit power of a node
You can define the transmit power of a node by initializing a callback to the Mesh library. It runs in the following manner:
{
Appli_BleStackInitCb,
Appli_BleSetTxPowerCb,
Appli_BleGattConnectionCompleteCb,
Appli_BleGattDisconnectionCompleteCb,
Appli_BleUnprovisionedIdentifyCb,
Appli_BleSetUUIDCb,
Appli_BleSetNumberOfElementsCb
UM2295 - Rev 2 page 12/37
UM2295
UART interface on the firmware
4.3
};
The Appli_BleSetTxPowerCb() calls the aci function to set the power aci_hal_set_tx_power_level(uint8_t En_High_Power, uint8_t PA_Level);
By default, +4 dbm is configured in the nodes for BlueNRG-1 and BlueNRG-2; this can be changed by the user.
For BlueNRG-1 and BlueNRG-2 , the following different settings are available in the firmware:
/* MACROS for Power Level definitions */
#define POWER_LEVEL_LOW 0
#define TX_POWER_LEVEL_MINUS_18DBM 0 // = -18 dBm,
#define TX_POWER_LEVEL_MINUS_15DBM 1 // = -15 dBm,
#define TX_POWER_LEVEL_MINUS_12DBM 2 // = -12 dBm,
#define TX_POWER_LEVEL_MINUS_9DBM 3 // = -9 dBm,
#define TX_POWER_LEVEL_MINUS_6DBM 4 // = -6 dBm,
#define TX_POWER_LEVEL_MINUS_2DBM 5 // = -2 dBm,
#define TX_POWER_LEVEL_0DBM 6 // = 0 dBm,
#define TX_POWER_LEVEL_PLUS_5DBM 7 // = 5 dBm.
#define POWER_LEVEL_HIGH 1
#define TX_POWER_LEVEL_MINUS_14DBM 0 // = -14 dBm,
#define TX_POWER_LEVEL_MINUS_11DBM 1 // = -11 dBm,
#define TX_POWER_LEVEL_MINUS_8DBM 2 // = -8 dBm,
#define TX_POWER_LEVEL_MINUS_5DBM 3 // = -5 dBm,
#define TX_POWER_LEVEL_PLUS_2DBM 5 // = 2 dBm,
#define TX_POWER_LEVEL_PLUS_4DBM 6 // = 4 dBm,
#define TX_POWER_LEVEL_PLUS_8DBM 7 // = 8 dBm
UART interface on the firmware
•
•
•
•
The boards can be connected to a PC via USB connection. Any terminal software (HyperTerminal, Hercules,
Putty, etc.) can be used to open the serial communication port on the PC to check the messages from the board.
The UART of the controller on the board is connected to the PC via a VCOM (virtual communication) port. The settings to open the communication port are:
• Baud: 115200 data size: 8 parity: none stop bits: 1 no hardware control
From the firmware main.c file, you can see certain messages are printed to the VCOM by the following code:
#if !defined(DISABLE_TRACES)
/* Prints the MAC Address of the board */
printf("BlueNRG-Mesh Lighting Demo v%s\n\r", BLUENRG_MESH_APPLICATION_VERSION);
printf("BlueNRG-Mesh Library v%s\n\r", BluenrgMesh_GetLibraryVersion());
printf("BD_MAC Address = [%02x]:[%02x]:[%02x]:[%02x]:[%02x]:[%02x] \n\r",
bdaddr[5],bdaddr[4],bdaddr[3],bdaddr[2],bdaddr[1],bdaddr[0] );
#endif
After the board is connected and the terminal window is opened, press the reset button. If the firmware starts successfully, the following messages are printed to the virtual com window
Figure 13. VCOM window
UM2295 - Rev 2 page 13/37
UM2295
MAC address management
In some evaluation boards, an error can be received. In this case, MAC address management section of the document helps to meet this issue. Examples of bad MAC address are provided below
Figure 14. Bad MAC address
4.4
4.5
MAC address management
MAC address is required to be unique in each node for the Mesh network. The following options are available to configure the MAC addresses of the node
Number
1
MAC address management
Using external MAC address
2
Using unique serial number of the device
3
Using static random
MAC address
Button usage
Table 3. MAC address management
Comments
User can program the nodes with desired unique MAC address. This is stored at specific location in the flash. It is user’s responsibility to make sure that the MAC address programmed in the device is compliant to the requirements of the Bluetooth communication.
To configure this, define the following macro in the project pre-processor.
EXTERNAL_MAC_ADDR_MGMT
It is possible to configure the MAC address of the device using the unique serial number available in each device.
This is the default setting.
It is possible to configure the MAC address of device using the static random MAC address
Features
BlueNRG-1 and BlueNRG-2 (STEVAL-IDB007V1 and STEVAL-IDB008V1)
Buttons LEDs
DL3 Blinks continuously
BlueNRG-MS (X-NUCLEO-IDB05A1 + NUCLEO-
L152RE)
Buttons LEDs
LD2 Blinks continuously Mesh Lib error
Mesh Lib library successful start
Provisioning
Un-
Provisioning
2 Blinks on DL3 NO Blinks
1.
RESET + PUSH1 button pressed
2.
Release RESET button
3.
Long press of
PUSH1 button causes unprovisioning
4.
Reset the board
DL3 Blinks for few times DL3 Blinks for few times
1.
DL3 blinks and then keeps glowing during unprovisioning
1.
RESET + USER button pressed
2.
Release RESET button
3.
Long press USER button causes unprovisioning
4.
Reset the board
LD2 Blinks and then keeps glowing during unprovisioning
UM2295 - Rev 2 page 14/37
4.6
4.7
UM2295
Initialization of application callbacks
Features
Running the demo from board
BlueNRG-1 and BlueNRG-2 (STEVAL-IDB007V1 and STEVAL-IDB008V1)
Buttons LEDs
1.
Press PUSH1 button on any board
2.
It will send the command on
Publication Address
1.
DL3 on the board toggles (If
Subscribed for the
Published Address)
2.
DL3 on other boards
(if subscribed for the
Published address) will also toggle
1.
BlueNRG-MS (X-NUCLEO-IDB05A1 + NUCLEO-
L152RE)
Buttons
Press USER button on any board
2.
It will send the command on
Publication
Address
LEDs
1.
LD2 on the board toggles (If
Subscribed for the
Published Address)
2.
LD2 on other boards (if subscribed for the
Published address) will also toggle
OTA
1.
Long Press PUSH2
2.
RESET the Board
1. ONLY on BlueNRG-2
Initialization of application callbacks
The configuration of the application starts by initializing the callbacks required for the different events and functionalities. These callbacks are used in the BlueNRG-Mesh library to call the functions based on specific events or the library state machine.
{
Vendor_WriteLocalDataCb,
Vendor_ReadLocalDataCb,
Vendor_OnResponseDataCb
};
/* Callbacks used by BlueNRG-Mesh library */
BluenrgMesh_SetVendorCbMap(&vendor_cb);
The structure MOBLE_VENDOR_CB_MAP is used to initialize the vendor model for the application implementation. The function BluenrgMesh_SetVendorCbMap(&vendor_cb); is used to initialize the vendor callbacks in the library.
Initialization and main application loop
This procedure develops an application for Mesh over BLE on the BlueNRG platforms.
The following steps are for the BlueNRG-2 and BlueNRG-1 platforms. The procedure is similar for the BlueNRG-
MS platform, but with a few minor differences.
Step 1.
Call the InitDevice() API.
This in turn calls the SystemInit() API to initialize the BlueNRG-1 device vector table, interrupt priorities and clock. The initialization is run similarly for the BlueNRG-MS platform. Even PWM is intialized for BlueNRG-1, BlueNRG-2.
Step 2.
Call the Appli_CheckBdMacAddr() API to check the validity of the MAC address.
If the MAC address is not valid, then the firmware is stuck in while(1) loop with LED blinking continuously.
Step 3.
Initialize the hardware callback functions for the BLE hardware.
You do this by updating MOBLE_USER_BLE_CB_MAP user_ble_cb =
{
Appli_BleStackInitCb,
Appli_BleSetTxPowerCb,
Appli_BleGattConnectionCompleteCb,
Appli_BleGattDisconnectionCompleteCb,
Appli_BleUnprovisionedIdentifyCb,
Appli_BleSetUUIDCb,
UM2295 - Rev 2 page 15/37
UM2295 - Rev 2
UM2295
Initialization and main application loop
Appli_BleSetNumberOfElementsCb
};
Step 4.
These APIs are useful to have an application interface for BLE radio initialization and TxPower configuration.
– Initialize GATT connection and disconnection callbacks for the application interface.
– BluenrgMesh_BleHardwareInitCallBack(&user_ble_cb) can be called to complete the initialization of hardware callbacks.
Step 5.
Initialize the BlueNRG-Mesh library by calling
BluenrgMesh_Init(&BLEMeshlib_Init_params) ) .
You do this by updating the structure containing Mesh library Initialisation info data .
const Mesh_Initialization_t BLEMeshlib_Init_params = { bdaddr,
&FnParams,
&LpnParams,
MESH_FEATURES,
&DynBufferParam
};
In the event of an error, the demo firmware prints a message on the terminal window opened for the
VCOM port created by the USB connection available on the boards, and the Appli_LedBlink()
API causes the LED to blink continuously.
Step 6.
Check whether the device has been provisioned or not. A provisioned device has network keys and other parameters configured in the internal flash memory.
Checks can be performed with BluenrgMesh_IsUnprovisioned() API.
If the Node is unprovisioned, BluenrgMesh_InitUnprovisionedNode() API initializes it.
If the device is already provisioned , then BluenrgMesh_InitprovisionedNode() API helps to initialize the device.
Step 7.
Print the messages to the terminal window for the nodes that are being initialised.
The message also prints the MAC address assigned to the node.
Step 8.
Check the button state. To initialize the node to the unprovisioned state, hold down the user button.
When the unprovisioning button sequence is detected, the BluenrgMesh_Unprovision() API erases all the network parameters configured in the internal memory of the device.
Once unprovisioning is complete, you need to reset the board.
Step 9.
Initialize all the 3 models (vendor, generic and lighting model) triggered by the events.
BluenrgMesh_ModelsInit();
Step 10.
Process MoBLE and HCI events in while(1) loop.
The application must call BluenrgMesh_Process(); ,BluenrgMesh_ModelsProcess(); ,
Appli_Process(); in while(1) loop as frequently as possible.
This function calls MobleStackProcess(); internally to process BLE communication.
Any application implementation shall be performed in the state-machine by non-blocking functions with frequent calls to BluenrgMesh_Process() .
Step 11.
Check for user-inputs or buttons regularly for any action to take.
page 16/37
UM2295
Mesh networking information
5 Mesh networking information
5.1
5.2
5.3
Local and remote concept
Remote actions or operations refer to other nodes in the network, while local actions refer to the resources on the same node in the network.
For example, if you want to control the LEDs of nodes on the BlueNRG-Mesh app, click the icon button to invoke the _SetRemoteData action from the app. This causes a Vendor_WriteLocalDataCb action on the node.
This is also the case when you wants to control the LEDs of the nodes of a group from the board. The LEDs on the nodes subscribed to the Publish address will toggle when the button on the board is pressed.
The same message received on the node which needs to turn on the LEDs requires a WriteLocal action on that node. This is shown in the figure below for the SetRemote / WriteLocal actions on different nodes in the network.
Figure 15. SetRemote/WriteLocal actions
User-Action to switch on remote node lights
LED ON
Vendor_ReadLocalDataCb
SetRemoteData ReadLocalData
Mesh Library Mesh Library
Source
Destination
Acknowledged and unacknowledged messages
By default, all messages in the Mesh network are configured as unacknowledged. The difference between acknowledged and unacknowledged messages is the response to the message. For example, a write message to a node may have a response in acknowledged communication. Whereas, in unacknowledged communication, the response may not be there.
You should use unacknowledged messages in the mesh network to avoid the exchange of multiple messages in the network, which may take time to the process.
Provisioning process
The process of configuring a devices in a network is called provisioning. The process is started by a “Provisioner”, which is a BlueNRG-Mesh app running on the smartphone.
UM2295 - Rev 2 page 17/37
UM2295
Provisioning process
Unprovisioning
Figure 16. Provisioning process
Unprovisioned device
Provisioning with data: network key, Key index
Flags, IV index, unicast address
Unconfigured mesh node
Configuration information
Configured mesh node
The BlueNRG-Mesh app can be installed on the smartphone with BLE 4.0 or higher. During installation, the app asks for some user permissions, refer to the appropriate BlueNRG-Mesh user manual for your device type
(Android or iOS) on www.st.com . The steps required for the provisioning are shown in the figure below.
Figure 17. Provisioning steps
UM2295 - Rev 2
The provisioning is executed by GATT connection between the smartphone and the unprovisioned device.
page 18/37
5.4
5.5
5.6
UM2295
GATT connection/disconnection node
RELATED LINKS
5.4 GATT connection/disconnection node on page 19
GATT connection/disconnection node
Each node in the network has the capability to make connection with the smartphone through GATT interface.
When this connection is established, the node becomes a “proxy”. The proxy has the responsibility to bridge the commands and response between the Mesh network and the smartphone. The detection of connection and disconnection with smartphone is managed by the following callbacks
Appli_BleGattConnectionCompleteCb;
Appli_BleGattDisconnectionCompleteCb;
These are initialized during the main loop. It can be interesting sometimes to know which node is connected to the smartphone when there are many nodes nearby.
During provisioning, the GATT connection is established with the node which needs to be provisioned. It may be noted that if the smartphone moves out of the range of the proxy node, it establishes a new connection with the node which is available. For example: in the example project, for BlueNRG-1 and BlueNRG-2 , a LED indication
(LED2) is used to show the proxy connection.
RELATED LINKS
5.3 Provisioning process on page 17
Write command from remote node
A command from a remote node or from a smartphone to an addressed node invokes a WriteLocalData callback.
This callback can be used to process the commands or data received inside the network. In the application demo, the Vendor_WriteLocalDataCb function is the callback where data or commands will be processed. The command/data flow can be visualised in the picture below.
Figure 18. Write command data flow
User-Action to switch remote node lights on
Vendor_WriteLocalDataCb
LED ON
SetRemoteData WriteLocalData
Mesh Library
Source
Mesh Library
Destination
The response data from the node is sent through SendResponse function.
Read command from a remote node
A Read command from a remote node or from a smartphone to an addressed node to get some information, invokes the Vendor_ReadLocalDataCb callback. This callback can be used to read some information that a remote node asks and provides the data back to the remote node. In the application demo, the
Vendor_ReadLocalDataCb function is the callback where the read commands is processed. The command/ data flow can be seen in the picture below.
UM2295 - Rev 2 page 19/37
UM2295
Application functions and callbacks
5.7
5.7.1
5.7.2
Figure 19. Read command from a remote node
User-Action to
Read a remote node information
ReadAction Sensor
ReadRemoteData() ResponseCb
Vendor_ReadLocalDataCb
ReadLocalData SendResponse
Prototype
Behaviour description
Input parameter
Output parameter
Function
Mesh Library
Source
Mesh Library
Destination
The response data from the node is sent via the BluenrgMesh_SendResponse function.
Application functions and callbacks
The following section explains the different APIs available for the user application.
User interface and indications
Table 4. Appli_LedCtrl
Description void Appli_LedCtrl(void)
It blinks the on-board LED. This function is used at power-on and at the error conditions due to user's attention
None
Void
Function
Prototype
Behaviour description
Input parameter
Output parameter
User and button interface
Table 5. SetLed
Description void SetLed(int state)
Sets the state of the LEDs or Lighting interface connected int state: sets the state of LEDs
Void
Table 6. Appli_ShortButtonPress
Function API parameters
Prototype
Behaviour description
Input parameter
Output parameter
Description
Static void Appli_ShortButtonPress(void)
Function calls when a button is pressed for short duration
Void
Void
UM2295 - Rev 2 page 20/37
UM2295
Application functions and callbacks
5.7.3
Prototype
Behaviour description
Input parameter
Output parameter
Function
Table 7. Appli_LongButtonPress
Description
Static void Appli_LongButtonPress(void)
Function calls when a button is pressed for long duration
Void
Void
Prototype
Behaviour description
Input parameter
Output parameter
Function
Table 8. Appli_UpdateButtonState
Description
Void Appli_UpdateButtonState(int isPressed)
Updates the button status int isPressed
Void
Device BLE configuration type interface
This section explains the functions available to the application developer to configure the device to be used in the network.
Prototype
Behaviour description
Input parameter
Output parameter
Function
Table 9. Appli_BleStackInitCb
Description
MOBLE_RESULT Appli_BleStackInitCb()
This function helps with hardware configuration; mainly the initialization of the BLE Stack based on the structured parameters defined in BlueNRG_Stack_Init_params.
The user can modify the Low level hardware configuration data for the device defined in CONFIG_TABLE like
LOW_SPEED_SOURCE and HS_STARTUP_TIME, which may depend on the user hardware design.
The Parameters initializes BlueNRG Stack
None
MOBLE_RESULT status of result
Prototype
Behaviour description
Input parameter
Output parameter
Function
Table 10. Appli_BleSetTxPowerCb
Description
MOBLE_RESULT Appli_BleSetTxPowerCb()
This callback sets the transmission power of BLE radio. IN turns this function call aci_hal_set_tx_power_level. By default, the power level is set to +4 dbm
None
MOBLE_RESULT status of result
UM2295 - Rev 2 page 21/37
UM2295
Application functions and callbacks
5.7.4
Prototype
Behaviour description
Input parameter
Output parameter
Table 11. Appli_BleGattConnectionCompleteCb
Function Description void Appli_BleGattConnectionCompleteCb(void)
This function is called when GATT Connection is detected by the node. The application can use this callback to indicate to the user that node is connected to the smartphone
Void
Void
Prototype
Behaviour description
Input parameter
Output parameter
Table 12. Appli_BleGattDisconnectionCompleteCb
Function Description void Appli_BleGattDisconnectionCompleteCb(void)
This function is called when GATTDisconnection is detected by the node. The application can use this callback to indicate to the user that node is no longer connected to the smartphone
None
None
Vendor model network data communication functions
The functions explained below help the developer to manage the network data communication and take the associated actions.
Prototype
Behaviour description
Input parameters
Output parameter
Function
Table 13. Vendor_WriteLocalDataCb
Description
MOBLE_RESULT
Vendor_WriteLocalDataCb(MOBLE_ADDRESS peer_addr,
MOBLE_ADDRESS dst_peer,
MOBLEUINT8 command,
MOBLEUINT8 const *data,
MOBLEUINT32 length,
MOBLEBOOL response)
Call back function called when action is required on node itself
MOBLE_ADDRESS peer_addr: address of the peer
MOBLE_ADDRESS dst_peer: destination address of the command. This address can be the address of Group to which the node is subscribed or the unicast address of element
MOBLEUINT16 command: command received for the action
MOBLEUINT8 const *data pointer to the data
MOBLEUINT32 length: length of the data
MOBLEBOOL response: If this is MOBLE_TRUE, the sender expects an acknowledgement
MOBLE_RESULT status of result
UM2295 - Rev 2 page 22/37
UM2295
Application functions and callbacks
5.7.5
5.7.6
Prototype
Behaviour description
Input parameter
Function
Table 14. Vendor_ReadLocalDataCb
Description
MOBLE_RESULT
Vendor_ReadLocalDataCb(MOBLE_ADDRESS peer_addr,
MOBLE_ADDRESS dst_peer, MOBLEUINT8 command,
MOBLEUINT8 const *data,
MOBLEUINT32 length,
MOBLEBOOL response)
Callback function invoked when some data are required from node
MOBLE_ADDRESS peer_addr: address of the peer
MOBLE_ADDRESS dst_peer: destination address of the command. This address can be the address of Group to which the node is subscribed or the unicast address of element
MOBLEUINT16 command : command received for processing
MOBLEUINT8 const *data pointer to the data
MOBLEUINT32 length: length of the data
MOBLEBOOL response: If this is MOBLE_TRUE, the sender expects an acknowledgement
MOBLE_RESULT status of result Output parameter
MAC address configuration
Prototype
Behaviour description
Input parameter
Output parameter
Function
Table 15. Appli_CheckBdMacAddr
Description int Appli_CheckBdMacAddr(void)
Checks MAC address validity
Void
MOBLEUINT8 sum return the sum calculated MAC
Prototype
Behaviour description
Input parameter
Output parameter
Function
Table 16. Appli_GetMACfromUniqueNumber
Description
#ifdef INTERNAL_UNIQUE_NUMBER_MAC static void Appli_GetMACfromUniqueNumber(void)
Reads the unique serial number of the device and generates the MAC address from it
Void
Void
BlueNRG-Mesh node configuration
The following tables list the available functions to configure the node to be used in the network.
UM2295 - Rev 2 page 23/37
UM2295 - Rev 2
UM2295
Application functions and callbacks
Table 17. BluenrgMesh_InitUnprovisionedNode
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Description
MOBLE_Result BluenrgMesh_InitUnprovisionedNode(void);
Initializes Unprovision Node void
MOBLE RESULT status of Result
Table 18. BluenrgMesh_InitProvisionedNode
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Description
MOBLE_Result BluenrgMesh_InitProvisionedNode(void);
Initializes Provision Node void
MOBLE RESULT status of Result
Table 19. BluenrgMesh_GetUnprovisionState
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Description
MOBLEUINT8 BluenrgMesh_GetUnprovisionState (void);
Get Provisioning process state void
MOBLEUINT8
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Table 20. BluenrgMesh_GetAddress
Description
MOBLE_ADDRESS BluenrgMesh_GetAddress (void);
Get mesh address of a node void
Mesh address of a node
Table 21. BluenrgMesh_GetPublishAddress
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Description
MOBLE_RESULT BluenrgMesh_SetTTL (MOBLEUINT8 ttl);
Get Publish address of a node void
Mesh address of a node page 24/37
UM2295 - Rev 2
UM2295
Application functions and callbacks
Table 22. BluenrgMesh_GetSubscriptionAddress
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Description
MOBLE_RESULT BluenrgMesh_GetSubscriptionAddress
(MOBLE_ADDRESS *addressList, , MOBLEUINT8
*sizeOfList, MOBLEUINT8 elementNumber );
Get Subscription address of a node
SubscriptionList, SizeofList, elementNumber
MOBLE RESULT status of Result
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Table 23. BluenrgMesh_SetTTL
Description
MOBLE_RESULT BluenrgMesh_SetTTL (MOBLEUINT8 ttl);
Set default TTL value
MOBLEUINT8 ttl value
MOBLE RESULT status of Result
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Table 24. BluenrgMesh_GetTTL
Description
MOBLEUINT8 BluenrgMesh_GetTTL (void);
Get default TTL value void
MOBLEUINT8 Default TTL value
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Table 25. BluenrgMesh_GetTTL
Description
MOBLE_RESULT BluenrgMesh_SetNetworkTransmitCount
(MOBLEUINT8 count);
Set Network Transmit Count value
MOBLEUINT8 count, network transmit value. Supported values are 1-8
MOBLE RESULT status of Result
Table 26. BluenrgMesh_GetNetworkTransmitCount
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Description
MOBLEUINT8 BluenrgMesh_GetNetworkTransmitCount
(void);
Get Network Transmit Count value void
MOBLE RESULT status of Result page 25/37
UM2295
Application functions and callbacks
5.7.7
Table 27. BluenrgMesh_SetRelayRetransmitCount
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Description
MOBLE_RESULT BluenrgMesh_SetRelayRetransmitCount
(MOBLEUINT8 count);
Set Relay Retransmit Count value
MOBLEUINT8 count Relay Retransmit value. Supported values are 1-8
MOBLE RESULT status of Result
Table 28. BluenrgMesh_GetRelayRetransmitCount
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Description
MOBLE_RESULT BluenrgMesh_GetRelayRetransmitCount
(void);
Get Relay Retransmit Count value void
MOBLE_RESULT Default Relay retransmit Count value
Function
Prototype
Table 29. BluenrgMesh_SetHeartbeatCallback
Behaviour Description
Input Parameter
Output Parameter
Description
MOBLE_RESULT BluenrgMesh_SetHeartbeatCallback
(MOBLE_HEARTBEAT_CB cb);
Set callback for handling heartbeat messages
MOBLE_HEARTBEAT_CB cb Callback
MOBLE RESULT status of Result
Table 30. BluenrgMesh_SetAttentionTimerCallback
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Description
MOBLE_RESULT BluenrgMesh_SetAttentionTimerCallback
(MOBLE_ATTENTION_TIMER_CB cb);
Set callback for attention timer.
To be used for attention during provisioning and for health model
MOBLE_ATTENTION_TIMER_CB cb Callback
MOBLE RESULT status of Result
BlueNRG-Mesh Library configuration
The following tables list the available functions to configure and initialize the ST BlueNRG-Mesh Library.
Function
Prototype
Table 31. BluenrgMesh_Init
Description
MOBLE_RESULT BluenrgMesh_Init (const
Mesh_Initialization_t* pInit_params);
UM2295 - Rev 2 page 26/37
UM2295 - Rev 2
UM2295
Application functions and callbacks
Function
Behaviour Description
Input Parameter
Output Parameter
Description
To initialize ST BlueNRG-Mesh Library
Bdaddr, Features to be supported by library,Low power node,Friendship & Dynamic Buffer parameters
MOBLE RESULT status of Result
Table 32. BluenrgMesh_GetLibraryVersion
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Description
Char* BluenrgMesh_GetLibraryVersion (void);
To get the latest library version void string
Table 33. BluenrgMesh_GetLibrarySubVersion
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Description
Char* BluenrgMesh_GetLibrarySubVersion (void);
To get the latest library sub version void string
Function
Prototype
Behaviour Description
Input Parameter
Output Parameter
Table 34. BluenrgMesh_Process
Description
MOBLE_RESULT BluenrgMesh_Process (void);
Mesh task processing function void
MOBLE RESULT status of Result
Function
Prototype
Input Parameter
Output Parameter
Table 35. BluenrgMesh_SetRemoteData
Behaviour Description
Description
MOBLE_RESULT BluenrgMesh_SetRemoteData
(MOBLE_ADDRESS peer, MOBLEUINT8 command,
MOBLEUINT8 const * data, MOBLEUINT32 length,
MOBLEUINT8 response);
Set remote data on the given peer peer Destination address, vendor model commands, Data buffer, Length of data in bytes, response (If not '0', used to get the response. If '0', no response)
MOBLE RESULT status of Result page 27/37
UM2295
Application functions and callbacks
Function
Prototype
Table 36. BluenrgMesh_ReadRemoteData
Behaviour Description
Input Parameter
Output Parameter
Description
MOBLE_RESULT BluenrgMesh_ReadRemoteData
(MOBLE_ADDRESS peer, MOBLEUINT16 command);
Read remote data on the given peer peer Destination address, vendor model commands
MOBLE RESULT status of Result
Function
Prototype
Input Parameter
Output Parameter
Table 37. BluenrgMesh_SendResponse
Behaviour Description
Description
MOBLE_RESULT BluenrgMesh_SendResponse
(MOBLE_ADDRESS peer, MOBLEUINT8 status,
MOBLEUINT8 const * data, MOBLEUINT32 length);
Send response on received packet peer Destination address, Status of response, Data buffer,
Length of data in bytes
MOBLE RESULT status of Result
UM2295 - Rev 2 page 28/37
A References
Name
Bluetooth specifications
Bluetooth specifications
Table 38. References
Title/description
Specification of the Bluetooth system (v4.0, v4.1, v4.2, v5.0)
Mesh profile specifications v1.0
UM2295
References
UM2295 - Rev 2 page 29/37
B
UM2295
Licensing and other information
Licensing and other information
Developer-friendly license terms
The initial BlueNRG-Mesh is built over Motorola’s Mesh Over Bluetooth Low Energy (MoBLE) technology.
The present solution involving both the Mesh library and applications is developed and maintained solely by
STMicroelectronics.
UM2295 - Rev 2 page 30/37
UM2295
Revision history
Table 39. Document revision history
Date
09-Feb-2018
Revision Changes
1 Initial release
27-Sep-18 2
Updated
Figure 5. Folders, sub-folders and contents of the package ,
,
, Section 4.2 Setting the transmit power of a node
,
Section 4.3 UART interface on the firmware ,
Table 3. MAC address management ,
Section 5.1 Local and remote concept ,
Figure 17. Provisioning steps ,
Section 5.5 Write command from remote node , Section 5.6 Read command from a remote node ,
Section 5.7.1 User interface and indications ,
Table 10. Appli_BleSetTxPowerCb
, Table 13. Vendor_WriteLocalDataCb
,
Table 14. Vendor_ReadLocalDataCb and Table 16. Appli_GetMACfromUniqueNumber .
Added Section 5.7.6 BlueNRG-Mesh node configuration and
Section 5.7.7 BlueNRG-Mesh Library configuration
UM2295 - Rev 2 page 31/37
UM2295
Contents
Contents
UM2295 - Rev 2 page 32/37
UM2295
Contents
UM2295 - Rev 2 page 33/37
UM2295
List of figures
List of figures
UM2295 - Rev 2 page 34/37
UM2295
List of tables
List of tables
UM2295 - Rev 2 page 35/37
● Acronyms and abbreviations
GUI
HAL
HW
IDE
LED
API
BLE
BSP
DFU
MCU
MoBLE
SoC
USB
Acronym
Table 40. Acronyms and abbreviations
Description
Application programming interface
Bluetooth Low Energy
Board support package
Device firmware upgrade
Graphical user interface
Hardware abstraction layer
Hardware
Integrated development environment
Light emitting diode
Microcontroller unit
Mesh over Bluetooth Low Energy
System-on-chip
Universal serial bus
UM2295
UM2295 - Rev 2 page 36/37
UM2295
IMPORTANT NOTICE – PLEASE READ CAREFULLY
STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgement.
Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of
Purchasers’ products.
No license, express or implied, to any intellectual property right is granted by ST herein.
Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.
ST and the ST logo are trademarks of ST. All other product or service names are the property of their respective owners.
Information in this document supersedes and replaces information previously supplied in any prior versions of this document.
© 2018 STMicroelectronics – All rights reserved
UM2295 - Rev 2 page 37/37
Preuzimanje
Javna poveznica ažurirana
Javna poveznica na vaš razgovor je ažurirana. You may view and manage your chat links after registration here.
Javna poveznica dokumenta
Oglas