Configuration

Overview

The Configuration feature is intended to allow End Customers to remotely configure features on the device. The configuration information is saved on the server as a JSON object, who's fields and structure are defined by the manufacturer for each model supported.

The Configuration can be changed both from the server and the device side.

Examples

  1. Configuration change via the End Customer Portal
  2. Configuration change via a device's remote control that updates the server after the change.

Implementation details

There are a number of aspects of configuration changes that need to be supported by the device's firmware to ensure correct operation.

  1. Handle configuration updates from the server.
  2. Update the server on local configuration changes.
  3. Initial device registration

Handle configuration updates from the server

When an end user changes a device’s configuration object in the cloud interface, the Xyte server will automatically increment the configuration version counter on the server and the new value will be returned to the device the next time it calls theSend Telemetry API.

The device should check the value of this counter against the value stored locally and, if the new number is higher, perform a configuration update using the following steps:

  1. Call the Get Config API to retrieve the latest configuration from the server.
  2. [Optional, for long requests] Tell the server that the command is being processed using the Update Command API.
  3. Apply the new configuration.
  4. Update the local storage with the new configuration version counter value.
  5. Call the Update Device API, passing the new config_version parameter to let the server know the configuration was successfully applied.

Update the server on local configuration changes.

Some devices might allow operators to change the configuration locally, via the user interface, shell access, remote control, or similar. In such cases, the device should immediately update the server with the new configuration object by following these steps:

  1. Call the Set Config API, passing the new configuration object.
  2. Update the local configuration version counter value to the one returned by the server.


Initial device registration

The steps below are important to synchronize the server and device configuration settings.

When a device successfully registers with the Xyte server, its is strongly recommended to immediately synchronize the state between the server and the device:

  1. Send a Get Config API call to check if the manufacturer setup a default configuration for devices.
  2. If the data is non empty
    1. Apply the configuration to the device.
    2. Update the server the configuration was applied via Update Device API.
  3. If the data is empty
    1. Update the server of the device's config via Set Config API (and save the returned config version number)

The above steps ensure the device and the server are synchronized during the initial registration flow.


Configuration schema

Since editing raw JSON might be confusing for end users, it is recommended to generate a JSON Schema describing the structure of the JSON object.

The JSON Schema setting is available in the Partner Portal, on the Config Schema tab of the model details page (Configuration -> Models -> select model).