Application SDK Development Tutorial

This tutorial provides hands-on experience developing Gecko OS Native C Applications using the Gecko OS Application SDK. The tutorial covers the steps required to develop and debug a Gecko OS application, as well as the process to deploy and manage a Gecko OS application on the Zentri Device Management Service (DMS) .

The application developed in this tutorial is a simple network-connected weather station app featuring the Si7021 Relative Temperature and Humidity (RH/T) Sensor available on the WGM160P Wireless Starter Kit (WSTK) mainboard.

The application source code for the tutorial is also provided for reference.

Additional Gecko OS Application Examples are available in the Gecko OS Application SDK.

This tutorial is written using Gecko OS SDK version 4.1.11 and Gecko OS Studio version 1.0.1.

Software and Hardware Requirements

This tutorial requires :

Topics

Advanced Topics

Creating a Project in GSS

Open GSS and navigate to the Projects page as shown below.

Select Create New Project then complete the project fields as shown below. A brief description of each field follows the image.

Note! Ensure that file and directory names do NOT contain spaces.

A description of the New Project page fields is provided below.

  • Project Name . The project identifier used in the IDE and the filesystem.
  • Target . The hardware target for the project. If a device is connected, this field will automatically be set to the connected device type.
  • License . Currently the STANDARD Gecko OS license is the only license that supports SDK development, therefore this is the only option.
  • Software . The Gecko OS version used for the project. This field should be set to the latest release unless a previous (older) release is required.
  • DMS Product Code . The product code used to identify the project on the DMS. The product code must NOT contain spaces and is a maximum of 16 characters.
  • Workspace Path . The local workspace directory on disk where the project will be created and where the Gecko OS ASDK source code will be extracted. GSS will create a default folder, however a different folder location may be entered.

Click the Create button to create the project. This initiates the process of downloading the SDK and platform files, creation of the project template and setup of the device for development. The project creation process can be run without a device connected (further information is available in the section, Setting up your Device for Development ).

During the Project Creation process, the following page is shown.

After the project is created, two options are presented: Open Project Folder and Open in IDE . If the IDE has not previously been installed, select the option that includes Install IDE .

Selecting Open in IDE launches the IDE, where the newly created weather project and the Gecko OS Application SDK can be explored. The project and Gecko OS ASDK are located adjacent to one another in the Project Explorer column on the left-hand side of the IDE.

Setting up Your Device for Development

A critical step for Gecko OS development is device setup. The device setup process performs the actions necessary to put the device in development mode and to enable the device to interact securely with the DMS. To learn more about the differences between development and production devices see: Understanding the terms Development and Production .

Device setup must be performed prior to using a device for development of a particular application. Device setup is required one time for a given application, although it must be repeated after switching from one project to another.

Your computer must be connected to the Internet for device setup to be successful. You can begin software development without performing device setup, but you will not be able to load and run the project on the device until this process is complete.

If a device is connected to your computer during the GSS project creation process, the device will be automatically set up for development.

Device setup can be performed at any time for a given project by double-clicking Setup Device under the Build Targets of your project as shown below.

The device setup process performs several actions outlined in the following list; DMS concepts referred to in the list below will be introduced later in this tutorial.

  • Initialize the device security keys necessary to communicate with DMS
  • Claim the device into your DMS account (if not already claimed)
  • Create a Product for your project named WEATHER
  • Activate the device to the WEATHER Product
  • Program the device with the default Gecko OS Product which is SILABS-WGM160P for the WGM160P module.

View your Device and Product in the DMS

Using a web browser, go to the Zentri DMS and login using your Silicon Labs account.

The activity log, available in the bottom left corner of DMS (example shown below), shows a log of recent activity in your account. Several entries will appear corresponding to the project creation and device setup process described in the tutorial so far.

Select the Devices tab of the DMS (see below), the device is claimed into your account (now owned by you) and activated to your new development product called WEATHER .

Select the Products tab, select the blue Development Products filter, and your recently created development Product WEATHER appears. See the example below.

You may have noticed the DMS appended a 6 character code in front of your Product code. The examples above show the product 03MWMC-WEATHER . The 6 character code is a unique DMS customer code and is used to identify your development products. Your customer code is automatically prepended when a development product is created.

Build and Debug the Application

Building the Application

Double-click one of the Build Targets of your project to build, download, and run the project on the device.

Choose from three options:

  • Download Application . Build the project and download only the executable portion of the project to the device. This excludes resources that would otherwise be programmed to the filesystem such as config files, web server assets, and so on.
  • Download Resources . Build the project and download only the resources to the device. This excludes the executable portion of the project.
  • Download Application and Resources . Build the project and download the executable and all of the resources to the device. This target downloads everything in the project to the Device.

The Download Application and Resources option is the fool-proof way to ensure the entire project is on the device. You should use this option the first time you build and download a project to a device. To save time during development, you can use Download Application if you have only modified your application code since the last download, or you can use Download Resources Only if you have only modified project resources since the last download.

After the build and download is complete, your application automatically runs on your device.

Debugging the Application

To start a debug session, click on the bug icon as shown below. The application must already be downloaded to the device.

The debugger launches and the application stops execution at the beginning of the function gos_app_init() , the entry point to all Gecko OS applications.

The output of the project build is located in the SDK subfolder named output . The SDK and all subfolders are available in the IDE Project Explorer column.

Output 'Hello World' via the Serial Port

The entry point to any Gecko OS application is the function gos_app_init() , see Gecko OS Application Structure . Notice that when the project was created, GSS automatically inserted a GOS_LOG("Hello World!"); statement in the gos_app_init() function. The GOS_LOG() statement is a macro that outputs the specified text to the log bus .

With the application downloaded to the device, open a device console, press the Reset button, and you will see the following text appear on the console. If you need help getting getting the console working, see Gecko OS Console . 

[Ready]
LOCAL> Hello world!

Type the Gecko OS command version (or the equivalent shortcut ver ) and the text similar to the following appears. 

LOCAL> ver
03MWMC-WEATHER-0.0.0-local, Gecko_OS-STANDARD-4.1.11-7064, WGM160P

Note that first part of the version is the product code created in the DMS during the project creation.

For practice, copy the following code and replace the "Hello World!" text by editing the gos_app_init() function in main.c . 

void gos_app_init(void)
{
  // Print to the serial terminal
  GOS_LOG("Weather Demo                     ");
  GOS_LOG("           |                     ");
  GOS_LOG("      \    |    /                ");
  GOS_LOG("       \       /                 ");
  GOS_LOG("         ,d8b,           .,      ");
  GOS_LOG(" (')-\")_ 88888 ---   ;';'  ';'. ");
  GOS_LOG("('-  (. ')98P'      ';.,;    ,;  ");
  GOS_LOG(" '-.(PjP)'     \        '.';.'   ");
  GOS_LOG("           |    \                ");
  GOS_LOG("           |                     ");
}

View complete tutorial source code

Save the changes and double click the Download Application target. After the application builds and downloads, the following text appears on the device console. 

[Ready]
LOCAL> Weather Demo
           |
      \    |    /
       \       /
         ,d8b,           .,
 (')-")_ 88888 ---   ;';'  ';'.
('-  (. ')98P'      ';.,;    ,;
 '-.(PjP)'     \       '.';.'
           |    \
           |

Networked Application with a Single Line of Code

Even though barely any code has been written, the project is already a complete, fully-functional network-ready application. You can test this in the device console by connecting to a network and downloading a portion of the Google Website using the sequence of Gecko OS commands shown below. Note that in the example below, the yellow text is user input and the white text is device output. 

LOCAL> network_up -s

! 41 networks found
!  # Ch RSSI MAC (BSSID)       Network (SSID)
#  0  1  -79 82:2A:A8:87:82:40 SiliconLabsGuest
#  1  1  -71 80:2A:A8:87:C2:8D SiliconLabs
#  2  2  -66 2C:30:33:51:36:57 NETGEAR61
#  3  6  -85 92:2A:A8:87:A3:39 <ssid hidden>
Type the number # that matches your Network: 0
Type the password for your Network         : ********
[Associating to SiliconLabsGuest]
In progress
LOCAL> Security type from probe: WPA2-AES
Obtaining IPv4 address via DHCP
IPv4 address: 10.1.54.38
[Associated]

LOCAL> http_get www.google.com

[2019-02-27 | 15:35:34: Opening: www.google.com]
Request GET /
Connecting (http): www.google.com:80
[2019-02-27 | 15:35:34: Opened: 1]
Status: 200
1
LOCAL> stream_read 1 1000

<!doctype html><html itemscope="" itemtype="http://schema.org/WebPage" lang="en"><head><meta content="Search the world's information, including webpages, images, videos and more. Google has many special features to help you find exactly what you're looking for." name="description"><meta content="noodp" name="robots"><meta content="text/html; charset=UTF-8" http-equiv="Content-Type"><meta content="/images/branding/googleg/1x/googleg_standard_color_128dp.png" itemprop="image"><title>Google</title><script nonce="kR0INZ86xC/a7AUJZCrEjg==">(function(){window.google={kEI:'Ra52XNPRMY6asQW0o4yQCA',kEXPI:'0,1353747,57,1958,1016,1406,698,527,730,1799,30,1227,806,911,247,25,203,27,222,1,37,430,2334178,329533,1294,12383,4855,32692,15247,867,6057,4704,1402,6381,3335,2,2,6801,364,1172,2147,1263,4242,224,2218,260,5107,575,835,284,2,579,727,2431,59,2,1,3,1297,4323,3390,10,300,658,609,774,2250,1407,3337,1146,5,2,2,981,764,222,2591,1021,2580,669,1050,1808,1129,268,81,7,1,2,488,620,29,1395,978,2632,696,3

In addition to the above example, the entire Gecko OS Command API is available for use with the application.

Also, at this early stage of development, the application may be deployed to the DMS with full over-the-air firmware update capabilities as described later in this tutorial in the sections Deploying your application to the DMS and Performing over the air firmware updates via the DMS

Introduction to the Project Makefile

You may have noticed a file named weather.mk in your project. This is the makefile for the project, which instructs the build system how to build your project. As you make changes to the project settings you may notice the makefile change to reflect these changes.

Note! When using the GSS Eclipse IDE for development, the makefile is automatically managed and edited by the IDE. Therefore, editing this file directly may not always produce the desired outcome. Also note that the IDE does not edit the makefile until a build is performed. Therefore, modifying project settings will not be reflected in the makefile until a build is performed.

Gecko OS Components

The Gecko OS build system utilizes the concept of 'components' to allow easy modularization and reuse of source code and other resources. A component can be thought of as a code library but it may also include other resources such as files to be stored on the filesystem. A component may also include sub-components. The component may contain source code or static libraries. The primary element of a component is a makefile. When a component is included in your project, the Gecko OS build system executes the build of the component makefile and adds the component to your application.

The Gecko OS Application SDK includes a variety of components that can be added to your project using the following procedure.

  1. Right click on the project name then select Properties .
  2. In the Properties dialog navigate to C/C++ Build -> Settings -> Components .
  3. Add a component using the relative path in the SDK. Note that the component path is equivalent to the relative path of the component within the SDK except with periods (.) instead of slashes (/) to separate sub folders. For example: components.gecko_os.drivers.hygrometers.si7013

Using a Device Driver to Communicate with the Si7021 Sensor

Next, you will learn how to add the Si7021 temperature/humidity sensor device driver to the project and use the driver to read the temperature and humidity from the sensor. The driver is included in the Gecko OS SDK as a component.

STEP 1. Add the Si7013 device driver component to the project as shown in the section Gecko OS Components . Note that the Si7013 driver also supports the Si7021 temperature/humidity sensor as both parts are from the same device family.

STEP 2. After adding the component in the project settings, the si7013 folder will appear in the Project Explorer as shown below. Note that this folder is a soft link to the component folder in the SDK directory.

STEP 3. Add code to detect the Si7021 using the newly added driver. The Si7021 driver uses the Gecko OS I2C Master peripheral API to communicate with the device. To use the driver, first include the driver header file with #include "si7013.h" and then declare a gos_i2c_device that is used as the handle to the driver. After those two are added, we can use the driver to communicate with the device. The code below adds the driver and calls two driver functions from within gos_app_init() to detect the device and read the device firmware. 

#include "gos.h"
#include "si7013.h"

static gos_i2c_device_t si7021_device =
{
  .port         = PLATFORM_STD_I2C,
  .address      = SI7021_ADDR >> 1,
  .speed        = GOS_I2C_CLOCK_HIGH_SPEED,
  .read_timeout = 50,   // si7021 can take up to 25 ms to finish a conversion
  .retries      = 0,
  .flags        = 0
};

// ------------------------------------------------------------------------------------------------
void gos_app_init(void)
{
  uint8_t part_id  = 0;
  uint8_t part_rev = 0;

  // Print to the serial terminal
  GOS_LOG("Weather Demo");

  // Detect the Si7021 and read the firmware version
  Si7013_Detect(&si7021_device, 0, &part_id);
  Si7013_GetFirmwareRevision(&si7021_device, 0, &part_rev);
  if(part_id == SI7021_DEVICE_ID)
  {
    GOS_LOG("Detected Si7021 Version %d.%d", ((part_rev >> 4) & 0xF), (part_rev & 0xF));
  }
  else
  {
    GOS_LOG("Si7021 Not Detected");
  }
}

View complete tutorial source code

STEP 4. Build and download the application by double-clicking on Download Application . After the download completes, the following text appears in the device console. 

[Ready]
LOCAL> Weather Demo
Detected Si7021 Version 2.0

Creating Events to Read and Report the Weather

Next, add a couple of events to read the temperature and humidity from the Si7021 and report the results to the device console. Gecko OS applications follow an event-driven programming model. The details will not be discussed in this tutorial, but more information can be found in the Gecko OS documentation:

For this tutorial, you will learn how to add a periodic event that initiates a Si7021 measurement. This event will, in-turn, register a timed event to read the results 50 milliseconds later, then report the results to the device console. The periodic event will run every 10 seconds.

STEP 1. Register the periodic event in the gos_app_init() as show below. 

#define WEATHER_REPORT_PERIOD_MS         10000

void gos_app_init(void)
{
  ...

  gos_event_register_periodic(start_measurement_event_handler, 0, WEATHER_REPORT_PERIOD_MS, 0);
}

View complete tutorial source code

STEP 2. Add the event handler functions as shown below to the main.c file of the project. The code registers a periodic handler start_measurement_event_handler() that runs every WEATHER_REPORT_PERIOD_MS seconds. The periodic handler starts a measurement, then registers a one-shot timer handler read_and_report_event_handler that reads and reports the sensor value after SI7021_MEASUREMENT_TIME_MS (which is enough time for the sensor reading to complete). Existing code is highlighted in blue text, new code is in black. 

#define SI7021_MEASUREMENT_TIME_MS       50  // the si7021 takes max 50ms to perform measurement

void gos_app_init(void)
{
  ...
}

// ------------------------------------------------------------------------------------------------
// Start the measurement then schedule a timed event to read the measurement
// ------------------------------------------------------------------------------------------------
static void start_measurement_event_handler(void *arg)
{
  //Initiate the measurement
  Si7013_StartNoHoldMeasureRHAndTemp(&si7021_device, 0);

  // The Si7013 takes a maximum of 50 ms to complete a measurement
  // therefore we register an event to read the results 50 ms later
  gos_event_register_timed(read_and_report_event_handler, arg, SI7021_MEASUREMENT_TIME_MS, 0);
}

// ------------------------------------------------------------------------------------------------
// Read the measurement then report the results
// ------------------------------------------------------------------------------------------------
static void read_and_report_event_handler(void *arg)
{ uint32_t rh_data;
  int32_t temp_data;
  char temp_float_str[10];
  char rh_float_str[10];

  //Read the measurement results
  Si7013_ReadNoHoldRHAndTemp(&si7021_device, 0, &rh_data, &temp_data);

  //Format the results to a floating point number and output to the console
  GOS_LOG("Temp: %s C | RH: %s %%",
           float_to_str((float)(temp_data/1000.0), temp_float_str, 1),
           float_to_str((float)(rh_data/1000.0), rh_float_str, 1));
}

View complete tutorial source code

STEP 3. After adding the code shown above, double-click on Download Application . Once the project is built and downloaded to the device the following will appear in the device console with a new report being added every 10 seconds. 

LOCAL> Weather Demo
Detected Si7021 Version 2.0
Temp: 29.2 C | RH: 31.3 %
Temp: 29.3 C | RH: 31.2 %
Temp: 29.2 C | RH: 31.1 %
Temp: 29.3 C | RH: 31.1 %

STEP 4. Place your finger on the Si7021 sensor or blow air over the top of it to see the results change as the sensor heats or cools. For your reference, the image below shows the location of the Si7021 sensor on the WSTK main board.

Adding the Gecko OS Web Application

The Gecko OS web application is technically a Gecko OS component. However, it is added/removed from a project differently in the IDE. By default, the web app component is added to a new project upon project creation because it is commonly used by many applications. To remove it, right click on the project then select Properties . In the Properties dialog navigate to C/C++ Build -> Settings -> General . Use the Add Gecko OS Webapp check box as shown in the image below. Before continuing, select Apply and Close .

Go to the web app component folder found in the SDK sub-directory resources/gecko_os/webapp , and view the web app makefile webapp.mk as well as the associated manifest.cfg file. Notice that this particular web app component does not consist of any code. It is purely a set of files programmed to the file system on the device.

With the application running, open the device console and type the ls command. You will see the web app files matching those listed in the manifest.cfg file. This is shown below with the web app files highlighted in yellow. 


LOCAL> ls
!  #   Size   Version Filename
#  0    297     3.1.5 favicon.ico.gz
#  1 320020    4.1.11 sys/kernel.bin
#  2 291920     3.3.0 sys/wfm_wf200.sec
#  3 189220     0.0.1 weather.app
#  4  23823     3.1.5 webapp/gecko-os.css.gz
#  5  73109     3.1.5 webapp/gecko-os.js.gz
#  6   1819     3.1.5 webapp/index.html
#  7   9530     3.1.5 webapp/unauthorized.html

For practice, remove the web app component from the project and view the changes to the application. To remove the web app, uncheck the Add Gecko OS Webapp check box in the project properties dialog as described previously.

Click Apply and Close , then double-click on the build target Download Application and Resources .

Note! Since the web app component includes resources, you must use Download Application and Resources for the changes to be reflected on the device. After the application is loaded, type the ls command in the device console again and observe that the web app files are no longer available on the device file system. 


LOCAL> ls
!  #   Size   Version Filename
#  0 320020    4.1.11 sys/kernel.bin
#  1 291920     3.3.0 sys/wfm_wf200.sec
#  2 189220     0.0.1 weather.app

Re-add the web app by checking the Add Gecko OS Webapp check box in the project properties dialog. Then, double click the Download Application and Resources build target. Confirm the web app files have been restored to the device file system.

Wi-Fi Setup Using the Web App

The web app can be used as the primary interface to configure Wi-Fi network settings for your device. To enable use of the web app, we will change the application code to start Web Setup if a Wi-Fi connection is not successful. Web Setup initiates softAP mode allowing the user to connect to the device via Wi-Fi as if the device itself was an access point. Once connected, the user can configure the Wi-Fi network.

Note! The Gecko OS SDK includes a device setup example application that can also be used to explore this functionality.

STEP 1. In the function gos_app_init() , add a call to a new function to start the network interface and register two new event handlers to monitor and report the status of the setup events. As before, existing code is in blue and new code is in black. 

void gos_app_init(void)
{
  ...

  gos_network_register_event_handler(GOS_INTERFACE_WLAN, wlan_network_event_handler);
  gos_setup_register_finished_event_handler(setup_finished_handler);

  start_network_interface();
}


View complete tutorial source code

STEP 2. Append the function start_network_interface() to main.c. This function attempts to connect to a Wi-Fi network and, if not successful, start Web Setup. 

// ------------------------------------------------------------------------------------------------
// Try to start WLAN interface
// On failure, start web setup
// NOTE: Web setup will idle timeout after setup.web.idle_timeout seconds
//       Upon timeout, the system is rebooted.
// ------------------------------------------------------------------------------------------------
static void start_network_interface(void)
{
  gos_result_t result;

  GOS_LOG("\r\n\r\nChecking if device is able to connect to local network ...");

  if (GOS_FAILED(result, gos_network_up(GOS_INTERFACE_WLAN, true)))
  {
    GOS_LOG("Failed to join local network, starting Web Setup");

    if (GOS_FAILED(result, gos_setup_start()))
    {
      GOS_LOG("Failed to start Web Setup, rebooting");
      gos_system_reboot();
    }
    else
    {
      char buffer_url[128];
      char buffer_username[64];
      char buffer_passkey[64];
      uint32_t idle_timeout;
      gos_settings_get_uint32("setup.web.idle_timeout", &idle_timeout);
      get_setup_url("setup.web.url", buffer_url, sizeof(buffer_url));
      get_device_name("setup.web.ssid", buffer_username, sizeof(buffer_username));
      gos_settings_get_print_str("setup.web.passkey", buffer_passkey, sizeof(buffer_passkey));
      GOS_LOG("");
      GOS_LOG("Device Web Setup started");
      GOS_LOG("  1. Connect to Wi-Fi network: %s with passkey: %s", buffer_username, buffer_passkey);
      GOS_LOG("  2. Open browser to http://%s", buffer_url);
      GOS_LOG("  3. Setup the device\r\n");
      if(idle_timeout != 0)
        GOS_LOG("NOTE: Web setup will idle timeout after %d seconds\r\n", idle_timeout);
    }
  }
  else
  {
    GOS_LOG("Device WLAN started");
  }
}

View complete tutorial source code

STEP 3. Append the function wlan_network_event_handler() to main.c. This function handles network events on the WLAN interface. 

// ------------------------------------------------------------------------------------------------
// Event handler for WLAN interface events
// ------------------------------------------------------------------------------------------------
static void wlan_network_event_handler(bool is_up)
{
  // If the WLAN interface has gone down AND softAP interface is NOT up try to restart the WLAN interface
  if ((is_up == false) && (gos_network_is_up(GOS_INTERFACE_SOFTAP) == false))
  {
    // If the network goes down try to restart it, else start web setup
    start_network_interface();
  }
}

View complete tutorial source code

STEP 4. Append the function setup_finished_handler() to main.c. This function is called when the user has set up the WLAN interface from the Web App. 

// ------------------------------------------------------------------------------------------------
// Just reboot the system when web setup finishes
// ------------------------------------------------------------------------------------------------
static void setup_finished_handler(void *unsed)
{
  GOS_LOG("Web setup finished, rebooting system");
  gos_system_reboot();
}

View complete tutorial source code

STEP 5. Append the following helper functions to main.c. These functions are used to format the device name and URL for console output. 

// ------------------------------------------------------------------------------------------------
// Convert '#' to last three chars of device's MAC address
// ------------------------------------------------------------------------------------------------
static const char* get_device_name(const char *setting, char *buffer, size_t buffer_length)
{
  int setting_len;
  char *setting_ptr;

  gos_settings_get_print_str(setting, buffer, buffer_length);
  setting_len = strlen(buffer);
  setting_ptr = &buffer[setting_len-1];

  if (*setting_ptr == '#')
  {
    char mac_str[20];

    // Example output:
    // 4C:55:CC:10:78:9B
    gos_settings_get_print_str("softap.mac", mac_str, sizeof(mac_str));

    *setting_ptr++ = mac_str[13];
    *setting_ptr++ = mac_str[15];
    *setting_ptr++ = mac_str[16];
    *setting_ptr = 0;
  }

  return buffer;
}

// ------------------------------------------------------------------------------------------------
// Get the first entry in the setup.web.url domain list
// ------------------------------------------------------------------------------------------------
static const char* get_setup_url(const char *setting, char *buffer, size_t buffer_length)
{
  gos_settings_get_print_str("setup.web.url", buffer, buffer_length);

  char *comma_ptr = strchr(buffer, ',');
  *comma_ptr = 0;

  return buffer;
}

View complete tutorial source code

STEP 6. Double click on the Download Application and Resources build target. After the application is loaded, you will see a message similar to the following in the device console. 


Failed to join local network, starting Web Setup
Finding best SoftAP channel ...
IPv4 address: 10.10.10.1
HTTP and REST API server listening on port: 80
Wi-Fi softAP: Gecko_OS-1BF on channel 1
Web browser : http://setup.com

Device Web Setup started
  1. Connect to Wi-Fi network: Gecko_OS-1BF with passkey: password
  2. Open browser to http://setup.com
  3. Set up the device

NOTE: Web setup will idle timeout after 300 seconds

STEP 7. Using a mobile device or a computer, follow the instructions to connect to the SoftAP created by the device and use the web app to configure the Wi-Fi settings. After the Wi-Fi settings are configured, the device will reboot. After reboot, the device will automatically connect to the Wi-Fi network.

Preserve NVM Settings During Development

The Wi-Fi settings configured in the previous section are stored in the Gecko OS variables wlan.ssid and wlan.passkey and saved in Non Volatile Memory (NVM) along with other settings. Typically, NVM is reset every time an application is downloaded to the device. This can become burdensome during development because it requires the developer to re-setup the Wi-Fi network and other settings each time the code is modified.

To remedy this, you can enable a project setting to preserve NVM settings through application programming. Right click on the project then select Properties . In the Properties dialog navigate to C/C++ Build -> Settings -> General . Click the Preserve NVM settings through application programmings? check box as shown in the image below.

Configuring Gecko OS for your Application

Gecko OS Variables configure a Gecko OS device. They are essentially just configuration settings. The Gecko OS Settings API is used to programmatically access Gecko OS variables . In the context of the C API, the terms variables and settings may be used interchangeably.

For this tutorial, you will create a settings.ini file and use the API function gos_load_app_settings_once() to configure the default state of the HTTP server. Any other Gecko OS variable can be added to the settings.ini file to configure the default value of the variable.

STEP 1. Create a new file in the project called settings.ini with the following content. 

# Enable the HTTP Server
http.server.enabled 1

# Enable the mDNS daemon
mdns.enabled 1

# Configure the mDNS name.
mdns.name mydevice-#

STEP 2. Add a function call to gos_load_app_settings_once() to the gos_app_init() function as shown below. This causes the settings stored in the settings.ini file to be loaded when the application is initialized. 

void gos_app_init(void)
{
  GOS_LOG("Weather Demo");
  ...

  gos_load_app_settings_once("settings.ini", 1);

  ...
}

View complete tutorial source code

STEP 3. Edit the project makefile weather.mk to specify the setting.ini file as shown below.

Note! Because GSS does not (yet) include a user interface control to add the settings.ini file, you must edit the makefile manually. 

# Paths to app settings .ini files  (paths are relative to project directory)
$(NAME)_SETTINGS_INCLUDES := settings.ini

STEP 4. Double click on the Download Application build target to rebuild and download the application. Note that the settings file is built into the application image and is NOT stored in the filesystem.

STEP 5. After the application is loaded on the device, verify the device settings are correct using the console as shown below. 

LOCAL> get http.server.enabled
1
LOCAL> get mdns.enabled
1
LOCAL> get mdns.name
mydevice-#

STEP 6. You should also now be able to access the web app by performing the following steps.

  1. Using a mobile device or a computer, connect to the same Wi-Fi network as your device
  2. Open a web browser
  3. Navigate to http://mydevice-NNN/ where NNN is the last three hex characters of the MAC address of the device. For example, if the MAC address of your device is 4C:55:CC:10:26:05 , the URL becomes mydevice-605 . Use the Gecko OS Command get wlan.mac to get the MAC address for your device.

Note! Not all clients support Network Discovery . In this case, connect to the web app using the IP address of the device, like the following http://10.10.10.1/ . The IP address of the device can be read with the wlan.network.ip variable.

Adding Files to the Filesystem

Gecko OS provides a reliable read/write filesystem for use by the application. See Gecko OS File System .

Add files to the filesystem using different methods including:

  • Use the IDE and a component with makefile during development
  • Manually add files to a bundle on the DMS. See the section Deploying your application to the DMS for more information about working with bundles on the DMS.
  • Manually add files to a specific device via the web app
  • An application can write files directly to the filesystem using the filesystem API .
  • An application can download files from a web server using the http_download command.

In this tutorial, you will focus on the first method to use the IDE and a component with makefile. The steps below create and include the file about.html and illustrate how to view the contents of this file in both the command console and the Web app.

STEP 1. Add a new file in the root directory of the project named about.html with the following contents. This is a simple HTML file that describes the application. 

<!DOCTYPE html>
<html>
    <head>
        <title>Gecko OS Weather Example Application</title>
    </head>
    <body>
        <h1>Gecko OS Weather Example Application</h1>
        <p>This example application is developed as part of the Gecko OS SDK Tutorial.</p>
        <p>The tutorial can be found at <a href="http://docs.silabs.com/gecko-os/4/standard/latest/"> http://docs.silabs.com/gecko-os/4/standard/latest/ </a></p>
    </body>
</html>

STEP 2. Add a new file to the root directory of the project named manifest.cfg with the following contents. The manifest file will list all the files to be added to the filesystem. For another example of a manifest file, view the manifest.cfg file of the webapp component. 

###############################################
#
# Resource Manifest
#
#################################
[about.html]

name: about.html
type: GENERAL
path: about.html
version: 1.0.0

STEP 3. Edit the makefile weather.mk to specify the manifest.cfg file.

Note! Because GSS does not (yet) include a user interface control to add the manifest file, you must manually edit the makefile. 

# Path to resource manifest (path is relative to project directory)
$(NAME)_RESOURCE_MANIFEST_PATH := manifest.cfg

STEP 4. Double-click on the Download Application and Resources build target to rebuild and download the application and resource to the device.

STEP 5. After the application is loaded on the device, verify the about.html file is available on the filesystem using the ls command as shown below. The new about.html file is highlighted in yellow. 

LOCAL> ls
!  #   Size   Version Filename
#  0    453     1.0.0 about.html
#  1    297     3.1.5 favicon.ico.gz
#  2 320020    4.1.11 sys/kernel.bin
#  3 291920     3.3.0 sys/wfm_wf200.sec
#  4 189220     0.0.1 weather.app
#  5  23823     3.1.5 webapp/gecko-os.css.gz
#  6  73109     3.1.5 webapp/gecko-os.js.gz
#  7   1819     3.1.5 webapp/index.html
#  8   9530     3.1.5 webapp/unauthorized.html
LOCAL>

STEP 6. Read the file contents in the command prompt as shown below. The yellow text is user input and the white text is device output. 

LOCAL> file_open about.html
[2019-06-04 | 20:28:31: Opened: 1]
1
LOCAL> read 1 500
<!DOCTYPE html>
<html>
    <head>
        <title>Gecko OS Weather Example Application</title>
    </head>
    <body>
        <h1>Gecko OS Weather Example Application</h1>
        <p>This example application is developed as part of the Gecko OS SDK Tutorial.</p>
        <p>The tutorial can be found at <a href="http://docs.silabs.com/gecko-os/4/standard/latest/ "> http://docs.silabs.com/gecko-os/4/standard/latest/ </a></p>
    </body>
</html>

[2019-06-04 | 20:28:47: Closed: 1]

STEP 7. View the about.html file in the device's web app by performing the following steps.

  1. Using a mobile device or a computer, connect to the same Wi-Fi network as your device
  2. Open a web browser
  3. Navigate to http://mydevice-NNN/about.html where NNN is the last three hex characters of the MAC address of the device. For example, if the MAC address of your device is 4C:55:CC:10:26:05 , the URL becomes mydevice-605 .

Note! Not all clients support Network Discovery . In this case, connect to the web app using the IP address of the device, like the following http://10.10.10.1/about.html . You can discover the IP address of the device be reading the wlan.network.ip Gecko OS variable.

Deploying your Application to the DMS

At any stage during the development process, your application can be deployed to the DMS as a development product. Once deployed, the application can be accessed by other devices and by other DMS users that have been given permission to access the product.

Note that your DMS account is limited to a default of 50 devices that can be activated to a Development Product. Development Products are intended for development and small pilot runs only and do not have the security and role-based access restrictions necessary for large scale Production.

It is important to understand the differences between development and production DMS products. More information can be found at: Understanding the terms Development and Production

STEP 1. As discussed in Setting up your device for development , a development product for your device is automatically created on the DMS when you set up the device. Log into dms.zentri.com and view your development products.

STEP 2. Click on the <User Code>-WEATHER project and select the Bundles tab. If you have not yet deployed the product to DMS, you will find that no bundles exist for the project as shown below.

STEP 3. In the GSS IDE, double-click on the Release to DMS build target as shown below.

STEP 4. On the DMS, you will now see a new bundle added to your development product. Every time you release your project to the DMS, a new bundle will be created and the bundle version will be incremented.

STEP 5. Select the new bundle to view the details and contents of the bundle.

As you can see from the screen shot above, the bundle was released in a Preview state providing a way to add/remove files to the bundle. Notice the bundle includes the file weather.app . This is the application binary that was compiled and tested using the SDK in the previous steps. Also, notice the bundle includes the files that are part of the web app.

A bundle can be in several states, including Published . Once the bundle is set to Published, the bundle can no longer be edited. The Gecko OS Application SDK automatically releases bundles to the DMS in a Preview state to enable developers to make final edits to the bundle before publishing.

STEP 6. If you do not have any changes for the bundle, set the bundle state to Published . Once set to Published , a new drop-down appears allowing you to select a Tag . The Alpha and Beta tags are used during product testing, but for release software the tag is set to Release . This sets the bundle to the default bundle delivered when a device firmware update (DFU) is initiated.

For additional details on the operation of bundles, see DMS tutorial . The notes below help to summarize the key aspects.

  • Remember that a Published bundle can no longer be changed. If you made a mistake, try copying the bundle and editing the new bundle.
  • The tag identifies which devices can gain access to the bundle. All devices are tagged as Release by default, including all standard evaluation boards. It is possible to change the tag of any device to alpha, beta or release. The device will then be able to access any bundle with a matching tag.
  • A Preview bundle can still be used to update the device firmware, but it's better to use a published bundle since the contents of the bundle are immutable (can’t be changed). This avoids confusion over which files are loaded onto a device if the bundle contents are changed multiple times.

Performing Over the Air Firmware Updates via the DMS

After a bundle is released to the DMS for your product, an over-the-air firmware update (OTA DFU) can be performed to update your device to the bundle. First, ensure that your Wi-Fi settings are configured correctly to connect to a Wi-Fi access point and that the access point has Internet access. In the device console, issue the (optional) Gecko OS command dfu_query to check if a new update is available. Then, issue dfu_update to perform the firmware update. The dfu_update command automatically performs a query to determine if an update is available and only performs the update if required. The console output below shows the entire update process. User input is shown in yellow. 

LOCAL> dfu_query
Request POST /check
Connecting (https): dfu.zentri.com:443
Starting TLS
1,03MWMC-WEATHER-0.0.1, Gecko_OS-STANDARD-4.1.11, WGM160P
LOCAL> dfu_update
UUID:EADE2FF30138EF705FC7265FD0CF5EFFFE9101BE
DFU restarting ...
Rebooting
Starting network ...
Request POST /request
Connecting (https): dfu.zentri.com:443
Starting TLS
Bundle version: 03MWMC-WEATHER-0.0.1, Gecko_OS-STANDARD-4.1.11, WGM160P
Performing 'single-pass' update
Caching  [size:   284] sys/device_credentials.bin
Caching  [size:178016] weather.app
Copying sys/device_credentials.bin (0x02000085) to internal flash
Copying weather.app (0x020000A9) to internal flash
Updating device credentials
Starting network ...
Request POST /result
Connecting (https): dfu.zentri.com:443
Starting TLS
Exiting DFU mode, status: 1
[2019-05-04 | 05:50:30: Ready]
[2019-05-04 | 05:50:30: Associating to SiliconLabsGuest]
DFU completed successfully

To successfully update firmware, the device must be activated to the product. To activate a device to a development product, the device must be claimed by a user that has access to the product. The Device Setup process described earlier will perform both of those steps. However, be careful when working with multiple projects to avoid unwittingly activating your device to a different product.

Sharing Your Development Product with Other Users or Other Devices

To share the product with other users or to update other devices without using the Device Setup process, use the dms_activate command to activate the device to a product as shown below. 

LOCAL> dms_activate 03MWMC-WEATHER
Request POST /activate
Connecting (https): dfu.zentri.com:443
Starting TLS
Device activated

The device must be claimed to a DMS user that has access to your development product. To provide another user access to your product, click on the <User Code>-WEATHER product in the DMS then select Users as shown below.

If the device is not already claimed, the user can claim their device using the dms_claim command. The dms_claim command requires an account token from the DMS. To obtain a token, log in to the DMS and in the upper right hand corner, select Profile followed by API Tokens . See the example screen capture below.

Copy one of the valid user tokens and paste it into the dms_claim command as shown below: 

LOCAL> dms_claim ****************
Request POST /claim
Connecting (https): dfu.zentri.com:443
Starting TLS
Device claimed

Once the device is claimed and activated, the dfu_update command can be used to update the device as described in the section: Performing over the air firmware updates via the DMS

Taking the Product to Production on the DMS

The tutorial has described the process of working with Development Products. A development product is unique to a developer and is only accessible by the developer unless another developer has been given explicit access to the Product. This enables product development and testing to be performed in isolation from devices deployed in the field. There is no chance that a device in the field can accidentally become activated and updated to a development version of the product. Once the development process is complete, a development product may be transitioned to production whereby the product can be deployed to a large fleet of devices in the field. Production Products are subject to a much higher level of security and the DMS provides a more sophisticated role-based level of access to assist with fleet management.

Further explanation of the differences between development and production DMS products can be found at: Understanding the terms Development and Production

The details of transitioning a product from development to production on the DMS will not be covered further in this tutorial. Details can be found in the DMS tutorial at http://dms.zentri.com .

Advanced Topics