Devices interact with the provisioning system primarily to retrieve a Client Interface Key (allows API access to their Cloud Profile on the One Platform) and to download content (e.g. for In-Field Update or for media download).
Devices that use the Device Provisioning Interface must have a software-readable unique identifier (e.g. Serial Number, MAC address, other UUID) that has been pre-registered with a Client Model on the One Platform. This will allow the Device to interact with the Device Provisioning Interface via the Device-specific APIs to do things like authenticate with the One Platform and to get new media content (e.g. in-field software upgrades).
In order to setup a Client Model and to add Serial Numbers to the Model, a Vendor must initialize the interface with the Vendor Management APIs (or Exosite Portals OEM admin interface).
Activation on the provisioning interface is the first step to all subsequent interactions. A Client must activate itself in order to gain access to its cloud profile and related Client Model characteristics.
Here is an example software flow chart for how device firmware could implement the activation process:
Software Flowchart for Device Activation
The activation sequence simply consists of the Client sending its unique identifier (e.g. Serial Number) to the One Platform, and receiving a Client Interface Key (CIK) back. The Client should then store the CIK in non-volatile memory and should use the CIK for subsequent interactions with the One Platform.
In cases where the client model isn't available for activation, the client should attempt its normal reading and writing of dataports to check if its already stored CIK is valid. If those read and write requests succeed, continue the application as normal. If those requests fail with a 401, the stored CIK is invalid and the device should again attempt to activate. Devices smart enough to know if they have already stored a CIK or not may skip doing reads and writes when there is no CIK available.
You must rate limit your activation requests. Repeatedly sending the same failing request wastes bandwidth and causes excessive server load especially with large fleets of devices. We suggest using an exponentially increasing delay to balance both real-time interactivity and resource consumption. That is to say, after the first error you would delay for one second, then two, four, eight, and so on seconds until you make a successful request which would reset your error counter. You will likely want to set a limit on the maximum delay to ensure your device doesn't become completely unresponsive after extended periods of being unable to activate, we suggest a cap of 15 minutes, but this value will depend on your specific application.
Every Client Model has a timeout period for activation – the timeout period starts when the Client Serial Number is enabled on the system (e.g. in Exosite Portals, this would be when a User adds a new Device to their Portal). If the Client does not activate before the timeout period expires, it must be re-enabled. This timeout period is enforced to ensure only authorized Client Owners can activate a Client matching their Serial Number.
Should the timeout period for activation expire, the Client Owner must either re-enable the Client for activation or remove the Client entirely.
A Client that has been activated as part of a Client Model is able to download authorized content from the Client Model. This feature is most commonly used for providing new firmware to devices in the field (e.g. in-field update), and for providing new media content to devices (e.g. new images for advertisement content).
The Client functions available are:
- Get Content List - Proivdes a list of available content
- Get Content Info - Get details of each content item (timestamp, description, etc)
- Get Content - Get actual content
The Client must have pre-knowledge of the naming scheme and format of the content for download. For example, a Device could know that it uses content with IDs starting with “firmware” for new firmware files. If the current firmware file is “firmware_v1″, it could query content ID “firmware_v2″ to determine if there is an authorized firmware update awaiting.
All Client Model content is managed by the Vendor who owns the Client Model. They are responsible for maintaining the content available to a given Content Model as well as for managing access rights to the content.