Gecko OS Command API Tutorial

This tutorial provides hands on experience using the Gecko OS Command API with the WGM160P Wi-Fi starter kit available from Silicon Labs.

Key Points

Hardware Requirements

Hardware Setup

Connect the WGM160P board to your PC using the provided USB cable.

Software Requirements

Note : You will need an internet connection to install the drivers for the USB-to-UART device on the WGM160P board.

Checking the Version

After connecting the board to the PC and opening the terminal program, press the RESET button on the board.

Gecko OS restarts and displays the version information for the device. Ensure this version is 4.0.0 or later.

To set up the latest version of Gecko OS on your device, use the Gecko OS Studio (GSS) .

The Help Command

The help command lists the commands and variables available for this platform and firmware version.

Variables are system-level variables that determine the configuration of the WGM160P module.

Commands are actions that the can be taken.

At the terminal prompt, type help to see the options for the help command.

Type help commands to see a list of commands supported by this module.

Commands used:

Connecting to the WGM160P over Wi-Fi

Gecko OS can run a softAP (soft Access Point) and an HTTP Server with a web application. Your mobile device connects to the softAP through Wi-Fi, and the Gecko OS web app provides a web-based interface to interact with your device.

To see the Gecko OS softAP details, at the terminal type get setup.web . This lists all the setup web variables and their values: 

> get setup.web
setup.web.captive_portal_enabled: 1
setup.web.client_list: ! Connected: 0
setup.web.idle_timeout: 300
setup.web.passkey: password
setup.web.root_filename: webapp/index.html
setup.web.ssid: Gecko_OS-#
setup.web.url: setup.com,www.setup.com,connectivitycheck.gstatic.com

To get a specific variable, rather than a group, use the full name of the variable. For example, to get the softAP MAC address: 

> get softap.mac
4C:55:CC:F4:86:AC

The variable setup.web.ssid defaults to the value Gecko_OS-# . The # is a placeholder for the last 3 digits of the softAP MAC address. In the example above, the setup.web.ssid is Gecko_OS-6AC .

As can be seen in the setup.web variable list, the default setup.web.passkey is password .

You can set the setup.web.ssid variable to a value of your choosing. For now, accept the default address.

To start the softAP and the HTTP server, use the setup_web command. On the terminal issue the command: 

setup_web

The terminal output is similar to the following: 

> setup_web
Finding best SoftAP channel ...
IPv4 address: 10.10.10.1
HTTP and REST API server listening on port: 80
Wi-Fi softAP: Gecko_OS-805 on channel 6
Web browser : http://setup.com
In progress

Then, using your phone or other Wi-Fi device, connect to the Gecko OS access point using the setup.web SSID and passkey.

Depending on your mobile device's operating system, the mobile device may automatically open a web browser and display the device web app. Alternatively, open a web browser and navigate to the device IPv4 address or URL

In the example shown, the IP address is 10.10.10.1 . You can use the IP address, or you can use one of the values shown in the setup.web.url variable. The defaults are setup.com or www.setup.com .

The web app display is similar to the following:

You can use the Connect screen to connect to your local WLAN. For now, let's explore other features of the web app.

Click the GPIOs tab in the web app menu. On a small screen, tap the three bar menu icon to open the menu first.

The GPIOs screen shows the active GPIOs available on your device.

Click the Files tab. The Files screen lists the files in your device flash file system.

This screen provides a convenient way to copy files to and from the device file system.

Commands used:

Type reboot to restart Gecko OS with no SoftAP or HTTP server running.

Scan and Connect

Now, let's connect to a Wi-Fi network. Use the scan command to find all the networks in range: 

scan

Commands used:

The wlan.ssid and wlan.passkey variables set the Wi-Fi network name and password, respectively.

Set the values of wlan.ssid and wlan.passkey to match the credentials of your Wi-Fi network, then save the values so they persist after a reboot: 

set wlan.ssid <NETWORK_NAME>
set wlan.passkey <NETWORK_PASSWORD>
save

To connect to the specified network, use the network_up command, or simply issue a command that requires network access: 

network_up

You should now be connected to the network.

Note : To join your specified network automatically each time the module is powered on or rebooted, issue the command: 

set wlan.auto_join.enabled 1

Commands used:

Listing Files

Gecko OS offers a file system and includes a Unix style list command ls .

Type ls to display a basic file list.

Type ls -v to display a more verbose list with file type, flags, and other information.

Commands used:

Reading from a File

Data sources like files are called streams in Gecko OS. To read from one of these files:

The stream handle is displayed in the response. If only one stream is open, the handle is 0 .

To view all open streams, including file and network streams, type: 

stream_list

To read 100 bytes from stream 0 , issue the command: 

stream_read 0 100

Commands used:

Downloading from a Website

To get a file from a website, use the http_get command.

For example, to open a stream with the Google homepage: 

http_get www.google.com

In this example we assume the HTTP stream has the stream handle 1 .

To read the first 1000 bytes from stream 1 : 

stream_read 1 1000

Commands used:

Closing a Stream

To close a stream, use the stream_close command.

In the examples below, we assume file stream 0 and HTTP stream 1 are still open.

To close the file stream 0 : 

stream_close 0

Use stream_list to view the open streams. Only stream 1 is still open. 

stream_close 1

Now no streams are open.

Commands used: