Gecko OS Web App

The Gecko OS Web App provides complete monitoring and control of your Gecko OS device using a web browser. It can be completely customized. See Customizing the Gecko OS Web App .

The web app can be run in any one of three modes:

The Gecko OS Web App serves as a complete demonstration showing how to use Gecko OS with the HTTP RESTful API .

The web app runs on the Gecko OS device. You can connect it by joining the softAP running on the Gecko OS device, or, if the Gecko OS device is connected to a WAN, by joining the same network.

Setup Web Mode

In the factory default configuration, your module is not configured to connect with a wireless network and does not have local wireless network access.

Before configuring your module, you can ensure your module is in a known state by performing a factory_reset .

You can use a Wi-Fi client with a web browser, such as a smartphone, tablet or PC, to connect to the Gecko OS web app via the module softAP wireless network to set up access to your wireless network.

Gecko OS evaluation boards are by default configured to enter Setup Web mode when you hold down Button 2, press Reset, and continue to hold down Button 2 for at least three seconds. See Web Setup Note .

On any Gecko OS device you can also make the module start Setup Web mode by opening a Gecko OS terminal and issuing the setup_web command: 

setup_web

On evaluation boards, the red LED blinks when the module soft AP network is turned on and waiting for a connection.

Using the Wi-Fi settings on your computer or mobile device, connect to the module soft AP wireless network. By default, the soft AP network name (SSID) is Gecko OS-### , where ### is replaced by the last 3 digits of the module MAC address, e.g. Gecko OS-2D6 . The default password is: password .

Open a web browser and navigate to setup.com or Gecko OS.com .

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

Click the name of your Wi-Fi network to select it.

Supply the network password in the following dialog.

The web app configures your module, saves the variables, and instructs the module to connect to your network.

If you choose the Reconnect to device option, the web app restarts your module and reconnects to it via your network, in Internet mode . This assumes that after disconnecting from the module soft AP network, your computer also reconnects to your network automatically. If the web app fails to reconnect, check the Wi-Fi on your computer or mobile device has roamed back to your network.

Note that the Reconnect to device option is available only in Setup Web mode.

Local Mode

Local mode provides all web app features (tabs) that do not require Internet access. Features requiring Internet access are Firmware Management and Cloud Services .

You can connect in Local mode via the module soft AP interface or via the module wlan interface .

To set up the HTTP server for the Gecko OS Web App, see the instructions in Internet Mode .

Internet Mode

Internet mode requires a Wi-Fi network with Internet access. All features (tabs) are available.

Automatically Connecting in Internet Mode

The simplest way to use the Gecko OS Web App in Internet mode is to set up the module with the web app in Setup Web mode , and check the Reconnect to device option. The web app performs all the necessary configuration to reconnect in Internet mode.

Manually Connecting in Internet Mode

Alternatively, you can manually configure the module to run the Gecko OS Web App as described below.

Issue the following commands from a terminal: 

set wlan.ssid                <YOUR NETWORK NAME>
set wlan.passkey             <YOUR NETWORK PASSWORD>
set wlan.auto_join.enabled   1
set http.server.enabled      1
set http.server.api_enabled  1
set mdns.enabled             1
set mdns.name                <YOUR MODULE NAME>
save
reboot

For example: 

set wlan.ssid               my_network
set wlan.passkey            my_secret_password
set wlan.auto_join.enabled  1
set http.server.enabled     1
set http.server.api_enabled 1
set mdns.enabled            1
set mdns.name               mymodule
save
reboot

After a reboot, the response from Gecko OS is similar to the following: 

Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.59
Starting mDNS
mDNS domain: mymodule.local
HTTP and REST API server listening on port: 80
[2019-01-01 | 23:48:42: Associated]

The module automatically connects to your network if wlan.auto_join.enabled is configured as described above.

With your computer or mobile device also connected to your network, open a web browser and navigate to the address of the Web App.

The address is the module IP address. In the example above, you can connect a browser to http://10.5.6.59 to use the Gecko OS Web App.

You can also use network discovery to avoid using the module IP address. The address is the mDNS domain name <YOUR MODULE NAME>.local . In the example above, you can connect a browser to http://mymodule.local . Some Windows systems may instead need to connect to http://mymodule . For further information see Networking & Security, Network Discovery .

Gecko OS Web App Features

The Gecko OS Web App provides information and configuration tabs that allow complete monitoring and control of your module.

All features (tabs) of the web app are available in Internet mode , unlike Setup Web mode and Local mode , in which the Firmware Management and Cloud Services tabs are not available.

Connect Tab

The Connect tab provides a way to join your module to a Wi-Fi network. When the Connect tab opens, it automatically scans for Wi-Fi networks in range and allows you to select your network and enter a password, as described above in Setup Web Mode .

Network Tab

If your Gecko OS device is already connected to your wireless network, then by default the web app displays the Network tab, showing some essential Gecko OS wlan interface variable settings.

Console Tab

The console tab works like a Gecko OS terminal or remote terminal. You can issue any Gecko OS command from this page. In the background, the web app uses the Gecko OS HTTP RESTful API to issue commands to the module and display responses.

As well as standard Gecko OS terminal behavior, the Console tab provides additional features, exclusive to the Gecko OS Web App. Additional commands mimic Linux shell commands and include:

Alias

The console alias command has the following syntax: alias <alias_name>="<command_string>" This lets you create a short name for a long command. Once an alias is set, you can type the <alias_name> in the console, in place of the full <command_string> . For example: alias g="get gpio.usage" To remove a previously aliased command, use unalias <alias_name> , e.g. unalias g

Clear

The clear command clears all text on the display and returns the cursor to the top line on the console

Grep

The console grep command allows filtering of output. The following example lists only those commands in the history that contain the text http : history | grep http The grep syntax also allows regular expressions. The following example lists only those files on the module file system whose names contain c followed by either s , t or v : ls | grep c[stv] Use the option -v to invert the grep result and display all lines but those that match the regular expression: ls | grep -v c[stv]

History

The history command displays a list of past commands issued on the console. You can re-issue a command by copying and pasting from the list, or by typing !i , where i is the index number of the command in the list. To return the last X entries in history, issue the command history X .

Remove (rm)

The rm command is identical to the Gecko OS file_delete command. Either command may be used to delete files from the module file system.

System Tab

The system tab displays a number of system variables, such as version, build date, module, board and MAC address, memory usage and time.

Files Tab

The Files Tab lists files stored on the module file system. You can upload, download and delete files.

Folder Emulation

The Gecko OS file system does not support directories or folders. It treats '/' characters in file names like any other character. For example, the file a/b/c is a file with a 5 character name.

The Gecko OS Web App Files tab provides folder emulation, to simplify some file operations. For example, a file called a/b/c is treated for some purposes as a file in directory 'b' which is itself contained in directory 'a'.

You can drill down into folders to display only the files in the folder. The current folder is displayed at the top of the Files tab. When you drag and drop a file, it is created in the current folder.

To create a folder, right click in the Files tab display and choose New Folder from the context menu.

Folders cannot be renamed or moved. A folder can be deleted if it contains no files or folders. When the folder is empty, right click the folder and choose Delete from the context menu.

Files can be renamed. Right-click the file and choose Rename from the context menu.

Files can be deleted. Click the Trash icon in the file row, or right-click the file and choose Delete from the context menu.

Naming Rules for Files tab Folder Emulation

To use Files tab folder emulation, care is required in naming files. The Files tab supports files named in the form: 

filename
dirname/filename

However file names with slashes at the beginning or the end of the file name are not supported. The Files tab does not display files or allow manipulation of files named with the following patterns: 

/filename           <- leading slash
/dirname/filename   <- leading slash
filename/           <- trailing slash
/filename/          <- leading & trailing slash
dirname/filename/   <- trailing slash
/dirname/filename/

Directory names must end in a slash, and must not start with a slash. The following pattern is allowed: 

dirname/

The following pattern is not supported and is not displayed in the Files tab: 

/dirname/           <- leading slash

When the Files tab creates a folder, it creates a file named with a trailing slash, and of length 1 byte. If a file is named with a trailing slash, the Files tab displays it as a folder only if it has length 1 byte, and does not display it otherwise.

Multiple consecutive slashes are treated as a single slash. For example, dir///file is treated as dir/file .

Using the Gecko OS file_create command, you can create files with names that do not follow the above naming rules. These rules apply only to the display and manipulation of files in the Gecko OS Web App Files tab.

GPIO Configuration Tab

The GPIO configuration tab lists the configuration details for GPIOs in use. This is equivalent to the output of the get gpio.usage command. For input GPIOs, the current state is listed. For output GPIOs, buttons are provided to set the state to high or low.

Firmware Management

The firmware management tab allows Over-the-Air (OTA) wireless firmware updates. This is the equivalent of issuing the ota command. This tab is available only with Internet access.

Cloud Services

The Cloud Services tab provides information and links related to the Zentri Device Management Service (DMS). The Cloud Services tab is available only in Internet mode.

Customizing the Web App

The Gecko OS Web App can be 100% customized, or subtly modified to suit your needs.

Source code for the customizable version contains all the features listed above with the exception of the Console tab.

See Application Examples, Customizing the Gecko OS Web App for a comprehensive description.