The Exosite One Platform's fundamental elements are clients which represent devices in the cloud. A device client contains resources like data sources, scripts, and meta information and is accessed by using a CIK (Client Identifier Key) to read, write, and modify it.
The simple scenario is for a user to 'add a device' using a user application like Exosite's Web Portal, which would generate a new client with a CIK. The user can add data sources to it, scripts, and other resources and copy the CIK (which is a 40 character hash) to the device's application code. This is known as a 'generic' device client. This scenario works great for development and prototyping, but if you are a vendor and want to deploy a fleet of 1000's of devices, it's not a great solution.
This brings us to the idea of Client Models. A client model is a pre-defined device profile that a vendor would create. This device profile copies an original 'clone' whenever a user adds a new device of this client model type. Besides creating this copy automatically for the owner, the device can use the Exosite provision API to activate and receive the CIK automatically without any manual copying of the CIK to the device.
Client Model Overview
Client models are unique to vendor accounts, which is a prerequisite to create client models. Each client model has the following attributes:
- Unique model identifier
- Friendly name for users to see
- Clone device
- List of serial numbers
- Content (Optional)
- Groups (Optional)
Getting a Vendor Account
The clone is a generic device that has been set up with data sources, data rules, scripts, and dispatches that the vendor wants to copy each time a user application adds a new device.
The serial number list is a 'whitelist' essentially of unique identifiers for devices that can be added by an owner. The serial number is typically dictated by a unique hardware identifier the device can use for API calls. Typically this is a Ethernet/WiFi MAC address or some other software readable identifier. The user application then asks the user what device they want to add and tells them to provide this unique identifier.
When a device activates using the provisioning API, it will call in with the vendor id, model id, and this unique identifier. If an owner has enabled this unique serial number (added it) then the One Platform will provide a CIK to the device in response to the activation request.
Content is essentially files that can be posted for this client model with a file identifier, the blob (actual content), a description, and a timestamp. Devices can then use the provision API to get content, look for updates and decide to download the content. This is useful for things like updating firmware and applications in the field, configuration files, and posting media files for devices to download.
Taking content to the next level, groups can be created that specify what serial numbers can access what content. This is useful for controlling access to certain content, perhaps if device owners have a license for more advanced features of your device.
Developers can use the provision API or the Portals Admin tools for managing client models.
Managing Client Models in the Portals Admin Interface
Here are the steps to creating and managing your client models from a developer stand-point.
Step 1. Create Clone
In a Portal for your whitelabel (sub-domain, domain), create a generic device and set up data sources, events (data rules), and scripts as you want every device (product) that is of your model to have. Any device that provisions as that model type and is enabled into an account will copy (clone) that setup including any data inside of data sources. Mark the device as a clone in it's Manage pop-up window. (There is a check-box for this)
Step 2. Create Model Type
As a whitelabel admin, you will have access to the Client Models area of the sub-domain / domain. Add a new model and attach your generic 'Clone' from step 1 to this model type. Add your serial numbers (MAC address, MEID, etc) for your devices. Typically Serial Numbers are chosen by identifying a unique number on the device that software can read, as the device will need to try to activate with that unique number.
Step 3. Add Content for you Model Type (optional)
If you would like to make content (firmware, config files, media) available to your device to download after activating (provisioning), you may add the content after the client model type is created. This can be edited at any time. This is done at the admin level of a whitelabel account or via Vendor APIs.
Step 4. Put Code on the device that uses Exosite's Provisioning API
Provisioning allows for a couple of things. First is that it allows products to be put into the field without preprogramming CIK (Exosite Platform Keys). It also allows control of what uniquely listed devices (by serial number) can activate and get access to content. When a device tries to activate it sends it's Vendor ID, Model ID, and Serial Number to the Exosite Platform. The Platform will return with a response that denies the request or includes a CIK. The Platform will only allow a device to activate if the device's Serial Number has been Enabled (see next step). Optionally, the device's code (application) can also check for content using it's Vendor ID, Model ID, and Serial Number. The Platform will return with a list of content, timestamps, and sizes.
Step 5. Decide who or what will Enable devices
Devices that have had their Serial Number listed to the Model Type or will be auto-added must be enabled. This can be done through Exosite Portals (User Adds devices) or with API function calls from other software using your Vendor Key. This creates a ownership path of the device and data in the Exosite Platform. There is a default Time To Live (TTL) of 24 hours for device clients to activate once the Serial Number has been enabled.
Step 6. Power on devices
Devices that have been enabled will receive a CIK from the Exosite Platform when it attempts to activate (API call). The device should store this CIK in non-volatile memory, as it will use this for communicating with the Platform (read, write, RPCs, etc). It's recommended to have the device try to re-activate once in a while since devices may be re-enabled or ownership changed, which would generate a new CIK. The device will have access to any available content, which is also recommended to have a check for over a time period as it may be updated.