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

qualification table

[*] 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.

BGAPI table

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.


The following libraries are delivered with the Bluetooth SDK and must be included in C application projects.

library table 1

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.

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

Studio Launcher

Software Example Descriptions

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