SILICON LABS Bluetooth LE SDK 5.0.0.0 GA Bluetooth Low Energy (LE) Software Instructions

SILICON LABS Bluetooth LE SDK 5.0.0.0 GA Bluetooth Low Energy (LE)

Software

Silicon Labs is a leading vendor in Bluetooth hardware and software technologies, used in products such as sports and fitness, consumer electronics, beacons, and smart home applications. The core SDK is an advanced Bluetooth 5.3 compliant stack that provides all of the core functionality along with multiple API to simplify development. The core functionality offers both standalone mode allowing a developer to create and run their application directly on the SoC, or in NCP mode allowing for the use of an external host MCU.
These release notes cover SDK version(s):
5.0.0.0 GA released December 14, 2022

KEY FEATURES

Bluetooth

• External bonding database to support infinite number of bondings and key sharing

• BGAPI event for Bluetooth buffer exhaustion signaling

• Active scan improvements

• Three-Wire UART (H5) Transport Layer for HCI (experimental)

• Certification-Based Authentication and pairing for High- and Mid-Vault devices(experimental)
  Multiprotocol

• Dynamic Multiprotocol Bluetooth and multi-PAN 802.15.4 in RCP mode

• BLE de-init and re-init for multiprotocol use cases

• Dynamic Multiprotocol Bluetooth andZigbee NCP – experimental

Compatibility and Use Notices
For information about security updates and notices, see the Security chapter of the Gecko Platform Release notes installed with this SDK or on the TECH DOCS tab on https://www.silabs.com/developers/bluetooth-low-energy. Silicon Labs also strongly recommends that you subscribe to Security Advisories for up-to-date information. For instructions as well as notes on using Secure Vault features, or if you are new to the Silicon Labs Bluetooth SDK, see Using This Release.

Compatible Compilers:
IAR Embedded Workbench for ARM (IAR-EWARM) version 9.20.4.

• Usingwine 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.

New Items

New Features
Added in release 5.0.0.0

External bonding database
The external bonding database is provided in this release as an optional feature component. When the feature is used, the application stores the persistent data of Bluetooth bondings. The Bluetooth stack sends BGAPI events to the application to store bonding data and to request the application to pass bonding data when needed.

Three-Wire UART transport layer support
Three-Wire UART transport layer support for HCI is available in this release.

Per-PHY Power Limit Configuration
A new per-PHY power limit configuration is available for specifying the maximum output power when TX power is limited by power spectral density.

New AFH configuration for enabling high power
New SL_BT_CONFIG_AFH_ENABLE_HIGH_POWER configuration option is added to the bluetooth_feature_afh component. Customers who want the device to behave as FHS, that is to use high power, in regions where AFH is not mandatory can enable this option only, and disable the SL_BT_CONFIG_AFH_ENABLE_AT_BOOT configuration.

New configurations in Bluetooth Controller
The Bluetooth Controller component has two new configurations:

• SL_BT_CONTROLLER_COMPLETED_PACKETS_THRESHOLD for defining the number of transmitted air interface ACL packets to trigger the Number Of Completed Packets HCI event
• SL_BT_CONTROLLER_COMPLETED_PACKETS_EVENTS_TIMEOUT for defining the maximum number of connection events since the previous Number Of Completed Packets HCI event to trigger reporting of any unreported completed ACL packets.

Read Version over HCI
UC component bt_hci_version is added for HCI vendor-specific read version command.
MQTT mock component
MQTT mock component is available for the bt_aoa_host_locator example application for testing purposes.
AoD receiver NCP example
The AoD receiver NCP example is available for Simplicity Studio Direction Finding tools.
Object Transfer Service
The Object Transfer Service (OTS) is available for applications to use the object transfer feature.
CTE transmitter SoC example
The CTE transmitter SoC example for Angle of Departure (AoD)
New Applications for TrustZone-compatible devices bt_soc_csr_generator and bt_soc_cbap applications are now available for all TrustZone-compatible devices.

New APIs
Added in release 5.0.0.0
sl_bt_gap_set_identity_address command : Set the Bluetooth identity address for central and peripheral roles.
sl_bt_external_bondingdb_set_data command: Pass bonding data of a connection from the external bonding database to the stack.
sl_bt_evt_external_bondingdb_data_request event: The Bluetooth stack requests the bonding data of a connection from the external bonding database.
sl_bt_evt_external_bondingdb_data event: Indicates that updated bonding data of a connection is available.
sl_bt_evt_external_bondingdb_data_ready event: The stack has received all the necessary bonding data from the application.
sl_bt_evt_system_resource_exhausted event: Indicates the system is running out of resources during the use of the Bluetooth stack.
New flag in sl_bt_system_linklayer_configure command: A new configuration flag is added for enabling reporting all SCA_RSP pack-ets even if those are not the responses to the scan request initiated by the local device.
New version constants in header sl_bt_version.h: SL_BT_VERSION_MAJOR, SL_BT _VERSION_MINOR, SL_BT _VERSION_PATCH, SL_BT_VERSION_BUILD, and SL_BT _VERSION_HASH
VS_SiliconLabs_Set_Max_Low_Tx_Power (0xfc1b): New vendor-specific HCI command for the per-PHY power limit configuration feature.

Improvements

Changed Items
Changed in release 5.0.0.0
Stack behavioral change in case of external bonding database

Following functionality or API behavioral changes when the external bonding database feature is used:

• sl_bt_store_bonding_configuration command must be called to define the list size before adding devices to the accept list.
• The sl_bt_get_bonding_handles, sl_bt_get_bonding_details, and find_bonding_by_address commands are unavailable.

Bluetooth RTOS adaptation
The Bluetooth RTOS adaptation (bluetooth_rtos_adaptation) kernel object uses dynamic memory allocation for improving adaptability, beginning with this release. The heap usage in applications using this component is increased by roughly 4900 bytes as a result of this change.

Bluetooth API for NCP host
The host-side NCP Bluetooth API in sl_bt_ncp_host.c now accepts NULL pointers to output parameters. If an application does not need an output value that is merely informational, the application can pass a NULL pointer to that output parameter and avoid allocating storage for the output.
bootloader-apploader
The bootloader-apploader component can be used for both bt_soc_csr_generator and bt_soc_cbap. Previously, the boot-loader_bgapi_uart_bootloader was used with bt_soc_csr_generator.

bt_soc_throughput_display example app
The bt_soc_throughput_display example app is no longer supported on BRD4169x boards.

Changed APIs
None

Fixed Issues

Fixed in release 5.0.0.0

always return 0 for GRANT denied counts when using the rail_util_coex component with Bluetooth.
1020072| Fix the issue where the coex REQUEST is held asserted for a longer duration than normal when a connection event pre-empts a lower-priority passive scan event that is at or near completion.
1039172| Fix multiple HCI packet handling in CPC-HCI bridge that causes a GATT discovery failure.
1039636| Fix an issue in the Bluetooth controller that overrides the low-power amplifier configuration to the high-power amplifier if the application selects the low-power amplifier. This issue causes an increase in transmission current. The fix is available since the Bluetooth SDK 4.2.0.0.
1040323| The mandatory ADI field has been added to the AUX_ADV_IND PDUs.
1042501| Fix an issue in AppLoader causing using static random address in Series-2 devices to fail.
1043031| Fix an issue with RAIL’s PA auto mode that would result in selecting an unsupported RAIL_TxPowerMode_t on chip OPNs that are missing the higher power PAs.
1057377| Fix an issue that the Apploader hits an assertion causing the OTA DFU to be unable to proceed on [M|B]GM240P modules.
1057775| Add BGM240P/BGM240S support in Bluetooth sample applications.
1058017| Fix for the bt_aoa_host_locator example to use less CPU on the host side.
1060118

1067617

| Fix an issue that causes efr32[M|B]g24 devices to stop sending Bluetooth packets properly after several hours of operation.
1063497| Fix an issue in the bt_ncp_host that it is unable to send data to the device. This issue was introduced in Bluetooth SDK 4.2.0.
1067967| Fix an issue that causes sl_bt_evt_sync_opened and sl_bt_evt_sync_transfer_received events to report a wrong adv_phy value if the periodic advertising train uses the coded PHY.
1068798| Fix an issue that causes sl_bt_connection_get_tx_power() and sl_bt_connection_get_remote_tx_power() to return an error when they are called with phy value sl_bt_gap_phy_coding_500k_coded.
1069081| Fix the vendor specific deinit command not working properly when called over HCI.
1069305| The stack now adds the device name to scan response data packet as needed when handling the command sl_bt_legacy_advertiser_generate_data() for generating advertising data for legacy advertising PDUs.
1069609| Fix an issue that makes it impossible to set scan parameters via command sl_bt_cmd_scanner_set_parameters() when the component bluetooth_feature_scanner is used, but neither the bluetooth_feature_legacy_scanner nor bluetooth_feature_extended_scanner is.
1078436| Fix the issue in Bluetooth SDK versions 4.0.0, 4.1.0, 4.2.0, and 4.2.1, where devices previously bonded with using Bluetooth SDK versions 3.3.2 or earlier appear to be not bonded.

Known Issues in the Current Release

Issues in bold were added since the previous release. If you have missed a release, recent release notes are available on https://www.si- labs.com/developers/bluetooth-low-energy in the Tech Docs tab.

368403

| If setting CTE interval to 1, a CTE request should be sent in every connection interval. But it is sent only in every second connection interval.|

None

641122

|

The Bluetooth stack component does not provide a configuration for RF antenna path.

| This is an issue specifically for BGM210P. One workaround is to manually update the configuration in sl_bluetooth_config.h in text edit mode.

If the OTA with Apploader is used, include the bluetooth_feature_ota_config component in application project. Call command sl_bt_ota_set_rf_path() to set the RF path for OTA mode.

650079

|

LE 2M PHY on EFR32[B|M]G12 and EFR32[B|M]G13 doesn’t

work with smartphones using the Mediatek Helio chip due to an interoperability issue.

| No workaround exists. For application development and testing, the disconnection can be avoided by disabling 2M PHY with sl_bt_connection_set_preferred_phy() or sl_bt_connection_set_default_preferred_phy().

682198

|

The Bluetooth stack has an interoperability issue on the 2M PHY with a Windows PC.

| No workaround exists. For application development and testing, the disconnection can be avoided by disabling 2M PHY with sl_bt_connection_set_preferred_phy() or sl_bt_connection_set_default_preferred_phy().

730692

| 4-7% packet error rate is observed on EFR32M|BG13 devices when RSSI is between -25 and -10 dBm. The PER is nominal (as per the datasheet) both above and below this range.|

None

756253

| The RSSI value on a Bluetooth connection returned by the Bluetooth API is incorrect on EFR32M|B1, EFR32M|B12, EFR32M|B13, and EFR32M|B21 devices. On EFR32M|B21 devices. It is about 8~10 dBm higher than the actual value, according to a measurement.| Install the “RAIL Utility, RSSI” component in the application project. This component provides a default RSSI offset for the chip that is applied at the RAIL level and can help to achieve more accurate RSSI measurements.

845506

|

When the Bluetooth_feature_afh component for AFH is included, the feature initialization always enables AFH.

| To include the component but not to enable AFH at device boot, change the parameter value from 1 to 0 in the function call of sl_btctrl_init_afh() in sl_bt_stack_init.c.
1031031| Changing the configuration in the bt_aoa_host_locator application results in crash in the application.| None

Deprecated Items

Deprecated in release 5.0.0.0
sl_bt_scanner_set_mode
sl_bt_scanner_set_timing

Deprecated version constants in sl_bt_version.h

• BG_VERSION_MAJOR, replaced by SL_BT_VERSION_MAJOR
• BG_VERSION_MINOR, replaced by SLBT VERSION_MINOR
• BG_VERSION_PATCH, replaced by SLBT VERSION_PATCH
• BG_VERSION_BUILD, replaced by SLBT VERSION_BUILD
• BG_VERSION_HASH, replaced by SLBT VERSION_HASH

Removed Items
Removed from release 5.0.0.0
BGAPI command sl_bt_dfu_reset

Multiprotocol Gateway and RCP)

New Items

Added in release 5.0.0.0
Added Dynamic Multiprotocol BLE and Zigbee NCP project (zigbee_ncp-ble_ncp- xxx.slcp). Released as experimental quality.
Added 802.15.4 concurrent listening for EFR32MG24 CMP RCP. This is the ability to run Zigbee and OpenThread simultaneously on different channels using a single RCP (rcp-802154-xxx.slcp and rcp-802154-blehci-xxx.slcp). Released as experimental quality.
Added zigbeed support for 32-bit x86 architecture.
Added support for BLE to de-init in multiprotocol use cases, freeing up memory resources for use by other protocol stacks.
The Stack API Trace now can be enabled for zigbeed by setting the debug-level to 4 or 5 in the zigbeed.conf file.
Zigbeed stack version as well as build date and time are now printed in the logs.

Improvements
None

Fixed Issues
Fixed in release 5.0.0.0

if BlueZ sent two at once.
834191| Improved the CPU utilization of the cpc-hci-bridge helper application.
1025713| Increased max length of zigbeed device path to 4096.
1036622| Fixed a problem using cmake to build ot-cli using the multipan RCP.
1040127| CPC security was failing to initialize for the rcp-uart-802154 and rcp-spi-802154 projects on mg13 and mg14 series parts. To work around this issue, mbedtls_entropy_adc has been added as entropy source for these parts. That might prevent the ADC from being used in combination with CPC security.
1066422| Fixed an intermittent buffer leak in zigbeed.
1068429| Fixed a race condition that could cause the CMP RCP to assert.
1068435| Added capability on the RCP node to check and buffer a single bidirectional Green Power data frame and send it out upon rx offset timeout.
1068942| Fixed a leak in the RCP source match table that could prevent Zigbee devices from joining.
1074172| Fixed sending leave request from zigbeed when receiving a poll from a non-child.
1074290| Stopped zigbeed from processing un-acked polls.
1079903| Fixed a bug in the CMP RCP that could cause SPINEL messages to be dispatched incorrectly, resulting in Zigbeed and OTBR crashing or exiting.

Known Issues in the Current Release
Issues in bold were added since the previous release. If you have missed a release, recent release notes are available on https://www.si- labs.com/developers/gecko-software-development-kit.

planned in a future release.
ID #| Description| Workaround
---|---|---
937562| Bluetoothctl ‘advertise on’ command fails with rcp-uart- 802154-blehci app on Raspberry Pi OS 11.| Use btmgmt app instead of bluetoothctl.

1031607

| The rcp-uart-802154.slcp project is running low on RAM on an MG1 part. Adding components may reduce the heap size below what is needed to support ECDH binding in CPC.|

A workaround is to disable CPC security via the SL_CPC_SECURITY_ENABLED configuration.

1032183| Zigbeed does not support EZSP coex commands.| Support is planned in a future release.
1036645| BGAPI host app cannot connect to multiprotocol NCP via CPC after a reset.| Reset CPCd or the NCP. This will be fixed in the next patch release.

1076235

| ot-cli does not run in the multiprotocol docker container due to a library version mismatch.| The issue can be worked around using the following shell commands: ‘./run.sh -o; cd /lib/arm-linux- gnueabihf; ln -s libreadline.so libreadline.so.7’
1074205| The CMP RCP does not support two networks on the same PAN id.| Use different PAN ids for each network. Support is planned in a future release.
1080517| Z3GatewayCPC does not currently automatically handle a reset of the NCP (CPC secondary).| Restart the Z3GatewayCPC process after the NCP has been reset.

Deprecated Items
None

Removed Items
None

Using This Release

This release contains the following

• Silicon Labs Bluetooth stack library
• Bluetooth sample applications

For more information about the Bluetooth SDK see QSG169: Bluetooth® SDK v3.x Quick Start Guide. If you are new to Bluetooth see UG103.14: Bluetooth LE Fundamentals.

Installation and Use
The Bluetooth 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/Sili-conLabs/gecko_sdk for more information.

Simplicity Studio installs the GSDK by default in:

• (Windows): C:\Users\\SimplicityStudio\SDKs\gecko_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/.

Security Information
Secure Vault Integration
When deployed to Secure Vault High devices, sensitive keys such as the Long Term Key (LTK) are protected using the Secure Vault Key Management functionality. The table below shows the protected keys and their storage protection characteristics.

compatibility reasons
Local Identity Resolving Key| Exportable| Must be Exportable because the key is shared with other devices.

Wrapped keys that are marked as “Non-Exportable” can be used but cannot be viewed or shared at runtime.
Wrapped 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.

Support
Development Kit customers are eligible for training and technical support. Use the Silicon Labs Bluetooth LE web page to obtain information about all Silicon Labs Bluetooth products and services, and to sign up for product support.
You can contact Silicon Laboratories support at http://www.silabs.com/support.

Simplicity Studio
One-click access to MCU and wireless tools, documentation, software, source code libraries & more. Available for Windows, Mac and Linux!

IoT Portfolio
www.silabs.com/IoT

SW/HW
www.silabs.com/simplicity

Quality
www.silabs.com/quality

Support & Community
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

• introvert.com
• 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
• Bluetooth Low Energy (LE) Software Development Kit - Silicon Labs

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>