General Overview

Release Notes | Downloads

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:

  1. 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.

Stack Figure Wireless Gecko

  1. 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.

Stack Figure Wireless Gecko

Bluetooth Stack Features

The features of the Silicon Labs Bluetooth stack are listed in the following table.

Stack Features

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, 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. To learn more and see the list of pre-qualified components, see QSG169: Bluetooth® SDK v3.x Quick-Start Guide.

The Bluetooth Stack APIs

This section briefly describes the different software APIs.

The Bluetooth API

The Bluetooth API provided by the Silicon Labs Bluetooth stack is the primary API to communicate with the 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), GATT client and server.

In addition to the Bluetooth features, the Bluetooth API 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.

The BGAPI Serial Protocol and the Bluetooth Host API

When configured in NCP (network co-processor) mode, the Bluetooth stack can be controlled using 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 both for the NCP target (EFR) and for the NCP host. It implements the serial protocol parser for all the APIs provided by the Bluetooth stack. The host code developed on top of host API can be written to be identical to the code for the EFR, which allows easy porting of the application code from the EFR to a separate host or vice versa.

BGAPI

The BGAPI serial protocol packet structure is described below. For more information see the BGAPI Headers.

BGAPI table

The Bluetooth Profile Toolkit GATT Builder

The Bluetooth Profile Toolkit is an 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, the GATT Configurator allows building the GATT in a visual way without hand editing the XML file. See UG438: GATT Configurator User’s Guide for Bluetooth SDK v3.x for details. Open the GATT Configurator in Simplicity Studio through the Project Configurator, Software Components tab, under Advanced Configurators. Click Open and the GATT Configurator tool opens the file gatt_configuration.btconf in a new tab.

Opening Bluetooth GATT Configurator

gatt_configuration.btconf provides the trunk of the GATT database. It is located inside the config > btconfig directory of your project. You can add additional XML files in the same directory and extend the GATT database. The contents of the additional XML files will appear as Contributed Items in the GATT Configurator UI. See for example the ota-dfu.xml file provided with most sample applications.

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.

GATT XML

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, such as 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 develops 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 under the Gecko Platform documentation.

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 QSG169: Bluetooth® SDK v3.x Quick-Start Guide.

About Demos and Examples

Starting application development from scratch is difficult. For that reason, 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.

Demos and Software Example can be found under the Example Projects & Demos tab in the launcher view of Simplicity Studio.

If an example project closely matches your needs, extend the code with your application code and rewrite the custom sections. Otherwise, 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.

Studio Launcher

Demo/Example Descriptions

The following examples are provided. Examples with (*) in their names have a matching pre-built demo.