Creating a Custom ZentriOS Bundle
A custom ZentriOS product bundle contains a version of ZentriOS 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 ZentriOS bundle by saving settings on a device in a configuration file, and adding the configuration file to a ZentriOS product bundle with the Zentri Device Management Service.
This app note describes how to:
- Create a default configuration file
- Create a custom ZentriOS bundle
- OTA a custom ZentriOS bundle
Default Configuration File
A default configuration file is a CSV file containing a list of ZentriOS settings.
The default configuration file MUST be named:
default_config.csv for ZentriOS to automatically load the settings file after an OTA or a factory reset.
ZentriOS 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 ZentriOS version that forms the basis for your product bundle.
Configure ZentriOS variables as required. See ZentriOS 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 ZentriOS 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
ZentriOS loads all the settings specified in the configuration file.
Once loaded, ZentriOS automatically runs save and reboot. After rebooting ZentriOS 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 ZentriOS Webapp and download the file from a web browser.
To start the webapp, issue the following command to the device using a ZentriOS terminal:
> setup web
This starts the ZentriOS Soft AP and webserver. Connect your computer to the ZentriOS device Soft AP Wi-Fi network. By default, the network name is
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 ZentriOS webapp is loaded, click on the
The Files tab enables you to download files from the ZentriOS 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 ZentriOS variables with a corresponding value.
We recommend that you remove any settings that are not modified from the ZentriOS 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 ZentriOS Device
To test the configuration file, you need to download it onto the ZentriOS device.
The easiest way to do this is using the ZentriOS 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 ZentriOS 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 ZentriOS version along with the collection of custom resource files your specify
- When devices OTA your product, they have your specified version of ZentriOS 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 ZentriOS plus your
OTAing a Custom ZentriOS Bundle
Now that our custom ZentriOS 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 ZentriOS
If your device already has ZentriOS:
- 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 username> <DMS password> > 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.
Devices Running WiConnect
If your device is running the legacy WiConnect firmware, issue the following command to register and activate the device:
> ota -a <Product Code>:<DMS username> <DMS passowrd>
This command registers your device and activates it with your product.
See Updating from WiConnect to ZentriOS.
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.
To update issue the ota command:
The device OTAs your custom firmware bundle which includes the specified ZentriOS version PLUS your custom resource files.
After ZentriOS completes the OTA, it finds the
default_config.csv file and automatically loads the settings file, saves the settings to NVM, and reboots with the new settings.
Supporting ZentriOS Editions and Versions