Users who have a Whitelabel or vendor account have access to the admin interface for their portals subdomain. (e.g. <mycompany>.exosite.com/admin) The admin interface includes tools for creating and managing client models.
- Creating A Client Model
- Managing Client Model Serial Number Lists
- Adding a Device using a Client Model
- Managing Client Model Content
Creating a Client Model
Create a Clone
In order to create a client model, a clone must first be created. A clone is a generic client representing your device. We typically recommend creating a portal in your subdomain that you use only for holding these clone generic devices. I've created a portal here called 'DOMAIN ADMIN' for this purpose.
Let's create a generic device called 'Super Coffee Machine CLONE'.
Then add data sources, data rules (Events) and Scripts to it. These resources will be duplicated every time a user or tool adds a new device of your client model. Scripts are going to do things like parse and make sense of data, perform configuration routines, data conversion, diagnose issues on the device from error data, and alerting.
Once your clone is set up, you can now create your client model and attach this clone to it.
Note: You can always update your clone at any time, update and add resources, etc. Devices that are added already will not get these updates but any devices added after the fact will have the updates. To update devices already enabled for your client model, you can run an application or script that uses the Exosite API to parse through the client tree.
Add your Client Model
To add your client model, go back into your subdomains admin interface (/admin) and go to 'Manage Models' under the Client Models tab on the left.
Start to fill out the information for your client model. The thing that can't be changed is the Model ID and this should be something that your device's code can easily use and should be kept short and descriptive. The Model Name is actually what users would see in the user interface and can be changed at any time. You'll notice that the 'Clone from Device' option has a drop-down menu which should show all devices you have access to in your portals, including the clone you created in the step above.
The Domain Dashboard doesn't have to be selected, we'll cover that in another section.
After filling out the information, and making sure you've provided a Model ID (unique to your vendor account), a Model Name and selected a Clone from Device, you can hit 'Add' which will add to your list of Models at the bottom.
You'll notice the client model is by default not published (Red indicator). You can publish your client model at this time by clicking on that indicator or leave it unpublished until you are ready.
Managing your Serial Number list
In order for a user or tool to add a device of your new client model type, you must specify the list of serial numbers that are accepted. This will control what can be added and also what devices can activate as your client model, providing a barrier to malicious software trying to get access.
The term Serial Number refers to an identifier used by the Exosite Platform's provisioning system that identifies individual devices and controls access. The actual number can be anything that is unique to each device. It could be a MAC address, and MEID or other cellular identifier, etc. We highly recommend choosing an identifier that your device software can read from the hardware, like a MAC Address.
Adding Individual Serial Numbers
To add an individual serial number to your client model, go to the Serial Numbers area under the Client Models tab in your admin interface (/admin/serialnumbers).
Select your model and click the option for Add 1 Serial Number. Specify your specific serial number here in the exact format (upper case, lower case, colons, etc) that your device will try to activate with and that your user will enter. When you created your client model, you can specify whether the Portals 'Add Device' interface will remove non-alpha numeric characters that the user may enter, so if you don't have your device activating with colons but your user enters them for the MAC address, Portals would remove these first.
After you've added your serial number, you'll see it shows up in the Serial Number List at the bottom of the page. This list will show you the status of the serial number and provides options to delete it, disable, and re-enable it manually. Once a user adds it and a device activates, the status will change to reflect this.
Adding a range of serial numbers
Adding serial numbers individually works well for development but soon you'll want to add ranges of serial numbers that are accepted or import a raw csv file with your list of serial numbers. Both of these options are available to you here.
To add a range, click the Auto Add SN option and choose the format (base10, base16, mac:48, mac-48, or mac.48). Specify your range (start and end) and the length of the SN. There may be other options like automatic conversion of the serial number case (upper/lower) for those that include letters (e.g. base 16 includes a, b, c, d, e, and f).
The way the range option works is that the portals 'Add Device' interface will check the range(s) of your client model and if it fits and has not already been used, will add the serial number to the serial number list, just like if you added it individually here.
You are set now, you can now add devices using your client model.
Adding a Device using the Client Model
Now that you've created your client model and have added serial numbers or a range of serial numbers, you or another user can add a device to their portal using the Add Device interface. Of course the Exosite API is also always available to do this from other applications.
Let's test this out now. This example uses a portal named 'User Testing' that we will try out adding a new device on. Go to the portal and go to the manage device's page (click 'Devices' in the manage menu on left side). Click the 'Add Device' link on the device manage page.
Your client model should be listed under 'Select a supported device below.'. You'll notice there is an option to add a generic device also. This option can be removed in the domain configuration area of the admin tools. Click 'Continue'.
Enter the serial number to test out for your device. Here we'll use '00:01:FF:00:22:01' which should fit into the range we specified earlier. Portals will automatically strip the colons out and convert to lower-case based on options selected for the client model and the range. After specifying a name, click 'Continue'. If everything was set up, you should see a CIK here on a confirmation page.
Let's look at that device now on this manage page. Click on the device to pop-up it's information. You should see that the data sources specified in the original clone are here. You'll also notice that the 'Status' is 'Not Activated' as the Exosite Platform is now waiting for the device to call the Activate API.
Checking out the scripts for this device under the Scripts manage page (/manage/scripts) you should see also that the scripts from the clone were copied and running (or complete if there they are not while loops).
Back in the admin tools area, the serial number in the client model's serial number list will show that it is used but not activated.
After the device has called the Activation API in which the Exosite Platform would have sent it's CIK to it, the device status will show as 'Activated' to the user and in your admin area.
Managing Client Model Content
Devices that have implemented client model provisioning with Exosite can access content specific to that client model. Content are files of any kind that are posted for client model so any device that calls the API with a valid serial number and CIK can get access. This is useful for things like in the field software updates, accessible media files, and configuration files that the fleet should download and use.
To add content to a client model, go to the subdomain's admin tools and click 'Content' under the Client Models tab on the left side. Select your client model, provide a name (this will be the content id used by the API), a description, type, and then upload the file.
Now that the content is uploaded, you'll find that you can edit it (post an update) clicking the edit icon next to the content. The next time the device checks, the time stamp for the content will be updated to this point.