Getting Started

Getting Started with SLWSTK6101 Embedded Software

The Blue Gecko Bluetooth Wireless Starter Kit (WSTK) is meant to help you evaluate Silicon Labs' Blue Gecko Bluetooth modules and get started with your own 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 and the Bluetooth SDK as described in section 3. Getting Started with Simplicity Studio and the Bluetooth SDK of QSG139: Getting Started with Bluetooth® Software Development, and get some experience with the pre-built demos. 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 the test three prebuilt demos:

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.

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

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

Kit parts

Flash the Examples

  1. With your device connected as described above, open Simplicity Studio.

  2. Select your device in the Debug Adapters pane.

  3. Under the Demos column, open the Bluetooth (SoC) Basic group and select the desired demo.

  4. In the Mode drop-down in the next dialog, select Run. Click Start.

Test the Bluetooth Demos Using an Android Smartphone

Testing SoC - Empty Demo

After flashing SoC - Empty demo to your device, the device automatically starts advertising itself as "Empty Example", and makes it possible to connect to it by other Bluetooth devices.

Install EFR Connect app from Google Play Store, and open it. To find your advertising device, select Bluetooth Browser on the Develop tab. This shows all advertising devices nearby. By clicking on the connect button next to "Empty Example", you can connect to your device. Its GATT database is automatically discovered and displayed. Click on any service to list the characteristics inside of it, and click on any characteristic to read its value.

Connecting to the SoC - Empty Demo

Testing the iBeacon Demo

Bluetooth beacons are non connectable advertisements, that help you locate a device, determine your own position or get a 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. Just start EFR Connect, and select Bluetooth Browser. To filter beacons, tap the Filter button, and select the beacon types you want to be displayed. The app will provide you with basic information about the beacon, like 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 SoC - Empty demo implements a minimal GATT database with basic static information like 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

Test the Bluetooth Demos Using an iOS Smartphone

Testing SoC - Empty Demo

After flashing SoC - Empty demo to your device, the device automatically starts advertising itself as "Empty Example", and makes it possible to connect to it by other Bluetooth devices.

Install EFR Connect app from Apple App Store, and open it. To find your advertising device, select Bluetooth Browser on the Develop tab. This shows all advertising devices nearby. By clicking on the connect button next to "Empty Example", you can connect to your device. Its GATT database is automatically discovered and displayed. Click on any service to list the characteristics inside of it, and click on any characteristic to read its value.

Connecting to the SoC - Empty Demo

Testing the iBeacon Demo

Bluetooth beacons are non connectable advertisements, that help you locate a device, determine your own position or get a 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. Just start EFR Connect, and select Bluetooth Browser. To filter beacons, tap the filter button, and select the beacon types you want to be displayed. The app will provide you with basic information about the beacon, like RSSI - which can help determine the distance of the beacon. Tap on the beacon to get more information about the data it provides.

Connecting to the SoC - Empty Demo

Testing the Health Thermometer Demo

While SoC - Empty demo implements a minimal GATT database with basic static information like 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.

Connecting to the SoC - Empty Demo

Starting Application Development

Developing a Bluetooth application consists of two main steps: defining the GATT database structure, and defining 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 Guide. The first bootloader loaded on a clean device should always be the combined bootloader.

To start developing your application, follow these steps (illustrated in the following figure):

Note: Your SDK version may be later than the version shown in the procedure illustrations.

  1. Click New Project in the Launcher perspective.

  2. Select Bluetooth SDK and click Next.

  3. Select SoC – Empty and click Next.

  4. Name your project and click Next.

  5. Verify that your selected part is shown, and select your preferred toolchain.

    Note: You should only select one toolchain. If you are using GCC, you must uncheck IAR. Otherwise the system will revert to IAR when you generate your files. Click Finish.

studio SoC-Empty studio SoC-Empty 2

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

You can create your own database at this point, or return to it later by clicking the .isc file in the Project Explorer pane on the left. For more information, see section UG365: GATT Configurator User’s Guide .

GATT Configurator

A reference for each characteristic is generated and defined in gatt_db.h (provided that you have defined an ID for it in the GATT configurator). You can use this references in your code to read / write the values of the characteristics in the GATT database with gecko_cmd_gatt_server_read_attribute_value() / gecko_cmd_gatt_server_write_attribute_value() commands.

Open app.c by double-clicking it in Project Explorer. You will find the event handlers in the main loop. You can extend this list with further event handlers. The full list of events – and stack commands – can be found in the API Reference.

main.c

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 on each of these methods refer to AN1086: Using the Gecko Bootloader with the Silicon Labs Bluetooth Applications.

Bluetooth SoC-Empty example

The Bluetooth SoC-Empty example is a minimal project that you can use as a template for any Bluetooth application.

The term SoC stands for "System on Chip", meaning that this is a standalone application that runs on the EFR32/BGM and does not require any external MCU or other active components to operate.

As the name implies, the example is an (almost) empty template that has only the bare minimum to make a working Bluetooth application.

Starting from Bluetooth SDK 2.11 and above the SoC-Empty example was restructured to allow the development of more portable code across different targets and future SDK releases. Compared with the previous SDK versions these were the two main changes:

Anatomy of the SoC-Empty example

This example code is written to be as simple as possible, without unnecessary abstraction layers or other gimmicks. It is split into two main parts:

The idea in this split is that all the automatically created initialization code is placed in main.c and the actual application code is separated into app.c. The objective is to keep application code independent of the target device and Bluetooth SDK version and decouple it from the automatically generated project in the SDK.

To enable easy porting of your application to different targets (or migrate between SDK versions), it is recommended to keep any edits to main.c at minimum (preferably none).

The application main entry point is in app.c. When working on a complex application, it is of course possible to split the application logic into multiple source files.

Device init (main.c)

The code in main.c fills the Bluetooth stack initialization structure (_gecko_configuration_t config_) with default values. Your application can override some of the defaults if needed before initializing the stack (done in app.c)

For full details on the stack configuration options, refer to UG136: Silicon Labs Bluetooth® C Application Developer's Guide.

The actual main function is really compact:

int main(void)
{
  /* Initialize device */
  initMcu();
  /* Initialize board */
  initBoard();
  /* Initialize application */
  initApp();
  /* Start application */
  appMain(&config);
}

The init functions contain initialization code for different MCU/board/app features, for further details you can check the content of those functions.

NOTE: If you need to do some initialization specific to your board, it is recommended to call those from app.c so that the auto-generated files are not touched. This will make it easier to maintain or port your project.

After the initialization the main() function calls the application entry point appMain(). A pointer to the stack configuration structure is passed as an argument so that the application can modify the settings if needed. The actual stack initialization (_gecko_init()_) is called from app.c.

Application code (app.c)

The application main entry point is in the function appMain() that has following prototype:

_void appMain(gecko_configuration_t *pconfig)_

Within this function the stack is initialized with _gecko_init()_ and then the application runs in an infinite loop that reads events from the stack (using the blocking _gecko_wait_event()_ call) and handles those events in a switch statement.

First event to handle is always the _system_boot_ event. This is generated when the stack has initialized and is ready to receive BGAPI commands from the application. In the SoC-Empty example, the boot event handler simply configures the advertising timing parameters and starts advertising in connectable mode.

A few other events are handled which provide some very basic Bluetooth functionality e.g. restarts advertising after the Bluetooth connection gets closed. Please refer to the SoC-Empty source code for more details.

Enabling debug printf

This example application now supports printf over the WSTK VCOM "out-of-the-box" but it is disabled by default so that the example itself is hardware agnostic. This is to ensure that it does not cause any issues if flashed to a custom hardware as-is (assuming the project was created for an OPN and not a radio board).

alt text

NOTE: Projects for radio boards include code specific to each radio board (e.g. disabling external SPI Flash) and they also enable the PTI (Packet Trace Interface) pins so that Bluetooth traffic can be captured with the Network Analyzer.

You will find a few calls to LOG() in main function which will print some basic debugging information. To enable printf you need to switch to 1 the following define in app.h

/* DEBUG_LEVEL is used to enable/disable debug prints. Set to 0 to disable debug prints completely */
#define DEBUG_LEVEL 1

Once enabled you will see a boot message coming out of the WSTK COM Port after reset as shown below.

alt text

NOTE: When creating the project for a radio board all the UART pins will be configured correctly because the radio configuration is known. For an OPN you will see warnings after building the code prompting you to set the correct pin mappings in hal-config-board.h.

Disabling sleep

The example has sleep enabled by default but this can be easily disabled using the following define in app.h

/* Set this value to 1 if you want to disable deep sleep completely */
#define DISABLE_SLEEP 1

When running into issues during application development one good initial test is to disable sleep (if enabled) to see if the issues persist, as that may help narrow down the problem.

GATT database

The SoC-Empty has a minimal GATT database where you can start adding services and characteristics as your application requires. If your device will only be used as a GATT client then the existing database should be sufficient for most applications.

alt text

For more information on creating your custom GATT database please refer to UG365: GATT Configurator User’s Guide and UG118: Blue Gecko Bluetooth® Profile Toolkit Developer's Guide.

OTA support

The minimal GATT database includes the Silicon Labs OTA service and in app.c you will find the handling for the OTA control characteristic which allows putting the device into OTA DFU mode. For more information on OTA (and UART) DFU please refer to AN1086: Using the Gecko Bootloader with the Silicon Labs Bluetooth® Applications.