You are viewing documentation for version: 4.0 | This version works with Simplicity Studio 5 only. If you have Simplicity Studio 4, switch to 2.13. | For additional versions, see Version History.

Getting Started

Getting Started with SLWSTK6101 Embedded Software

The Blue Gecko Bluetooth Wireless Starter Kit (WSTK) helps evaluate Silicon Labs' Blue Gecko Bluetooth modules and get started with software development. The kits come in different versions with different module radio boards. See https://www.silabs.com/products/development-tools/wireless/bluetooth/bluegecko-bluetooth-low-energy-module-wireless-starter-kit for details on current configurations.

To get started with the WSTK, download Simplicity Studio 5 (SSv5) and the Bluetooth SDK v3.x and work on the pre-built demos to get some experience. The Bluetooth SDK comes with some prebuilt demos that can be flashed to your EFR32 device and tested using a Smartphone. Here we show how to test three prebuilt demos:

• NCP Empty demo
• iBeacon demo
• Health Thermometer demo

Prepare the WSTK

1. Connect a Bluetooth Module Radio Board to the WSTK Main Board as shown in the following figure.

2. Connect the WSTK to a PC using the Main Board USB connector.

3. Turn the Power switch to "AEM" position.

Note: At this stage, you might be prompted to install the drivers for the WSTK Main Board but you can skip this for now.

4. Check that the blue USB Connection Indicator LED turns on or starts blinking.

5. Check that the Main Board LCD display turns on and displays a Silicon Labs logo. Before starting to test the demo application note the following parts on the WSTK Main Board:

• Temperature & Humidity Sensor
• PB0 button
• LED0

Kit parts

Flash the Demos

1. With your device connected as described above, open SSv5.

2. Select your device in the Debug Adapters view.

3. In the Launcher windows, select Example Projects & Demos tab.

4. Click RUN on the demo of choice.

Test the Bluetooth Demos Using a Smartphone

Testing the NCP Empty Demo

1. Load the NCP Empty demo on the target. Open Simplicity Studio with a WSTK and radio board connected and select the corresponding debug adapter.
2. On the OVERVIEW tab, under "General Information", select the Gecko SDK Suite if it is not selected. On the Example Projects & Demos tab, select the NCP Empty demo and click RUN. This flashes the demo to your device, but it does not start advertising automatically.
3. At this point, NCP Commander can be used to send BGAPI commands to the kit, using UART. Connections, advertising and other standard Bluetooth Low Energy operation can be controlled via this tool. NCP commander can be found in the Simplicity Studio 5 Tool menu:

4. Launch NCP Commander and then establish the connection to the kit. If everything works correctly, you should see the result of the “sl_bt_system_get_identity_address” command displayed in green:

   

6. In the ‘Advertise’ menu, click on the + button and then Start to start advertising.

   

7. On the central side (smartphone), install the EFR Connect app from the App Store, and open it. To find your advertising device, tap the Develop tab, and tap Bluetooth Browser. This shows all advertising devices nearby. Connect to your device by tapping Connect next to "Silabs Example”. Its GATT database is automatically discovered and displayed. Tap any service to list its characteristics and tap any characteristic to read its value.

   

Testing the iBeacon Demo

Bluetooth beacons are unconnectable advertisements that help you locate a device, determine your own position, or get minimal information about an asset the beaconing device is attached to.

After flashing the iBeacon demo to your device, you can find the beacon signal with the Bluetooth Browser of EFR Connect app. Start EFR Connect and select Bluetooth Browser. To filter beacons, tap the Filter button and select the beacon types to display. The app will provide basic information about the beacon, such as RSSI, which can help determine the distance of the beacon. Tap on the beacon to get more information about the data it provides.

Beaconing Demo

Testing the Health Thermometer Demo

While the NCP Empty demo implements a minimal GATT database with basic static information such as device name, the Health Thermometer demo extends this database with live temperature measurements.

After flashing the Health Thermometer demo to your device, open EFR Connect app, select the Demo tab, and select Health Thermometer. Find your device advertising as Thermometer Example in the device list and click on it to connect. The mobile phone app automatically finds the Temperature measurement characteristic of the device, reads its value periodically, and displays the value on the screen of the phone.

Try touching the temperature sensor (located on the WSTK as you can see in section Prepare the WSTK). You should be able to see the temperature changing.

Health Thermometer Demo

Getting Started with BGM220 Explorer Kit

The BGM220 Explorer Kit (part number: BGM220-EK4314A) is focused on rapid prototyping and IoT concept creation around Silicon Labs BGM220P module.

Kit Overview

The kit features USB interface, on-board J-Link debugger, one user LED/button and support for hardware add-on boards via a mikroBus socket, and a qwiic connector.

Explorer Kit

The hardware add-on support allows developers to create and prototype applications using a virtually endless combination of off-the-shelf boards from mikroE, sparkfun, AdaFruit, and Seeed Studios. The boards from Seeed Studios feature a connector, which is pin compatible with the qwiic connector but mechanically incompatible and it requires an adaption cable or board.

Testing the Bluetooth Demos

The Bluetooth SDK comes with pre-built demos that can be directly flashed into this kit and tested using a smartphone running the EFR Connect mobile app (Android, iOS):

• SoC iBeacon
• NCP Empty

The iBeacon can be tested with EFR Connect as documented in the above getting started section. NCP Empty can be tested with NCP Commander, which can be launched via the Tools dialog in Simplicity Studio 5.

GitHub Examples

Silicon Labs applications_examples GitHub repository contains additional examples that can run on the BGM220 Explorer Kit. Some of them leverage 3rd party add-on boards and they are typically found in the bluetooth_applications repository.

Porting Code from mikroSDK and Arduino

If using a mikroE click board, ready made examples are on your specific mikroE click board Web page that typically reside in mikroE's libstock and/or GitHub. Those examples are using the mikroSDK, which provides abstraction to the supported hardware kits provided by mikroE.

If using a board from sparkfun, Adafruit, or Seeed Studios, they typically have examples for the Arduino IDE, which run on some of their own controller boards that are supported by the Arduino platform.

Those examples will not run out of the box on the BGM220 Explorer Kit, but with a small amount of effort they can be easily ported by using the guide below, which maps mikroSDK and Arduino APIs for UART/SPI/I2C/GPIO functionality into the Silicon Labs platform equivalents.

Whether porting from mikroSDK or Arduino, EMLIB and Platform Drivers/Services contain the most useful Silicon Labs APIs. For corresponding documentation, see below:

• EMLIB - a low level peripheral driver library for all Silicon labs EFM32 and EFR32 device families

• Platform Drivers - a higher level driver layer built on top of EMLIB. EMDRV abstracts some aspects of peripheral initialization and use but is more limited in peripheral coverage than EMLIB.

Additionally, Silicon Labs' Peripheral Examples on GitHub are a good resource for simple demonstration of peripheral control using EMLIB.

mikroSDK Porting Guide

The mikroE ecosystem of click boards from MikroElektronika are typically supported by a collection of driver modules and example code built upon the mikroSDK. These click boards feature a mikroBUS connector for connection to a host board and can include connections for power (3.3 V, 5 V, GND), communications (UART, SPI, and/or I2C), and assorted other functions (GPIO, PWM, INT).

The mikroSDK is a framework that provides abstraction for the communication and GPIO functions of the mikroE click boards by wrapping vendor-specific functions in a common API framework to accomplish these tasks that is portable across a wide range of host devices. The microSDK is therefore ported to a new device via the assignment of function pointers and other device-specific configuration options. At this time, there is no official mikroSDK port for Silicon Labs devices.

Note: The goal of this configuration guide is not to instruct the user on how to port the mikroSDK to the BGM220 or other Silicon Labs devices, but instead to introduce the user to the spectrum of Silicon Labs' native APIs and how to use these APIs instead of the mikroSDK.

There is currently a wide selection of mikroE click accessory boards to facilitate product development with devices such as sensors, display/LEDs, storage, interface, and HMI. Some of these boards are shown below.

mikroE click boards

Using the mikroBUS-compatible socket included on the Explorer Kit BGM220, these boards can be used with the BGM220 as the host controller via the pin functions connecting the mikroBUS socket to the BGM220.

When porting mikroE click examples to the Silicon Labs platform, it is important to understand that interaction between the host controller and the click board is accomplished using a subset of UART, I2C, SPI, GPIO, analog, PWM, or interrupt. Pins for each function are allocated between the BGM220 and the mikroBUS connector, as shown below.

mikroBUS Socket

Note: Knowledge of the pin mapping shown above combined with use of Silicon Labs' native APIs, as shown below, enable a user to port existing click examples to the Explorer Kit BGM220 by substituting Silicon Labs API calls for mikroSDK and click driver API calls.

The following sections cover four main categories of API-enabled interactions between a host device (BGM220P in this case) and a click board: GPIO, SPI, I2C, and UART. Note that the functions and structures presented here correspond to elements of the core mikroHAL and mikroBUS APIs of the mikroSDK and their closest Silicon Labs counterparts. Many click boards have additional libraries and driver files that integrate with these layers to create the mikroE project framework. However, these core elements should help guide users porting to the Silicon Labs platform.

GPIO

The mikroSDK uses a complex system of function pointers and data structures to initialize a low level GPIO driver layer with initialization, "get," and "set" function pointers for each GPIO pin on the mikroBUS header. This structure is inherited by higher-level driver layers, which use "get" and "set" functions in higher-level wrapper functions.

By contrast, the Silicon Labs APIs for GPIO control, or em_gpio, are straightforward and easy to understand. Generally speaking, firmware should first initialize a pin and set its mode (i.e., input type, output type, and so on) by calling GPIO_PinModeSet(), then use various API calls to control or read the pin state. The following table represents a comparison and possible suggested substitution scheme for using em_gpio in place of the mikroSDK GPIO API.

Note: More em_gpio functions are available in EMLIB. For more information,see the GPIO API Documentation.

SPI

As with the mikroSDK GPIO API, the mikroSDK SPI framework relies on vendor-specific function pointers assigned in a configuration layer to provide an interface for SPI communications.

Silicon Labs offers the low-level EMLIB SPI (Synchronous USART) and higher-level EMDRV driver SPIDRV APIs for SPI communication, provided as source code. The suggested substitutions in the following table assume that the host SoC is the SPI central, however EMLIB and SPIDRV offer peripheral SPI functions as well.

When using EMLIB, firmware must separately configure all SPI pins to the proper mode using the EMLIB GPIO functions before using the pins for SPI communications. When using SPIDRV, however, firmware specifies the desired port and pins to use for the SPI bus in the SPIDRV_Init data structure, and configuration of these pins is handled by the SPIDRV_Init() function.

Note: More EMLIB and SPIDRV functions are available than shown here. See em_usart and and SPIDRV API documentation for more information.

I2C

As with other mikroSDK modules, the mikroSDK I2C framework relies on vendor-specific function pointers assigned in a configuration layer to provide an interface for I2C communications.

Silicon Labs offers the EMLIB I2C driver em_i2c for firmware control of the I2C interface, which differs slightly in approach from the mikroSDK framework. The em_i2c firmware interface relies on the configuration of the I2C peripheral block and desired transfer parameters using the I2C_Init() and I2C_TransferInit() functions. Management of the I2C transfer state machine handled by repeated calls to I2C_Transfer(), which handles the different phases of the I2C transfer and hardware state machine.

When using EMLIB, firmware must separately configure all I2C pins to the proper mode using the EMLIB GPIO functions before using the pins for I2C communications.

Note: The em_i2c driver library provides additional functions and features beyond those described here. See the em_i2c API documentation for more information.

UART

In a similar fashion as other mikroSDK API modules, the mikroSDK UART framework relies on vendor-specific function pointers assigned in a configuration layer to provide an interface for UART communications.

Silicon Labs offers the low-level EMLIB UART (asynchronous USART) and higher-level EMDRV driver UARTDRV APIs for UART communication, provided as source code.

When using EMLIB, firmware must separately configure all UART pins to the proper mode using the EMLIB GPIO functions before using the pins for UART communications. When using UARTDRV, however, firmware specifies the desired port and pins to use for the UART bus in the UARTDRV_InitUart_t data structure. Configuration of these pins is handled by the UARTDRV_InitUart() or UARTDRV_InitLeuart() function.

Note: The EMLIB em_usart and EMDRV UARTDRV APIs provide additional functionality and support a wider feature set of the USART peripheral than is described in this porting guide. See the em_usart and UARTDRV API documentation for more information.

Arduino Porting Guide

Many open-source examples, including those designed for use with expansion boards from sparkfun, Adafruit, or Seeed Studios, use the Arduino API. This section provides a basic mapping of some of the Arduino API functions for serial communications and GPIO handling onto suggested or possible replacement calls from the Silicon Labs EMLIB and EMDRV libraries.

Although the Arduino API contains many submodules for different tasks, this guide focuses on Silicon Labs API replacements for GPIO control (Arduino Digital IO API), SPI communications (Arduino SPI API), I2C communications (Arduino Wire API), and UART communications (Arduino Serial and SoftwareSerial APIs).

GPIO (Arduino Digital IO API)

The Silicon Labs APIs for GPIO control, or em_gpio, provide straightforward and easy to understand functions for GPIO initialization and control. Generally speaking, firmware should first initialize a pin and set its mode (i.e., input type, output type, and so on) by calling GPIO_PinModeSet(), then use various API calls to control or read the pin state. The following table represents a comparison and possible suggested substitution scheme for using em_gpio in place of the Arduino Digital I/O API.

Note: More em_gpio functions are available in EMLIB than shown here. See the em_gpio API documentation for more information.

SPI (Arduino SPI API)

Silicon Labs offers the low-level EMLIB SPI (Synchronous USART) and higher-level EMDRV driver SPIDRV APIs for SPI communication, provided as source code. The suggested substitutions in the following table assume that the host SoC is the SPI central. However, EMLIB and SPIDRV offer SPI functions as well.

When using EMLIB, firmware must separately configure all SPI pins to the proper mode using the EMLIB GPIO functions before using the pins for SPI communications. When using SPIDRV, however, firmware specifies the desired port and pins to use for the SPI bus in the SPIDRV_Init data structure. Configuration of these pins is handled by the SPIDRV_Init() function.

Note: More EMLIB and SPIDRV functions are available than shown here. See the em_usart and and SPIDRV API documentation for more information.

I2C (Arduino Wire API)

Silicon Labs offers the EMLIB I2C driver (em_i2c) for firmware control of the I2C interface, which differs slightly in approach from the Arduino Wire API. The em_i2c firmware interface relies on the configuration of the I2C peripheral block and desired transfer parameters using the I2C_Init() and I2C_TransferInit() functions. Management of the I2C transfer state machine is then handled by repeated calls to I2C_Transfer(), which handles the different phases of the I2C transfer and hardware state machine.

When using EMLIB, firmware must separately configure all I2C pins to the proper mode using the EMLIB GPIO functions before using the pins for I2C communications.

Note: The em_i2c driver library provides additional functions and features beyond those described here. See the em_i2c API documentation for more information.

UART (Arduino Serial and SoftwareSerial APIs)

Silicon Labs offers the low-level EMLIB UART (asynchronous USART) and higher-level EMDRV driver UARTDRV APIs for UART communication, provided as source code. Additionally, Silicon Labs offers a higher-level driver called RetargetIo that re-targets some standard IO functions such as printf and may be useful for replacement of some Arduino Serial and SoftwareSerial functions.

When using EMLIB, firmware must separately configure all UART pins to the proper mode using the EMLIB GPIO functions before using the pins for UART communications. When using UARTDRV, however, firmware specifies the desired port and pins to use for the UART bus in the UARTDRV_InitUart_t data structure, and configuration of these pins is handled by the UARTDRV_InitUart() or UARTDRV_InitLeuart() function. Similarly, when using RetargetIo functions, USART and GPIO initialization is handled by RETARGET_SerialInit(). Note that the RetargetIo library is Silicon Labs board-specific library, which relies on board support configuration files to properly configure GPIO and peripherals used in communications.

Note: The EMLIB em_usart, EMDRV UARTDRV, and RetargetIo APIs provide additional functionality and support a wider feature set of the USART peripheral than described in this porting guide. See the em_usart, UARTDRV, and RetargetIo API documentation for more information.

Arduino Serial API porting:

Arduino SoftwareSerial API porting:

Starting Application Development

Developing a Bluetooth application consists of defining the GATT database structure and the event handlers for events such as connection_opened, connection_closed, and so on.

The most common starting point for application development is the SOC-Empty example. This project contains a simple GATT database (including the Generic Access service, Device Information service, and OTA service) and a while loop that handles some events raised by the stack. You can extend both the GATT database and the event handlers of this example according to your needs.

Note: Beginning with Bluetooth SDK version 2.7.0.0, all devices must be loaded with the Gecko Bootloader as well as the application. While you are getting started, the easiest way to do this is to load any of the precompiled demo images, which come with the bootloader configured as part of the image. When you flash your application, it overwrites the demo application but the bootloader remains. Subsequently, you may wish to build your own bootloader, as described in UG266: Silicon Labs Gecko Bootloader User's Guide. The first bootloader loaded on a clean device should always be the combined bootloader.

New Project creation is done through three dialogs:

• Target, SDK, and Toolchain
• Examples
• Configuration

An indicator at the top of the dialog shows you where you are.

You can start a project from different locations in the Launcher Perspective, as described in the Simplicity Studio 5 User’s Guide. Start from the File menu because that takes you through all three of the above dialogs.

1. Select New >> Silicon Labs Project Wizard.
2. Review your SDK and toolchain. To use IAR instead of GCC, change it here. After you have created a project, it is difficult to switch toolchains. Click NEXT.
3. On the Example Project Selection dialog, filter on Bluetooth and select SoC Empty. Click NEXT.
4. On the Project Configuration dialog, rename your project. Note that if you change any linked resource, it is changed for any other project that references it. While you are getting started, the default choice to include project files but link to the SDK is best.
5. Click FINISH.

GATT Database

Every Bluetooth connection has a GATT client and a GATT server. The server holds a GATT database, which is a collection of Characteristics that can be read and written by the client. The Characteristics are grouped into Services. The group of Services determines a Bluetooth Profile.

If implementing a GATT server (typically on the peripheral device), define a GATT database structure. This structure can't be modified during runtime, so it has to be designed in advance. Clients (typically the central device) can also have a GATT database, even if no device will query it, so you can keep the default database structure in your code.

The GATT Configurator is a simple-to-use tool to help you build your own GATT database. A list of project Profiles/Services/Characteristics/Descriptors is shown on the left and details about the selected item is shown on the right. An options menu is provided above the Profiles list.

The GATT Configurator automatically appears after creating the project to help create your own GATT database with a few clicks. Note that a Simplicity IDE perspective control is now included in the upper right of the screen.

You can create your own database at this point, or return to it later either by double-clicking the gatt_configuration.btconf file under your project in Project Explorer, or through the Project Configurator's Advanced > GATT Configurator component. For more information, see section UG438: GATT Configurator User’s Guide for Bluetooth SDK v3.x .

To add a custom service, click the Profile (Custom BLE GATT), and then click Add (1). To add a custom characteristic, select a service and then click Add (1). To add a predefined service/characteristic click Add Predefined (6). To learn more about the configurator see UG438: GATT Configurator User’s Guide for Bluetooth SDK v3.x.

You can find a detailed description of any Profile/Service/Characteristic/Descriptor on https://www.bluetooth.com/specifications/gatt.

Characteristics are generally complex structures of fields. To know what fields a characteristic has, see https://www.bluetooth.com/specifications/gatt/characteristics.

A reference for each characteristic is generated and defined in gatt_db.h. You can use this references in your code to read / write the values of the characteristics in the local GATT database with sl_bt_gatt_server_read_attribute_value() / sl_bt_gatt_server_write_attribute_value() commands.

Bluetooth Event Handlers

Open app.c by double-clicking it in Project Explorer. You will find the Bluetooth event handlers in sl_bt_on_event(). You can extend this list with further event handlers. The full list of events and stack commands is in the API Reference.

main.c

To learn more about Bluetooth application development, see UG434: Silicon Labs Bluetooth ® C Application Developer's Guide for SDK v3.x. If you are developing an NCP application, see AN1259: Using the v3.x Silicon Labs Bluetooth® Stack in Network CoProcessor Mode.

Component Configuration

Bluetooth SDK v3.x projects are based on a Gecko Platform component-based architecture. Software features and functions can be installed and configured through Simplicity Studio’s Project Configurator. When you install a component, the installation process will do the following:

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.
4. Copy the configurations files into the /config folder.
5. Modify the corresponding auto-generated files to integrate the component into the application.

Additionally, "init" type software components will implement the initialization code for a given component, using their corresponding configuration file as input.

Some software components, such as OTA DFU, will fully integrate into the application to perform a specific task without any additional code, while other components provide an API for use in the application.

To see the component library, click the .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.

Components installed in the project are checked (1), and can be uninstalled. Configurable components are indicated by a gear symbol (2).

Click Configure to open the Component Editor and see a configurable component’s parameters.

As you change component configurations, your changes are automatically saved and project files are automatically generated. You can see generation progress in the lower right corner of the Simplicity IDE. Wait until generation is complete before building the application image.

Building and Flashing

To build and debug your project click Debug () in the upper left corner of the Simplicity IDE perspective. It will build and download your project, and open up the Debug perspective. Click Play ( ) to start running you project on the device.

Enabling Field Updates

Deploying new firmware for devices in the field can be done by UART DFU (Device Firmware Update) or, for SoC applications, OTA DFU (Over-the-Air Device Firmware Update). For more information about each of these methods, see AN1086: Using the Gecko Bootloader with the Silicon Labs Bluetooth Applications.