Command API Quickstart

The fastest way to learn about the Gecko OS Command API is to use a desktop machine and a UART terminal application or a web browser over Wi-Fi.

To connect your Gecko OS device to a Wi-Fi network, you need to supply the device with network credentials: the wireless network name (SSID) and password. Let's get started!

There are a few steps involved:

When you have set up a Gecko OS terminal, verified your Wi-Fi network credentials and tested the connection, you can work with the extensive feature set provided by Gecko OS. One of the key features is device firmware update (DFU). Gecko OS provides multiple options to update firmware, including wireless update over-the-air (OTA). Firmware update enables you to load the latest version of Gecko OS, or load specific Gecko OS products for development purposes, onto your device. The steps to perform DFU OTA are:

Programming Gecko OS onto your Device

Some WGM-series IoT devices from Silicon Labs may not be factory programmed with Gecko OS. Follow the Device Setup Guide to program your device with Gecko OS.

Performing a Factory Reset

You may optionally perform a factory reset to ensure the device is in a known state.
Performing a factory_reset returns variables to the default configuration.

Note : On a Silicon Labs Wireless Starter Kit (WSTK), Button 1 is labelled PB0 .

The device can be factory reset with the factory_reset command using a Gecko OS terminal .

To perform a factory reset:

  • Press Button 1 and do not release it.
  • Press and release the Reset button
  • Continue to press Button 1 for at least 10 seconds
  • Release Button 1 .

Opening a Gecko OS Terminal

You can control your Gecko OS device using the Gecko OS Command API via a UART serial terminal or console application.

Note : If your new Gecko OS device does not respond to commands, you may need to program it with Gecko OS .

For a Gecko OS evaluation board, plug the board into the USB port of your computer using a USB cable. USB provides power and a UART serial connection.

For a device not on an evaluation board, connect the terminal to device UART 1 and provide power to the device. For pinout information, see Peripherals, GPIO Functions and Pins or the device datasheet.

With the device UART connected:

  • Open a communication terminal application e.g. Teraterm
  • Find the UART serial (COM) port associated with the eval board
  • Set the communication parameters to 115200 8N1 with NO hardware flow control
  • Press the enter key. Gecko OS responds with a ready message and command prompt: 
Ready
>
  • At the Gecko OS prompt, type version and check for a response similar to the text below. 
> version
SILABS-WGM160P-4.0.11, Gecko_OS-STANDARD-4.0.8, WGM160P

If problems arise, see the Gecko OS Troubleshooting Guide .

Setting up Wi-Fi Network Credentials

The Wi-Fi network credentials used by Gecko OS are stored in the wlan.ssid and wlan.passkey variables.

There are several ways to set these values, including:

Setting up with the Command API

To set up with the command API, open a Gecko OS terminal as described above.

Enter the following commands in a Gecko OS terminal:

Gecko OS Commands Description 

set wlan.ssid     YOUR_AP_NAME
set wlan.passkey  YOUR_AP_PASSWORD
save


SSID (Service Set Identifier, or network name) for your Access Point
Password for your Access Point
Save variables so the values persist after reboot

Substitute the appropriate values for the placeholders YOUR_AP_NAME and YOUR_AP_PASSWORD .

Now you can verify the network connection . See below .

Setting Up with the Gecko OS Web App

The Gecko OS Web App provides a graphical interface to configure the network credentials on the device using a web browser. Gecko OS runs a Soft AP and an HTTP web server on the Gecko OS device. You connect to the soft AP with a mobile device or computer, and run the Web App in a web browser.

In a Gecko OS terminal, enter the command: 

setup_web

Evaluation boards may also be placed into web setup mode without connecting a Gecko OS terminal:

  • Press Button 2 and do not release it
  • Press and release the Reset button
  • Continue to hold Button 2 for at least three seconds
  • Release Button 2

For more details, see Gecko OS Web App, Setup Web Mode .

This starts the Gecko OS Soft AP. By default the Soft AP SSID is Gecko OS-nnn , where nnn is the last three hex digits of the device WLAN MAC address, e.g. Gecko OS-2D6 . The default password is password .

Connect a mobile device or Wi-Fi enabled computer to this network. Open a web browser and navigate to setup.com or Gecko OS.com .

The Gecko OS Web App opens the Web App connect tab by default, and scans for Wi-Fi networks in range.

Select your preferred network, enter the network password and click Connect . The Web App verifies the password and connects to the WLAN. If you select the Reconnect to device option, the web app restarts your Gecko OS device, and attempts to reconnect to it via the WLAN. For more details, see Gecko OS Web App, Setup Web Mode .

Now you can verify the network connection . See below .

Verifying the Network Connection

When you issue any Gecko OS command that requires network access, Gecko OS attempts to bring the network up using the values set for wlan.ssid and wlan.passkey .

You can bring the network up with the network_up command.

In the Gecko OS terminal , at the > prompt, enter the command as shown. The response should be similar to the following:

Gecko OS Commands Description 

> network_up
In progress
> [Associating to YOUR_NETWORK_NAME]
> Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.74


<- Bring the network up
Gecko OS responds with progress messages

If your Gecko OS device successfully obtains an IP address, it is successfully connected to the network.

Most Gecko OS evaluation boards have a network indicator LED to help determine successful connection to a network (but the WSTK does not). The network indicator LED changes its blink rate from fast (no IP address), to medium (DHCP in progress) to slow (DHCP successful, IP address obtained).

If your WLAN is connected to the Internet, you can try an Internet protocol command. For example, ping a known host:

Gecko OS Commands Description 

> ping google.com
Ping reply in 7ms


<- ping a Google web address
Gecko OS response indicates success

Claiming Your Device

The Zentri Device Management Service can be used to manage secure and authenticated firmware udpates, as well as the health and location of Gecko OS devices deployed in the field. A free DMS account is required before DMS features such as firmware updates are available. To create a DMS account, go to https://dms.zentri.com and follow the Create an Account link. The DMS username (your email address) and password you register are used when you login to the DMS to obtain an API token. See dms_claim .

To claim your device, issue the dms_claim command in a Gecko OS terminal :

Gecko OS Commands Description 

> dms_claim <YOUR_TOKEN>
Request POST /claim
Connecting (https): dfu.zentri.com:443
Starting TLS
{"result":"ok"}


<- claim your device
Gecko OS response shows a successful result

When you have successfully claimed your device, you can update it . See below .

For full details of the DMS claim and OTA update process, see Update and Recovery .

Performing a Firmware Update

To update the firmware on your device, see Device Firmware Update (DFU) .

Gecko OS Applications

Now that you have established control over your Gecko OS device, you can experiment with the rich set of Gecko OS features using the Gecko OS Command API.

There are many application notes demonstrating Gecko OS networking applications. See Application Examples .

Getting Help

As well as the Gecko OS documentation provided on this website, Gecko OS also provides interactive command line help. At the Gecko OS terminal prompt, issue the help command: 

> help
Help options for the Gecko OS Command API ...
  help all        -> Print a list of all Commands and Variables
  help commands   -> Print a list of Commands
  help variables  -> Print a list of readable Variables
  help <command>  -> Print help for a specific Command
  help <variable> -> Print help for a specific Variable

  Additional help is available online at /gecko-os/4/standard/latest