AN975: Bluetooth® Application
Development with IAR
This document demonstrates how the Silicon Labs Bluetooth® stack can be used to
build customer applications on the novel Silicon Labs EFR32 chip with IAR Embedded
workbench.
The recommended software development flow for developing Bluetooth applications is
based on Silicon Labs Simplicity Studio. This application note describes an alternative
development flow, which is based on IAR Embedded Workbench for ARM.
For a description of the recommended development flow, see QSG108: Getting Started
with Silicon Labs’ Bluetooth® Software.
KEY POINTS
• Lists prerequisites.
• Describes Bluetooth® SDK.
• Discusses stack configuration.
• Offers SoC software design examples and
lists steps for adding a new service.
• Provides instructions on performing Overthe-Air (OTA) updates.
• Includes an acronym list.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4
AN975: Bluetooth® Application Development with IAR
Prerequisites
1. Prerequisites
The IAR example projects are built to support the following variants of EFR32 based radio boards:
• BRD4100A (Blue Gecko 10.5 dBm)
• BRD4151A (Mighty Gecko 19.5 dBm)
• BRD4153A (Mighty Gecko 13 dBm)
• BRD4300A (BGM111-A)
• BRD4301A (BGM113-A)
These examples were tested with the WSTK Main Board Controller Software Build 435. This firmware package or later must be installed on your WSTK.
IAR Embedded Workbench for ARM 7.60 or later is needed to build the EFR32 target application.
The Silicon Labs Bluetooth SDK containing the Bluetooth stack and the examples is also needed and can be downloaded through Simplicity Studio.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 1
AN975: Bluetooth® Application Development with IAR
Bluetooth SDK
2. Bluetooth SDK
The Bluetooth SDK supports a few different design architectures and development models. Software developers can decide whether
the device’s application software runs on a separate host (for example an MCU), in Network Co-Processor mode (NCP), or whether
they want to execute their application on-board the fully standalone EFR32 chips. For developing a single chip standalone system, customers can use the BASIC-style BGScript programming language, or write native C code on the EFR32 where the Bluetooth stack is
provided as a library. This application note describes a sample application, the Health Thermometer (HTM) service, which was designed to support developing single-chip System-on-Chip (SoC) software.
The HTM service can act as a Bluetooth peripheral and server able to communicate with any Bluetooth client device. For the client, we
recommend the Silicon Labs Blue Gecko application for iOS and Android platforms, which demonstrates all features of this application.
This document does not describe the Silicon Labs Bluetooth stack in detail. If interested, refer to the Bluetooth Smart Software API
Reference Manual.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 2
AN975: Bluetooth® Application Development with IAR
Stack Configuration
3. Stack Configuration
The Bluetooth stack has a number of configuration options and API functions associated with it. This section discusses these features.
3.1 API Functions
Several API functions are provided for interacting with the stack. These functions are prototyped in native_gecko.h and discussed
here.
gecko_init()
This function takes a single argument - a pointer to a gecko_configuration_t struct. Its purpose is to initialize the stack with the parameters provided in the struct. Initialization for a typical application looks like this:
This configuration reserves sufficient memory for four simultaneous connections, enables sleep mode, and disables the flags for the
stack's special features that go beyond the scope of this application note.
gecko_wait_event()
This is a blocking function that waits for an event to be sent by the stack. Once an event has been received, a pointer to a gecko_cmd_p
acket struct is returned.
gecko_peek_event()
This is a non-blocking function similar to gecko_wait_event(). If an event is found, a pointer to the gecko_cmd_packet struct is returned, otherwise NULL is returned.
gecko_event_pending()
This function checks to see if any events are pending. If an event is found, the function returns non-zero to indicate that the event
should be processed by either gecko_peek_event() or gecko_wait_event(). If no event is found, zero is returned.
gecko_can_sleep_ms()
This function is used to determine how long in milliseconds the stack can sleep. The return value is the number of milliseconds the
stack can sleep. If sleep is not possible, zero is returned.
gecko_sleep_for_ms()
This function is used to put the stack to sleep for a maximum number of milliseconds. This number is set in the single parameter taken
by this function. The return value is the number of milliseconds actually slept. It is possible that the stack will awaken due to an external
event.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 3
AN975: Bluetooth® Application Development with IAR
Stack Configuration
Important Note on Blocking Wait
Currently, scheduling is handled completely by the Bluetooth stack. The gecko_wait_event() function in the main loop only returns if
the stack receives a Bluetooth event, which means the timer event feature of the stack must be used for scheduling user-specific tasks.
Use the gecko_peak_event() function if the blocking wait does not fit your application.
Examples
The following examples demonstrate two methods for processing events from the stack. The first uses the blocking wait_for_event()
method. In this example, the application simply waits until an event has been received from the stack and then processes it. Since this
example relies on events from the Bluetooth stack, a recurring timer is started in the reset event to allow the application to perform a
task unrelated to the Bluetooth stack, such as gathering temperature data every 100 ms.
The second example uses the gecko_event_pending() API function. In this case, the application checks to see if any event is waiting
to be processed. If an event is waiting it is processed, otherwise the event processing section is skipped. Next, gecko_can_sleep_for_
ms() is called to determine how long the stack can be put to sleep. If the time is longer than 10 ms then the stack is put to sleep for the
maximum time found by gecko_can_sleep_for_ms().
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 4
AN975: Bluetooth® Application Development with IAR
SoC Examples
4. SoC Examples
The soc-thermometer sample application implements the Health Thermometer (HTM) service. Acting as a server, it sends simulated
temperature measurement values. The service is intended for healthcare and fitness applications. This service demonstrates how information can be transferred from server to client.
4.1 Software Design
The system is built on top of the Silicon Labs Bluetooth stack, the Silicon Labs energyAware Drivers and Peripheral Support, which are
provided as libraries (see the figure below).
Figure 4.1. Architecture of the Example Application
This application note only describes the topmost layer of this architecture.
The application itself must be generated with Simplicity Studio even if the preferred IDE is IAR Embedded Workbench, whereas its dependencies on other modules are listed in other folders (lib, CMSIS, Device, emlib, emdrv) in the root of the SDK.
To open and edit a source code example in Simplicity Studio:
1. Verify that your WSTK is detected and the Bluetooth SDK is the preferred SDK.
2. From the Launcher page, select one of the Software examples in the middle column. It will be loaded to the Simplicity Studio IDE.
3. Click [Generate] in the upper right to generate a hardware configuration file for the connected kit or part.
4. To build the project, open the Project menu and select Build project.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 5
AN975: Bluetooth® Application Development with IAR
SoC Examples
The sample application consists of the following files:
Libraries:
binstack.o
Bluetooth stack host library. This is the core of the Bluetooth stack.
binbootloader.o
Bootloader for the application.
stack.a
Provides access to the GATT database, connection management services, and interfaces to the application through command-respond pairs and events.
emlib
Silicon Labs Peripheral Support library for the EFM32 series of microcontrollers and for the EFR series of RF transceivers and System-On-Chip devices, delivered as source code.
Gattdb:
thermometer.bgproj
XML configuration file describing the GATT database.
Before building the project, the bgbuild tool must generate gattdb.c and gattdb.h from the bgproj
file. This is performed automatically by a custom build option when building the project.
gattdb.c / gattdb.h
Generated source files from thermometer.bgproj. These files are used for accessing the GATT
entries by the application.
Include:
Header files for the stack (stack.a) library.
aat.h
Application address table header file containing addresses needed by the bootloader.
Application Source Code:
main.c
The main body of the application that initializes the Bluetooth stack as well as the endless loop that
initializes and periodically calls the stack and the application.
InitDevice.c
Contains device-specific low level init functions for default mode.
SupervisorInitDevice.c
Contains device-specific low level init functions for supervisor mode.
For a detailed description of the application software, refer to the Bluetooth Smart Software API Reference Manual.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 6
AN975: Bluetooth® Application Development with IAR
SoC Examples
4.2 Steps for Adding a New Service
1. Open the IAR Embedded workbench workspace file iar\examples.eww. In the main.c file, the configuration parameters can be
updated in the static const gecko_configuration_t config variable.
The following parameters can be set:
• UART parameters
• I2C parameters:
•
•
•
•
•
• If you want to add I2C communication for your project, you can enable it here and set the signal location according to the
EFR32 datasheet.
GPIO parameters:
• The initial configuration of GPIO ports can be configured.
GATT Database:
• Dynamically switch your GATT database run-time.
High/Low Frequency Oscillator parameters (HFXO, LFXO)
DC/DC regulator parameters
Oscillator tuning capacitance (Ctune) value
2. Modify gatt_db.bgproj to add your service to the GATT database.
Figure 4.2. thermometer.bgproj
Below is an example service definition code snippet which can be added to the .bgproj file.
<!-- My service -->
<service uuid="f6ec37db-bda1-46ec-a43a-6d86de88561d" advertise="true">
<description>My Service</description>
<characteristic buuid="af20fbac-2518-4998-9af7-af42540731b3" id="my_data">
<!-- my data -->
<properties write="true" indicate="true" />
<value type="hex" length="20" user="true" />
</characteristic>
</service>
For a detailed user’s guide for the GATT database definition, .bgproj file syntax and functionality, refer to the UG118: Blue Gecko
Bluetooth® Profile Toolkit Developer User's Guide. For the correct service UUIDs, refer to www.bluetooth.org.
3. Build your application by pressing F7. By building the application the .bgproj service definition is used to generate the c source
version of the service configuration (gatt_db.c and gatt_db.h), and the tagged fields’ ID will be accessible from the code through
gatt_db.h.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 7
AN975: Bluetooth® Application Development with IAR
SoC Examples
Figure 4.3. gatt_db.h
4. Silicon Labs recommends that you create a new group for your service.
Figure 4.4. Add Group
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 8
AN975: Bluetooth® Application Development with IAR
SoC Examples
5. Now you can implement the new service in your source files. The example service below prints out the characteristic value to
STDOUT (the terminal I/O window in the IAR debugger).
/* my_service.c */
/* BG stack headers */
#include "bg_types.h"
#include "gatt_db.h"
#include "native_gecko.h"
#include "infrastructure.h"
/* Own header*/
#include "my_service.h"
/* header for printf */
#include <stdio.h>
void AttrValueChanged_my_data(uint8array *value)
{
int i;
for (i = 0; i < value->len; i++)
{
printf("my_data[%d] = 0x%x \r\n",i,value->data[i]);
}
printf("\r\n");
}
The header file for the service is shown below:
/* my_service.h*/
#ifndef MY_SERVICE_H
#define MY_SERVICE_H
#include "native_gecko.h"
void AttrValueChanged_my_data(uint8array *value);
#endif /* MY_SERVICE_H */
6. Once the service implementation .c file is ready, add it to the IAR project, as shown below.
Figure 4.5. Add Files to Group
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 9
AN975: Bluetooth® Application Development with IAR
SoC Examples
7. Add your header file's path to IAR. Open [Options]→[C/C++ Compiler]→[Preprocessor], and browse for your header file.
Figure 4.6. Add Header File Path
8. Include your service header file in main.c. Now you can extend the main.c to react to Bluetooth events. Main.c must be inspected
if the particular event is handled. The event names can be looked up from the Bluetooth API Reference. Add the event ID-event
handler function to main.c.
A possible extension of the event handler may look like this:
/* Value of attribute changed from the local database by remote GATT client */
case gecko_evt_gatt_server_attribute_value_id:
/* Check if the event is because “my_data” changed by the remote GATT client */
if(gattdb_my_data == evt->data.evt_gatt_server_attribute_value.attribute)
{
/* Call my handler */
AttrValueChanged_my_data(&(evt->data.evt_gatt_server_attribute_value.value));
}
break;
9. Rebuild your project and click [Download and Debug] to test it.
For testing, the Silicon Labs Blue Gecko app for iOS or Android can be used.
1. Select the [BLE Stack & Profile Test] option from the welcome screen.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 10
AN975: Bluetooth® Application Development with IAR
SoC Examples
Figure 4.7. BLE Stack & Profile Test in Blue Gecko App
2. The application begins searching for devices; your kit should appear as a connectable device. Tap the device ID.
Figure 4.8. Blue Gecko App Found Devices
3. The application then discovers the GATT database. If ready, the new service will appear. Tap the service.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 11
AN975: Bluetooth® Application Development with IAR
SoC Examples
Figure 4.9. New Example Service in GATT
4. To write some data to the characteristic, In the iOS app tap [Edit] or in the Android tap the pen icon. Enter the value, and tap
[Save] to send the value over BLE.
Figure 4.10. Sending "Hello World" Over BLE
5. The example service will print the received data values to the terminal I/O window. In the view menu of the IAR debugger, select
terminal I/O.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 12
AN975: Bluetooth® Application Development with IAR
SoC Examples
Figure 4.11. Terminal Output
Now you can see the data entered on the mobile device. You have successfully implemented your first custom Bluetooth service.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 13
AN975: Bluetooth® Application Development with IAR
Over the AIR (OTA) Updates
5. Over the AIR (OTA) Updates
One of the possibilities with the Silicon Labs Bluetooth stack is to update the firmware over the Bluetooth connection. It is possible to
update the user application alone or the user application and Bluetooth stack together. This section describes how to accomplish this.
5.1 Adding OTA Support
In order to have support for OTA updates, the following service must be in the bgproj file.
This service is already included in the thermometer example so there is no need to add it. In the section of the application that processes events, handling for the user write request event is required.
Calling gecko_cmd_system_reset(1) causes the device to reboot into device firmware update (DFU) mode. This section of code is
also included in the thermometer example.
5.2 Creating DFU Files
In order to update the device firmware, it is necessary to create an image that the OTA client can recognize. This is done with the dfu
tool. Running the following command creates two files, app.dfu and full.dfu.
..\..\bin\dfutool.exe Debug\Exe\thermometer.elf
These files contain the user application and the user application + Bluetooth stack, respectively.
5.3 Performing OTA Updates
The process of performing OTA updates is detailed in this knowledge base article:
http://community.silabs.com/t5/Wireless-Knowledge-Base/OTA-DFU-host-example-for-Blue-Gecko/ta-p/171696
Please follow these instructions to update your firmware via OTA.
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 14
AN975: Bluetooth® Application Development with IAR
List of Acronyms
6. List of Acronyms
ATT
Attribute Protocol
BLE
Bluetooth Low Energy (also known as Bluetooth Smart)
BSP
Board Support Package
GAP
Generic Access Profile
GATT
Generic Attribute Profile
Glib
Graphics Library
HTM
Health Thermometer Module
IA
Immediate Alert
IAR EWARM
IAR Embedded Workbench for ARM
L2CAP
Logical Link Control and Adaptation Protocol
LCD
Liquid Crystal Display
OTA
Over the Air
PB
Push Button
SMP
Security Manager Protocol
SoC
System On Chip
UUID
Universally Unique Identifier
WSTK
Wireless Starter Kit
silabs.com | Smart. Connected. Energy-friendly.
Rev. 0.4 | 15
Smart.
Connected.
Energy-Friendly.
Products
Quality
www.silabs.com/products
www.silabs.com/quality
Support and Community
community.silabs.com
Disclaimer
Silicon Labs intends to provide customers with the latest, accurate, and in-depth documentation of all peripherals and modules available for system and software implementers using or
intending to use the Silicon Labs products. Characterization data, available modules and peripherals, memory sizes and memory addresses refer to each specific device, and "Typical"
parameters provided can and do vary in different applications. Application examples described herein are for illustrative purposes only. Silicon Labs reserves the right to make changes
without further notice and limitation to product information, specifications, and descriptions herein, and does not give warranties as to the accuracy or completeness of the included
information. Silicon Labs shall have no liability for the consequences of use of the information supplied herein. This document does not imply or express copyright licenses granted
hereunder to design or fabricate any integrated circuits. The products are not designed or authorized to be used within any Life Support System without the specific written consent of
Silicon Labs. A "Life Support System" is any product or system intended to support or sustain life and/or health, which, if it fails, can be reasonably expected to result in significant
personal injury or death. Silicon Labs products are not designed or authorized for military applications. Silicon Labs products shall under no circumstances be used in weapons of mass
destruction including (but not limited to) nuclear, biological or chemical weapons, or missiles capable of delivering such weapons.
Trademark Information
Silicon Laboratories Inc.® , Silicon Laboratories®, Silicon Labs®, SiLabs® and the Silicon Labs logo®, Bluegiga®, Bluegiga Logo®, Clockbuilder®, CMEMS®, DSPLL®, EFM®,
EFM32®, EFR, Ember®, Energy Micro, Energy Micro logo and combinations thereof, "the world’s most energy friendly microcontrollers", Ember®, EZLink®, EZRadio®, EZRadioPRO®,
Gecko®, ISOmodem®, Precision32®, ProSLIC®, Simplicity Studio®, SiPHY®, Telegesis, the Telegesis Logo®, USBXpress® and others are trademarks or registered trademarks of
Silicon Labs. ARM, CORTEX, Cortex-M3 and THUMB are trademarks or registered trademarks of ARM Holdings. Keil is a registered trademark of ARM Limited. All other products or
brand names mentioned herein are trademarks of their respective holders.
Silicon Laboratories Inc.
400 West Cesar Chavez
Austin, TX 78701
USA
http://www.silabs.com