STMicroelectronics FP-LIT-BLEMESH1 User Manual
Διαφήμιση
Διαφήμιση
UM2992
User manual
Getting started with FP-LIT-BLEMESH1 function pack for IoT nodes with
Bluetooth® Low Energy mesh connectivity and lighting mode
Introduction
FP-LIT-BLEMESH1 is an STM32Cube function pack, which lets you connect Bluetooth® Low Energy nodes to a smartphone via Bluetooth® Low Energy, through a suitable Android™ or iOS™ application, to set the HSL values and send the data to the lighting hardware using the Bluetooth® Low Energy mesh lighting model.
The software lets you easily create your own application for extending Bluetooth® mesh networks (by offering a ready-to-use mesh core library), a complete set of compatible APIs, and a lighting demo application running on either X-NUCLEO-IDB05A2 or X-NUCLEO-BNRG2A1 and X-NUCLEO-LED12A1 expansion boards connected to a NUCLEO-L476RG development board.
The software runs on the STM32 microcontroller and includes all the necessary drivers to recognize the devices on the STM32
Nucleo development board and the expansion boards.
RELATED LINKS
Visit the STM32Cube ecosystem web page on www.st.com for further information
UM2992 - Rev 1 - February 2022
For further information contact your local STMicroelectronics sales office.
www.st.com
1 Acronyms and abbreviations
GATT
Acronym
BSP
HAL
SPI
CMSIS
HSL
Table 1. List of acronyms
Description
Generic attribute profile
Board support package
Hardware abstraction layer
Serial peripheral interface
Cortex® microcontroller software interface standard
Hue saturation lighting
UM2992
Acronyms and abbreviations
UM2992 - Rev 1 page 2/19
2
2.1
2.2
UM2992
FP-LIT-BLEMESH1 software expansion for STM32Cube
FP-LIT-BLEMESH1 software expansion for STM32Cube
Overview
The FP-LIT-BLEMESH1 software package expands STM32Cube functionality.
The key features of the package are:
•
•
•
•
•
Complete software to build a mesh network with Bluetooth® Low Energy nodes supporting the Bluetooth® mesh lighting model, defined in Bluetooth® mesh specification V1.0.1
Hue, saturation, and lightness (HSL) values set by the STBLEMesh Android and iOS app using the lighting model changes the RGB values of the X-NUCLEO-LED12A1 LED expansion board connected to a NUCLEO-L476RG
Compatible with BLE-enabled smartphones to monitor and control multiple Bluetooth® Low Energy nodes, using the proxy protocol and legacy Bluetooth® Low Energy GATT connectivity
Two-layer security, thanks to the 128-bit AES CCM encryption and 256-bit ECDH protocol, ensuring protection from multiple attacks, including Replay, Bit-Flipping, Eavesdropping, Man-in-the-Middle, and
Trashcan
Sample implementation available on:
•
•
– the X-NUCLEO-IDB05A2 and X-NUCLEO-LED12A1 expansion boards connected to a NUCLEO-
L476RG development board
– the X-NUCLEO-BNRG2A1 and X-NUCLEO-LED12A1 expansion boards connected to a NUCLEO-
L476RG development board
Easy portability across different MCU families, thanks to STM32Cube
Free, user-friendly license terms
The function pack software includes the LED1202 , which is a 12-channel low quiescent current LED driver, when the X-NUCLEO-LED12A1 expansion board is mounted on top of the STM32 Nucleo .
The package is compatible with the STBLEMesh Android/iOS application available at GooglePlay/iTunes stores, which can be used to set information and send it via Bluetooth® Low Energy. It integrates BlueNRG products with the embedded Bluetooth® Low Energy communication in a powerful, range-extending mesh network with real full-duplex communication. The package flexibility allows you to build your own application.
•
•
Architecture
The software is based on the STM32CubeHAL, the hardware abstraction layer for the STM32 microcontroller.
The package extends STM32Cube by providing a board support package (BSP) to enable development of applications using Bluetooth mesh profile and model specifications.
The software layers used by the application software to access and use the expansion boards are: the STM32Cube HAL layer , which provides a simple, generic, multi-instance set of application programming interfaces (APIs) to interact with the upper application, library, and stack layers. It has generic and extension
APIs and is directly built around a generic architecture and allows successive layers like the middleware layer to implement functions without requiring specific hardware configurations for a given microcontroller unit (MCU). This structure improves the library code reusability and guarantees an easy portability on other devices.
the board support package (BSP) layer supports all the peripherals on the STM32 Nucleo except the
MCU. This limited set of APIs provides a programming interface for certain board-specific peripherals like the LED, the user button, etc. This interface also helps in identifying the specific board version.
UM2992 - Rev 1 page 3/19
2.3
Application
Figure 1. FP-LIT-BLEMESH1 software architecture
Lighting model application
Middleware
Hardware
Abstraction
Hardware
BlueNRGMesh library ST Cryptographic library
STM32Cube Hardware Abstraction Layer
STM32 Nucleo expansion boards
X-NUCLEO-IDB05A2 (Connect)/
X-NUCLEO-BNRG2A1 (Connect)
X-NUCLEO-LED12A1 (Lighting)
STM32 Nucleo development board
NUCLEO-L476RG
Folder structure
Figure 2. FP-LIT-BLEMESH1 package folder structure
UM2992
Folder structure
2.4
The following folders are included in the software package:
•
•
•
•
•
Documentation : contains a compiled HTML file generated from the source code, which details the software components and APIs.
Drivers : contains the HAL drivers and the board-specific drivers for each supported board or hardware platform, including the on-board components and the CMSIS vendor-independent hardware abstraction layer for the Arm® Cortex®-M processor series.
Middlewares : contains libraries and protocols related to the Bluetooth and Bluetooth mesh profile and model specifications.
Projects : contains a sample application used to update the RGB lights HSL value, provided for the
NUCLEO-L476RG platform with three development environments, IAR Embedded Workbench for Arm (IAR-
EWARM), RealView Microcontroller Development Kit (MDK-ARM-STM32), and STM32CubeIDE .
Utilities : contains the STM32L4_MAC folder that provides an external MAC address.
APIs
Detailed technical information with full user API function and parameter description are in a compiled HTML file in the “Documentation” folder.
UM2992 - Rev 1 page 4/19
2.5
2.5.1
UM2992
Sample application description
Sample application description
Initialization of application callbacks
The "Projects" directory provides an example application using the X-NUCLEO-IDB05A2 or X-NUCLEO-
BNRG2A1 and X-NUCLEO-LED12A1 expansion boards with the NUCLEO-L476RG development board.
Ready to be built projects are available for multiple IDEs.
This application starts by initializing the callbacks required for the different events and functionalities. The callbacks are used in the BlueNRG-Mesh library to call the functions based on specific events or by the mesh library state machine.
__attribute__((aligned(4))) const MODEL_SIG_cb_t Model_SIG_cb[] =
#ifdef ENABLE_LIGHT_MODEL_SERVER
{
{
LightModelServer_GetOpcodeTableCb,
LightModelServer_GetStatusRequestCb,
LightModelServer_ProcessMessageCb
},
};
__attribute__((aligned(4))) const Appli_Light_cb_t LightAppli_cb =
{
/* Light Lightness callbacks */
Appli_Light_Lightness_Set,
Appli_Light_Lightness_Status,
Appli_Light_Lightness_Linear_Set,
Appli_Light_Lightness_Linear_Status,
Appli_Light_Lightness_Default_Set,
Appli_Light_Lightness_Default_Status,
Appli_Light_Lightness_Last_Set,
Appli_Light_Lightness_Range_Set,
Appli_Light_Lightness_Range_Status,
Appli_Light_Ctl_Set,
Appli_Light_Ctl_Status,
Appli_Light_CtlTemperature_Set,
Appli_Light_CtlTemperature_Status,
Appli_Light_CtlTemperature_Range_Set,
Appli_Light_CtlTemperature_Range_Status,
Appli_Light_CtlDefault_Set,
Appli_Light_CtlDefault_Status,
Appli_Light_Hsl_Set,
Appli_Light_Hsl_Status,
Appli_Light_HslHue_Set,
Appli_Light_HslHue_Status,
Appli_Light_HslSaturation_Set,
Appli_Light_HslSaturation_Status,
Appli_Light_HslDefault_Set,
Appli_Light_HslDefault_Status,
Appli_Light_HslRange_Set,
Appli_Light_HslRange_Status
};
/* Callbacks used by BlueNRG-Mesh Models */
result = BluenrgMesh_SetSIGModelsCbMap(Model_SIG_cb, MODEL_SIG_COUNT);
if(MOBLE_FAILED(result))
{
TRACE_I(TF_INIT,"BluenrgMesh models init failed \r\n");
while (1)
{
Appli_LedBlink();
}
}
The Model_SIG_cb structure is used to initialize the SIG models for the application implementation. The
BluenrgMesh_SetSIGModelsCbMap(Model_SIG_cb, MODEL_SIG_COUNT); function is used to initialize the different callbacks in the library.
UM2992 - Rev 1 page 5/19
2.5.2
UM2992
Sample application description
Initialization and main application loop
This procedure develops an application for mesh over Bluetooth® Low Energy on the BlueNRG platforms.
Step 1.
Call the InitDevice() API, which calls the SystemInit() API, to initialize the device vector table, interrupt priorities, and clock.
Step 2.
Call the Appli_CheckBdMacAddr() API to check the validity of the MAC address.
If the MAC address is not valid, the firmware is stuck in the while(1) loop and the LED continuously blinks.
Step 3.
Initialize the hardware callback functions for the Bluetooth® Low Energy hardware by updating
MOBLE_USER_BLE_CB_MAP user_ble_cb = .
{
Appli_BleStackInitCb,
Appli_BleSetTxPowerCb,
Appli_BleGattConnectionCompleteCb,
Appli_BleGattDisconnectionCompleteCb,
Appli_BleUnprovisionedIdentifyCb,
Appli_BleSetUUICb,
Appli_BleSetProductInfoCb,
Appli_BleSetNumberOfElementsCb,
Appli_BleDisableFilterCb
};
Step 4.
To rely on an application interface for the Bluetooth® Low Energy radio initialization and Tx power configuration, initialize the GATT connection and disconnection callbacks for the application interface.
Step 5.
Call BluenrgMesh_BleHardwareInitCallBack(&user_ble_cb) to complete the initialization of hardware callbacks.
Step 6.
Initialize the BlueNRG-Mesh library by calling BluenrgMesh_Init(&BLEMeshlib_Init_params) .
If an error occurs, a message ("Could not initialize BlueNRG-Mesh library!") pops up on the terminal window, which was opened for the VCOM port created by the board USB connection. This error makes the LED blink continuously.
Step 7.
Check whether the device has been provisioned or not.
A provisioned device has network keys and other parameters configured in the internal flash memory. You can check them with the BluenrgMesh_IsUnprovisioned() API. If the node is unprovisioned, the BluenrgMesh_InitUnprovisionedNode() API initializes it. If the device is already provisioned, the BluenrgMesh_InitprovisionedNode() API helps to initialize the device.
Step 8.
Print the messages to the terminal window for the nodes that are being initialized.
The message also prints the MAC address assigned to the node.
Step 9.
Initialize the BlueNRG-Mesh models using the BluenrgMesh_ModelsInit() API.
Step 10.
To initialize the node to the unprovisioned state, hold down the user button.
It erases all the network parameters configured in the device internal memory. Once the unprovisioning is complete, reset the board.
Step 11.
Initialize the LED drivers and the GPIO mounted on the X-NUCLEO-LED12A1 .
The application must call BluenrgMesh_Process() in while(1) loop as frequently as possible.
This function calls BLE_StackTick() internally to process Bluetooth® Low Energy communication.
The BluenrgMesh_ModelsProcess() (model processing) and Appli_Process() APIs are also called in while(1) loop.
Any application implementation is performed in the state machine by nonblocking functions with frequent calls to BluenrgMesh_Process() .
Step 12.
Check for user inputs or buttons for any action to take.
UM2992 - Rev 1 page 6/19
2.5.3
Note:
2.5.4
UM2992
Sample application description
GATT connection/disconnection node
Each node in the network can connect to a smartphone through the GATT interface. When this connection is established, the node becomes a proxy, which acts as a bridge between the mesh network commands and the smartphone responses.
You can detect the smartphone connection and disconnection through the following callbacks:
•
•
Appli_BleGattConnectionCompleteCb;
Appli_BleGattDisconnectionCompleteCb;
These are initialized during the main loop.
During the provisioning, the GATT connection is established with the node that needs to be provisioned.
If the smartphone moves out of the proxy node range, it establishes a new connection with the available node.
Lighting model
The specification defines the number of light states, messages, and models that are explicitly defined to be nonspecific in their functionality.
There are different types of light sources with different capabilities. Accordingly, there are different ways to express the state of a light.
A more advanced method of controlling a light is changing the lightness by controlling the light lightness actual state.
If a light is a tunable white, it is possible to control its color temperature through the light CTL.
If a light is a color-changing light, it is possible to control the three dimensions (hue, saturation, and lightness) by controlling each state independently.
Figure 3. Lighting model message flow
UM2992 - Rev 1
The number of octets depends on the parameters dedicated for the model. They are different for each lighting model.
The middle layer receives messages from the library. It then checks for the opcode according to the different application of the light model. As an example of the light lightness model, the opcode is checked in the middle layer. The message with the defined data parameters is then transmitted to the light lightness application.
The types of messages are:
• Set Acknowledged message , sent by the client to set the desired value to the model on the server. It expects then the response message from the server.
page 7/19
2.5.5
UM2992
Sample application description
•
•
Set Unacknowledged message , sent by the client to set the desired value to the model on the server. It does not expect any response message from the server.
Get message , sent by the client to the server to get the state of the model as a response message from the server.
External MAC address utilities
The "Utilities" folder contains the STM32L4_MAC folder, which provides a hex file of an external MAC address.
To use this address, uncomment the EXTERNAL_MAC_ADDR_MGMT macro in the mesh_cfg.h file of the
"Middleware" folder.
The demo application firmware and the MAC address are flashed independently. Thus, you do not have to update the firmware if the other firmware has already been flashed.
The MAC address is flashed the first time and at every full chip erase.
UM2992 - Rev 1 page 8/19
3
3.1
3.1.1
UM2992
System setup guide
System setup guide
Hardware description
STM32 Nucleo
STM32 Nucleo development boards provide an affordable and flexible way for users to test solutions and build prototypes with any STM32 microcontroller line.
The Arduino connectivity support and ST morpho connectors make it easy to expand the functionality of the
STM32 Nucleo open development platform with a wide range of specialized expansion boards to choose from.
The STM32 Nucleo board does not require separate probes as it integrates the ST-LINK/V2-1 debugger/ programmer.
The STM32 Nucleo board comes with the comprehensive STM32 software HAL library together with various packaged software examples for different IDEs (IAR EWARM, Keil MDK-ARM, STM32CubeIDE , mbed and GCC/
LLVM).
All STM32 Nucleo users have free access to the mbed online resources (compiler, C/C++ SDK and developer community) at www.mbed.org to easily build complete applications.
Figure 4. STM32 Nucleo board
UM2992 - Rev 1 page 9/19
3.1.2
UM2992
Hardware description
X-NUCLEO-IDB05A2 expansion board
The X-NUCLEO-IDB05A2 Bluetooth® Low Energy expansion board is based on the BlueNRG-M0 Bluetooth®
Low Energy network processor module.
The BlueNRG-M0 is Bluetooth v4.2 compliant, FCC, and IC certified (FCC ID: S9NBNRGM0AL; IC: 8976C-
BNRGM0AL). It supports simultaneous master/slave roles and can behave as a Bluetooth® Low Energy sensor and hub device at the same time.
The BlueNRG-M0 provides a complete RF platform in a tiny form factor, with integrated radio, antenna, high frequency, and LPO oscillators.
The X-NUCLEO-IDB05A2 is compatible with the ST morpho (not mounted) and Arduino UNO R3 connector layout.
The X-NUCLEO-IDB05A2 interfaces with the STM32 microcontroller via the SPI pin and allows changing the default SPI clock, SPI chip select, and SPI IRQ by replacing a resistor on the expansion board.
Figure 5. X-NUCLEO-IDB05A2 expansion board
UM2992 - Rev 1 page 10/19
3.1.3
UM2992
Hardware description
X-NUCLEO-BNRG2A1 expansion board
The X-NUCLEO-BNRG2A1 expansion board provides Bluetooth® Low Energy connectivity for developer applications and can be plugged onto an STM32 Nucleo development board (for example, NUCLEO-L476RG with an ultra-low power STM32 microcontroller) through its Arduino UNO R3 connectors.
The expansion board features the Bluetooth ® v5.2 compliant and FCC certified BlueNRG-M2SP application processor module based on the ST BlueNRG-2 System-on-Chip. This SoC manages the complete Bluetooth®
Low Energy stack and protocols on its Cortex-M0 core and programmable flash memory, which can accommodate custom applications developed using the SDK. The BlueNRG-M2SP module supports master and slave modes, increased transfer rates with data length extension (DLE), and AES-128 security encryption.
The X-NUCLEO-BNRG2A1 interfaces with the STM32 Nucleo microcontroller via SPI connections and GPIO pins, some of which can be configured through the hardware.
Figure 6. X-NUCLEO-BNRG2A1 expansion board
UM2992 - Rev 1 page 11/19
3.1.4
UM2992
Hardware setup
X-NUCLEO-LED12A1 expansion board
The X-NUCLEO-LED12A1 LED driver expansion board for STM32 Nucleo features four LED1202 devices that can drive up to 48 LEDs.
The LED1202 is a 12-channel low quiescent current LED driver, which guarantees a 5 V output driving capability.
Each channel is able to provide up to 20 mA with a headroom voltage of 350 mV (typical) only.
The output current can be adjusted separately for each channel through an 8-bit analog and 12-bit digital dimming control.
The X-NUCLEO-LED12A1 expansion board comes with an additional LED panel board that houses two LEDs matrices: a 6x8 white LED matrix and a 4x4 RGB matrix.
LED matrices can be supplied via an external power supply, which is connected to the J13 connector, and by selecting the right path through the J15 jumper to reach the maximum luminosity available.
Figure 7. X-NUCLEO-LED12A1 expansion board
Figure 8. LED panel board
3.2
Hardware setup
To set up a suitable development environment for creating applications for the STM32 Nucleo equipped with the lighting or Bluetooth® Low Energy expansion board, you need the following hardware components:
1.
One STM32 Nucleo development board (order code: NUCLEO-L476RG )
2.
One Bluetooth® Low Energy expansion board (order code: X-NUCLEO-IDB05A2 or X-NUCLEO-BNRG2A1 )
3.
One LED expansion board (order code: X-NUCLEO-LED12A1 )
4.
One USB type A to Mini-B USB cable to connect the STM32 Nucleo to the PC
UM2992 - Rev 1 page 12/19
3.3
3.4
UM2992
Software setup
•
•
Software setup
The following software components are required for the setup of a suitable development environment to create applications for the STM32 Nucleo board with the Bluetooth® Low Energy and the LED expansion board:
FP-LIT-BLEMESH1 : an STM32Cube function pack for IoT node with Bluetooth® Low Energy mesh connectivity and lighting model. The firmware and related documentation are available on www.st.com.
Development tool-chain and compilers. The STM32Cube expansion software supports the three following environments to select from:
– IAR Embedded Workbench for Arm ® (IAR-EWARM) toolchain + ST-LINK
– RealView Microcontroller Development Kit (MDK-ARM-STM32) toolchain + ST-LINK
– STM32CubeIDE + ST-LINK
System setup
The STM32 Nucleo board integrates the ST-LINK/V2-1 debugger/programmer.
The developer can download the ST-LINK/V2-1 USB driver by looking for the STSW-LINK009 software on www.st.com.
You can easily connect the X-NUCLEO-LED12A1 LED expansion board to the STM32 Nucleo through the
Arduino UNO R3 extension connector.
Figure 9. Hardware setup for FP-LIT-BLEMESH1
UM2992 - Rev 1
The X-NUCLEO-LED12A1 can interface with the external STM32 microcontroller on the STM32 Nucleo using the
I²C communication protocol.
You can also connect either the X-NUCLEO-IDB05A2 or the X-NUCLEO-BNRG2A1 expansion board to the
STM32 Nucleo through the Arduino UNO R3 extension connector.
page 13/19
UM2992
References
Appendix A References
1.
Mesh over Bluetooth® Low Energy: STSW-BNRG-Mesh
2.
Bluetooth mesh networking specifications: https://www.bluetooth.com/specifications/mesh-specifications
3.
Bluetooth mesh model specification: https://www.bluetooth.com/specifications/adopted-specifications
UM2992 - Rev 1 page 14/19
Revision history
Date
25-Feb-2022
Table 2. Document revision history
Revision
1 Initial release.
Changes
UM2992
UM2992 - Rev 1 page 15/19
UM2992
Contents
Contents
UM2992 - Rev 1 page 16/19
UM2992
List of tables
List of tables
UM2992 - Rev 1 page 17/19
UM2992
List of figures
List of figures
UM2992 - Rev 1 page 18/19
UM2992
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. For additional information about ST trademarks, please refer to www.st.com/trademarks . 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.
© 2022 STMicroelectronics – All rights reserved
UM2992 - Rev 1 page 19/19
Λήψη
Δημόσιος σύνδεσμος ενημερώθηκε
Ο δημόσιος σύνδεσμος για τη συνομιλία σας ενημερώθηκε. You may view and manage your chat links after registration here.
Δημόσιος σύνδεσμος εγγράφου
Διαφήμιση
