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.

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:

• 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)

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:

• Chapter 1: Flex SDK Product Overview
• 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:

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

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 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 (EmberEventControl consumes 6 Bytes) for blinkEvent and implement the blinkHandler callback for the Event we added, as follows:

EmberEventControl blinkEvent;

void blinkHandler(void){
  halToggleLed(0);
  emberEventControlSetDelayMS(blinkEvent, 500);
}

In blinkHandler we've chosen to:

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

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:

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

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