General Overview#
About the Bluetooth Stack#
The Silicon Labs Bluetooth stack is an advanced Bluetooth 5-compliant protocol stack implementing the Bluetooth low energy standard. It supports multiple connections, concurrent central, peripheral, broadcaster, and observer roles. The Silicon Labs Bluetooth stack is meant for Silicon Labs Wireless Gecko SoCs and modules.
The Silicon Labs Bluetooth stack provides multiple APIs for the developer to access the Bluetooth functionality. Two modes are supported:
Standalone mode, where both the Bluetooth stack and the application run in a Wireless Geckos SoC or module. The application can be developed with C programming language.
Network Co-Processor (NCP) mode, where the Bluetooth stack runs in a Wireless Gecko and the application runs on a separate host MCU. For this use case, the Bluetooth stack can be configured into NCP mode where the API is exposed over a serial interface such as UART.
Bluetooth Stack Features#
The features of the Silicon Labs Bluetooth stack are listed in the following table.
Bluetooth Qualification#
All products deploying Bluetooth technology must go through the Bluetooth SIG's Qualification Process. There are online resources to learn more about the Bluetooth Qualification Process as well as tutorials on the Launch Studio, which is the online tool used to complete the Bluetooth Qualification Process. If you need assistance to qualify your device you can consider reaching out to your nearest Bluetooth Qualification Consultant.
When qualifying your end-product based on Silicon Labs’ Bluetooth stack you will integrate the pre-qualified components listed in the table below, depending on which SDK version was used to build your application.
[*] Note: For end-product qualifications based on this component, because of the Erratum 10734 you must also check the items 21/17 and 34/13 in the "Summary ICS" and upload the test evidence and a declaration, which can be requested through the support portal.
The above software-based pre-qualified components are two out of the three components to integrate when proceeding with the "Qualification Process with Required Testing". Despite the “Required Testing", customers do not need to do any additional testing, given that the test reports are embedded in the pre-qualified components for the SIG to review.
In addition to these two software components you must also have integrated a qualified RF-PHY component in your end-product listing. If you are designing with one of Silicon Labs’ Bluetooth modules then refer to the module datasheet for the appropriate component QDID to use. If you are designing with an SoC then you may need to obtain your own RF-PHY qualification with the Bluetooth SIG depending on your hardware design. In the latter case, please consult your nearest Bluetooth Qualification Consultant or Silicon Labs through the support portal, to understand if an existing Silicon Labs RF-PHY pre-qualification could be used.
The Bluetooth Stack APIs#
This section briefly describes the different software APIs available for the developer.
The BGAPI Bluetooth API#
The BGAPI is the Bluetooth API provided by the Silicon Labs Bluetooth stack. It provides access to all the Bluetooth functionality implemented by the Bluetooth stack, such as: the Generic Access Profile (GAP), connection manager, the security manager (SM), and GATT client and server.
In addition to the Bluetooth APIs, the BGAPI also provides access to a few other functions like the Direct Test Mode (DTM) API for RF testing purposes, the Persistent Store (PS) API for reading and writing keys to and from the devices flash memory, the DFU (Device Firmware Update) API for field firmware updates, and the System API for various system level functions
CMSIS and emlib#
The Cortex Microcontroller Software Interface Standard (CMSIS) is a common coding standard for all ARM Cortex devices. The CMSIS library provided by Silicon Labs contains header files, defines (for peripherals, registers and bitfields), and startup files for all devices. In addition, CMSIS includes functions that are common to all Cortex devices, like interrupt handling, intrinsic functions, etc. Although it is possible to write to registers using hard-coded address and data values, it is recommended to use the defines to ensure portability and readability of the code.
To simplify programming Wireless Geckos, Silicon Labs developed and maintains a complete C function library called emlib that provides efficient, clear, and robust access to and control of all peripherals and core functions in the device. This library resides within the em_xxx.c (for example, em_dac.c) and em_xxx.h files in the SDK. The emlib documentation is available on the Silicon Labs’ website.
The BGAPI Serial Protocol and BGLIB Host API#
When configured in NCP (network co-processor) mode, the Bluetooth stack also implements the BGAPI serial protocol. This allows the Bluetooth stack to be controlled over a serial interface such as UART from a separate host like an EFM32 microcontroller. The BGAPI serial protocol provides exactly the same Bluetooth APIs over UART as the BGAPI API when used in a standalone mode.
The BGAPI serial protocol is a lightweight, binary protocol that carries the BGAPI commands from the host to the Bluetooth stack and responses and events from the Bluetooth stack back to the host.
The Bluetooth SDK delivers a ready-made BGAPI serial protocol parser implementation, called BGLIB. It implements the serial protocol parser and C language function and events for all the APIs provided by the Bluetooth stack. The host code developed on top of BGLIB can be written to be identical to the code for the Wireless Gecko, which allows easy porting of the application code from the Wireless Gecko to a separate host or vice versa.
The BGAPI serial protocol packet structure is described below.
The Bluetooth Profile Toolkit GATT Builder#
The Bluetooth Profile Toolkit is a simple XML-based API and description language used to describe the GATT-based service and characteristic easily without the need to write them in code. The XML files can be easily written by hand based on the information contained in UG118: Blue Gecko Bluetooth® Profile Toolkit Developer Guide. Use the Profile Toolkit GATT Builder if you are developing outside of Simplicity Studio.
Within Simplicity Studio, we provide the GATT Configurator, a tool that allows building the GATT in a visual way, without hand editing the XML file. See UG365: GATT Configurator User’s Guide for details.
The GATT database developed with the Profile Toolkit is converted to a .c file and a .h file and included in the application project as a pre-build step when the firmware is compiled. Then the GATT can be accessed with the Bluetooth stack GATT APIs or by a remote Bluetooth device.
About the Bluetooth SDK#
The Bluetooth SDK is a full software development kit that enables you to develop applications on top of the Bluetooth stack using C programming language. The SDK also supports making standalone applications, where the Bluetooth stack and the application both run in the Wireless Gecko, or the network co-processor (NCP) architecture, where the application runs on an external host and the Bluetooth stack runs in the Wireless Gecko. SDK contents and folder structure are described in the following sections.
Libraries#
The following libraries are delivered with the Bluetooth SDK and must be included in C application projects.
Include files#
The following files are delivered with the Bluetooth SDK and must be included in C application projects.
Platform Components#
The following components are delivered with the Bluetooth SDK. The platform components are under the platform folder.
About Demos and Examples#
Because starting application development from scratch is difficult, the Bluetooth SDK comes with a number of built-in demos and examples covering the most frequent use cases, as shown in the following figure. Demos are pre-built application images that you can run immediately. Software examples can be modified before building the application image. Demos with the same name as software examples are built from their respective example.
Note: The demos and examples you see are determined by the part selected. If you are using a custom solution with more than one part, click on the part you are working with to see only the items applicable to that part.
To download and run a demo on your device, click the demo. In the Mode drop-down in the next dialog, select Run. Click Start.
To import software example code into your workspace as a new project using default project configurations, click the name of the example to open the Simplicity Studio IDE. To build the example project click Debug
If an example project closely matches your needs, you need only extend the code with your application code, and rewrite only what must be customized for your needs. Otherwise you should start with the SOC-Empty application. Note that the ‘SOC-Empty’ application is not blank, but rather provides a minimal project that only starts advertising
Software Example Descriptions#
The following examples are provided. Examples with (*) in their names have a matching pre-built demo.
Silicon Labs Gecko Bootloader examples (see UG266: Silicon Labs Gecko Bootloader User Guide and AN1086: Using the Gecko Bootloader with Silicon Labs Bluetooth Applications)
Bluetooth Examples
Bluetooth (NCP)
NCP – Host: NCP (Network co-processor) Host example that connects to an NCP target via USART. It demonstrates the usage of BGLib with or without USART flow-control. This example does not have a Bluetooth function over the radio as it uses the EFR32 only as a host device.
NCP target – Empty(*): Network co-processor target application with a minimal GATT database. Use this as a starting point to create an NCP firmware. An NCP device can be controlled from another (host) device or directly from your PC with BGTool. This example together with BG Tool provides an easy way to get started and also debug your application by issuing commands to the stack step-by-step.
Bluetooth (SOC - Basic):
SOC – Empty(*): A minimal project structure, used as a starting point for custom applications. The project has the basic functionality enabling peripheral connectivity and contains a minimal GATT database that can be expanded to fit your application requirements.
SOC – iBeacon(*): An iBeacon device implementation that sends non-connectible advertisements in iBeacon format. The iBeacon Service gives Bluetooth accessories a simple and convenient way to send iBeacons to iOS devices. This example demonstrates the power consumption at 0 dBm TX power.
SOC – Thermometer – Client: Implements a Client that discovers and connects up to 4 BLE devices advertising themselves as Thermometer Servers. It displays the discovery process and the temperature values received via UART.
SOC – Thermometer(*): Implements the Thermometer (GATT Server) Role of the Health Thermometer Profile, which enables a Collector device to connect and interact with a Thermometer.
Note: Some radio boards will exhibit random pixels in in the display when this example is running because they have a shared pin for sensor and display enable signals.
Bluetooth (Advanced):
SOC – DTM: Used to run Bluetooth DTM (direct test mode) tests for radio testing. See AN1046: Bluetooth® Radio Frequency Physical Layer Evaluation for more information.
SOC – Thermometer - RTOS: The SOC - Thermometer example based on Micrium RTOS.
Thunderboard
SOC - Thunderboard React, - Thunderboard Sense, and - Thunderboard Sense 2(*): Examples used to show the applicable Thunderboard features.
SOC - Voice over Bluetooth Low Energy: Demonstrates how voice capture can be sent over a Bluetooth Low Energy Link.
Dynamic Multiprotocol Examples (see [AN1134: Dynamic Multiprotocol Development with Bluetooth and Proprietary Protocols on RAIL](https://www.silabs.com/documents/public/application-notes/an1134-bluetooth-rail-dynamic-multiprotocol.pdf) for more information)
SOC - Empty - RAIL – DMP(*): A minimal project structure, used as a starting point for custom Dynamic Multiprotocol applications. The project has the basic functionality enabling peripheral connectivity, without GATT services. It runs on top of Micrium OS RTOS and multiprotocol RAIL.
SOC - Light - RAIL – DMP(*): Implements the Light (GATT Server) Role, which enables a Switch device to connect to and interact with it. The device acts as a connection Peripheral. This is a Dynamic Multiprotocol reference application, running on top of Micrium OS RTOS and multiprotocol RAIL. To learn how to test this demo see QSG155: Using the Silicon Labs Dynamic Multiprotocol Demonstration Applications.
SOC - Range Test - RAIL - DMP(*): Range Test with Bluetooth connectivity. It runs on top of Micrium OS RTOS and multiprotocol RAIL.
NCP Host Examples located in C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite<version>\app\bluetooth\examples_ncp_host
Empty: Minimal host-side project structure, used as a starting point for NCP host applications.
ota-dfu: Demonstrates how to perform a OTA DFU on a Silicon Labs Bluetooth Device. It requires a WSTK with a radio board flashed with an NCP firmware to be used as the GATT client that performs the OTA.
uart-dfu: Demonstrates how to perform a UART DFU on a Silicon Labs Bluetooth Device running NCP firmware.
Voice over Bluetooth Low Energy: Client-side application that couples with the “SOC – Voice over Bluetooth Low Energy” for the Thunderboard Sense kit. It requires a WSTK with a radio board flashed with an NCP firmware.