Introduction to Device Connectivity
Exosite's most basic concept is to make internet connected physical things useful to people and businesses. Exosite's products help developers, companies, and organizations build IoT (Internet of Things) product solutions - providing pieces of the IoT system including device code, a device connectivity / application platform, and hosted applications and services.
Basic Device Communication
The first goal of device connectivity is to have the device interact with Exosite's One Platform, which provides a virtual representation of that thing in the cloud. The most common way for devices to interact is via Exosite's HTTP Device API (Application Programming Interface). Using this API, a standard message would like the following, which is in HTTP format. We will pick it a part here to help give some context to the Exosite One Platform which it is communicating to.
POST /onep:v1/stack/alias HTTP/1.1 Host: m2.exosite.com X-Exosite-CIK: af027fe792f0fc74cedbe3777f5a22961e7b8384 Content-Type: application/x-www-form-urlencoded; charset=utf-8 Content-Length: 14 temperature=44
Most of this syntax from this message is standard to the HTTP format. There are a couple of key parts here to analyze.
The device is communicating with Exosite's HTTP Data API, which can be found at this address: m2.exosite.com. (Note: This is an API, you can not ping this address). Want to quick try out the API - the current unix timestamp is hosted (without auth) at this address: https://m2.exosite.com/timestamp
This is the URL for the Exosite HTTP Data API. In this case, we are writing data to an alias that represents the piece of data in the platform, otherwise known as a dataport.
This long 40 character hexadecimal number is a Client Interface Key or CIK. This is the authorization for this HTTP message to be accepted. Each device in the platform has an associated CIK. This CIK typically comes the Provisioning activation call, where the Platform sends the CIK down to the device after the proper provision steps have occurred and the device has made it's activate request. For getting started though, the Portals evaluation tool (https://portals.exosite.com) allows you to create
generic devices with a activated CIK to copy over to your device.
Finally, the body of the message is temperature=44. This will write a value of 44 to dataport in the One Platform. Dataports store historical values, each with a unix timestamp. As of
Content-Type: application/x-www-form-urlencoded Non-alphanumeric characters from both part of the equal must be percent encoded as defined by the standard https://www.w3.org/TR/html401/interact/forms.html.
To learn more about the Exosite One Platform, check out the One Platform Guide.
Standard Questions about device communication
Can I read data or send data to the device?
Yes, the platform allows for reading data. In regards to sending data (push), there are a few methods of doing this but the most common is to use
long-polling method for HTTP Data API or the
wait RPC. These methods are covered under each API's documentation.
Here is an example of reading data.
GET /onep:v1/stack/alias?command HTTP/1.1 Host: m2.exosite.com X-Exosite-CIK: af027fe792f0fc74cedbe3777f5a22961e7b8384 Accept: application/x-www-form-urlencoded; charset=utf-8 <blank line>
Note that instead of a POST, this is a GET request.
Adding this query parameter
?command to the URL will look to retrieve the value of the dataport with alias
The response will look something like this.
HTTP/1.1 200 OK Date: <date> Server: <server> Connection: Close Content-Length: 14 command=dothis
Here would be an example of making a long-poll request with the HTTP Data API
GET /onep:v1/stack/alias?command HTTP/1.1 Host: m2.exosite.com X-Exosite-CIK: af027fe792f0fc74cedbe3777f5a22961e7b8384 Accept: application/x-www-form-urlencoded; charset=utf-8 Request-Timeout: 300 <blank line>
This call would not return immediately. The server will respond with a value when there is a new value written or the 300 second timeout occurs. This gives the device immediate updates when new data is available.
Why are there multiple APIs?
Devices can very in the resources they have available, including memory, IP socket, Operating System (or none), etc. Exosite wants to provide the best possible solution to allow embedded developers a path that fits their product. HTTP is well established. The JSON RPC uses HTTP to transmit large JSON formatted data sets and gives more features than the standard HTTP Data API, but may not be appropriate for a small embedded device. JSON RPC makes perfect sense to use on a Linux based device though, for example using our Python library.
Code libraries can make life much easier for the different code languages. Exosite supports a large number of libraries as open source code for use on on gateways, embedded devices, and custom applications like web apps and mobile applications.
For devices, there are a number of embedded development kits that are supported with ExositeReady™ or have had reference code ported to them.
- ExositeReady™ Embedded Device SDK - Links to supported hardware platforms
- Other Reference Hardware Platform Support
If you have a question about a specific embedded module, microcontroller, gateway, or development kit - please feel free to ask us through support.
Looking for answers you may have yet? Check out the Exosite support site knowledge base articles on the One Platform.