Creating a Custom Gecko OS Bundle

A custom Gecko OS product bundle contains a version of Gecko OS with custom settings and resource files. All your devices in the field can OTA the product, to be automatically configured with your custom settings and resources. No external host processor or manual device configuration is required.

You can create a custom Gecko OS bundle by saving settings on a device in a configuration file, and adding the configuration file to a Gecko OS product bundle with the Zentri Device Management Service.

This app note describes how to:

Default Configuration File

A default configuration file is a CSV file containing a list of Gecko OS settings.

The default configuration file MUST be named: default_config.csv for Gecko OS to automatically load the settings file after an OTA or a factory reset.

Gecko OS loads the file settings when:

For more details on the default configuration file see: Configuration and Setup, Variable Configuration .

The configuration file format is described in Configuration and Setup, Variable Configuration File .

Creating the Default Configuration File

In this example we create a default configuration file to be loaded onto all devices that OTA to our custom product bundle firmware.

You can create a configuration file manually with a text editor. See Modifying the Configuration File .

You can set up a configuration, and save it in a configuration file which can be later edited in a text editor.

To save an existing configuration: 

> save default_config.csv
> factory_reset x --forced
> load -v default_config.csv

Gecko OS loads all the settings specified in the configuration file.

Once loaded, Gecko OS automatically runs save and reboot . After rebooting Gecko OS runs the settings in the configuration file.

Saving the Configuration File to a Computer

The default_config.csv is now created on the device. We can copy it from the device external flash to a computer for editing and adding to a firmware bundle.

The easiest way to copy the file is to start the Gecko OS Webapp and download the file from a web browser.

To start the webapp, issue the following command to the device using a Gecko OS terminal: 

> setup web

This starts the Gecko OS Soft AP and webserver. Connect your computer to the Gecko OS device Soft AP Wi-Fi network. By default, the network name is Gecko OS-XXX , (where XXX is the last 3 digits of the device MAC address). The network password is password .

On the computer, open a web browser and enter the URL: http://setup.com

When the Gecko OS webapp is loaded, click on the Files tab.

The Files tab enables you to download files from the Gecko OS device to your computer.

Find the file default_config.csv and save to your computer.

Modifying the Configuration File

This step is not essential, but it is recommended.

On the computer, open the default_config.csv file in a text editor.

The file contains a list of all Gecko OS variables with a corresponding value.

We recommend that you remove any settings that are not modified from the Gecko OS default value.

Note : It may also be necessary to remove the wlan.ssid and wlan.passkey settings. These may contain confidential information, and the information may not apply to the networks that are available to other devices running your product.

Downloading the Configuration File to the Gecko OS Device

To test the configuration file, you need to download it onto the Gecko OS device.

The easiest way to do this is using the Gecko OS Webapp.

Set up the web app as described above, and open http://setup.com on your computer web browser.

Open the Files tab.

Drag and drop the default_config.csv onto the Files tab target area.

To overwrite an existing default_config.csv on the device, check the Overwrite checkbox in the Files tab before dragging and dropping the file.

Testing the Configuration File

Test the default_config.csv by factory resetting the device then loading the default_config.csv file: 

> factory_reset x --forced
> load -v default_config.csv

If the settings file is malformed or contains a bad setting, the load command output displays information about the fault.

Ensure the default_config.csv loads properly loads before continuing.

Creating a Custom Gecko OS Product Bundle

For full documentation of products and product bundles in the Zentri Device Management Server (DMS), see Using the DMS, Products .

The procedure is as follows:

Once the default_config.csv is added to the bundle, any devices that OTA the bundle will get Gecko OS plus your default_config.csv .

OTAing a Custom Gecko OS Bundle

Now that our custom Gecko OS Bundle is on the DMS, we need to configure our devices to OTA the bundle.

The way this is done depends on what firmware is currently on our devices.

Devices Running Gecko OS

If your device already has Gecko OS: 

> dms_claim <dms_token>
> dms_activate <Product Code>

Note : You need to run these commands only once.

After running the dms_claim command you may track your device in the DMS: https://dms.zentri.com

The dms_activate command 'activates' your device with your product. After running the command, you next OTA retrieves the firmware specific to the device's activated product.

Note that you may also 'activate' your device with your product using the DMS webapp: https://dms.zentri.com . In this case the 'dms_activate' command is not needed.

Updating Your Device to Your Custom Bundle

Now that your device is registered with your DMS account and activated with your Product, you may update it to your custom firmware bundle.

OTA is unavailable in this version. You may be able to use Device Firmware Update (DFU) to update the device.

Supporting Gecko OS Versions

Change Log

Modified Changes
2019-01-01 Created