Web App Recovery

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

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

However when a ZentriOS 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 ZentriOS device to connect to the local network. Some applications may require additional configuration.

The ZentriOS Web App provides an interface for end users to communicate with a ZentriOS 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 ZentriOS 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. ZentriOS 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 Zentri 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 ZentriOS terminal.

In this demonstration the end user does not communicate with the module via a ZentriOS 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 ZentriOS 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 ZentriOS Web App, Setup Web Mode and Configuration and Setup, Setup with a Web Browser.

If the Web App is unusable, ZentriOS 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 ZentriOS 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 ZentriOS 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 ZentriOS terminal connnected to the Mackerel test device:

ZentriOS CommandsDescription

set setup.gpio.cmd          "setup web"
set setup.gpio.control_gpio 11
set setup.gpio.level        1
set setup.gpio.mode         gpio
save
reboot
setup web 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, ZentriOS 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 ZentriOS-#, where # is replaced by the last three characters of the WLAN MAC address, e.g. ZentriOS-605.

Direct a web browser to the web setup address: by default 10.10.10.1, ZentriOS.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 ZentriOS 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 ZentriOS 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 ZentriOS terminal connnected to the Mackerel test device:

ZentriOS CommandsDescription

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]
ZentriOS-3.0.0.0, Built:2015-11-11 11:11:11 for AMW004.3, Board:AMW004-E03.3
[Ready]
[Associating to Zentri]
> 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, ZentriOS 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 ZentriOS 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 ZentriOS Editions and Versions

Change Log

ModifiedChanges
2015-Apr-08Created