Web App Recovery (currently unavailable)

The Web App Recovery system helps end users stay connected in case of damage to the Web App.

Many of Gecko OS's features are intended for developers, to allow flexible configuration of Gecko OS devices for specific applications. The UART interface and the remote terminal interface provide developers with full access to all Gecko OS features.

However when a Gecko OS application is in the hands of the end user, there is still some configuration required. At a minimum, an end user needs to supply WLAN credentials to allow the Gecko OS device to connect to the local network. Some applications may require additional configuration.

The Web App provides an interface for end users to communicate with a Gecko OS device. The Web App can be modified with the desired styling and branding, and edited to provide end users with only the options they need. See Customizing the Web App . The most basic option is providing WLAN credentials.

The Web App may become unusable in some circumstances. Web App files may become lost or damaged, or some misconfiguration may prevent the web app from working.

In the event the Web App is unusable, the Web App Recovery system provides a way for the end user to restore the WLAN credentials, and to recover complete use of the Web App. The Web App Recovery system uses the minimal web app in the file .recovery.html . Gecko OS redirects automatically to .recovery.html if the Web App file structure is missing or damaged.

This application note demonstrates using the Web App Recovery system to set WLAN SSID and password, and to recover the working Web App. There are two actors in this activity:

Features demonstrated

Prerequisites

This demonstration uses a Silabs Mackerel evaluation board in the default configuration.

Setup and configuration instructions in this application note specify whether they are performed by the developer, or by the end user.

The developer can configure the module via a Gecko OS terminal.

In this demonstration the end user does not communicate with the module via a Gecko OS terminal. The only way for the end user to communicate with the module is via Wi-Fi and a Web browser, or by pressing buttons on the Gecko OS device.

Recovering WLAN Credentials

If the Web App is working, you can use the web setup feature to run the Web App and set the WLAN credentials. See Web App, Setup Web Mode and Configuration and Setup, Setup with a Web Browser .

If the Web App is unusable, Gecko OS automatically redirects the web browser to the file .recovery.html . This is a simple web interface into which the end use can enter the WLAN SSID and password.

Developer Configuration

First we provide a way for the end user to initiate web setup. The end user cannot use a terminal to run the setup web command.

In a real-world Gecko OS application, the host MCU might determine whether setup is required and run the setup_web command automatically. Alternatively, the user could press a button on the Gecko OS device.

In this demonstration the end user presses Button 2 on the Mackerel board. This corresponds to GPIO 11.

Enter the following commands into a Gecko OS terminal connected to the Mackerel test device:

Gecko OS Commands Description 

set setup.gpio.cmd          "setup_web"
set setup.gpio.control_gpio 11
set setup.gpio.level        1
set setup.gpio.mode         gpio
save
reboot

web setup runs when GPIO asserted
GPIO 11 corresponds to Mackerel Button 2
GPIO goes high (button pressed) to run command
GPIO is asserted for 3 seconds through a PoR
Save
Reboot

The default variables determining the Web App root are:

If the root file is not found in the file system, Gecko OS determines that there is damage to the Web App file structure, and institutes Web App Recovery.

To simulate damage to the Web App run by the setup_web command, change the value of setup.web.root_filename to a file that doesn't exist: 

set setup.web.root_filename bogus.html
save
network_restart

End User Actions

Press Button 2, then press and release Reset, and continue to hold Button 2 for 3 seconds. The module restarts and blinks the red indicator LED (softap).

Connect a phone, tablet or PC to the softap. The Soft AP SSID is by default Gecko OS-# , where # is replaced by the last three characters of the WLAN MAC address, e.g. Gecko OS-605 .

Direct a web browser to the web setup address: by default 10.10.10.1 , Gecko OS.com or setup.com .

Enter the WLAN SSID and password into the fields and click save .

At this point the WLAN credentials recovery is complete. The WLAN SSID and password are saved.

The next section demonstrates how to set up the Gecko OS application so the user can also recover the Web App.

Recovering the Web App

The recovery system can recover the files for the Web App if they are damaged. To do this, the module needs to connect to the WLAN and run the HTTP server. The module does not automatically join the WLAN, or run the HTTP server. This needs to be set up by the developer. We also set up an mDNS address so the end user can connect to the module without knowing its IP address.

Developer Configuration

This setup assumes the WLAN SSID and password are correctly configured and saved. If not, recover them as described in the previous section.

In a real-world application, the host MCU might run Gecko OS commands to join the WLAN and launch the HTTP server. In this demonstration, we configure the module to join the WLAN and run the HTTP server automatically on boot.

Enter the following commands into a Gecko OS terminal connnected to the Mackerel test device:

Gecko OS Commands Description 

set wlan.auto_join.enabled 1
set http.server.enabled    1
set mdns.enabled           1
set mdns.name              mymodule
save
reboot


Automatically join WLAN on boot
Automatically start HTTP server on boot
Enable mDNS
Set known address for module
Save
Reboot

On rebooting the module displays responses similar to the following: 

Rebooting
[2015-04-07 | 07:24:11: Disassociated]
SILABS-AMW007-2.1.5, Gecko OS-2.1.5, AMW007-W00001
[Ready]
[Associating to Silabs]
> Obtaining IPv4 address via DHCP
IPv4 address: 10.5.6.108
Starting mDNS
mDNS domain: mymodule.local
HTTP and REST API server listening on port: 80
[Associated]

To simulate damage to the Web App run by the HTTP server, change the value of http.server.root_filename to a file that doesn't exist: 

set http.server.root_filename bogus.html
save
network_restart

End User Actions

Connect a phone, tablet or PC to the WLAN.

Direct a web browser to mymodule/ (or mymodule.local/ ).

If the Web App is damaged, Gecko OS automatically redirects to .recovery.html .

The .recovery.html app detects that it has access to the WLAN, and displays the Web App recovery page.

Click Recover to download the Web App files. By default, the WebApp files associated with the currently installed Gecko OS release are downloaded from the resources.zentri.com site. The developer can modify the .recovery.html page to download Web App files from another site.

When the download is complete, the .recovery.html app redirects to the recovered web app:

Supporting Gecko OS Editions and Versions

Change Log

Modified Changes
2015-Apr-08 Created