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 get your Gecko OS device onto a wireless network, you need to supply the device with network credentials: the wireless network name (SSID) and password.

Let's get started!

There are 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 all the rich capabilities of Gecko OS. One of the most important Gecko OS features is over-the-air update (OTA). This lets you load the latest version of Gecko OS, or load specific Gecko OS products for development purposes. The steps are:

Performing a Factory Reset

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

You can factory reset with the factory_reset command, using a Gecko OS terminal .

With a Silabs evaluation board, you can perform a factory reset with the Reset button and 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.

For a Gecko OS evaluation board, plug the computer USB port into the evaluation board micro USB port. USB provides power and 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: 

Ready
>
> version
SILABS-AMW007-2.1.5, Gecko OS-2.1.5, AMW007-W00001

If problems arise, see the Gecko OS Troubleshooting Guide .

Setting up Wi-Fi Network Credentials

Your network credentials are stored in the Gecko OS 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 into 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 Web App

The 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 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

You can put Silabs evaluation boards into setup web mode without connecting a Gecko OS terminal:

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

This starts the Gecko OS Soft AP. By default the Soft AP SSID is Gecko OS Web Setup ### , where ### is the last three hex digits of the device WLAN MAC address, e.g. Gecko OS Web Setup 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 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 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_AP_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, you are connected.

Silabs evaluation boards have a network indicator LED to help determine successful association. 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 Silabs Device Management Service tracks Gecko OS devices, their owners, their firmware configuration and many other details. The DMS handles Over-the-Air (OTA) updates, providing a secure way to update devices in the field.

You need a free DMS account before using DMS features like OTA. To create an account go to the DMS Signup page. The DMS username (your email address) and password you register are used when you claim your device.

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

Gecko OS Commands Description 

> dms_claim YOUR_DMS_USERNAME YOUR_DMS_PASSWORD
Request POST /claim
Connecting (https): ota.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 perform an OTA update. See below .

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

Performing an OTA

Use OTA to update to the latest version of your device's Gecko OS product, or to load a development Gecko OS device with a specific Gecko OS product or version. You need to claim your device before performing an OTA. See above .

To OTA, in the Gecko OS terminal , issue the ota command:

Gecko OS Commands Description 

> ota
Disassociated]
UUID: 06413041000000002E0049001951343438333231
Connecting to network
Security type from probe: WPA2-AES
Request POST /ota
Connecting (https): ota.zentri.com:443
Starting TLS
Bundle size: 729088, Free space: 823296, Core size: 425984
Bundle version: SILABS-AMW007-2.1.5, Gecko OS-2.1.5, AMW007-W00001
...


<- update your device via the DMS server
Gecko OS displays progress messages

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

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 http://docs.silabs.com/gecko-os