Web App Recovery
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:
- the developer, who configures the Gecko OS application
- the end user, who uses the Gecko OS application.
- HTTP server
- Soft AP
- Web App Recovery
- Web Setup
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.
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|
The default variables determining the Web App root are:
- http.server.root_filename: webapp/index.html
- setup.web.root_filename: webapp/index.html
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.
Direct a web browser to the web setup address: by default
Gecko OS.com or
Enter the WLAN SSID and password into the fields and click
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.
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|
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
If the Web App is damaged, Gecko OS automatically redirects to
.recovery.html app detects that it has access to the WLAN, and displays the Web App recovery page.
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