Update and Recovery
Gecko OS is part of a larger sophisticated application framework installed on all Gecko OS devices. The framework provides a hardened bootloader, read/write file system, safemode recovery mechanism, and secure over-the-air (OTA) update capability.
DFU - Device Firmware Update
The Gecko OS Device Firmware Update (DFU) feature allows device firmware to be updated via the device serial interface. See Device Firmware Update.
The Device Management Server (DMS)
To update a Gecko OS device using Gecko OS, you need to sign up for an account with the Device Management Server (DMS) and then you need to claim your device.
You may also need to activate your device to a Gecko OS product.
The terms claim and activate are used in a special sense with the DMS, and are defined as follows.
- claim - associate a particular device with your user account.
- activate - associate a device with a product.
To perform Gecko OS OTA update, the steps are:
- Sign up for an account with DMS (one time only)
- Claim Your Device
Signing up with the DMS
To sign up for an account with the DMS, go to https://dms.zentri.com and follow the
Create an Account link.
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:
The Gecko DMS Commands
When using Gecko OS, DMS commands is used to claim and activate devices:
- dms_claim - claim a device. Use
claimto claim a device that is already running Gecko OS.
- dms_activate - activate a product. Use
activateto activate a device as a different product, such as a custom product you have created.
Activate a Product by Product Code
To activate a device to a specific product, use the dms_activate command.
dms_activate <product code>
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.
|Gecko OS Commands||Description|
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 Gecko OS using the
For a detailed discussion of recovery procedures, see the Recovery from Safemode application note.
To force entry into safemode, assert the factory reset GPIO for more than
Safemode Network Connectivity Failures
The issue of network connectivity failures in safemode is addressed by three variables:
- system.safemode.console_timeout - Set the duration for which the Gecko OS terminal console is active in safemode, before sleep or reboot.
- system.safemode.sleep_timeout - Set the duration for which the device sleeps before rebooting.
- system.safemode.ota_auto_retry - If
system.safemode.ota_auto_retryis enabled, the safemode app repeatedly attempts OTA.
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 returns the device to a known state.
The device may be factory reset by GPIO or by the Gecko OS factory_reset command.
After a successful factory reset, all variables are set to the factory configuration and the device reboots.
See Configuration and Setup, Resetting Variable Values for details of reset types and the reset process.
See Configuration and Setup, Factory Configuration for details on creating a custom factory configuration file.
Factory Reset GPIO
The factory reset GPIO is GPIO 0 on all Gecko OS devices. To perform a factory reset by GPIO:
- hold the factory reset pin high for more than
10and less than
20seconds through a hardware reset.
Button 1 is wired to GPIO 0 on evaluation boards. On an evaluation board, to factory reset:
- Press Button 1 and do not release it.
- Press and release the Reset button.
- Continue to press Button 1 for at least 10 seconds.
- Release Button 1.
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: You can configure a factory reset GPIO. See system.factory_reset.gpio.
To ensure factory reset is invoked, the GPIO (or button) must not be asserted for more than
If the factory reset GPIO is asserted for more than
20 seconds then the device is forced into safemode.
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:
- issue get wlan.mac to obtain the device MAC address
- then issue the factory_reset command with the returned MAC address as its argument:
factory_reset <MAC address>