How to use device configuration schema

Introduction

Firmware components installed on a device often need additional configuration metadata in order to function properly. In order to define all of the necessary configuration parameters for firmware components running on a device, we created the Device Configuration Schema (DCS). DCS serves as a cloud-to-device templating system for usage in a custom application.

Since a DCS is tied to a particular component, and a device can run an arbitrary number of firmware components grouped as a bundle, an application has the ability to access all associated DCS's for a given device instance at the following REST API endpoint:

/devices/_DEVICE_ID_/configSchemas

Once the set of DCS's for a device instance is retrieved, the application will have all of the information regarding what parameters need to be configured and shared with the device, and can define their user interface accordingly. In addition, because firmware component software may have many sub-systems with their own unique required configurations, we designed the structure of DCS to be flexible enough to handle complex use cases.

DCS Structure

The structure of DCS for a given component version is represented as a JSON array of objects. Each object in the DCS array represents a set of parameters for a particular part of the firmware component. The top level structure of each parameter set object is defined with the following attributes:

  • FieldTypeRequiredDescription
  • namestringyesThe name of the parameter set.
  • descriptionstringnoThe description of the parameter set.
  • repeatablebooleanyesWhether or not the parameter set can be used as a template to generate multiple configurations.
  • keyNamestringyesThe formatted key name used to store the configuration in MODE's key-value store.
  • parametersarray of objectsyesThe set of actual parameters which belong to the parameter set.

The last field in each object within the DCS, parameters, is an array of objects, where each object contains the following fields:

  • FieldTypeRequiredDescription
  • keystringyesThe JSON key that will be used when creating the configuration.
  • typestringyesThe variable type for the parameter.
  • requiredbooleanyesWhether or not this parameter needs to have a value associated with it in the configuration.
  • labelstringyesThe label that will be displayed for the parameter in the application when creating the configuration.
  • descriptionstringnoThe description for the parameter to be displayed in the application when creating the configuration.
  • defaultValueVariousnoThe default value for the parameter if nothing is provided when creating the configuration.
  • optionsarray of objectsnoThe set of values that parameter can be set as; this can be useful if you want the parameter to take on a limited set of values.
  • minnumbernoThe minimum value that the parameter must be greater than or equal to. This is only supported for numeric types.
  • maxnumbernoThe maximum value that the parameter must be less than or equal to. This is only supported for numeric types.
  • regexstringnoThe regex validation to be performed by the application when creating a string parameter.

The options field is an array of objects, where each object contains the following fields:

  • FieldTypeRequiredDescription
  • labelstringyesThe label that will be displayed for the option in the application when creating the configuration.
  • valueVariousnoThe value associated with the particular option that the parameter is allowed to be set as.

In the interest of maintaining consistency with MODE's key-value store, DDP, the types of value you can use when creating a DCS are:

  • Number
  • String
  • Boolean
  • Array
  • Simple Javascript object

An example of a DCS can be found below:

[
    {
        "name": "Customer X's file transfer driver settings",
        "description": "File transfer driver settings for Customer X.",
        "parameters": [
            {
                "key": "sshHost",
                "type": "string",
                "required": true,
                "label": "SSH Host",
                "default": "host1.example.com"
            },
            {
                "key": "sshPassword",
                "type": "string",
                "required": true,
                "label": "SSH Password",
                "default": "password1234"
            }
        ]
    },
    {
        "name": "Log retrieval module schema",
        "description": "Configuration schema for log retrieval.",
        "parameters": [
            {
                "key": "coreDirectory",
                "type": "string",
                "required": true,
                "label": "SSH Host",
                "default": "/var/log"
            }
        ]
    }
]

As you can see, the DCS consists of two sub-schemas, one that will be used by the driver software inside of the firmware component, and another that will be used by a separate software module. This level of flexibility in the DCS allows for the ability to structure templates for a given component's configuration in many different ways.

From Schema to Device

When a logical device instance is instantiated in the cloud, it will be necessary to reference what required DCS need to be used in order for the firmware components installed to function correctly. As described previously, the device /devices/_DEVICE_ID_/configSchemas endpoint can be used to retrieve the set of DCS corresponding to the device.

The developers building the custom application are free to use the set of DCS's to create a configuration using any data store and format that they see fit. The DCS system was designed with MODE's Device Data Proxy in mind, so it is recommended that developers use this key-value store, as devices are expected to interface with the DDP so that key-value pairs can be propagated to them.

Once the configuration is propgated to the device via DDP or an alternative mechanism, it will be the responsibility of the firmware developers to ensure that the individual parts of the DCS are properly read by the associated software pieces of the firmware component. To this end, it is recommended that a DCS for a particular component is designed with this association to individual software modules in mind.

Creating New Component Versions

The decision behind associating the DCS to a component version was made because when the version of a component changes, the software behind that component has changed. As a result, it is possible that the necessary configuration parameters needed for that version of the component has also changed; for example, maybe new parameters were added or old ones were removed.

It is also possible that the DCS from one version to the next has not changed at all. In this case, it is recommended that the develop simply copies the DCS from the previous version to the new version. For more details on how to create component versions, and the associated DCS, please see the Firmware Bundles & OTA Updates Manual.