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.
- How to use the WGM160P WSTK out of the box
- Where to go to get started and find documentation
- How to use the Gecko OS Command API
- How to connect to the WGM160P module as a Wi-Fi Access Point
- WGM160P kit, including:
- WGM160P board
- USB cable
- Getting Started card
Connect the WGM160P board to your PC using the provided USB cable.
- For Windows, use a terminal program such as Tera Term, RealTerm, or Terminal. See the UART parameters to
- For a Mac, the terminal can be accessed using
tty.usbserial. There may be a modifier at the end of this for your computer. To set the connection to the right settings, type:
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.
help commands to see a list of commands supported by this module.
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
setup.web.ssid defaults to the value
# is a placeholder for the last 3 digits of the softAP MAC address. In the example above, the
As can be seen in the
setup.web variable list, the default
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:
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
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.
GPIOs tab in the web app menu. On a small screen, tap the three bar menu icon to open the menu first.
GPIOs screen shows the active GPIOs available on your device.
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.
reboot to restart Gecko OS with no SoftAP or HTTP server running.
Scan and Connect
Now, let's connect to a Wi-Fi network.
scan command to find all the networks in range:
The wlan.ssid and wlan.passkey variables set the Wi-Fi network name and password, respectively.
Set the values of
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:
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
Gecko OS offers a file system and includes a Unix style list command
ls to display a basic file list.
ls -v to display a more verbose list with file type, flags, and other information.
Reading from a File
Data sources like files are called streams in Gecko OS. To read from one of these files:
- Issue the
lscommand to display a list of the files.
- Issue the
file_opencommand to open the file. For example:
The stream handle is displayed in the response. If only one stream is open, the handle is
To view all open streams, including file and network streams, type:
100 bytes from stream
0, issue the command:
stream_read 0 100
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:
In this example we assume the HTTP stream has the stream handle
To read the first 1000 bytes from stream
stream_read 1 1000
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
Use stream_list to view the open streams. Only stream
1 is still open.
Now no streams are open.