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:

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:

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

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

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

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 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 ZentriOS-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:

When the ZentriOS webapp is loaded, click on the Files tab.

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.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 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 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 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:

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

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:

> 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:

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: 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:

> ota

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.