This is a guide for developers looking to create device client software (firmware, code) and use Exosite Platform / Portals to ensure a positive out-of-box experience for your products, kits, demos, etc.
Exosite provides libraries and many reference projects for device application and firmware that may jumpstart your own code project. Review the available Device SDKs, Libraries, and hardware platform reference code..
Getting started notes / check list:
- Learn about what clients are, which represent devices in the Exosite One Platform.
- Decide on what API to use.
- Use DNS URLs (like m2.exosite.com). Do not hard code server ip addresses for the API calls. Servers can and will change, IP addresses are not always guaranteed to stay. Be sure that devices check DNS more than just at boot up, whether on a recurring time period check or with exception handling when it can't connect to the server. Devices in the field may not have the ability to be reset / re-powered on to get the new IP Address through DNS.
- Make sure to think through how you will handle different response codes from the server for retries, detecting bad network connections, and bad Exosite authorization (CIK).
- You may want to start with hard-coded client identifier keys (CIK) which are used as a key to talk to the API. Once functionality is there for using the API (read, write, etc) implement provisioning with vendor client models so devices can automatically receive a CIK for large deployments. To get a hard-coded CIK, add a 'generic' device to your account.
- Think about how users can identify the state of the device in regards to connecting to the network and to Exosite. Example, using flashing LEDs to report connection status or error conditions.
- Create a Data Architecture.
- What data does the device need, what data does the UI need, what data do you as the device vendor need?
- What is the format of that data. Is it individual streams of integers, floats, or strings? Is it formatted data like JSON or XML or CSV?
- Will there be scripts that need to be created to process, analyze, or send out dispatches?
Basic Write and Read Functionality
Decide what data the device needs to send to and read from the cloud. These are called dataports in the platform and may also be referred to as data sources or data streams.
Recommended APIs to get basic support for write / read functionality:
Decide how the device client code will get the Client Identifier Key (CIK) to access the API. If you are not using a Vendor / Client Model Type (Exosite sub-domain Whitelabel Vendor account), you should assume users will create a generic device type. For generic devices, copy CIK manually into the code on the device, which you can find in the portal by going to the Devices manage page and clicking on your device.
(We recommend using a Whitelabel account to create your own Client Model instead - see below for additional information).
Troubleshooting HTTP Messages
Most developers start using our HTTP Data interface, using POST and GET methods. If you'd like an example of putting together one of these HTTP messages, this example script is a good reference. It's python but shows using TCP socket, not a HTTP library. So, it is useful for reference even if using C code for example.
Of course if you have python on your computer you can quickly test this with your own CIK and data source alias.
Advanced API Functions
The RPC API allows for more advanced functionality beyond read/write from the device, including recording (logging data), creating sub-devices (nodes), editing the device client's setup on the platform, and calling multiple functions in one request. The RPC is available over HTTP in JSON format or over CoAP in CBOR format.
Use Cloud Scripting Engine
Add Platform Scripts to your devices in the Exosite One Platform which can perform processing of data, analytics, and alerting.
- parsing raw data
- sending out alerts
- detection of device status, whether it is online
- manipulate the data for user interfaces
These next items require Vendor accounts
Client Models / Device Activation (vendor accounts)
Client Models represent a product line or fleet. Vendors accounts can create client models, which are essentially a profile that is cloned each time a device is added to the account, but also give the vendor fleet management functionality. The use of client models requires devices to 'activate' as a specific unique device under that client model.
Use the Provisioning API on the device so that it activates as a specific Client Model (specific product). This also allows a device to connect to the platform without having to have a CIK manually programmed into it, allows a device to get content updates, and allows you to manage each specific device's access. Provisioning is available for devices using either HTTP or CoAP. To use provisioning, you need a vendor ID through a Whitelabel account with Exosite or by working with an existing Vendor that can provide a Model ID to use.
- The Provision API requires a unique serial number. Typically this is a MAC address, serial number that is readable by software, or a cellular ESN/MEID.
- When the device activates with the platform, store the provided CIK from the platform in non-volatile memory. The CIK is only provided once.
- Have the device code check for activation at power-up or if receiving HTTP 40x error responses, even if it has a good CIK already (i.e., activated once). This is because the device may be re-enabled by the user or an application, which will generate a new CIK. It may also be deleted by the user and added by someone else, which is very typical for evaluation / demo kits. You can find a good device state flow chart diagram here.
- Vendors should use their vendor specific host for API calls .m2.exosite.com which will allow us to improve performance over-time as more connections are made.
In-Field Firmware Updates / Content (vendor accounts)
Devices must be a part of a vendor client model and must be activated to access the content. Content is listed for the specific Client Model devices, each individual devices should make the API request to either list all content, get information on a specific content item, or download a specific content item. Content can be published for client models; each piece of content has a specific identifier, timestamp, type, and meta field. The timestamp and identifier can be used to check for downloading content.
Developers can create their own custom scheme for how devices know when to download new content. Versioning can be done by using an identifier name scheme like 'firmware_v1', 'firmware_v2', or by using the timestamps of the files to determine if it should be downloaded and applied.
The actual use of content on the device is up to developers, whether it is to update the firmware, applications, for configuration, or files like images for various media applications.
If performing in field firmware updates, be sure to follow best practices including checking checksums, verifying full downloads, having a back-up device bootloader, etc.
Plan for Scaling (vendor accounts)
If you have a Provisioning Vendor ID (any business solution account), be sure to use the specific vendor API address. The format is typically <vendorid>.m2.exosite.com. This can be found on your Portals solution admin home page (https://<vendorid>.exosite.com/admin/home) under Vendor API information. This is important if we need to work with you to off-load network traffic or customize the API handling for your devices.
Improve Troubleshooting for Users / Technicians / Developers
Debug Output / Status Indicators
Many devices that will be connected to Exosite do not have a screen or user interface. We recommend using LEDs to provide some type of status and error conditions for the network connection and Exosite provisioning.
- Blink an LED once per second if no network connection, twice per second if can't connect to Exosite, keep on if connected and working.
- Have a debug serial port that lets user know status conditions (this is more for developers)
Helpful HTTP Headers
For HTTP requests, add a "User-Agent" header. This enables us to help you trouble-shoot, examine your network load, and handle custom requests. Below is an example of the format:
- Example User-Agent:acme_bg100/bg1xx_firmware/1.3
NOTE: If you are using an Exosite library or Activator code, we recommend using this for your code identifier.
Suggestions for Development Kit Vendors
- Provide source code for client apps for kits and demonstration devices.
- Give users a SDK / library for the Exosite commands for their own application development.
- Provide command line options to program CIK manually
- Provide good debug messages on responses from the Exosite platform (e.g. HTTP Responses)