The Bluetooth SoC-Empty example is a project that you can use as a template for any standalone Bluetooth application.
Note: this example expects a specific Gecko Bootloader to be present on your device. For details see the Troubleshooting section.
To learn the Bluetooth technology basics, see UG103.14: Bluetooth LE Fundamentals.
To get started with Silicon Labs Bluetooth and Simplicity Studio, see QSG169: Bluetooth SDK v3.x Quick Start Guide.
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. This skeleton can be extended with the application logic.
The development of a Bluetooth applications consist of three main steps:
- Designing the GATT database
- Responding to the events raised by the Bluetooth stack
- Implementing additional application logic
These steps are covered in the following sections. To learn more about programming an SoC application, see UG434: Silicon Labs Bluetooth ® C Application Developer's Guide for SDK v3.x.
The SOC-empty example implements a basic GATT database. GATT definitions (services/characteristics) can be extended using the GATT Configurator, which can be found under Advanced Configurators in the Software Components tab of the Project Configurator. To open the Project Configurator, open the .slcp file of the project.
To learn how to use the GATT Configurator, see UG438: GATT Configurator User’s Guide for Bluetooth SDK v3.x.
A Bluetooth application is event driven. The Bluetooth stack generates events e.g., when a remote device connects or disconnects or when it writes a characteristic in the local GATT database. The application has to handle these events in the sl_bt_on_event() function. The prototype of this function is implemented in app.c. To handle more events, the switch-case statement of this function is to be extended. For the list of Bluetooth events, see the online Bluetooth API Reference.
Additional application logic has to be implemented in the app_init() and app_process_action() functions. Find the definitions of these functions in app.c. The app_init() function is called once when the device is booted, and app_process_action() is called repeatedly in a while(1) loop. For example, you can poll peripherals in this function. To save energy and to have this function called at specific intervals only, for example once every second, use the services of the Sleeptimer. If you need a more sophisticated application, consider using RTOS (see AN1260: Integrating v3.x Silicon Labs Bluetooth Applications with Real-Time Operating Systems).
The SOC-Empty application is almost empty. It implements a basic application to demonstrate how to handle events, how to use the GATT database, and how to add software components.
- A simple application is implemented in the event handler function that starts advertising on boot (and on connection_closed event). This makes it possible for remote devices to find the device and connect to it.
- A simple GATT database is defined by adding Generic Access and Device Information services. This makes it possible for remote devices to read out some basic information such as the device name.
- The OTA DFU software component is added, which extends both the event handlers (see sl_ota_dfu.c) and the GATT database (see ota_dfu.xml). This makes it possible to make Over-The-Air Device-Firmware-Upgrade without any additional application code.
As described above, an empty example does nothing except advertising and letting other devices connect and read its basic GATT database. To test this feature, do the following:
- Build and flash the SoC-Empty example to your device.
- Make sure a bootloader is installed. See the Troubleshooting section.
- Download the EFR Connect smartphone app, available on iOS and Android.
- Open the app and choose the Bluetooth Browser.
- Now you should find your device advertising as "Empty Example". Tap Connect.
- The connection is opened, and the GATT database is automatically discovered. Find the device name characteristic under Generic Access service and try to read out the device name.
Note that Example Projects do not include a bootloader. However, Bluetooth-based Example Projects expect a bootloader to be present on the device in order to support device firmware upgrade (DFU). To get your application to work, you should either
- flash the proper bootloader or
- remove the DFU functionality from the project.
If you do not wish to add a bootloader, then remove the DFU functionality by uninstalling the Bootloader Application Interface software component -- and all of its dependants. This will automatically put your application code to the start address of the flash, which means that a bootloader is no longer needed, but also that you will not be able to upgrade your firmware.
If you want to add a bootloader, then either
-
Create a bootloader project, build it and flash it to your device. Note that different projects expect different bootloaders:
- for NCP and RCP projects create a BGAPI UART DFU type bootloader
- for SoC projects on Series 1 devices create a Bluetooth in-place OTA DFU type bootloader or any Internal Storage type bootloader
- for SoC projects on Series 2 devices create a Bluetooth Apploader OTA DFU type bootloader
-
or run a precompiled Demo on your device from the Launcher view before flashing your application. Precompiled demos flash both bootloader and application images to the device. Flashing your own application image after the demo will overwrite the demo application but leave the bootloader in place.
- For NCP and RCP projects, flash the Bluetooth - NCP demo.
- For SoC projects, flash the Bluetooth - SoC Thermometer demo.
Important Notes:
-
when you flash your application image to the device, use the .hex or .s37 output file. Flashing .bin files may overwrite (erase) the bootloader.
-
On Series 1 devices (EFR32xG1x), both first stage and second stage bootloaders have to be flashed. This can be done at once by flashing the -combined.s37 file found in the bootloader project after building the project.
-
On Series 2 devices SoC example projects require a Bluetooth Apploader OTA DFU type bootloader by default. This bootloader needs a lot of flash space and does not fit into the regular bootloader area, hence the application start address must be shifted. This shift is automatically done by the Apploader Support for Applications software component, which is installed by default. If you want to use any other bootloader type, you should remove this software component in order to shift the application start address back to the end of the regular bootloader area. Note, that in this case you cannot do OTA DFU with Apploader, but you can still implement application-level OTA DFU by installing the Application OTA DFU software component instead of In-place OTA DFU.
For more information on bootloaders, see UG103.6: Bootloader Fundamentals and UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.
Before programming the radio board mounted on the mainboard, make sure the power supply switch is in the AEM position (right side) as shown below.
UG103.14: Bluetooth LE Fundamentals
QSG169: Bluetooth SDK v3.x Quick Start Guide
UG434: Silicon Labs Bluetooth ® C Application Developer's Guide for SDK v3.x
You are always encouraged and welcome to report any issues you found to us via Silicon Labs Community.