Silicon Labs UG434 User Manual
UG434: Silicon Labs Bluetooth ® C
Application Developer's Guide for
SDK v3.x
This document is an essential reference for everybody developing C-based applications for the Silicon Labs Wireless Gecko
products using the Silicon Labs Bluetooth stack. The guide covers the Bluetooth stack architecture, application development
flow, usage, and limitations of the MCU core and peripherals,
stack configuration options, and stack resource usage. This version applies to the Silicon Labs Bluetooth Software Development
Kit (SDK) version 3.0.x and higher.
The purpose of the document is to capture and fill in the blanks between the Bluetooth
Stack API reference, Gecko SDK API reference, and Wireless Gecko reference manuals, when developing Bluetooth applications for the Wireless Geckos. This document
exposes details that will help developers make the most out of the available hardware
resources.
KEY POINTS
• Project structure and development flow
• Bluetooth stack and Wireless Gecko
configuration
• Interrupt handling
• Event and sleep management
• Resource usage and available resources
silabs.com | Building a more connected world. Rev. 0.6
Table of Contents
1. Introduction ................................4
1.1 About this Version .............................4
1.2 Prerequisites ..............................4
2. Application Development Flow.........................5
2.1 Application Build Flow ...........................6
3. Project Structure ..............................7
3.1 Bluetooth Files ..............................7
3.2 GATT Database .............................9
3.3 Device Firmware Upgrade ..........................9
3.4 RTOS Support ..............................10
3.5 Multiprotocol Support ............................10
3.6 Platform Components ...........................10
4. Configuring the Bluetooth Stack and a Wireless Gecko Device ...........11
4.1 Wireless Gecko MCU and Peripherals Configuration .................11
4.1.1 Adaptive Frequency Hopping........................11
4.1.2 Bluetooth Clocks ............................12
4.1.3 DC-DC Configuration ..........................13
4.1.4 LNA ................................13
4.1.5 Periodic Advertising ...........................14
4.1.6 PTI ................................14
4.1.7 Transmit Power ............................14
4.1.8 Whitelisting..............................15
4.1.9 Wi-Fi coexistence ...........................15
4.1.10 OTA Configuration ...........................15
4.1.11 Even Connection Distribution Algorithm ....................16
4.2 Bluetooth Configuration with sl_bt_init_stack() ...................17
4.2.1 Bluetooth On-Demand Start ........................18
4.2.2 CONFIG_FLAGS............................18
4.2.3 Mbedtls ...............................18
4.2.4 Multiprotocol Priority Configuration ......................19
4.2.5 Sleep................................19
4.2.6 Bluetooth Stack Configuration .......................20
4.2.7 PA.................................20
4.2.8 Software Timers ............................21
4.2.9 RF Path ...............................21
4.2.10 NVM3 Error Codes...........................21
5. Bluetooth Stack Event Handling .......................22
5.1 Non-Blocking Event Listener .........................22
5.1.1 Notification for Updating Event Listener ....................22
5.2 Event Listener with RTOS ..........................23
silabs.com
| Building a more connected world. Rev. 0.6 | 2
5.2.1 Commands from Multiple Tasks .......................23
6. Interrupts ................................ 24
6.1 External Event ..............................24
6.2 Priorities ................................25
7. Wireless Gecko Resources .........................26
7.1 Flash .................................27
7.1.1 Optimizing Flash Usage .........................28
7.1.2 Bluetooth Bonding Database ........................28
7.2 Linking.................................29
7.3 RAM .................................30
7.3.1 Bluetooth Stack ............................30
7.3.2 Bluetooth Object Pools ..........................30
7.3.3 Bluetooth Buffer Memory .........................30
7.3.4 Bluetooth GATT Database ........................31
7.3.5 Call Stack ..............................31
7.3.6 Heap memory ............................31
8. Application ELF-file............................ 32
9. Documentation .............................34
silabs.com
| Building a more connected world. Rev. 0.6 | 3
UG434: Silicon Labs Bluetooth ® C Application Developer's Guide for SDK v3.x
Introduction
1. Introduction
This document is a C developer’s guide for the Silicon Labs Bluetooth stack. It covers various angles of development, and is an important reference to everyone developing in C for Wireless Gecko products that are running the Bluetooth stack.
The document covers the following topics:
• Section 2. Application Development Flow discusses the application development flow.
• Section 3. Project Structure reviews project structure.
• Section 4. Configuring the Bluetooth Stack and a Wireless Gecko Device explains the project include libraries and the actual
Wireless Gecko configuration in the application code.
• Section 5. Bluetooth Stack Event Handling is an important piece for everyone developing with the Silicon Labs Bluetooth stack, as it
explains how the application runs in sync with the stack in an event-based architecture.
• Section 6. Interrupts and section 7. Wireless Gecko Resources touch on the topics of peripherals and the chipset resources, covering what is reserved for the stack usage, how interrupts should be handled, and the stack’s memory footprint and available memory
for the application.
1.1 About this Version
The current version of Silicon Labs' Bluetooth SDK is 3.1.x.
Currently supported compilers and IDE versions are:
• IDE: Simplicity Studio 5.1.0 or newer
• Compiler: IAR v8.30.1 and GCC 7.2.1
1.2 Prerequisites
This document assumes the current version of Silicon Labs’ Bluetooth SDK has been properly installed to the development machine
(Windows, MAC OSX, or Linux), and that the reader is familiar with the quick start guides and with the SDK’s examples. Also, the reader should have a basic understanding of Bluetooth technology. For more information, see UG103.14: Bluetooth Technology Fundamen-
tals.
For instructions on getting started using example applications in Silicon Labs Simplicity Studio development environment, see QSG169:
Bluetooth® SDK v3.x Quick Start Guide.
silabs.com | Building a more connected world. Rev. 0.6 | 4
UG434: Silicon Labs Bluetooth ® C Application Developer's Guide for SDK v3.x
Application Development Flow
2. Application Development Flow
The following figure describes the high-level firmware structure. The developer creates an application on top of the stack, which Silicon
Labs provides as a precompiled object-file, enabling the Bluetooth connectivity for the end-device.
Figure 2.1. Bluetooth Stack Architecture Block Diagram
The Bluetooth stack contains following blocks.
• Bootloader—The Gecko Bootloader is not part of the stack but is provided with the Bluetooth SDK. See UG266: Gecko Bootloader
User Guide and AN1086: Using the Gecko Bootloader with Silicon Labs Bluetooth Applications for more information. For information
on bootloading in general, see UG103.06: Bootloading Fundamentals.
• Bluetooth stack—Bluetooth functionality consisting of link layer, generic access profile, security manager, attribute protocol, and
generic attribute profile.
• Bluetooth AppLoader—An application that starts after the bootloader. It checks if the user application is valid and, if it is, AppLoader starts the application. If the application image is not valid, AppLoader starts the OTA process to try to receive a valid application
image. This requires using the Gecko Bootloader.
silabs.com | Building a more connected world. Rev. 0.6 | 5
UG434: Silicon Labs Bluetooth ® C Application Developer's Guide for SDK v3.x
Application Development Flow
2.1 Application Build Flow
Figure 2.2. Bluetooth Project Build Flow
Building a project starts by defining the Bluetooth services and characteristics (GATT definitions) and by writing the application source
code from Silicon Labs-provided examples or an empty project template, as described in QSG169: Bluetooth® SDK v3.x Quick Start
Guide.
SDK v2.1.0 and later offer two ways to define Bluetooth services and characteristics. The first option is the Visual GATT Editor GUI in
Simplicity Studio. This is a graphical tool for designing the GATT and for generating gatt_db.c and gatt_db.h. Additionally, it can import .xml and .bgproj GATT definition files. The Visual GATT Editor is the default tool for GATT definition and generation in Simplicity
Studio projects.
The second option is to create an .xml or .bgproj according to the UG118: Blue Gecko Bluetooth® Profile Toolkit Developer's Guide and
then use the BGBuild executable as a pre-compilation step to convert the GATT definition file into .c and .h. This method is used in IAR
Embedded Workbench projects.
Compiling the project generates an object file, which is then linked with the pre-compiled libraries provided in the SDK. The output of
the linking is a flash image that can be programmed to the supported Wireless Gecko devices.
silabs.com | Building a more connected world. Rev. 0.6 | 6
UG434: Silicon Labs
Bluetooth ® C Application Developer's Guide for SDK v3.x
Project Structure
3. Project Structure
This section explains the application project structure and the mandatory and optional resources that must be included in the project.
3.1 Bluetooth Files
Library Files
The Bluetooth stack libraries are:
• binapploader.o: Binary image of the Bluetooth AppLoader, provides the optional OTA (Over-the-Air) functionality.
• binapploader_nvm3.o: Binary image of the Bluetooth AppLoader for EFR32[B|M]G1x devices with NVM3 support.
• libbluetooth.a: Bluetooth stack library.
• libpsstore.a: PS Store functionality for the Bluetooth stack. This is not available on EFR32[B|M]G2x devices. NVM3 must be used
instead.
RAIL
The Bluetooth stack uses RAIL to access the radio and RAIL libraries needs to be linked with Bluetooth stack. RAIL has separate libraries for each device family and for single- and multi-protocol environments. RAIL libraries are provided in the Gecko SDK Suite. For
more information refer to UG103.13: RAIL Fundamentals and other RAIL documentation.
Note: To ensure regulatory compliance of the radio module, the Bluetooth stack for the radio module needs to be linked together with
the RAIL library and the configuration library for the radio module. These are librail_module_<soc family><compiler>_release.a and librail_config<modulename>.a.
EMLIB and EMDRV
The Bluetooth stack uses EMLIB and EMDRV libraries to access EFR32 hardware. EMLIB and EMDRV peripheral libraries are provided in source code and they must be included in the project. EMLIB and EMDRV are part of the Gecko SDK Suite. For more details on
EMLIB and EMDRV, see platform EMDRV documentation and EMLIB documentation on https://docs.silabs.com/.
mbed TLS
The Bluetooth stack uses the Mbedtls library for cryptographic operations. The Mbedtls library is provided in source code and must be
included in the project. Mbedtls is part of the Gecko SDK Suite. For more details, refer to the Mbedtls documentation.
Sleep Timer
Sleep Timer is a platform component providing for software timers, timekeeping and date functionality. The Bluetooth stack uses it for
deep sleep and it must be included in the project. See platform sleeptimer documentation.
Power Manager
Power Manager is a platform component that manages the system's energy modes. Its main purpose is to transition the system to a low
energy mode when the processor has nothing to execute. See the reference for your MCU on https://docs.silabs.com/ under Modules>
Platform Services>Power Manager.
Header Files
sl_bt_version.h
This file contains the Bluetooth stack version.
silabs.com | Building a more connected world. Rev. 0.6 | 7
UG434: Silicon Labs
Bluetooth ® C Application Developer's Guide for SDK v3.x
Project Structure
API Header Files
These files define the Bluetooth stack API.
These files serve two purposes: first they contain the actual Bluetooth stack API and the commands and events for the stack, and second they provide a configuration and event management API to the Bluetooth stack.
The configuration, event, and sleep management API is described below.
sl_status_t sl_bt_init_stack(const sl_bt_configuration_t *config)
This function takes a single argument - a pointer to a sl_bt_configuration_t struct. Its purpose is to configure and initialize the Bluetooth stack with the parameters provided in the struct. Once the function sl_bt_init_stack() is called, each required stack
component must be initialized separately. This separation allows memory optimization, by not including those stack components that
are not needed. Project Configurator in Simplicity Studio 5 (SSv5) will take care of the stack initialization. In non-SSv5 applications the
application must call sl_bt_init_stack() and then initialize BGAPI classes.
The following APIs can be used to initialize stack components separately:
• sl_bt_class_dfu_init();
• sl_bt_class_system_init();
• sl_bt_class_gap_init();
• sl_bt_class_avertiser_init();
• sl_bt_class_scanner_init();
• sl_bt_class_sync_init();
• sl_bt_class_connection_init();
• sl_bt_class_gatt_init();
• sl_bt_class_gatt_server_init();
• sl_bt_class_ota_init();
• sl_bt_class_nvm_init();
• sl_bt_class_test_init();
• sl_bt_class_sm_init();
• sl_bt_class_coex_init();
• sl_bt_class_cte_transmitter_init();
• sl_bt_class_cte_receiver_init();
sl_status_t sl_bt_pop_event(sl_bt_msg_t* evt)
This is a non-blocking function to request Bluetooth events from the Bluetooth stack. When an event is requested and the event queue
is not empty, an event object is copied into the memory provided by application. If there are no events in the event queue, SL_STATUS_NOT_FOUND is returned.
The stack’s event handling is discussed in detail in section 5. Bluetooth Stack Event Handling.
int sl_bt_event_pending(void)
This function checks to see if any Bluetooth stack events are pending in the event queue. If a pending Bluetooth event is found, the
function returns a non-zero value to indicate that the event should be processed by sl_bt_pop_event(). If no event is found, zero is
returned.
silabs.com | Building a more connected world. Rev. 0.6 | 8
UG434: Silicon Labs Bluetooth ® C Application Developer's Guide for SDK v3.x
Project Structure
sl_bt_types.h
sl_bt_stack_init.h
sl_bt_api.h
sl_bgapi.h
These files contain the Bluetooth stack API and the commands and events for the stack, and a configuration API for the Bluetooth
stack.
sl_bt_ncp_host_api.c, sl_bt_ncp_host.c, sl_bt_ncp_host.h and sl_bt_internal.h
These files are used when developing applications for an external host. They provide the API definitions and adaptation layer between
the host application and the BGTAPI serial protocol.
3.2 GATT Database
The GATT (Generic Attribute Profile) database is a standardized way of describing the Bluetooth profiles, services, and characteristics
of a Bluetooth device. With the Silicon Labs Bluetooth stack, the GATT definitions are either directly edited in the Visual GATT Editor
GUI in Simplicity Studio or are written in XML and passed to the BGBuild executable as a pre-build task. For more information on how
to create GATT databases and the syntax, refer to UG118: Blue Gecko Bluetooth® Smart Profile Toolkit Developer's Guide.
gatt_db.c and gatt_db.h
The gatt_db.c defines the GATT database structure and content, and is auto-generated by BGBuild or by the Visual GATT Editor.
gatt_db.h includes this database and the handles of local characteristics and services. Type definitions of GATT are automatically included from bg_gatt_db_def.h to gatt_db.h.
3.3 Device Firmware Upgrade
Device Firmware Upgrade (DFU) is the process of upgrading the application either over a serial link or over-the-air (OTA). In both cases
the application needs to add the following file to enable the support for DFU.
application_properties.c
This file includes the application properties struct that contains information about the application image, such as type, version, and security. The struct is defined in application_properties.h in the Gecko Bootloader API. A pre-generated file is included in Simplicity
Studio projects, which can be modified to include application-specific properties. The application properties can be accessed using the
Gecko Bootloader API. The following members can be updated by changing the defines:
// Version number for this application (uint32_t)
#define APP_PROPERTIES_VERSION
// Unique ID (e.g. UUID or GUID) for the product this application is built for (uint8_t[16])
#define APP_PROPERTIES_ID
When using the OTA process with Bluetooth AppLoader, a pointer to the application properties struct needs to be set to application
vector table vector 13. This is enabled automatically when using the default startup file and the struct name is sl_app_properties.
silabs.com | Building a more connected world. Rev. 0.6 | 9
UG434: Silicon Labs Bluetooth ® C Application Developer's Guide for SDK v3.x
Project Structure
3.4 RTOS Support
The Bluetooth stack can also run on Micrium RTOS and FreeRTOS. In this case the following files are added to the project:
sl_bt_rtos_adaptation.c
sl_bt_rtos_adaptation.h
sl_bt_rtos_config.h
sl_bt_rtos_adaptation.c and sl_bt_rtos_adaptation.h
sl_bt_rtos_adaptation.c and sl_bt_rtos_adaptation.h provide the RTOS tasks for the IPC (Inter-Process Communication) with
the Bluetooth stack and other RTOS tasks using CMSIS-RTOS2.
sl_bt_rtos_config.h
sl_bt_rtos_config.h is used to set the Bluetooth RTOS task priorities.
Support for RTOS needs to be configured for the Bluetooth Stack in the sl_bt_configuration_t struct. The config_flags field
needs to have SL_BT_CONFIG_FLAG_RTOS set. This causes the Bluetooth stack to rely on the RTOS for sleeping, rather than sleeping
directly. scheduler_callback and stack_schedule_callback must be configured to call proper functions. These callbacks are used
to wake up the corresponding tasks.
The Bluetooth Stack configuration to use with RTOS is as follows:
.config_flags = SL_BT_CONFIG_FLAG_RTOS,
.scheduler_callback = sli_bt_rtos_ll_callback,
.stack_schedule_callback = sli_bt_rtos_stack_callback,
sl_bt_rtos_init() can be called to initialize the stack and create needed RTOS tasks.
void sl_bt_rtos_init();
It calls function sl_bt_init() to initialize the Bluetooth stack.
3.5 Multiprotocol Support
When the Bluetooth Stack is used in a multiprotocol environment, multiprotocol features in the Bluetooth stack must be enabled with
following function:
sl_bt__init_multiprotocol();
Using Bluetooth in a multiprotocol environment also requires using the RAIL library with multiprotocol support.
3.6 Platform Components
The v3.x Bluetooth stack relies on many platform components that are part of the underlying Gecko Platform infrastructure of the Gecko
SDK Suite. The autogen folder contains sources for initializing the hardware and processing events. The config folder includes hardware and stack configuration options.
silabs.com | Building a more connected world. Rev. 0.6 | 10
UG434: Silicon Labs Bluetooth ® C Application Developer's Guide for SDK v3.x
Configuring the Bluetooth Stack and a Wireless Gecko Device
4. Configuring the Bluetooth Stack and a Wireless Gecko Device
To run the Bluetooth stack and an application on a Wireless Gecko, the MCU and its peripherals have to be properly configured.
4.1 Wireless Gecko MCU and Peripherals Configuration
sl_system_init()
The sl_system_init() function is used to initialize the system. It will call platform, driver, service, stack, and internal app init functions,
which are located in the autogen folder.
App_init()
The App_init() function is used to initialize application-specific features.
4.1.1 Adaptive Frequency Hopping
Bluetooth Stack implements Adaptive Frequency Hopping (AFH), conforming with the ETSI EN 300 328 standard. AFH is required
when using transmit power +10 dBm and over. AFH may also provide performance improvement by avoiding congested channels.
To enable AFH in the Bluetooth stack, the following initialization function must be called:
void sl_bt_init_afh();
This is included automatically when including the bluetooth_feature_afh component. In a master-slave connection, both ends can
use AFH independent of each other. The master may be non-adaptive, but the slave still may need to be adaptive. The standard allows
using control transfer on a blocked channel. For compliance reasons, if the slave detects that a blocked channel is in use, it will only
send a single packet on that channel to prevent connection timeouts.
Note: Legacy advertising does NOT use Adaptive Frequency Hopping. Legacy advertising uses 3 channels, and AFH needs a minimum of 15 channels to fulfill the requirements of the ETSI standard. Extended advertising must be used to enable AFH with advertising.
silabs.com | Building a more connected world. Rev. 0.6 | 11
Loading...