Connect Tutorial 1 - Getting Started with Application Development
10/274/2019 | 03:53 PM
This is the first tutorial in a series that demonstrates "the essentials" of building applications based on Silicon Labs Connect. See Connect Tutorial Series: Table of Contents for an overview of topics addressed in the series, general pre-requisites to ensure you get the most out of the exercises, and definitive Connect references for when you're ready to dive deeper.
In the simple example that follows, we'll get our first taste of using the Connect application framework to impact how the hardware behaves. First, however, let's briefly review what Connect is, and summarize the high-level "when" and "why" it can provide the best solution for your application needs.
Note: the "Basic Application Example" chapter later in this document presents additional prerequisites for that exercise.
What is Connect
Connect (comprised by the Connect Stack and Application Framework) is a production-quality wireless networking solution for Sub-GHz and 2.4GHz proprietary applications. As part of the Flex SDK, it supports the Silicon Labs Wireless Gecko (EFR32) portfolio. Based on a 802.15.4-compliant MAC, Connect is both fully-featured and highly customizable - freeing developers from the mundane details of network and radio configuration to focus on building optimized and differentiated applications.
Included with Connect are "out of the box" EFR32 radio configurations tuned for compliance to regional standards around the world and optimized for maximal performance. A modular architecture and the integrated Connect application framework enable rapid & resource-efficient feature implementation, with the flexibility to port across platforms as markets/applications evolve.
Connect Stack Modes
Networks built from Connect-based devices are configured in one (and only one) of three modes:
1) Extended Star Mode
A mode that provides a simplified "ZigBee-like" (not a true mesh) network, without the alliance/certification requirements and with a smaller resource footprint
A PAN coordinator (blue node in the figure below) administers a centralized network, permitting joining by end nodes (white nodes - can be sleepy) and range extenders (red nodes) to realize Point-to-Point, Star, and Extended Star networks
The Network layer supports message routing between any two devices (and multiple endpoints at those devices) in the network
Multiple built-in features ("plugins") provided by the stack and/or application framework
2) Direct Mode
A mode for proprietary applications that prefer more complete control of network behavior
Supports connections between devices that are in range of each other (green nodes below) - any such device with correct PAN parameters can join
The Network layer supports endpoints, but provides no routing "out of the box" - optimized routing can be implemented in the application
Multiple built-in features ("plugins") provided by the stack and/or application framework
3) MAC Mode
A mode (essentially: the Connect MAC layer) for applications that need to be fully IEEE 802.15.4 compatible and interoperable (when used with a 15.4-compliant radio configuration)
Supports connections between devices (can be sleepy) that are in range of each other (green nodes below)
Connect Network layer is not implemented (thus, no endpoints and fewer built-in features available)
Uses a more complex API than other modes
Supported Network Topologies
As described in the previous sections, the three Connect modes can realize one or more of the following network topologies:
Point-to-Point
Star
Extended Star
Single-Hop (Direct or MAC)
Selecting a Mode for your Application
A Connect network consists of devices all operating in the same mode. Since the API and supported features can vary significantly between modes, it is non-trivial to change the mode of an existing Connect application. Hence, it is important to carefully consider the topology and feature sets provided by each mode before selecting the one for your design.
As an alternative to the Connect modes above, proprietary wireless applications can be built on EFR32 using RAIL (Radio Abstraction Interface Layer) - the other workflow provided within Flex SDK. In short, RAIL:
provides commonly-used Phy and MAC layer radio API functions to implement proprietary wireless protocols
is highly flexible (custom frame formats, can interface to legacy proprietary protocols, etc.)
does not include a network layer (so no "out of the box" multi-hop support, etc.), security, nor application features (like OTA bootloading, etc.)
Connect-based designs are best suited to those applications that:
use a simple network topology
want a fully-featured stack (with network layer and application framework)
need "out of the box" task and sleep scheduling, OTA bootloading, association, security, etc.
On the other hand, a RAIL-based approach may be more appropriate when applications:
require legacy proprietary network support (Connect uses a fixed frame format)
demand maximum energy optimization (though Connect leverages low-energy features of the EFR32 to support battery-powered/sleepy nodes, a custom RAIL solution with full control of energy mode and radio state transitions can be tailored with "bare metal" application-specific tuning)
Chapter 2: Setting Up Your Development Environment
Chapter 3: Functionality in the Launcher Perspective
(Optional) Chapter 4 thru Section 4.1: Working with Connect SoC Examples
At this point you should have established a suitable development environment and target hardware to explore building applications with the Connect stack. The Flex SDK (which includes Connect) is supported on all Wireless (Flex/Blue/Mighty) Gecko Series 1 (EFR32xG1x) devices. These tutorials leverage the built-in Simplicity Studio support for peripherals and I/O on the Wireless Starter Kit (WSTK) boards.
Create a new Flex SDK Project
With your WSTK connected, while in the Simplicity IDE perspective, select Project/New/Silicon Labs AppBuilder Project:
In the "Applications" dialog that opens, select "Silicon Labs Flex SDK" and click [Next]. In the "Stacks" dialog, select the most recent Flex SDK available and click [Next]. In the "Select Application" dialog, select the Connect (SoC): Empty Example application, and click [Next].
Name your project and click [Next]. On the "Project Setup" dialog, confirm that the "Boards" and "Part" sections reflect your target hardware, then select your preferred toolchain build configuration and click [Finish]
A new project with your preferred configuration is created, and the .isc file opens in AppBuilder to the [General] tab. Make sure your preferred toolchain appears in the "Toolchain" position of the "Select architecture for this application" section (if not, click [Edit Architecture] and select it - or confirm it is selected already - and click [Ok]).
Plugins, Callbacks, and Events in Connect
In this tutorial, we'll build "blinky" - embedded firmware's answer to the classic "Hello, World!" example. However, more than simply toggling an LED on your target board, this first exercise will demonstrate two fundamental aspects of Connect-based applications:
Developers modify application behavior by implementing callback functions and custom events that interact with built-in features and operations internal to Connect (the stack and application framework)
Developers perform initial Connect (stack and application framework) configuration with the AppBuilder GUI within Simplicity Studio, to generate a Connect-based project trimmed to the desired Connect components
Connect provides "out of the box" support for a variety of optional functionality. The stack and application framework are structured so that these modular features (called "plugins") can be enabled if needed and discarded if not (minimizing any penalty from unused resources).
To add support for the WSTK on-board LED to our project, on the AppBuilder [Plugins] tab we need to select the HAL Library, provides API: hal, token, board, button, led plugin from the Connect HAL group. This will provide our project with board support (BSP) for the WSTK and the led API we'll use to toggle an LED.
Note: the Connect SoC Empty application enables this plugin by default, so we don't need to change anything here
Create an Event to Trigger an LED Toggle
A simple event scheduler is implemented in the Connect application framework. Rather than directly manipulating an MCU timer peripheral, the Connect development best-practice is to instead use this scheduler to set up delayed (or immediate) events that can fire associated callbacks at desired points in time. We'll create such an event to periodically execute our LED toggle function next.
On the AppBuilder [Other] tab, scroll to the "Event Configuration" section and click [Add new]. Click the newly-added row elements in the table to edit the name of our new "command" element (essentially, the event "control" used to schedule this event) from the default eventData to blinkEvent. Similarly, rename our new callback (the function that should run in response to each occurrence of the event) from eventHandler to blinkHandler.
At the moment, this event doesn't actually exist - we're simply requesting that AppBuilder create it for us in a later step.
Select Callbacks
In addition to the callbacks we define to respond to our custom events, we typically want to also implement callbacks that interact with pieces of the Connect stack or application framework (often in support of the optional plugins we've enabled in our project). Rather than an infinite loop in main(), callbacks are where a Connect-based application exerts customized control over application behavior.
We've previously requested an event that we plan to use for the periodic "triggering" of our LED toggle function. We now need a way to initiate (after device power-on or reset) the first occurrence of the event (we'll configure the resulting callback to schedule the next occurrence each time the event fires again). To do so, we use the AppBuilder [Callbacks] tab to select both the "Is used?" and "Stub?" checkboxes for the emberAfMainInitCallback element in "Callback Configuration".
Note: the Connect SoC Empty application uses this callback by default, so we don't need to change anything here:
As indicated by the "Origin" column, this callback is associated with the "Main" plugin (a non-optional element of Connect-based applications). Click this row in the table to reveal the following in the "Callback declaration" section of the frame:
/** @brief Main Init
*
* This function is called when the application starts and can be used to
* perform any additional initialization required at system startup.
*/
void emberAfMainInitCallback(void)
{
}
As suggested by the comments, this callback runs once when the application starts - we'll use it later to initiate our LED-toggling event.
Putting it All Together
Thus far, we have used AppBuilder to:
select appropriate plugins to enable the optional feature support we need,
create an event we'll use to time our LED blink rate, and
identify where to initialize the periodic blink event after power-on/resets
It's now time to generate our project (by clicking the [Generate] button) in AppBuilder. Doing so will populate the Simplicity Studio project workspace with source files and linked resources to support the configuration specified in our AppBuilder (.isc) file.
Writing Code in a "Generated" AppBuilder Project
Among other changes, observe that the AppBuilder generation process created a new flex-callbacks.c source file in the project directory. This is the location where you should both allocate RAM (EmberEventControlconsumes 6 Bytes) for blinkEvent and implement the blinkHandler callback for the Event we added, as follows:
call halToggleLed(API reference) to briefly toggle the GPIO driving LED "0" on the WSTK
call emberEventControlSetDelayMS(API reference) to set the blinkEvent control to run again in 500ms
Note: an event callback will run repeatedly unless/until its control is either set inactive or delayed.
The flex-callbacks.c source file is also where AppBuilder placed the callback stub we requested in the [Plugins] tab before generating the project:
/** @brief Main Init
*
* This function is called when the application starts and can be used to
* perform any additional initialization required at system startup.
*/
void emberAfMainInitCallback(void) {
// your code here
}
In our final step before compiling this project, we'll replace the "your code here" comment with a call (API reference) to initially activate our blinkEvent control:
emberEventControlSetActive(blinkEvent);
Running the Project
At this point the example is ready to be built and flashed to the target device. Having completed QSG138 previously, Simplicity Studio should be ready to largely automate this process for you.
Build the project and flash it to your device. Once running, "LED0" on the WSTK should be blinking about once a second.
This exercise provided a description of the callback-oriented design employed by Connect-based applications, and a trivial demonstration of:
using AppBuilder to set up a simple Connect configuration
defining application behavior using plugins, callbacks, and events
Later editions of the Connect Tutorial series will further explore the deep wealth of built-in functionality available in Connect (including - unlike this one - actual wireless networking!), and provide increasingly more involved demonstrations of how to tap into that power. In addition to surveying the broad landscape of stack and application framework features, these exercises will walk you through Connect development best-practices.
Connect Tutorial 1 - Getting Started with Application Development
This is the first tutorial in a series that demonstrates "the essentials" of building applications based on Silicon Labs Connect. See Connect Tutorial Series: Table of Contents for an overview of topics addressed in the series, general pre-requisites to ensure you get the most out of the exercises, and definitive Connect references for when you're ready to dive deeper.
In the simple example that follows, we'll get our first taste of using the Connect application framework to impact how the hardware behaves. First, however, let's briefly review what Connect is, and summarize the high-level "when" and "why" it can provide the best solution for your application needs.
Note: the "Basic Application Example" chapter later in this document presents additional prerequisites for that exercise.
What is Connect
Connect (comprised by the Connect Stack and Application Framework) is a production-quality wireless networking solution for Sub-GHz and 2.4GHz proprietary applications. As part of the Flex SDK, it supports the Silicon Labs Wireless Gecko (EFR32) portfolio. Based on a 802.15.4-compliant MAC, Connect is both fully-featured and highly customizable - freeing developers from the mundane details of network and radio configuration to focus on building optimized and differentiated applications.
Included with Connect are "out of the box" EFR32 radio configurations tuned for compliance to regional standards around the world and optimized for maximal performance. A modular architecture and the integrated Connect application framework enable rapid & resource-efficient feature implementation, with the flexibility to port across platforms as markets/applications evolve.
Connect Stack Modes
Networks built from Connect-based devices are configured in one (and only one) of three modes:
1) Extended Star Mode
2) Direct Mode
3) MAC Mode
Supported Network Topologies
As described in the previous sections, the three Connect modes can realize one or more of the following network topologies:
Selecting a Mode for your Application
A Connect network consists of devices all operating in the same mode. Since the API and supported features can vary significantly between modes, it is non-trivial to change the mode of an existing Connect application. Hence, it is important to carefully consider the topology and feature sets provided by each mode before selecting the one for your design.
See UG235.03: Architecture of the Silicon Labs Connect Stack and UG235.04: Customizing Applications with Silicon Labs Connect for more information on the Connect modes and built-in feature sets available within each.
When to Use Connect (instead of RAIL)
As an alternative to the Connect modes above, proprietary wireless applications can be built on EFR32 using RAIL (Radio Abstraction Interface Layer) - the other workflow provided within Flex SDK. In short, RAIL:
Connect-based designs are best suited to those applications that:
On the other hand, a RAIL-based approach may be more appropriate when applications:
For clarity, this analysis largely omits Connect's MAC mode as it in many ways is a counterpoint to the two other Connect modes. Consult the Connect references cited above for additional insight on MAC mode. For more information on RAIL, see QSG138: Getting Started with the Silicon Labs Flex Software Development Kit for the Wireless Gecko (EFR32™) Portfolio and the RAIL Tutorial Series.
Basic Application Example: Blinky
Before proceeding with the tutorial example, we recommend that you complete these foundational chapters from QSG138: Getting Started with the Silicon Labs Flex Software Development Kit for the Wireless Gecko (EFR32™) Portfolio:
At this point you should have established a suitable development environment and target hardware to explore building applications with the Connect stack. The Flex SDK (which includes Connect) is supported on all Wireless (Flex/Blue/Mighty) Gecko Series 1 (EFR32xG1x) devices. These tutorials leverage the built-in Simplicity Studio support for peripherals and I/O on the Wireless Starter Kit (WSTK) boards.
Create a new Flex SDK Project
With your WSTK connected, while in the Simplicity IDE perspective, select Project/New/Silicon Labs AppBuilder Project:
In the "Applications" dialog that opens, select "Silicon Labs Flex SDK" and click [Next]. In the "Stacks" dialog, select the most recent Flex SDK available and click [Next]. In the "Select Application" dialog, select the Connect (SoC): Empty Example application, and click [Next].
Name your project and click [Next]. On the "Project Setup" dialog, confirm that the "Boards" and "Part" sections reflect your target hardware, then select your preferred toolchain build configuration and click [Finish]
A new project with your preferred configuration is created, and the .isc file opens in AppBuilder to the [General] tab. Make sure your preferred toolchain appears in the "Toolchain" position of the "Select architecture for this application" section (if not, click [Edit Architecture] and select it - or confirm it is selected already - and click [Ok]).
Plugins, Callbacks, and Events in Connect
In this tutorial, we'll build "blinky" - embedded firmware's answer to the classic "Hello, World!" example. However, more than simply toggling an LED on your target board, this first exercise will demonstrate two fundamental aspects of Connect-based applications:
Connect provides "out of the box" support for a variety of optional functionality. The stack and application framework are structured so that these modular features (called "plugins") can be enabled if needed and discarded if not (minimizing any penalty from unused resources).
As UG235.01: Developing Code with Silicon Labs Connect and UG235.04: Customizing Applications with Silicon Labs Connect describe in detail, desired plugins are selected using the [Plugins] tab in AppBuilder within Simplicity Studio. When the AppBuilder project is then generated, callback functions to support the selected plugins are created in the project source files for developers to populate with application-specific code.
Select Plugins
To add support for the WSTK on-board LED to our project, on the AppBuilder [Plugins] tab we need to select the HAL Library, provides API: hal, token, board, button, led plugin from the Connect HAL group. This will provide our project with board support (BSP) for the WSTK and the
led
API we'll use to toggle an LED.Note: the Connect SoC Empty application enables this plugin by default, so we don't need to change anything here
Create an Event to Trigger an LED Toggle
A simple event scheduler is implemented in the Connect application framework. Rather than directly manipulating an MCU timer peripheral, the Connect development best-practice is to instead use this scheduler to set up delayed (or immediate) events that can fire associated callbacks at desired points in time. We'll create such an event to periodically execute our LED toggle function next.
On the AppBuilder [Other] tab, scroll to the "Event Configuration" section and click [Add new]. Click the newly-added row elements in the table to edit the name of our new "command" element (essentially, the event "control" used to schedule this event) from the default
eventData
toblinkEvent
. Similarly, rename our new callback (the function that should run in response to each occurrence of the event) fromeventHandler
toblinkHandler
.At the moment, this event doesn't actually exist - we're simply requesting that AppBuilder create it for us in a later step.
Select Callbacks
In addition to the callbacks we define to respond to our custom events, we typically want to also implement callbacks that interact with pieces of the Connect stack or application framework (often in support of the optional plugins we've enabled in our project). Rather than an infinite loop in
main()
, callbacks are where a Connect-based application exerts customized control over application behavior.We've previously requested an event that we plan to use for the periodic "triggering" of our LED toggle function. We now need a way to initiate (after device power-on or reset) the first occurrence of the event (we'll configure the resulting callback to schedule the next occurrence each time the event fires again). To do so, we use the AppBuilder [Callbacks] tab to select both the "Is used?" and "Stub?" checkboxes for the
emberAfMainInitCallback
element in "Callback Configuration".Note: the Connect SoC Empty application uses this callback by default, so we don't need to change anything here:
As indicated by the "Origin" column, this callback is associated with the "Main" plugin (a non-optional element of Connect-based applications). Click this row in the table to reveal the following in the "Callback declaration" section of the frame:
As suggested by the comments, this callback runs once when the application starts - we'll use it later to initiate our LED-toggling event.
Putting it All Together
Thus far, we have used AppBuilder to:
It's now time to generate our project (by clicking the [Generate] button) in AppBuilder. Doing so will populate the Simplicity Studio project workspace with source files and linked resources to support the configuration specified in our AppBuilder (.isc) file.
Writing Code in a "Generated" AppBuilder Project
Among other changes, observe that the AppBuilder generation process created a new
flex-callbacks.c
source file in the project directory. This is the location where you should both allocate RAM (EmberEventControl
consumes 6 Bytes) forblinkEvent
and implement theblinkHandler
callback for the Event we added, as follows:In
blinkHandler
we've chosen to:halToggleLed
(API reference) to briefly toggle the GPIO driving LED "0" on the WSTKemberEventControlSetDelayMS
(API reference) to set theblinkEvent
control to run again in 500msNote: an event callback will run repeatedly unless/until its control is either set inactive or delayed.
The
flex-callbacks.c
source file is also where AppBuilder placed the callback stub we requested in the [Plugins] tab before generating the project:In our final step before compiling this project, we'll replace the "your code here" comment with a call (API reference) to initially activate our
blinkEvent
control:Running the Project
At this point the example is ready to be built and flashed to the target device. Having completed QSG138 previously, Simplicity Studio should be ready to largely automate this process for you.
Build the project and flash it to your device. Once running, "LED0" on the WSTK should be blinking about once a second.
If not, review QSG138: Getting Started with the Silicon Labs Flex Software Development Kit for the Wireless Gecko (EFR32™) Portfolio or seek help on the Silicon Labs Proprietary Community.
Review and Further Instruction
This exercise provided a description of the callback-oriented design employed by Connect-based applications, and a trivial demonstration of:
Later editions of the Connect Tutorial series will further explore the deep wealth of built-in functionality available in Connect (including - unlike this one - actual wireless networking!), and provide increasingly more involved demonstrations of how to tap into that power. In addition to surveying the broad landscape of stack and application framework features, these exercises will walk you through Connect development best-practices.
When coupled with the deep-dive resources referenced throughout this document (UG235: Silicon Labs Connect User's Guide Series, Connect Stack API Documentation), the tutorial series will prepare developers new to Connect to both plan out and rapidly execute on optimized Connect-based application designs.
API References
Functions
emberAfMainInitCallback()
halToggleLed()
emberEventControlSetActive()
emberEventControlSetDelayMS()
Type definitions
EmberEventControl