UG136: Silicon Labs Bluetooth Smart SoC Application Developer's Guide

UG136: Silicon Labs Bluetooth Smart SoC Application Developer's Guide The Silicon Labs Bluetooth Smart C-SDK and Silicon Labs development tools allow developers to quickly and easily customize and test Bluetooth Smart applications on Silicon Labs development kits or custom hardware. This guide provides background on using these tools for different purposes. KEY FEATURES Plugin Descriptions Application structures How to use an existing profile with custom hardware. How to modify a profile. How to use the Bluetooth Smart stack with a custom application. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2

Getting Started 1. Getting Started This guide assumes that you have already performed the initial software and hardware setup and configuration steps as described in QSG120, Silicon Labs AppBuilder-Based Bluetooth Smart C-SDK Quick Start Guide. These steps include: 1. Purchased your Wireless Starter Kit. 2. Downloaded and installed the required software components, including: The Simplicity Studio development environment The Silicon Labs Bluetooth Smart C-SDK IAR Embedded Workbench for ARM 7.30, used as a compiler in the Simplicity Studio development environment Updated your WSTK firmware with KIT Manager Other tools required for developing in NCP mode 3. Configured Simplicity Studio for your hardware and software. 4. Familiarized yourself with compiling and flashing a sample application. 1.1 NCP and SoC Bluetooth Smart Applications The Bluetooth Smart C-SDK allows you to develop System-On-Chip (SoC) software applications on a single microcontroller in C language, and it also supports interfacing an external host microcontroller to another microcontroller (Network Co-Processor, NCP) running the Bluetooth Smart stack over a UART interface using the C language BGAPI protocol. Additional information about the Bluetooth Smart Stack, the BGAPI protocol, and the software architecture is provided in QSG108, Blue Gecko Bluetooth Smart Software Quick-Start Guide. 1.2 Definitions In Bluetooth Smart, the following terms are used: Characteristic: A set of data including a value and properties such as declarations and descriptors. Service: A collection of characteristics and relationships to other services that encapsulate the behavior of part of a device. Profile: A high level definition that determines how services are used to enable an application or use case. Bluetooth profiles specify general behaviors that Bluetooth-enabled devices use to communicate with other Bluetooth devices. At a minimum, each Bluetooth profile contains information on the following topics: Dependencies on other profiles Suggested user interface formats Specific parts of the Bluetooth protocol stack used by the profile. To perform its task, each profile uses particular options and parameters at each layer of the stack Device: A combination of hardware and software that operates according to a Bluetooth profile. Application Framework: A body of Silicon Labs code that sits on top of the Bluetooth Smart stack, consumes the stack handler interface, and exposes its own more highly abstracted interface to the developer. Simplicity Studio Application Builder (AppBuilder) is used to configure application framework code. Plugin: An implementation of a piece of functionality within the application framework. Plugins are customizable through plugin options in AppBuilder, and extendable through the framework s callback interface. Project: The files generated by AppBuilder that can be compiled into a binary that in turn can be loaded onto the target device. The project includes customized header files and array definitions in C code to represent the desired application behavior. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 1

Plugin Descriptions 2. Plugin Descriptions The Silicon Labs Bluetooth Smart SDK libraries offer a number of plugins that allow you to customize your application. 2.1 Plugins for Bluetooth Smart services 2.1.1 Standard Bluetooth Smart Services Generic Access Service GAP Plugin The Generic Access Service contains generic information about the device. The following characteristics are supported: Device Name: The device name that appears in advertisements. The device will be listed with this name on scanning Bluetooth Smart devices. By default, this name will be generated from the Bluetooth Smart MAC address to assure uniqueness. This name can be overwritten be a plugin option of this plugin. Appearance: The external appearance of this device, which can be set by a plugin option. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 2

Plugin Descriptions Device Information Service Device Information Plugin The Device Information Service exposes manufacturer and/or vendor information about a device. All characteristics are read-only, and their value can be supported by plugin options. The following characteristics are supported: Manufacturer Name String: This characteristic represents the name of the manufacturer of the device. Model Number String: This characteristic represents the model number that is assigned by the device vendor. Serial Number String: This characteristic represents the serial number for a particular instance of the device. Hardware Revision String: This characteristic represents the hardware revision for the hardware within the device. Firmware Revision String: This characteristic represents the firmware revision for the firmware within the device. Software Revision String: This characteristic represents the software revision for the software within the device. System ID: This characteristic represents a structure containing an Organizationally Unique Identifier (OUI) followed by a manufacturer-defined identifier and is unique for each individual instance of the product. IEEE 11073-20601 Regulatory Certification Data List: This characteristic represents regulatory and certification information for the product in a list defined in IEEE 11073-20601. PnP ID: The PnP ID characteristic is a set of values used to create a device ID value that is unique for this device. Battery Service - Battery Plugin The Battery Service exposes the state of a battery within a device. The following characteristics are supported: Battery Level: The Battery Level characteristic is read using the GATT Read Characteristic Value sub-procedure and returns the current battery level as a percentage from 0% to 100%; 0% represents a battery that is fully discharged, 100% represents a battery that is fully charged. Callbacks: A new battery measurement value is available, where batterylevel = battery level in percent. void emberafpluginbattmeasavailablecallback(uint8_t batterylevel) Battery Measurement Indications have been switched on. void emberafpluginbattindicationsoncallback(void) silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 3

Plugin Descriptions Health Thermometer Service - Health Thermometer Plugin The Health Thermometer service exposes temperature and other data from a thermometer intended for healthcare and fitness applications. The following characteristics are supported: Temperature Measurement: The Temperature Measurement characteristic is a variable length structure containing a Flags field, a Temperature Measurement Value field and, based upon the contents of the Flags field, optionally a Time Stamp field and/or a Temperature Type field. These optional fields, and the temperature unit can be switched on/off with plugin options. Temperature Type: This characteristic is used to describe the type of temperature measurement in relation to the location on the human body at which the temperature was measured. Characteristic can be turned on by enabling Temperature Type, and setting Location of Temperature Type to In Temperature Type Char. If this option is set to In Temperature Measurement Char, then Temperature Type will be part of the Temperature Measurement Characteristic. Its value can also be set here. Measurement Interval: This characteristic is used to enable and control the interval between consecutive temperature measurements. A default value can be given here, which can be also modified at run-time with GATT characteristic write commands. The new value will only be accepted if it is within the bounds that are also specified here. If this option is not selected, then 1 sec will be used as default value. Callbacks: A new temperature measurement value is available, where temperature = measured temperature value in Celsius. void emberafplugintempmeasavailablecallback(float temperature) Temperature Measurement Indications have been switched on. void emberafplugintempindicationsoncallback(void) silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 4

Plugin Descriptions Immediate Alert Service - Immediate Alert Plugin This service exposes a control point to allow a peer device to cause the device to immediately alert. The following characteristics are supported: Alert Level: The Alert Level characteristic is a control point that allows a peer to command this device to alert to a given level. If the written alert level is No Alert, no alerting is done on this device. If the written alert level is Mild Alert, the device alerts. If the written alert level is High Alert, the device alerts in the strongest possible way. In the current callback implementation Alert Levels influence the blinking frequency of LEDs and they are displayed on screen (WSTK LCD for SoC, and terminal screen for NCP-host). Callbacks: No Alert received void emberafpluginianoalertcallback(void) Low Alert received void emberafpluginialowalertcallback(void) High Alert received void emberafpluginiahighalertcallback(void) Link loss Service - Link Loss Plugin This service defines behavior (alert level) when a link is lost between two devices. The following characteristics are supported: Alert Level: The Alert Level characteristic is used to expose the current link loss alert level that determines how the device alerts when the link is lost. This alert continues until one of following conditions occurs: An implementation-specific timeout User interaction on this device A new alert level is written The physical link is disconnected When the link is lost, and the current link loss alert level is No Alert, no alerting is done on this device. When the link is lost, and the current link loss alert level is Mild Alert, the device alerts. When the link is lost, and the current link loss alert level is High Alert, the device alerts in the strongest possible way. In the current callback implementation Alert Levels are displayed on screen (WSTK LCD for SoC, and terminal screen for NCPhost). Callbacks: No Alert received void emberafpluginllnoalertcallback(void) Low Alert received void emberafpluginlllowalertcallback(void) High Alert received void emberafpluginllhighalertcallback(void) silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 5

Plugin Descriptions Cycling Power Service - Cycling Power Plugin This service exposes power- and force-related data and optionally speed- and cadence-related data from a Cycling Power sensor intended for sports and fitness applications. The following characteristics are supported: Cycling Power Measurement: The Cycling Power Measurement characteristic is a variable length structure containing a Flags field, an Instantaneous Power field and, based on the contents of the Flags field, may contain one or more additional fields, which can be turned on and off using plugin options. Pedal Power Balance Present: If present: Pedal Power Balance Reference Accumulated Torque Present: If present: Accumulated Torque Source Wheel Revolution Data Present Crank Revolution Data Present Extreme Force Magnitudes Present Extreme Torque Magnitudes Present Extreme Angles Present Top Dead Spot Angle Present Bottom Dead Spot Angle Present Accumulated Energy Present Cycling Power Feature: The CP Feature characteristic is used to report a list of features supported by the device. Pedal Power Balance Accumulated Torque Wheel Revolution Data Extreme Magnitudes Extreme Angles Top and Bottom Dead Spot Angle Accumulated Energy Sensor Location: The Sensor Location characteristic is used to expose the location of the sensor, which can be set by a plugin option. Cycling Power Vector: The Cycling Power Vector characteristic is a variable length structure containing a Flags field and one or more additional fields, which can be turned on and off using plugin options. First Crank Measurement Crank Revolution Instantaneous Force Magnitude Array Instantaneous Torque Magnitude Array Instantaneous Measurement Direction silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 6

Plugin Descriptions Cycling Power Control Point: The Cycling Power Control Point characteristic is used to request a specific function to be executed on the receiving device. The following functions are supported: Set Cumulative Value: Initiate the procedure to set a cumulative value. The new value is sent as parameter following the op code. Request Sampling Rate: Request the sampling rate value set in the Sensor Callbacks: A new cyclic power measurement value is available, where cpmeas = measured cyclic power. void emberafplugincpmeasavailablecallback(cpcyclicpowermeas_t cpmeas) Cyclic Power Measurement Notifications have been switched on. void emberafplugincpnotificationsoncallback(void) A new cyclic power vector value is available, where cpvect = measured cyclic power vector. void emberafplugincpvectormeasavailablecallback(cpcyclicpowervector_t cpvect) Cyclic Power Measurement Notifications have been switched on. void emberafplugincpvectornotificationsoncallback(void) Cyclic Power Measurement Control Point has been received, where opcode = op code of the control point command. void emberafplugincpcontrolpointwrittencallback(uint8_t opcode) Cycling Speed and Cadence Service - Cycling Speed and Cadence Plugin This service exposes speed-related and cadence-related data from a CSC (Cycling Speed and Cadence) sensor intended for fitness applications. The following characteristics are supported: CSC Measurement: The CSC Measurement characteristic is a variable length structure containing a Flags field and, based on the contents of the Flags field, may contain one or more additional fields, depending on what is supported by the device in the CSC Feature characteristic. CSC Feature: The CSC Feature characteristic is used to describe the supported features of the Server, which can be controlled with plugin options. Wheel Revolution Data Crank Revolution Data SC Control Point: The SC Control Point characteristic is used to request a specific function to be executed on the receiving device. The following functions are supported: Set Cumulative Value: Initiate the procedure to set a cumulative value. The new value is sent as parameter following the op code. Callbacks: A new CSC measurement value is available, where cscmeas = measured CSC value. void emberafplugincscmeasavailablecallback(cscmeas_t cscmeas) CSC Measurement Notifications have been switched on. void emberafplugincscnotificationsoncallback(void) CSC Measurement Control Point has been received, where opcode = op code of control point command. void emberafplugincsccontrolpointwrittencallback(uint8_t opcode) silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 7

Plugin Descriptions Heart Rate Service - Heart Rate Plugin This service exposes heart rate and other data from a Heart Rate Sensor intended for fitness applications. The following characteristics are supported: Heart Rate Measurement: This characteristic is used to send a heart rate measurement. Based on the contents of the Flags field, may contain one or more additional fiulds: Sensor Contact Status Energy Expended Status RR-Interval The format of the Heart Rate Measurement Value can also be specified with plugin options. Body Sensor Location: The Body Sensor Location characteristic of the device is used to describe the intended location of the heart rate measurement for the device, which can be set using a plugin option. Heart Rate Control Point: The Heart Rate Control Point characteristic is used to request a specific function to be executed on the receiving device. The following functions are supported: Reset Energy Expended: Resets the value of the Energy Expended field in the Heart Rate Measurement characteristic to 0. Callbacks: A new Heart Rate measurement value is available, where hrmeasval = measured heart rate value. void emberafpluginhrmeasavailablecallback(uint16_t hrmeasval) Heart Rate Measurement Notifications have been switched on void emberafpluginhrnotificationsoncallback(void) Tx Power Service - Tx Power Plugin This service exposes a device s current transmit power level when in a connection. The following characteristics are supported: Tx Power Level: The Tx Power Level characteristic represents the current transmit power level of a physical layer for which the characteristic is associated. The initial value of the transmit power can be specified by a plugin option. The Bluetooth Smart stack can only set discrete transmit power levels, but it will tend to set the closest possible power level. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 8

Plugin Descriptions HID over GATT Service - HID over GATT Plugin The HID Service exposes characteristics required for an HID Device to transfer HID report descriptors and reports to a HID Host. This also exposes the characteristics for an HID Host to write to a Device. The plugin is not intended to provide a full-featured configurable service. Rather, it provides a demonstration of how such a service can be implemented. The demonstration works differently on the SoC and NCP-host platforms. On the SoC platform, due to the unavailability of a keyboard, a left button push on the WSTK will trigger the text that was written in the plugin option to appear on the HID Host. On the NCP-host platform, after connection, the text typed on the NCP Host will appear on the HID Host. The following characteristics are supported: Protocol Mode: The Protocol Mode characteristic is used to expose the current protocol mode of the HID Service with which it is associated, or to set the desired protocol mode of the HID Service. Report: The Report characteristic is used to exchange data between a HID Device and a HID Host. Report Map: The Report Map characteristic value contains formatting and other information for Input Report, Output Report, and Feature Report data transferred between an HID Device and HID Host. Boot Keyboard Input Report: The Boot Keyboard Input Report characteristic is used to transfer fixed format and length Input Report data between a HID Host operating in Boot Protocol Mode and a HID Service corresponding to a boot keyboard.. HID Information: The HID Information characteristic is used to hold a set of values known as the HID Device s HID Attributes HID Control Point: The HID Control Point characteristic is a control-point attribute that defines the following HID Commands when written: Suspend Exit Suspend Callbacks: A characer is about to be sent out, where CharCode = ASCII code of the character to be sent. void emberafpluginhidsendnewcharcallback(uint8_t CharCode) 2.1.2 Proprietary Bluetooth Smart Services Cable Replacement Server Service - Cable Replacement Server Plugin The Cable Replacement Server Plugin implements the proprietary Cable Replacement Service to demonstrate how two devices can exchange data over a Bluetooth Smart link. The Client Device must use the Cable Replacement Client Plugin. For further descriptions please refer to the Cable Replacement Profile. Callbacks: Cable Replacement Server received data from Client, where character = the character that was received by the Server. void emberafplugincableserverdata2servercallback(char character) Cable Replacement Server is about to send data to Client, where character = the character to be sent to the Client. void emberafplugincableserverdata2clientcallback(char character) Cable Replacement Server Characteristic Value has been changed, where clientconfig = new value of Client Characteristic Configuration Descriptor Value (CCCD). void emberafplugincableservercharstatuschangecallback(uint16_t clientconfig) silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 9

Plugin Descriptions 2.1.3 Client-Specific Services Cable Replacement Client Service - Cable Replacement Client Plugin The Cable Replacement Client Plugin implements the proprietary Cable Replacement Service to demonstrate how two devices can exchange data over a Bluetooth Smart link. For further descriptions please refer to the Cable Replacement Profile. Callbacks: Cable Replacement Client is about to send a new character to the Cable Replacement Server, where character = the character to be sent. void emberafplugincableclientdata2servercallback(char character) Cable Replacement Client has received a new character, where character = the character that was received. void emberafplugincableclientdata2clientcallback(char character) Cable Replacement Client Notifications enabled. void emberafplugincableclientnotificationsenabledcallback(void) Apple Notification Center - Apple Notification Center Plugin The Apple Notification Center Service (ANCS) gives Bluetooth Smart accessories that connect to ios devices through a Bluetooth Smart link a simple and convenient way to access many kinds of notifications generated on ios devices. An accessory acting as a GATT client is free to access and use other services provided by the ios device while using the ANCS. The example implements the Notification Consumer (Client) Role in the Apple Notification Center Service. Callbacks: Characteristic value received, where anccategoryid = the ANC Category ID, and anccategorycount = the current number of active ios notifications in the given category. void emberafpluginanccharvaluereceivedcallback(uint8_t anccategoryid, uint8_t anccategorycount) silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 10

Plugin Descriptions 2.2 Plugins for Other Bluetooth Smart Features 2.2.1 Server-Specific Features Advertisement Plugin This plugin can be used to set Bluetooth Smart advertisement parameters. It will start advertising the selected services (the gatt_db.c database) with the specified parameters (minimum and maximum advertising interval) from the plugin options. It is possible to change advertising parameters or stop advertising after a specified time (Duration of first period of advertising). The new advertising parameters for the second period of advertising can also be given. If the advertising should stop, then Duration of second period of advertising should be set to zero. For indefinite advertising time, the duration of the first or second advertising period must be set to 16383. It is also possible to manually set the advertising and scan response content using: void advinitcustomadvertising(uint8_t datalen, uint8_t *pdata, uint8_t scandatalen, uint8_t *pscandata) and start advertising using: void advswitchadvmessage(void) In this case the Overwrite default GATT table based advertisement with custom advertising content plugin option must be checked. Callbacks: Advertising started. void emberafpluginadvertisingstartedcallback(void) Advertising stopped. void emberafpluginadvertisingstoppedcallback(void) Connection Plugin This plugin has the option to initiate the pairing and bonding process automatically, as soon as the connection is made. It is also possible that encryption is made with the pairing option unchecked if the other party initiates encryption, or Insufficient Authentication is returned from the Server (provided the device is in the Client Role) silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 11

Plugin Descriptions Callbacks: Connection started. void emberafpluginconnectionopenedeventcallback(void) Connection terminated. void emberafpluginconnectionterminatedeventcallback(void) Beacon Plugin This plugin broadcasts non-connectable advertisement messages, called beacons, based on the specification of the most widely known beacon formats: ibeacons, EddyStone, and AltBeacon. ibeacon AirLocate: A beacon protocol developed by Apple. A universally unique identifier is sent to all scanning devices in the proximity, where the reception of the UUID can trigger an action. The following parameters can be specified: Beacon advertisement interval Option to transmit fixed TX power information as opposed to the sensed value Major Value Minor Value altbeacon: An Open source Proximity Beacon Specification authored by Radius Networks. The following parameters can be specified: Beacon advertisement interval Option to transmit fixed TX power information as opposed to the sensed value Major Value Minor Value EddyStone: Eddystone is a Bluetooth Smart beacon profile released by Google. Beacon advertisement interval Option to transmit fixed TX power information as opposed to the sensed value Supported EddyStone frame types: EddyStone-URL: The Eddystone-URL frame broadcasts an URL, which can be specified as a plugin option. EddyStone-UID: The Eddystone-UID frame broadcasts an opaque, unique 16-byte Beacon ID composed of a 10-byte namespace (NID) and a 6-byte instance (BID). These can be specified as plugin options. EddyStone-TLM: Eddystone beacons may transmit Telemetry data about their own operation to clients, like measured battery voltage, temperature, time since boot-up and advertised frame count. The advertisement interval of EddyStone-TLM frames can also be specified as a plugin option. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 12

Plugin Descriptions Callbacks: Beaconing started void emberafpluginbeaconingstartedcallback(void) silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 13

Plugin Descriptions 2.2.2 Client-Specific Features Service Discovery Plugin This plugin discovers all services and characteristics of the Server. Callbacks: Service Discovery completed. void emberafplugindiscoverycompletedcallback(void) Central Plugin This plugin turns on scanning mode in the Device, and monitors the Device name in advertisement and scan response packets. The following scanning parameters can be specified as plugin options: Scan Interval Scan window Scan type (Active/Passive) In passive scanning mode the module only listens for advertising packets and will not transmit any packet. In active scanning mode the module will send out a scan request packet upon receiving advertising packet from a remote device and then it will listen for the scan response packet from remote device Minimum connection interval Maximum connection interval Slave latency Supervision timeout A connection is initiated if a Device with the name specified as a plugin option is found. 2.3 Plugins for Bluetooth Smart Utilities 2.3.1 Code Correlation Plugin This plugin enables Code Correlation for the Simplicity Energy Profiler. Code Correlation is the functionality that allows you to profile and view energy consumption in an application by its functions as it executes in real time. Code Correlation also allows you to select a sample point in the Energy Profiler's graph view and view the source code line that was executed at that time by the processor. This will allow a software developer to see which parts of the executed code use the most energy, and thereby find and fix bugs and optimize the code for energy consumption. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 14

Plugin Descriptions 2.3.2 Idle/Sleep Plugin Silicon Labs implementation of sleeping. This plugin can be used on devices that should deep sleep. The plugin will attempt to put the device in deep sleep (EM2) when possible. The application can control sleeping through callbacks that it may implement. The minimum sleep duration can be specified as a plugin option. Callbacks: Is it Ok to sleep? where durationms = the requested sleep duration in milliseconds. bool emberafpluginidlesleepoktosleepcallback(uint32_t durationms) Wake up, where durationms = the length of time the device slept in milliseconds. void emberafpluginidlesleepwakeupcallback(uint32_t durationms) 2.3.3 PTI This plugin enables the usage of Network Analyzer to capture and decode Bluetooth Smart frames. The corresponding pin locations are to be specified as plugin options. 2.4 Application-Specific Plugins 2.4.1 Bluetooth Smart Demo Application Application core modules. 2.4.2 Bluetooth Smart Demo Application, HW Abstraction Hardware specific modules of the application. 2.5 Platform-Specific Plugins 2.5.1 Bluetooth Smart Platform Platform core modules. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 15

Plugin Descriptions 2.5.2 Bluetooth Smart Platform, HW Abstraction Hardware-specific modules of the platform. Callbacks: Main Stack Init on EFR32 void emberafmainefr32stackinitcallback(void) Main Application Init on EFR32 void emberafmainefr32appinitcallback(void) Main Stack Init on Host int emberafmainhoststackinitcallback(int argc, char* argv[]) Main Application Init on Host void emberafmainhostappinitcallback(void) Main Stack Tick void emberafmainstacktickcallback(void) Main Application Tick void emberafmainapptickcallback(void) silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 16

Sample Applications and AppBuilder 3. Sample Applications and AppBuilder 3.1 Sample Application Architecture The figure below shows the architecture of any Bluetooth Smart C-SDK sample application. Figure 3.1 Bluetooth Smart C-SDK Architecture The Libraries box on the lower left contains those components that are provided by Silicon Labs in library form. The link layer and stack modules use the EMLIB and EMDRV API to access hardware resources. This API is also available for the Application. For more information please refer to the EMLIB Doxygen documentation under the doc directory of the SDK. It can be accessed from Silicon Labs Bluetooth Smart SDK Documentation in the Start menu. The link layer implementing the HCI interface is provided as a separate library, however it does not have a public API and is not intended for direct use. The Bluetooth Smart stack library is built on top of the link layer, and thus depends on it. The Bluetooth Smart Software API Reference Manual is located in the sdk > doc folder of the C-SDK installation. The WSTK library includes drivers common to WSTK kits, such as push-button, LED, display, temperature sensor and serial. The Radio library is a collection of low level EFR32 radio functions that provides hardware abstraction. All.a files have been created by IArchiver of the IAR Toolchain. The AppBuilder plugins box on the upper left is made up of the profile and application modules. AppBuilder plugins are small replaceable building blocks that may be individually added to or removed from the application using the GUI. These plugins have been implemented as example and are meant for customers to customize. Features: Collection of Bluetooth Smart service, advertisement and beacon plugins. Features callbacks: Physically part of the Features, but their implementations are provided by the Application, hence logically belong there. This is the place to make modifications such as changing how the measured temperature value is displayed. App CFG: Contains structures and functions to register handler functions to various GATT events. This module has been written to allow AppBuilder build-time configuration. Platform HW: Low level PTI and serial flash configurations and functions. Platform: Provides the event control API that can be used for creating and scheduling and running events. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 17

Sample Applications and AppBuilder App HW: The hardware abstraction plugin of the AppBuilder Plugins box is a collection of hardware-specific function implementations. Separating these from the hardware-agnostic application modules makes it easy to port these sample applications to custom hardware designs. Application: Implementation of the application. Responsible for running application events and calling Bluetooth Smart stack event handlers. Application callbacks: Callback functions that are called and implemented by the application, in a separate file. On the right is the group of files that are automatically generated based on plugin options configured through the AppBuilder GUI. BGPROJ / gatt_db.c/h: *.bgproj is an xml representation of the GATT database from which gatt_db.c and gatt_db.h files are generated during the prebuild step. HWCONF / Initdevice.c/h: Hardware configuration document file is the output of the Simplicity Studio Hardware Configurator. InitDevice.c and InitDevice.h are the two output files generated automatically. Bookkeeping: Automatically generated by AppBuilder to provide a plugin s initialization function that initializes each enabled App- Builder plugin. It also provides a plugin s tick function that periodically calls the tick function of each plugin (that provides it). Events: A central location of all event-handler pairs. This file is generated to create the list passed as input to the Platform module s event control API. AppBuilder Configuration header: This header file is included in all source files and is generated by AppBuilder to provide build-time configuration of the sample applications. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 18

Sample Applications and AppBuilder 3.2 Sample Application Interface QSG120, Silicon Labs AppBuilder-Based Bluetooth Smart C-SDK Quick Start Guide, contains procedures for generating both SoC and NCP example projects. As described in the Quick Start Guide, the procedures for an NCP example are different than for an SoC example. The descriptions in this section use an SoC example to illustrate selecting a profile, compiling it, and flashing it onto your hardware. This section provides an overview. More detailed procedures for customization are provided in section 4. Modifying Sample Applications. After you select an example template, an AppBuilder interface opens. Among other things, the AppBuilder interface exposes the plugins used by the template as well as their callbacks. The Plugins tab lists plugins available for the application to use. Those that are already used are checked. Click on a plugin to show its description, options, and details. The figure below shows the Advertisement Plugin with the options configured for the example. Figure 3.2 The Advertisement Plugin You can see the source for the various components of the plugin by expanding a category to show the files and double-clicking on any file (see figure below). silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 19

Sample Applications and AppBuilder Figure 3.3 Advertisement.c Source The Callbacks tab shows the callbacks used by the example template. Select a callback to see its details (see figure below). Figure 3.4 emberafpluginadvertisingstartedcallback silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 20

Modifying Sample Applications 4. Modifying Sample Applications There are several ways to modify sample apps to suit your requirements. 4.1 Modify Plugin Options/Add New Plugins You can add new features or services by selecting new plugins from the Plugins Tab by checking the corresponding plugin checkbox in your template file (with.isc extension), and tailor the plugin options according to your requirements. Plugins and their options are documented in the section 2. Plugin Descriptions. Figure 4.1 Plugins Tab silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 21

Modifying Sample Applications 4.2 Add New Peripherals When you want to use other peripherals of the EFR32 microcontroller, the Hardware Configurator allows you to do this as easily as a couple of mouse clicks. When you generate the project from the template file with AppBuilder, a Hardware Configurator file is also generated and opened automatically. You can add your hardware changes to this model. The Hardware Configurator will automatically generate initialization code for the selected hardware peripherals and port I/Os as soon as you click [Save]. The code will be generated in InitDevice.c file, in the void enter_defaultmode_from_reset(void) function. Figure 4.2 Hardware Configurator Note that some peripherals are greyed out and cannot be modified. Those peripherals are used by the Bluetooth Smart stack s and the sample apps normal operation. You can also use the Hardware Configurator to configure peripherals on your custom-designed PCB. In this case make sure to select the option None for the Kit when you create your project. In this case no kit-specific Hardware Configuration option will be loaded, only the peripheral initializations needed for the Bluetooth Smart Stack, as shown in the figure below. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 22

Modifying Sample Applications Figure 4.3 Project Configuration, No Kit For a more detailed description of the Hardware Configurator please refer to AN0823, Simplicity Configurator User Guide, available from the Application Notes tile in the Simplicity perspective silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 23

Modifying Sample Applications 4.3 Add Callbacks Another way to extend the sample apps is by implementing one of the offered callbacks to handle an event. If you select the Callbacks tab, all possible callbacks are listed (see figure below). If the box in the Is used? column is not checked, the callbacks are simple stubbed functions. If you want to implement them, check the Is used? box and add your implementation to the ble-soc-callbacks.c, or ble-ncp-callbacks.c file for the NCP/Host model. This file should not be overwritten after AppBuilder Generation. All callbacks should be implemented in ble-soc-callbacks.c (ble-ncp-callbacks.c), but in order to keep the hierarchy of your project it is good practice to put into the handler function only a function call of another function implemented the corresponding plugin s <feature name>_callback.c file. Some callbacks are already implemented by the sample apps. If you want your own implementation of the callback then first modify the previous implementation in ble-soc-callbacks.c (ble-ncp-callbacks.c), or edit it directly in <feature name>_callback.c files. Be sure to copy the modified plugin files into your workspace first (see section 4.4 Edit the Plugins). Figure 4.4 Callbacks Tab silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 24

Modifying Sample Applications 4.4 Edit the Plugins Sometimes it is necessary to modify the files of a plugin directly. Plugin files are not copied into your workspace, only linked from the C- SDK. This means that, if you modify these shared files in the C-SDK, it will affect all other sample apps using that plugin. Therefore, when you want to edit these plugin files, a warning dialog (shown below) will give you the opportunity to copy that file in your workspace. It is always recommended that you click [Make a Copy]. Figure 4.5 Plugin Edit Warning The Application Hardware Abstraction (app_hw) plugin contains WSTK6100- and sample application-specific files. If you have a custom designed PCB then you will almost certainly have to modify or exclude from the build the app_ui.c, app_hw.c and graphics-efr32.c files. App_hw.c contains hardware, specifically sensor-specific, initialization code and function calls. For many implemented Bluetooth Smart Profiles, the necessary sensors were physically unavailable, and therefore only a dummy implementation of a sensor call is provided. Users will have to edit this file and substitute the call of their own sensor functions here. App_ui.c contains user interface-specific initialization code and function calls, specifically the handling of LEDs, buttons, and LCD for the supported kits. If support for custom-designed boards is needed, the content of the app_ui initialization function (void appuiinit(u int16_t devid)), the periodically called void appuitick(void) and the function for displaying content on the LCD/screen void appu iwritestring(char *string) must be rewritten, or commented out. 4.5 Build and Debug the Modified Sample Application Now you can build and debug the modified sample application. Simplicity Studio contains powerful tools to help you with debugging and optimizing your sample application. Profiler enables power profiling of code in real time by measuring power consumption, and Network Analyzer captures a trace of wireless network activity. Note that Network Analyzer is only usable if the PTI plugin is enabled, and Profiler s Code Correlation is only usable if the Code Correlation plugin is enabled. These tools and others of interest to developers are documented in AN0822, Simplicity Studio User Guide, available through the Application Notes tile in the Simplicity perspective. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 25

Use Cases for Modifying the Sample Applications 5. Use Cases for Modifying the Sample Applications This section reviews three standard customization use cases: Use Case 1: Using an Existing Profile with Custom Hardware A developer wants to build a Bluetooth Smart standard device and hook it up to custom hardware. The developer would like to have an entire framework, and we should make it as easy as possible to build a production-worthy application (persistence, bootloading, etc.). Use Case 2: Modifying a Profile A developer wants to start with an existing profile, but wants to add GATT services that are not yet implemented by the Silicon Labs Bluetooth Smart sample apps. Use case 3: Using the Bluetooth Smart Stack with a Custom Application A developer is either writing an entire application from scratch or is porting an existing application, and only want an example of how to use the Silicon Labs Bluetooth Smart stack. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 26

Use Cases for Modifying the Sample Applications 5.1 Use Case 1 - Using an Existing Profile with Custom Hardware As an example, this procedure will create a Thermometer which also supports a Battery Service. The hardware will be a custom PCB with an EFR32MG1P233F256GM48 microcontroller mounted on it. It has two LEDs on Port F6 and F7. One of them should be switched on while battery measurements are being sent over Bluetooth, and another one should blink every time a temperature measurement is sent. The PCB has a temperature sensor that communicates with the MCU over I2C, and a voltage sensor over a shunt resistor, whose value is measured over ADC by the MCU. In order to port an existing sample application to a custom hardware, the highlighted modules in the figure below need to be modified. App HW and Platform HW are part of two AppBuilder plugins of the SDK, whereas the hardware configurator file (*.hwconf) belongs to the application and is automatically updated when modifications are made through the Hardware Configurator GUI. Figure 5.1 Bluetooth Smart C-SDK on Custom HW 1. Open Simplicity Studio and wait until your microcontroller is detected (If it is not detected automatically, click Refresh Detected Hardware). 2. Click the Software Examples Tile to make a new project. 3. In the Example Project Configuration dialog, make sure the Kit is set to None. The Part should be selected automatically, if not, select it manually. Make sure the Bluetooth Smart SDK is selected. Click [Next >]. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 27

Use Cases for Modifying the Sample Applications Figure 5.2 Example Project Configuration 4. Select the sample app that most resembles the Profile configuration you want to achieve. Since the target is one microcontroller responsible for all software tasks, select the Health Thermometer Profile sample app for an SoC framework. Click [Next >]. 5. Click [Finish] to create the Project. Figure 5.3 Example Profile Selection 6. The.isc file of the Thermometer sample app should open in AppBuilder. Go to the Plugins tab and check the Battery Service plugin to add it. 7. The Health Thermometer Plugin should be checked. Temperature measurement should be transferred in Celsius degrees with a time stamp. To keep the plugin as simple as possible, turn off (uncheck) Temperature Type and Measurement Interval Characteristics. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 28

Use Cases for Modifying the Sample Applications Figure 5.4 Health Thermometer Plugin 8. To add encryption to avoid eavesdropping, select the Connection plugin and turn on Pairing and Bonding. Figure 5.5 Connection Plugin Options 9. To configure GAP appearance and advertised name, select the GAP plugin. Enter the device name Battery Thermometer, and select Generic Thermometer for Appearance. Figure 5.6 GAP Plugin Options 10. Select the Device Information Plugin and turn off everything except the Manufacturer name and the Software Version. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 29

Use Cases for Modifying the Sample Applications Figure 5.7 Device Information Plugin Options 11. Go to the Callbacks tab, to select callbacks for blinking and switching on the LEDs. Selected callbacks have a check mark in the Is Used? column. To switch on LED0 when a new temperature value is received, make sure emberafplugintempmeasavailablecallback() is checked. To switch off LED0 and LED1 when a the connection is terminated, make sure emberafpluginconnectionterminatedeventcall back() is checked. To switch on LED1 when the Battery Indications have been switched on, make sure emberafpluginbattindicationsoncallbac k() is checked. 12. Click [Generate] to generate the project. Do not overwrite ble-soc-callback.c. 13. In the Hardware Configurator, open the generated.hwconf file, and set the pins for the LEDs to Output. In the example PCB a temperature sensor communicates with the MCU over I2C. To measure the battery voltage over ADC, configure those peripherals and the corresponding GPIO pins. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 30

Use Cases for Modifying the Sample Applications Figure 5.8 Hardware Configurator 14. Open ble-soc-callbacks.c, and implement the LED toggling for the enabled callbacks. The Ports are already initialized. 15. Note that emberafpluginconnectionterminatedeventcallback() and emberafplugintempmeasavailablecallback() already have an implementation. These must be overwritten with the custom implementations. 16. Open the app_hw plugin and look for the int32_t apphwreadtm(int32_t* tempdata) and uint8_t apphwreadbatterylevel( void) functions. Substitute the dummy implementation of reading the temperature and voltage measurement with the appropriate calls of I2C-Read and ADC-Read function from Emlib, Emdrv or a custom driver. The app_hw plugin is shown in Figure 3.1 Bluetooth Smart C-SDK Architecture on page 17 as a yellow box. 17. In the plugin edit warning dialog (Figure 4.5 Plugin Edit Warning on page 25), check Make a Copyy to copy the plugin into your workspace. 18. The app_ui plugin will also have to be modified, since the design does not have an LCD or screen. Edit the app_ui.c file by commenting out the following functions: void appuiinit(uint16_t devid); void appuitick(void); void appuiwritestring(char *string); 19. In the plugin edit warning dialog (Figure 4.5 Plugin Edit Warning on page 25), check Make a Copy to copy the plugin into your workspace. 20. Build and debug the application. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 31

Use Cases for Modifying the Sample Applications 5.2 Use Case 2 - Modifying a Profile To customize any of the pre-implemented services, you must manually modify the GATT database of the device. The GATT database contains all Bluetooth Smart profile-, service-, and characteristic-level information and is highlighted with yellow in the AppBuilder generated files box, shown on the right in the figure below. Using AppBuilder, you can fine-tune the pre-implemented GATT definitions for the supplied service plugins. Customizing the GATT database manually is only necessary when the plugin options do not provide the needed flexibility for a specific design. Section 2. Plugin Descriptions, details the built-in customization options. Figure 5.9 Bluetooth Smart C-SDK with Custom Profile To customize the GATT database manually, edit the.bgproj file of the project, which is an xml representation of the GATT database. For detailed description of the format, refer to UG118, Blue Gecko Bluetooth Smart Profile Toolkit Developer User's Guide, distributed with the Bluetooth Smart C-SDK. As an example of how to customize a profile, start with the SOC Demo for Smart Phone App. Once you generate the example application in AppBuilder and build the project in Simplicity IDE, you have a working binary that realizes the Health Thermometer profile, the Immediate Alert profile, and an ibeacon. As the first step, modify the Health Thermometer profile and its service. Assume you need to add a custom characteristic to provide some further information about the measurement. When you click [Generate], a GATT database file based on the selected plugins is created with a.bgproj extension. This is shown as a yellow box within the AppBuilder generated files group in the figure above. C code for the GATT database will be created from this XML-based description before compilation, so this.bgproj file should be manually modified according to the instructions in UG118, Blue Gecko Bluetooth Smart Profile Toolkit Developer User's Guide, to add more services and characteristics. Edit the.bgproj file by first double-clicking it in the Project Explorer pane, then selecting the Source tab below. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 32

Use Cases for Modifying the Sample Applications Figure 5.10 Source Tab In this example, add a new characteristic to extend the already existing standard-based ones. If the new characteristic also contains a Client Characteristic Configuration Descriptor, that means Notifications or Indications can be sent about the characteristic, then the plugin code must be edited in SDK. Select the source file of the plugin from Studio s Project Explorer and add a Handler function for the Characteristic Status Change. Plugins are located under the Features directory in the SDK, and are highlighted with yellow in the AppBuilder plugins box. You must also add the corresponding event ID event handler function pair to the appcfggattservercharstatus structure in the app_cfg plugin (see the yellow App CFG box in AppBuilder plugins group in Figure 5.9 Bluetooth Smart C-SDK with Custom Profile on page 32). As always, when you modify these plugins be sure to make a copy of the original plugin in the plugin edit warning dialog (Figure 4.5 Plugin Edit Warning on page 25). 5.3 Use Case 3 - Using the Bluetooth Smart Stack with a Custom Application Refer to AN975, Bluetooth Smart Application Development with IAR, located in the sdk > doc folder of your Bluetooth Smart C-SDK installation. silabs.com Smart. Connected. Energy-friendly. Rev. 0.2 33