Overview

Configuration lets End Customers remotely set Device options. The Configuration is stored on the server as a JSON object whose shape is defined by the manufacturer per Device Model.

Configuration changes can originate from either side:

1. The End Customer changes a value in the Customer Portal.
2. The Device changes a value locally (e.g. via its physical UI or a remote control) and pushes the new state to the server.

Implementation responsibilities

The Device firmware needs to handle three Configuration scenarios:

1. Apply Configuration updates pushed from the server.
2. Push Configuration updates that originate locally on the Device.
3. Synchronize Configuration on initial Device registration.

Apply server-side Configuration updates

When a user changes the Configuration in the cloud, the server increments the Configuration version counter. The new counter value is returned to the Device on the next Send Telemetry API call.

The Device compares the returned counter to its locally persisted value. If the server's counter is higher:

1. Call Get Config API to fetch the latest Configuration.
2. (Optional, for slow operations.) Call Update Command API to tell the server the change is in progress.
3. Apply the new Configuration locally.
4. Persist the new counter value.
5. Call Update Device API with the new config_version to confirm the change was applied.

Push local Configuration updates to the server

Some Devices let operators change Configuration locally — through the Device's UI, shell access, a remote control, or similar. When that happens, the Device should immediately:

1. Call Set Config API with the new Configuration object.
2. Persist the Configuration version counter returned by the server.

Synchronize Configuration on initial registration

Right after a successful registration, the Device should reconcile its Configuration with the server.

1. Call Get Config API to check whether the manufacturer has set a default Configuration for new Devices.
2. If the response is non-empty:
   1. Apply the Configuration locally.
   2. Confirm via Update Device API.
3. If the response is empty:
   1. Push the Device's current Configuration via Set Config API and persist the returned version counter.

This sequence guarantees the Device and the server are in sync at the end of the registration flow.

Configuration schema

Editing raw JSON is a poor user experience, so define a JSON Schema that describes the Configuration object's structure. The Customer Portal renders a form-based editor from this schema.

The schema is set per Device Model in the Partner Portal, on the Config Schema tab of the Model details page (Configuration → Models → select model).