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:
- Create a default configuration file
- Create a custom Gecko OS bundle
- OTA a custom Gecko OS bundle
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:
- an OTA is successfully completed
- the factory reset GPIO is asserted for 5s
- The command
load default_config.csvis issued. In this case, any config file can be specified as the argument to
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:
Activate your device to the Gecko OS version that forms the basis for your product bundle.
Configure Gecko OS variables as required. See Gecko OS Command API Variables.
- Be sure to TEST the settings and ensure everything is functioning the way you want before continuing to the next step
Once Gecko OS is configured, save the settings to the file: 'default_config.csv' with the command:
> save default_config.csv
- Test the newly created default configuration file by factory resetting the device and loading the settings file. First reset:
> factory_reset x --forced
- Then load. For a verbose listing as the settings are loaded, use the load command
> 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
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
On the computer, open a web browser and enter the URL:
When the Gecko OS webapp is loaded, click on the
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.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.
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
default_config.csv by factory resetting the device then loading the
> 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.
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:
- Log into the Zentri DMS
- If necessary, create a Product. See DMS, Creating a Product
- A Product contains the firmware your devices OTA.
- Select your product and create a new Product Bundle. See DMS, Creating a Bundle
- A Bundle is Gecko OS version along with the collection of custom resource files your specify
- When devices OTA your product, they have your specified version of Gecko OS plus any resource files you include in the bundle. See Using the DMS, Products.
- Once the bundle is created, drag and drop the newly created
default_config.csvinto the bundle.
default_config.csv is added to the bundle, any devices that OTA the bundle will get Gecko OS plus your
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:
- run the dms_claim command to register the device with your account
- then run dms_activate to activate the device to your product
> 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
- Gecko OS-4.0