Configuration

Overview

The Configuration API allows configuration changes to be made to devices by the end user (remotely, via the Xyte platform) and directly on the device by the operator. The device configuration is shared between the device and the cloud server using a JSON object defined by the manufacturer. Synchronization is achieved via an automatically managed "configuration version" counter. This number is returned as part of the telemetry response, in the config_version field.

Configuration changed from the cloud

When an end user changes a device’s configuration object in the cloud interface, the Xyte server will automatically increment the configuration version counter 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.

Configuration changed in the device

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.

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 partners portal, on the Config Schema tab of the model details page (Configuration -> Models -> select model). This will auto-generate a simple-to-use configuration editor for the end user.