SILICON LABS 4.2.3.0 GA Bluetooth Mesh SDK User Guide
- June 17, 2024
- SILICON LABS
Table of Contents
SILICON LABS 4.2.3.0 GA Bluetooth Mesh SDK User Guide
Bluetooth mesh is a new topology available for Bluetooth Low Energy (LE)
devices that enables many-to-many (m:m) communication. It’s optimized for
creating large-scale device networks, and is ideally suited for building
automation, sensor networks, and asset tracking. Our software and SDK for
Bluetooth development supports Bluetooth Mesh and Bluetooth 5.3 functionality.
Developers can add mesh networking communication to LE devices such as
connected lights, home automation, and asset tracking systems. The software
also supports Bluetooth beaconing, beacon scanning, and GATT connections so
Bluetooth mesh can connect to smart phones, tablets, and other Bluetooth LE
devices.
This release includes features supported by the Bluetooth mesh specification
version 1.1.
These release notes cover SDK versions:
4.2.3.0 released January 24, 2024 (support for EFR32xG21, Revision C and
later)
4.2.2.0 released August 16, 2023 (support for EFR32xG21, Revision C and later)
4.2.1.0 released May 3, 2023
4.2.0.0 released March 8, 2023
4.1.0.0-prev released February 1, 2023 (limited access)
4.0.0.0-prev released December 14, 2022 (limited access)
3.0.0.0-prev released June 20, 2022 (limited access)
KEY FEATURES
- Support for mesh draft specification 1.1:
- Mesh Protocol
- Mesh Binary Large Object Transfer Model (MBT)
- Mesh Device Firmware Update Model (DFU)
- Reduced project flash consumption by optimizing Mesh stack code size
- Support added for xGM240P PCB Modules and BG22/BGM220 Explorer Kits
- Support added for GCC version 10.32021.10 and IAR version 9.20.4
Compatibility and Use Notices
For more information about security updates and notices, see the Security
chapter of the Gecko Platform Release notes installed with this SDK or on the
Silicon Labs Release Notes page. Silicon Labs also strongly recommends that
you subscribe to Security Advisories for up-to-date information. For
instructions, or if you are new to the Silicon Labs Bluetooth mesh SDK, see
Using This Release.
Specification Compatibility:
This release contains an implementation of the Mesh Protocol 1.1, Mesh Model
1.1, Mesh Binary Large Object Transfer, and Mesh Device Firmware Update
specifications. These specifications are not yet adopted Bluetooth SIG
specifications, and no Bluetooth qualification program currently exists for
these specifications. Therefore, these specifications are not approved for use
in commercial production. Any experimental use of the features in these
specifications are “AS IS”, and no Bluetooth license rights are granted.
Compatible Compilers:
IAR Embedded Workbench for ARM (IAR-EWARM) version 9.20.4
-
Using wine to build with the IarBuild.exe command line utility or IAR Embedded Workbench GUI on macOS or Linux could result in incorrect files being used due to collisions in wine’s hashing algorithm for generating short file names.
-
Customers on macOS or Linux are advised not to build with IAR outside of Simplicity Studio. Customers who do should carefully verify that the correct files are being used.
GCC (The GNU Compiler Collection) version 10.3-2021.10, provided with Simplicity Studio. -
Link-time optimization feature of GCC has been disabled, resulting in a slight increase of image size.
1 New Items
1.1 New Features
Added in release 4.2.1.0 New Hardware: Support for EFR32xG21 Rev C and Rev D
Added in release 4.2.0.0
The default Bluetooth address used for advertising Mesh data and secure
network beacons has been changed to be a private address that is periodically
reassigned to a new random value. This is because using a public address would
not work well with Mesh 1.1 privacy enhancing features, Private Network
Beacons and Private GATT Proxy.
Added in release 4.0.0-prev
Support for Bluetooth mesh over advertising extensions (AE) has been added as
a proprietary extension. This feature facilitates faster transmission of long
messages, compared to the standard Bluetooth Mesh using regular
advertisements. For instance, device firmware update using AE can result in
greatly reduced transmission times compared to standard operation. Bluetooth
Mesh over AE is, however, not compliant with the Bluetooth mesh specification.
Products using Mesh over AE are not fully interoperable with products that are
strictly compliant with the Bluetooth mesh specification.
Support for choosing the BLE advertising BGAPI the Bluetooth mesh stack uses
internally has been added. Previously, the mesh stack used internally only the
old BGAPI, which prevented the use of the newer BLE advertising BGAPIs in the
application, since the old and the new APIs do not work interoperable. Now the
BGAPI the stack uses can be specified by component selection in the project.
Example applications:
IV update is demonstrated through the embedded examples and Bluetooth Mesh
Host Provisioner.
Key refresh and key export to Network Analyzer is demonstrated with Bluetooth
Mesh Host Provisioner.
Tooling:
NCP Commander is now able to create a new mesh Network, provision and
configure nodes into that network, and send mesh packets using the Generic On
off Client and Generic Level Client models. This allows testing nodes with
Generic Level and Onoff Server models and any other models bound to these.
New Hardware:
Support for xGM240 SIP Modules
Added in release 3.0.0-prev
The support for the following have been added based on specifications that are
in Validation status and are not available for qualification. In order to
obtain Bluetooth SIG qualification, customers will need to upgrade to a
release which will be based on the adopted specification, which will be made
available after the adoption.
-
Mesh Protocol 1.1 with the following features
· Remote Provisioning (RPR)
· Certificate Based Provisioning (CBP) · Private Beacons(PRB) -
Mesh Binary Large Object Transfer Model (MBT)
-
Mesh Device Firmware Update Model (DFU)
New Example Applications
Embedded applications:
Bluetooth Mesh SoC DFU Distributor: Demonstrates the Firmware Distributor
role based on the BT Mesh Model specification. Distributor is responsible for
delivering new firmware images to the Updating nodes and monitoring the
progress of the firmware update.
Bluetooth Mesh – NCP Empty 1.1: NCP mode target application including remote
provisioning support. To be used with the BT Mesh Host Provisioned example
found in GSDK folder app/bluetooth/example_host/btmesh_host_provisioner
Bluetooth Mesh – SoC Empty with Certificate-Based Provisioning support:
Demonstrates the bare minimum needed for a Bluetooth Mesh C application that
allows Certificate-Based Provisioning (CBP). The application starts
Unprovisioned Device Beaconing after boot waiting to be provisioned to a Mesh
Network.
Bluetooth Mesh – SoC CSR Generator: Certificate generating firmware example.
Software is generating the device EC key pair, the signing request for the
device certificate, and other related data. The generated data can be read out
by the Central Authority.
NCP Host applications:
Bluetooth Mesh Host Provisioner was extended with Remote Provisioning and
Certificate Based Provisioning support.
New Components
-
BLOB Storage: Provides an API for storing binary large objects (BLOB) via the bootloader.
-
BLOB Transfer Client: Provides BT Mesh BLOB (binary large object) Transfer Client functionality, defined in mesh specification.
-
BLOB Transfer Server: Provides BT Mesh BLOB (binary large object) Transfer Server functionality, defined in mesh specification.
-
DFU distributor: Wrapper software component for DFU distributor role in Bluetooth Mesh applications.
-
Firmware Update Client: Provides BT Mesh Firmware Update Client functionality, defined in mesh specification.
-
Firmware Update Server: Provides BT Mesh Firmware Update Server functionality, defined in mesh specification.
-
Firmware Distribution Server: Provides BT Mesh Firmware Distribution Server functionality, defined in mesh specification.
-
Remote Provisioning: Used to support remote provisioning client functionality of provisioning devices into a mesh network by
interacting with a mesh node that supports the Remote Provisioning Server model. -
Remote Provisioning Server: Used to support remote provisioning server functionality of provisioning a remote device over the mesh network and to perform the Node Provisioning Protocol Interface procedures.
-
DFU updating node: Wrapper software component for DFU updating node role in Bluetooth Mesh applications.
New Documents
- QSG183: Bluetooth Mesh SDK Quick-Start Guide for SDK v4.x · AN1319: Bluetooth Mesh Device Firmware Update
- AN1370: Bluetooth Mesh Device Firmware Update Example Walkthrough
- AN1368: Bluetooth Mesh Remote Provisioning
- AN1405: Bluetooth Mesh on Advertising Extensions
Added in release 3.0.0.0
New Development Tools
More user-friendly filtering for Software Examples in Simplicity Studio.
New Hardware Support
Support was added for xGM240P PCB Modules and BG22/BGM220 Explorer Kits.
1.2 New APIs
Added in release 4.2.0.0
Test API has been ameded with a new call, sl_btmesh_test_send_private_beacons,
that can be used for sending private network beacons for testing purposes.
Test API has been amended with a new call,
sl_btmesh_test_adv_use_random_address, that can be used for setting the type
of Bluetooth address used for Mesh advertising.
Added in release 4.1.0-prev
Test API has been ameded with a new call,
sl_btmesh_test_update_key_refresh_phase that can be used for testing various
key refresh phases locally without a configuration client.
Added in release 4.0.0-prev
Bluetooth mesh over AE adds client and server vendor models using Silicon Labs
vendor messages for over-the-air configuration of the feature, as well as the
corresponding BGAPI classes sl_btmesh_silabs_config_client and
sl_btmesh_silabs_config_server.
Node API has been amended with multiple additions:
-
APIs for saving the proxy solicitation RPL state, and for examining whether saving the RPL is needed, have been added
(sl_btmesh_node_save_proxy_solicitation_rpl, and sl_btmesh_node_get_proxy_solicitation_rpl_status). -
APIs for reading and writing unprovisioned device URI data to persistent storage have been added (sl_btmesh_node_set_oob_uri,and sl_btmesh_node_get_oob_uri).
-
An API for locally accessing the Models Metadata page, sl_btmesh_node_get_local_model_metadata_page, and the correspond-ing events, sl_btmesh_node_local_model_metadata_page and sl_btmesh_node_local_model_metadata_page_end.
Provisioner’s control over the key refresh procedure has been improved by
additional APIs, sl_btmesh_prov_set_key_refresh_failure,
sl_btmesh_prov_phase_timeout_get, and sl_btmesh_prov_phase_timeout_set. Also,
the Provisioner can now specify the amount of parallel key refresh
configuration requests by setting the configuration variable
SL_BTMESH_CONFIG_LIMIT_PROV_CONCURRENT_KR. Note that the value should be less
than or equal to the overall number of parallel configuration client requests.
Configuration client’s control over configuration requests has been improved
by an additional API sl_btmesh_config_client_set_request_timeout_for_node, and
an event sl_btmesh_config_client_obo_ack_received, which is generated when a
friend node acknowledges a transport message that has an LPN as the
destination.
Health client model API has been amended with explicit initialization and
deinitialization, so that health client model code will be pulled into a
project only when it is needed: sl_btmesh_health_client_init and
sl_btmesh_health_client_deinit.
Test command for adjusting PB-ADV timing paramerers has been provided as
sl_btmesh_test_set_adv_provisioning_bearer_timing. Note that the default
timing values are those that the specification defines; timings should be
adjusted only for debugging purposes.
Added in release 3.0.0-prev
Multiple new BGAPI classes have been added to support the Mesh 1.1
specification release new features. For the details of the added classes
please see the API reference; the additions are summarized below.
Support for Mesh binary large object transfer adds BGAPI classes for MBT
client model and MBT server model.
Support for Mesh device firmware update adds BGAPI classes for firmware update
client model, firmware update server model, firmware distribution client
model, firmware distribution server model, and firmware standalone updater
model, as well as a supporting BGAPI class for device firmware image cache
manipulation.
Support for Mesh 1.1 remote provisioning adds BGAPI classes for remote
provisioning client model and remote provisioning server model.
Support for Mesh 1.1 private beacons adds BGAPI classes for private beacon
client model and private beacon server model.
Support for Mesh 1.1 minor enhancements adds BGAPI classes for SAR
configuration client model, SAR configuration server model, large composition
data client model, large composition data server model, on-demand private
proxy client model, on-demand private proxy server model, and solicitation PDU
RPL configuration client model.
Furthermore, existing BGAPI classes have been amended as listed below.
Mesh 1.1 enhanced provisioning algorithm support adds one command to node
BGAPI, sl_btmesh_node_set_provisioning_algorithm(), and defines flag
enumeration values for both Mesh 1.0 and 1.1 provisioning algorithms.
Mesh 1.1 certificate-based provisioning support adds one command to node
BGAPI, sl_btmesh_node_init_provisioning_records(), and three commands as well
as two events to provisioner BGAPI:
sl_btmesh_prov_init_provisioning_records(),
sl_btmesh_prov_get_provisioning_records_list(),
sl_btmesh_prov_get_provisioning_record_data(),
sl_btmesh_provisioning_records_list(), and
sl_btmesh_provisioning_record_data().
Support for the Node Provisioning Protocol Interface procedures adds two
events to the node BGAPI, sl_btmesh_node_address_updated() and
sl_btmesh_node_dcd_updated().
Proxy solicitation support adds one new BGAPI command to the proxy BGAPI:
sl_btmesh_proxy_send_solicitation().
New BGAPI commands have been added to the test BGAPI to support private beacon
testing: sl_btmesh_test_get_private_identity() and
sl_btmesh_test_set_private_identity().
2 Improvements
The supported complier versions have been updated. GCC version 10.3-2021.10 and IAR version 9.20.4 are now supported. The flash footprint of the mesh stack implementation has been reduced by optimization of structures and removal of unnecessary dependencies between components. Exact reduction depends on the features used by the project.
3 Fixed Issues
4 Known Issues in the Current Release
Issues in bold were added since the previous release.
5 Deprecated Items
None
6 Removed Items
Removed in release 3.0.0.0
The deprecated BGAPI command sl_btmesh_node_erase_mesh_nvm() has been removed.
Use sl_btmesh_node_reset() instead.
7 Using This Release
This release contains the following
- Silicon Labs Bluetooth mesh stack library
- Bluetooth mesh sample applications
If you are a first time user, see QSG176: Silicon Labs Bluetooth Mesh SDK v2.x Quick-Start Guide.
7.1 Installation and Use
The Bluetooth mesh SDK is provided as part of the Gecko SDK (GSDK), the suite of Silicon Labs SDKs. To quickly get started with the GSDK, install Simplicity Studio 5, which will set up your development environment and walk you through GSDK installation. Simplicity Studio 5 includes everything needed for IoT product development with Silicon Labs devices, including a resource and project launcher, software configuration tools, full IDE with GNU toolchain, and analysis tools. Installation instructions are provided in the online Simplicity Studio 5 User’s Guide.
Alternatively, Gecko SDK may be installed manually by downloading or cloning
the latest from GitHub. See https://github.com/SiliconLabs/gecko_sdk for
more information.
The GSDK default install location has changed with Simplicity Studio 5.3 and
higher.
- Windows: C:Users
SimplicityStudioSDKsgecko_sdk - MacOS: /Users/
/SimplicityStudio/SDKs/gecko_sdk
Documentation specific to the SDK version is installed with the SDK. Additional information can often be found in the knowledge base articles (KBAs). API references and other information about this and earlier releases is available on https://docs.silabs.com/.
7.2 Security Information
Secure Vault Integration
This version of the stack is integrated with Secure Vault Key Management. When
deployed to Secure Vault High devices, mesh encryption keys are protected
using the Secure Vault Key Management functionality. The table below shows the
protected keys and their storage protection characteristics.
Keys that are marked as “Non-Exportable” can be used but cannot be viewed or shared at runtime. Keys that are marked as “Exportable” can be used or shared at runtime but remain encrypted while stored in flash.
For more information on Secure Vault Key Management functionality, see AN1271: Secure Key Storage
Security Advisories
To subscribe to Security Advisories, log in to the Silicon Labs customer
portal, then select Account Home. Click HOME to go to the portal home page and
then click the Manage Notifications tile. Make sure that `Software/Security
Advisory Notices & Product Change Notices (PCNs)’ is checked, and that you are
subscribed at minimum for your platform and protocol. Click Save to save any
changes.
7.3 Support
Development Kit customers are eligible for training and technical support. Use
the Silicon Labs Bluetooth mesh web page to obtain
information about all Silicon Labs Bluetooth products and services, and to
sign up for product support.
Contact Silicon Laboratories support at http://www.silabs.com/support.
www.silabs.com/IoT
www.silabs.com/simplicity
www.silabs.com/quality
www.silabs.com/community
Disclaimer
Silicon Labs intends to provide customers with the latest, accurate, and in-
depth documentation of all peripherals and modules available for system and
software implementers using or intending to use the Silicon Labs products.
Characterization data, available modules and peripherals, memory sizes and
memory addresses refer to each specific device, and “Typical” parameters
provided can and do vary in different applications. Application examples
described herein are for illustrative purposes only. Silicon Labs reserves the
right to make changes without further notice to the product information,
specifications, and descriptions herein, and does not give warranties as to
the accuracy or completeness of the included information. Without prior
notification, Silicon Labs may update product firmware during the
manufacturing process for security or reliability reasons. Such changes will
not alter the specifications or the performance of the product. Silicon Labs
shall have no liability for the consequences of use of the information
supplied in this document. This document does not imply or expressly grant any
license to design or fabricate any integrated circuits. The products are not
designed or authorized to be used within any FDA Class III devices,
applications for which FDA premarket approval is required or Life Support
Systems without the specific written consent of Silicon Labs. A “Life Support
System” is any product or system intended to support or sustain life and/or
health, which, if it fails, can be reasonably expected to result in
significant personal injury or death. Silicon Labs products are not designed
or authorized for military applications. Silicon Labs products shall under no
circumstances be used in weapons of mass destruction including (but not
limited to) nuclear, biological or chemical weapons, or missiles capable of
delivering such weapons. Silicon Labs disclaims all express and implied
warranties and shall not be responsible or liable for any injuries or damages
related to use of a Silicon Labs product in such unauthorized applications.
Note: This content may contain offensive terminology that is now obsolete.
Silicon Labs is replacing these terms with inclusive language wherever
possible. For more information, visit www.silabs.com/about-us/inclusive-
lexicon-project
Trademark Information
Silicon Laboratories Inc.®, Silicon Laboratories®, Silicon Labs®, SiLabs® and
the Silicon Labs logo®, Bluegiga®, Bluegiga Logo®, EFM®, EFM32®, EFR, Ember®,
Energy Micro, Energy Micro logo and combinations thereof, “the world’s most
energy friendly microcontrollers”, Redpine Signals®, WiSeConnect , n-Link,
ThreadArch®, EZLink®, EZRadio®, EZRadioPRO®, Gecko®, Gecko OS, Gecko OS
Studio, Precision32®, Simplicity Studio®, Telegesis, the Telegesis Logo®,
USBXpress® , Zentri, the Zentri logo and Zentri DMS, Z-Wave®, and others are
trademarks or registered trademarks of Silicon Labs. ARM, CORTEX, Cortex-M3
and THUMB are trademarks or registered trademarks of ARM Holdings. Keil is a
registered trademark of ARM Limited. Wi-Fi is a registered trademark of the
Wi-Fi Alliance. All other products or brand names mentioned herein are
trademarks of their respective holders.
Silicon Laboratories Inc. 400 West Cesar Chavez Austin, TX 78701 USA
www.silabs.com
References
- Silicon Labs
- Silicon Labs
- About Us - Silicon Labs
- Silicon Labs Community
- Internet of Things (IoT) - Silicon Labs
- Simplicity Studio - Silicon Labs
- Technical Support - Silicon Labs