Update and Recovery

ZentriOS is part of a larger sophisticated application framework installed on all ZentriOS devices. The framework provides a hardened bootloader, read/write file system, safemode recovery mechanism, and secure over-the-air (OTA) update capability.

Secure OTA Update

Zentri manages a secure online OTA server that offers each ZentriOS device with the ability to securely update individual files, applications or an entire firmware bundle. The OTA command is used to update device firmware.

The OTA process is secured by industry standard TLS/HTTPS using server and client certificates that forces

HTTPS is the same security your web browser uses to make secure transactions with your bank over the internet. Zentri adds an additional layer of security, since the Zentri OTA server checks the unique security certificate and hardware UUID of each ZentriOS device that requests an update.

If an OTA update fails to complete for some reason, you can resume it later. Rejoin the network and run the ota command again.

The ZentriOS OTA feature uses the Zentri Device Management Server (DMS).

To update from an old version of WiConnect to ZentriOS, see Updating from WiConnect to ZentriOS.

The Zentri Device Management Server (DMS)

To update a ZentriOS device using ZentriOS, you need to sign up for an account with the Zentri Device Management Server (DMS) and then you need to claim your device.

You may also need to activate your device to a ZentriOS product.

The terms claim and activate are used in a special sense with the DMS, and are defined as follows.

To perform ZentriOS OTA update, the steps are:

Signing up with the DMS

To sign up for an account with the DMS, go to the Zentri DMS Sign up page:

https://dms.zentri.com/signup

During the sign up process, you will create a DMS username and password.

Claim Your Device

To claim your device, issue the dms claim command:

dms claim <dms_username> <dms_password>

After you have claimed the device, future OTA update requests are directed to the Zentri Device Management Service.

Update ZentriOS Using OTA

Once the device is claimed, update to the latest version of your ZentriOS product by issuing the ota command..

Note: OTA requires a memory-intensive TLS connection, and may fail if memory is low. See Networking and Security, Increasing Available Memory for TLS.

If the ota command fails with the message:

{"result":"fail","message":"device not claimed"}

then you need to claim the device before running the ota command. See The Zentri DMS above.

The ZentriOS dms Command

When using ZentriOS, the dms command is used to claim and activate devices:

Activate a Product by Product Code

To activate a device to a specific product, use the dms activate command.

dms activate <product code>

To update the device to the latest published firmware bundle for the product:

ota

When issued with no arguments, the OTA command updates to the most recent firmware bundle version for the product, or does nothing if the device already has the most recent version installed.

Safe Mode

Safe mode operation is guaranteed in the unlikely event the device is configured in a way that causes repeated and/or unexpected reboots. The bootloader automatically switches to safe mode after eight exceptions occur with the offending boot application. Safe mode is indicated by the system.safemode.status variable.

It is easy to return the device to normal operation when the device is in safe mode. Follow the command sequence in the following table and your device will be back to normal in no time.

ZentriOS Commands Description

get system.safemode.status
faults_print
faults_reset
faults_print
reboot

<- Check if the device is in safemode? 0 = no, 1 = yes
<- Print a list of faults (8 faults should print)
<- Reset faults counter
<- Check there are no more faults after reset
<- Reboot the device

In some cases, a misconfigured device may quickly return to safe mode since the device may be inadvertently setup to invoke a fault. If this occurs, we recommend the device is returned to factory reset.

Once in safe mode, the device boots into the kernel. The kernel provides the ability to update the firmware, or switch back to ZentriOS using the faults_reset command and system.boot.image variable.

For a detailed discussion of recovery procedures, see the Recovery from Safemode application note.

For details of safemode app behaviour in relation to ZAPs, see SDK Development, Recovery Using the Safemode App

Commands and Variables Available in Safe Mode

In safe mode a subset of the commands and variables is available.

Safe Mode Commands

Safe Mode Variables

Factory Reset

Factory reset returns the device to a known state.

The device may be factory reset by GPIO or by the ZentriOS factory_reset command.

After a successful factory reset, all variables are set to factory defaults and the device reboots.

See Configuration and Setup, Resetting Variable Values for details of reset types and the reset process.

Factory Reset GPIO

The factory reset GPIO is GPIO 0 on all ZentriOS devices. To perform a factory reset by GPIO:

Button 1 is wired to GPIO 0 on Zentri evaluation boards. On a Zentri evaluation board, to factory reset:

Note: GPIO 0 always acts as the factory reset GPIO. GPIO 0 may be configured to initialize to another GPIO function, but the factory reset function takes priority over other functions.

Note: On the AMW1x6 Numbat, GPIO 0 is overloaded for JTAG debugging. Button 1 works for factory reset only when zap.debug.enabled is set to 0. See AMW106 hardware, AMW106 GPIOs 0 to 4 Disabled During SDK Debugging.

Note: You can configure an auxiliary factory reset GPIO. See system.factory_reset.aux_gpio.

Locking Variable Values

The following variables can be locked to prevent change on factory reset. See system.variable_lock:

Factory Reset Command

Use the factory_reset command to perform a factory reset. To avoid accidental factory reset, the device Wi-Fi MAC address must be provided:

Web App Recovery

In the event that the Web App does not work, due to a damaged file structure or misconfiguration, you can use the Web App Recovery system to regain access to the network and restore the Web App files. See the Web App Recovery application note.