Configuration and Setup

Setup, in its simplest form, is Wi-Fi Setup , also called Wi-Fi provisioning: providing Gecko OS with your network ssid and passkey. Once these details are provided, Gecko OS automatically brings the network up when it is required by any Gecko OS activity.

Setup may also involve Variable Configuration .

To configure your own version of the Web App, see Customizing the Web App .

Some of the procedures described below use a Gecko OS terminal. Connecting a terminal is described in Getting Started .

Wi-Fi Setup

A number of flexible and easy-to-use options are available to set up a device running Gecko OS.

Gecko OS is so easy to setup, we bet that within just a couple of minutes after plugging your evaluation board in, you'll be connected to a Wi-Fi network. Why not try it right now? With just four Gecko OS commands, you can connect to the Internet and download information! Enter the following commands into a Gecko OS terminal, substituting the name and password for your access point:

Gecko OS Commands Description 

set wlan.ssid     "Your AP Name"
set wlan.passkey  "Your secret password"

http_get          https://google.com

stream_read       0 1000


<- Name of your Access Point
<- Password for your Access Point

<- Sample information: get the home page
   from the Google secure web address
<- Read 1000-bytes of the sample

The setup steps are the first two lines of the example above - connecting to your local Wi-Fi Access Point. For further quick start information see Getting Started .

Setup with a Web browser

Gecko OS provides the option to use a web browser running on a network client (such as a smartphone, tablet or computer) to set the wlan.ssid and wlan.passkey .

In web setup mode, the Gecko OS device starts a soft AP and an HTTP server. The network client joins the device network via the soft AP and loads a set up page running on the Gecko OS HTTP server.

Note : Web setup mode does NOT currently support WEP. You can setup WEP using a terminal and Gecko OS commands. See wlan.passkey .

Starting Web Setup Mode on a Silabs Evaluation Board

On a Silabs evaluation board in the factory default state, you can start web setup mode without connecting via a terminal: hold down Button 2, press Reset, and continue to hold down Button 2 for another three seconds. The evaluation board red LED flashes to indicate the Gecko OS soft AP is running. See Initiating Setup by GPIO .

Starting Web Setup Mode from a Gecko OS Terminal

Alternatively, to start web setup mode, connect via a terminal and enter the command setup_web .

Gecko OS starts the local network and web server as indicated by the final message: In progress . 

> setup_web
[Disassociated]
IPv4 address: 10.10.10.1
Web setup started with the SSID: "Gecko-OS-###"
In progress

Opening the Web Setup Page

Open the Wi-Fi settings on your smartphone, tablet or computer and join the network called Gecko OS-###. The ### represents a unique ID derived from the last 3 characters of the device MAC address , e.g. Gecko-OS-2D6 for a device with MAC address 4C:55:CC:10:32:D6 . The password for the network is simply: password .

The local network name and password, and the web address may be customised to suit your needs. See setup.web.ssid , setup.web.passkey and setup.web.url .

After joining the local network, open a web browser on the network client and direct the browser to setup.com. The Gecko OS web page appears, and a scan begins for Wi-Fi access points in range. Select the remote network you wish to join, enter the network password then select Save & Exit and follow the prompts.

Once the settings are successfully saved, Gecko OS prints Web Setup Mode exited to the terminal. You can check that the settings were successfully saved using get wlan.ssid and get wlan.passkey . 

Web Setup Mode exited
> get wlan.ssid
YOUR_NETWORK_NAME
> get wlan.passkey
YOUR_NETWORK_PASSWORD

Web Setup Timeout

Web Setup times out after a period of user inactivity. If after web setup starts, the user does not open the web page, Gecko OS exits setup mode after five minutes. If after opening the page the user does not click any button on the web page for five minutes, the web setup page displays a warning message. If there is no activity for 60 seconds after the message is displayed, the web page exits and web setup stops.

Setup by Gecko OS Terminal

Perhaps the most common option used for general setup (and also the most convenient when prototyping) is to use a Gecko OS terminal and set variables using Gecko OS commands. See Getting Started .

It is straightforward to set the wlan.ssid and wlan.passkey variables manually. Be sure to save afterwards, or the values will be lost when the device reboots. 

> set wlan.ssid YOUR_NETWORK_NAME
Set OK
> set wlan.passkey YOUR_NETWORK_PASSWORD
Set OK
> save
Saved
Success

Any subsequent command requiring network access, such as an ICMP (Internet Control Message Protocol) ping, automatically results in the device attempting to join the network. 

> ping -g
[Associating to YOUR_NETWORK_NAME]
Security type from probe: WPA2-Mixed
Obtaining IPv4 address via DHCP
IPv4 address: 192.168.0.31
[Associated]
Ping reply in 25ms

Network Setup Option

The network_up command provides a -s option that prompts for the network and passkey. This simplifies the process by scanning for networks and allowing the desired network to be selected by index number, e.g.: 

> nup -s
Scanning for networks...
! 5 networks found
!  # Ch RSSI MAC (BSSID)       Network (SSID)
#  0  1  -78 00:0E:E8:B2:FE:FC someone-else
#  1  1  -79 18:33:9D:5F:9E:F3 another-network
#  2  6  -53 84:1B:5E:D8:0F:18 Zentri_EXT
#  3  6  -28 30:85:A9:E7:9C:B0 Silabs
#  4 11  -84 58:BF:EA:D8:C9:D2 not_us

Type the number # that matches your Network: 3
Type the password for your Network         : <passkey>

After running nup -s you may want to set wlan.auto_join.enabled . Save the variables if you want them to persist through a reboot: 

> set wlan.auto_join.enabled 1
Set OK
> save
Saved
Success

Setup by Remote Terminal

An (optionally) password-secured remote terminal provides command line setup convenience (look ma, no wires!) via one of the Gecko OS wireless network interfaces. See Application Examples - Remote Terminal . After connecting to the Gecko OS device via a remote terminal, follow the procedure described above in Setup by Gecko OS Terminal .

Initiating Setup by GPIO

Setup can be triggered by changing the level of a specified GPIO.

If the GPIO specified by setup.gpio.control_gpio is held for 3 seconds during and immediately after reset, then the command setup_web runs.

On Gecko OS evaluation boards, the default factory configuration is:

Variable Value
setup.gpio.control_gpio GPIO corresponding to Button 2

Accordingly, on a default configuration eval board, hold down Button 2, press reset, and continue to hold Button 2 for three seconds to start web setup.

Web Setup Note : On some Gecko OS evaluation boards, the web setup GPIO configuration to Button 2 to is lost after a hardware factory_reset using Button 1. In this case use the setup_web command to enter web setup mode, or use another configuration method.

Variable Configuration

Gecko OS maintains current variable values in Configuration RAM . To ensure that variable values persist after reboot, you save Configuration RAM to NVM flash with the save command. NVM stands for Non-Volatile-Memory. When you reboot, the device loads the configuration from NVM flash into Configuration RAM.

NVM flash is backed up in NVM backup . If NVM flash becomes corrupted, the values are automatically restored from NVM backup.

You can save Configuration RAM to a file by specifying a configuration filename with the save command, e.g.: save config1.cfg

To store multiple configurations, save multiple files.

You can load a specified variable configuration file with the load command after reboot is complete, e.g.: load config1.cfg

Platform-specific variable values are typically stored in OTP (One-Time Programmable) memory. For example, settings related to antenna configuration, buttons or indicator LEDs on Mackerel or Moray evaluation boards are stored in OTP memory at manufacture.

To summarise, variable values are stored in several places:

Variable Location Description
Factory Default Values Stored in firmware
Configuration RAM Stores current variable values. Must be saved to persist.
NVM Flash Saved variable values
NVM Backup Backup of variable values
OTP memory Platform-specific variable values
Variable files Snapshot of Configuration RAM

Variable values are restored from these storage locations as described below in Resetting Variable Values .

Resetting Variable Values

There are several kinds of reset that affect the value of variables.

Powerup or Reboot

To restore variable values on restart, Gecko OS:

Hard Factory Reset

A hard factory reset returns all values to their original default values. This is under user control. To perform a hard factory reset:

either

The factory_reset command requires a MAC address in order to avoid accidental reset. The MAC address can be obtained from the wlan.mac variable.

To restore variable values, Gecko OS:

Soft Factory Reset

A soft factory reset restores the NVM from NVM backup. This happens automatically if the NVM is corrupted.

To restore variable values, Gecko OS: