Silicon Labs AN1255, SDK v2.x, SDK v3.x User Manual

AN1255: Transitioning from the v2.x to the
v3.x Bluetooth® SDK

Bluetooth Software Development Kit (SDK) v3.0 contains a number of changes com­pared to Bluetooth SDK v2.x. Many of these changes are due to an underlying framework
redesign that results in an improved developer experience within the new Simplicity Stu­dio 5. Projects are now built on a component architecture. Simplicity Studio 5 includes
project configuration tools that provide an enhanced level of software component discov­erability, configurability, and dependency management. These include a Component Ed­itor, and a redesigned GATT configurator.

In Bluetooth SDK v3.0, sample applications have a new software architecture, the Blue­tooth API is updated, and the GATT configurator is completely redesigned. Additionally
the stack can now be configured in separate header files, and platform components can
be added to the project with the Component Editor instead of copying and including files
manually. While these changes are a result of overall improvements in the SDK and in
Simplicity Studio 5 it also means that migrating projects from Bluetooth SDK v2.x to v3.0
is not trivial. This document explains the steps needed to move your Bluetooth v2.x project
into the v3.0 environment.

KEY POINTS

Reviews differences in:

• Software architecture

• The API

• GATT configurator

• Stack configuration

• Adding platform components

silabs.com | Building a more connected world. Rev. 0.3

AN1255: Transitioning from the v2.x to the v3.x Bluetooth® SDK

Introduction

1 Introduction

Silicon Labs has introduced both a complete update to its Simplicity Studio tool suite, as well as a new, component-based Gecko Platform
architecture.

Version 5 of the Simplicity Studio tool suite represents a ground-up redesign of the underlying architecture. The Simplicity Studio 5 (SSv5)
framework includes a new user interface engine that enables attractive and responsive web-like user interfaces. The integrated develop­ment environment (IDE) was also upgraded with the latest versions of Eclipse and the C/C++ Development Tooling (CDT). This added
robustness, performance improvements, and enables developers to customize their experience using the latest plug-ins from the Eclipse
Marketplace.

Gecko Software Development Kit suite version 3.0.0.0 (GSDK v3.0) is released with SSv5. It introduces a new underlying Gecko Platform
architecture based on components. Both the Bluetooth and the Flex v3.x SDKs are based on this new component-based architecture.
With SSv5 and GSDK v3.0, Bluetooth developers will benefit from the following component-based project configuration features:

• Search and filter to find and discover software components that work with the target device

• Automatically pull in all component dependencies and initialization code

• Configurable software components including peripheral inits, drivers, middleware, and stacks

• All configuration settings in C header files for usage outside of Simplicity Studio

• Configuration validation to alert developers to errors or issues

• Easily manage all project source via git or other SCM tools

• Managed migration to future component and SDK versions

• Simplified transitions from Silicon Labs development kits to custom hardware

Other features of the SSv5/GSDK v3.0 development environment include:

• Project source management options (link to SDK sources or copy all contents to user folder)

• Graphical pin configuration

• Redesigned Bluetooth Configurator with a fresh UI that’s more intuitive for Bluetooth and GATT customization

• Redesigned Radio Configurator with a fresh UI that’s more intuitive for single- and multi-PHY customization

• Iterative development (configure components, edit sources, compile, debug) using SSv5 configuration tools and third-party IDEs

• GNU makefiles as a build option

Other changes are specific to the SDK. Bluetooth SDK v3.0 contains a number of changes compared to Bluetooth SDK v2.x. The main
changes are as follows:

1. The project structure of the sample applications has changed. Many autogenerated files and unified configuration files help adding
and configuring software components.

2. The entire project generation is now based on software components. This makes it possible to add functionality to the project with
only a click, instead of copying files manually and looking for dependencies.

3. The sample applications have a completely new software architecture to align with the concept of software components. Adding RTOS
to your project is also simplified.

4. The Bluetooth API has changed. The API commands and events use a new nomenclature to comply with Silicon Labs standards.
Additionally, some new classes and commands are introduced and some of them are removed to make the API more transparent and
consistent.

5. The GATT configurator is completely redesigned. The new user interface is more modern, while the generator tool makes it possible
to add partial extensions to the GATT database. This means that the GATT database can be easily extended programmatically.

6. The stack can now be configured in a separate header file (instead of main.c). A Component Configurator tool in SSv5 is available to
configure all the parameters, which makes it easy to use predefined values, and to validate custom values.

7. The AppLoader application has new features which requires the update of the bootloader.

This document guides you through these changes, and describes the migration steps necessary to move a project from Bluetooth SDK
v2.x to v3.0.

For details about the release, see the release notes provided with the SDK.

silabs.com | Building a more connected world. Rev. 0.3 | 2

AN1255: Transitioning from the v2.x to the v3.x Bluetooth® SDK

Project Structure

2 Project Structure

In Bluetooth SDK v2.x a Bluetooth project contains the following folders:

/app Application specific files
/hardware Development board configuration files and drivers for external peripherals
/platform Device configuration files and drivers for the MCU peripherals
/protocol Bluetooth stack files
/util Utilities

When a new project is generated, a subset of the SDK files (source files, headers, configuration headers) is copied from the SDK folder
into the project folders based on hardware type and on the needs of the sample application. Additionally, some files (for example
init_mcu.c, hal-config.h, and so on) are generated from templates into the root folder of the project. Again, the output is based on the
hardware type and on the needs of the sample application.

In Bluetooth SDK v3.0 auto-generated files and configurations headers are clearly separated from the static SDK files and gathered into
separate folders:

/autogen Automatically generated files based on the installed software components
/config Editable configuration files for the software components
/gecko_sdk_3.0.0
/app Application specific files
/hardware Development board configuration files and drivers for external peripherals
/platform Device configuration files and drivers for the MCU peripherals
/protocol Bluetooth stack files
/util Utilities

Developers can now easily see which files can be modified by the generator script and it is easy to access all configuration files. This is
especially important, because in Bluetooth SDK v3.0 many more files are generated by the addition of software components (see Sec­tion 3 Software Components).

silabs.com | Building a more connected world. Rev. 0.3 | 3

AN1255: Transitioning from the v2.x to the v3.x Bluetooth® SDK

Project Structure

Due to the new project structure – and due to the new auto-generated files required by the Bluetooth stack – migrating a v2.x
project into Bluetooth SDK v3.0 must begin by creating a new SoC-Empty project in the new SDK. Application logic should be
pulled into this new project. After you select a compatible part on SSv5’s Welcome page, an SoC-Empty project can be created
from the Part-specific Launcher perspective. The Technology filter makes it easy to find applicable projects.

silabs.com | Building a more connected world. Rev. 0.3 | 4

AN1255: Transitioning from the v2.x to the v3.x Bluetooth® SDK

Project Structure

In the project configuration dialog you can rename the project, change the project location, and define how to handle project files.

Note: In Bluetooth SDK v2.x all SDK files are copied into the project by default. In Bluetooth SDK v3.0 SDK files, considered to be
static, are linked by default. If you want to version-control your full project, it is recommended to change this setting to “Copy contents”
in the Project Configuration wizard, when you create the new project to have all content needed by the project in one folder.

Bluetooth Projects automatically open on a ‘readme’ tab that describes the example. Other tabs are the Project Configurator (<project
name>.slcp and the GATT configurator (gatt_configuration.btconf) (see section 6 GATT Configurator for more information).

silabs.com | Building a more connected world. Rev. 0.3 | 5

AN1255: Transitioning from the v2.x to the v3.x Bluetooth® SDK

Software Components

3 Software Components

To add a new software component, for example a UART driver, in Bluetooth SDK v2.x the user must:

1. Copy the corresponding SDK files from the SDK folder into the project folder.

2. Copy all the dependencies of the given component into the project folder.

3. Add new include directories to the project settings.

And additionally:

4. Write the initialization code manually in the application.

5. Configure the component manually in the config files.

6. Use the API of the component in the application.

This is quite a cumbersome process, especially when figuring out the dependencies between components.

In Bluetooth SDK v3.0 software components can be added easily by installing them from the Component Library. The installation pro­cess will automatically execute the first three steps listed above, and it also modifies the corresponding auto-generated files to integrate
the component into the application (“glue logic”).

Additionally the Component Configurator provides the possibility of:

1. Adding an “init” type component that initializes the software component

2. Configuring the component with a GUI

Some software components (like OTA DFU) will fully integrate into the application to perform a specific task without the need of any
additional code, while other components provide an API to be used in the application. The only task left for the developer is to use the
API of those component in the application.

It is important to note that in Bluetooth SDK v3.0 the Bluetooth stack itself is also just a collection of software components that can be
added to and removed from the project.

When migrating a project into Bluetooth SDK v3.0, start by finding out which functionality can be provided by installing a
software component from the Component Library. Although this means you must become familiar with the software compo­nents first, it will save time later. Generally speaking, if you would have copied an additional SDK file into your project, you will
probably find a software component that solves the integration of that file.

silabs.com | Building a more connected world. Rev. 0.3 | 6

AN1255: Transitioning from the v2.x to the v3.x Bluetooth® SDK

Software Components

To see the component library, click the <project-name>.slcp tab of your project, and click Software Components. A number of filters
as well as a keyword search are available to help you explore the various component categories. Note that components for all installed
SDKs are presented.

silabs.com | Building a more connected world. Rev. 0.3 | 7

AN1255: Transitioning from the v2.x to the v3.x Bluetooth® SDK

Software Components

Components installed in the project are checked (1), and can be uninstalled. Configurable components are indicated by a gear symbol
(2). To display only installed components or only configurable components, use the checkboxes at the top of the editor.

Click Configure to see a configurable component’s parameters in the Component Configurator.

See QSG169: Bluetooth® SDK v3.x Quick Start Guide and the online Simplicity Studio 5 User’s Guide

for more information about the

SSv5 project interface and the Bluetooth SDK.

silabs.com | Building a more connected world. Rev. 0.3 | 8

AN1255: Transitioning from the v2.x to the v3.x Bluetooth® SDK

main.c

app.c

int main(void)

void appMain(gecko_configuration_t *pconfig)

}

Software Architecture

4 Software Architecture

4.1 Bluetooth Event Handling

In Bluetooth SDK v2.x the sample applications were written with simplicity in mind. Although many platform files are included in the project
– to make the features provided by the hardware available for the application – the application itself has a simple and transparent archi­tecture. Taking the SoC-Empty project as an example:

• The stack configuration is defined in main.c

• MCU, board and app are initialized in main.c

• Stack is initialized in app.c

• There is a simple loop in app.c to fetch and handle Bluetooth events

{
/* Initialize device */
initMcu();
/* Initialize board */
initBoard();
/* Initialize application */
initApp();

/* Start application */
appMain(&config);

}

This software architecture is very easy to understand. However, it has drawbacks:

• Sleep is managed by the Bluetooth stack.
when a Bluetooth event is triggered. If your application implements processes that should run regularly you must rely on the Bluetooth
stack software timers.

• The application is totally Bluetooth-event-driven. If your application needs custom events, you have to use the external signals of the
Bluetooth stack to extend the Bluetooth events with custom events.

• If your application needs a state machine, it may be challenging to merge the states of the state machine with the Bluetooth event
handlers / connection states.

• Since different software components (for example one that is reading your sensors, one that blinks the LEDs, and so on) may have
different needs, you always have to adjust your software architecture to these needs.

• While all of these problems can be addressed by using RTOS, RTOS may consume too many resources for your application.

gecko_wait_event() puts the device into sleep mode, and processing continues only

{
/* Initialize stack */
gecko_init(pconfig);

while (1) {
/* Event pointer for handling events */
struct gecko_cmd_packet* evt;

/* Check for stack event. */
evt = gecko_wait_event();

/* Handle events */
switch (BGLIB_MSG_ID(evt->header)) {

case gecko_evt_system_boot_id:
printLog("system booted\r\n");
break;

case gecko_evt_le_connection_opened_id:
printLog("connection opened\r\n");
break;

default:
break;
}
}

silabs.com | Building a more connected world. Rev. 0.3 | 9

AN1255: Transitioning from the v2.x to the v3.x Bluetooth® SDK

main.c

sl_system_process_action.c

app.c

int main(void)

void

void

sl_event_handler.c

void

sl_bluetooth.c

}

Software Architecture

In contrast to this, the sample applications of Bluetooth SDK v3.0 were written with flexibility in mind. Although this makes the code a bit
less transparent, at the same time it makes it easy to extend the software with a new software component.

• Each software component has an
is sent into sleep mode when neither of them needs the CPU. Sleep is automatically handled by the power manager. Here, the

Bluetooth stack is just one of the software components, it does not have a distinguished role.

• To regularly run a process the common sleeptimer can be used instead of the soft timers of the Bluetooth stack.

• When an interrupt wakes up the device, you do not need to trigger an external signal to get out of the

process functions will be called and can catch their respective events triggered by interrupts.

Furthermore:

• Due to the unified software architecture software components can easily be integrated into the code by adding the proper function
calls to predefined places in the code. This process is automatically handled by the Component Editor, which makes the addition of
a software component as easy as ticking a checkbox.

• Software components define their dependencies, therefore whenever a new component is added, all of its dependencies are also
automatically added to your project.

• In the new software architecture all configuration is put into header files. On one hand this separates functionality from config, and on
the other hand it makes it possible to provide a Component Editor for all configurations. Software components, including the Bluetooth
stack, can be easily configured within SSv5.

init and a process function. The process functions are run in an infinite loop, and the device

wait_event phase. All the

For these reasons, the new SoC-Empty example project is a bit more complicated. Main.c calls a generic
which then calls the
event fetching in its own
mented in the application (app.c). Note: some components (like OTA DFU) may also handle some Bluetooth events before the application.

{
sl_system_init();
app_init();

while (1) {
sl_system_process_action();
app_process_action();
sl_power_manager_sleep();
}
}

init and process function,

init and process functions of each installed component. The Bluetooth component implements the Bluetooth

process function and ultimately calls the event handler function (sl_bt_on_event), which is to be imple-

sl_system_process_action(void)
{
sl_platform_process_action();
sl_service_process_action();

sl_stack_process_action();

sl_internal_app_process_action();
}

sl_stack_process_action(void)
{
sl_bt_step();
}

void sl_bt_step()

{
sl_bt_msg_t evt;

sl_status_t status =
sl_bt_pop_event(&evt);

if(status != SL_STATUS_OK){
return;
}

sl_bt_process_event(&evt);

}

void

sl_bt_process_event(sl_bt_msg_t

*evt)
{
sl_bt_ota_dfu_on_event(evt);

sl_bt_on_event(evt);

sl_bt_on_event(sl_bt_msg_t*

evt)
{
// Handle stack events
}

silabs.com | Building a more connected world. Rev. 0.3 | 10