Building Connected Devices¶

This guide goes through the steps of connecting a IoT device to Exosite's platform and using it with the ExoSense application. Weaved in with these steps is an overview of the device interface, data scheme, and terminology.

Requirements¶

Create an IoT Connector¶

To build direct connected products for ExoSense use, the device firmware or application needs to communicate over one of Exosite's device API protocols to an IoT Connector that you manage.

Deploy a new IoT Connector using one of the Templates found in the Exchange IoT Marketplace. For the purposes of this guide, we will use the ExoSense Standard Connector Template. This template includes the required API Resources needed for the ExoSense Device Interface.

Once created, you can manage your connector by clicking on it.

Protocol Settings and Provisioning¶

Using the IoT Connector Management area, set the required API protocol (HTTP or MQTT), the authentication settings, and get the unique connector API Endpoint.

For the purposes of this guide and the tutorial steps, we will be using HTTP with Token provisioning, but similar steps are followed for MQTT.

Check Resources Setup¶

ExoSense requires and uses the following resources. Having used the Standard ExoSense Connector Template, these should already be set up.

The full specification can be found here Exosite Schema

Add a Device Identity¶

All connected IoT devices are represented by a unique ID in an IoT Connector. All data events include this identifier so the data can be mapped properly. Since all identities must be provisioned and require authorization to use the API, the data remains securely associated to that device through the system.

Add your first device identity by using the + New Device(s) button. (Depending on your settings, devices may also register their identity when they provision).

For this guide, we are going to add identity A0001. Note that when you add the identity, it will show that it has not yet authenticated yet.

After adding, you can click on the device to see the state of it's resources.

Data Interface¶

The most important resources to understand are data_in and config_io. Devices may not need to use other resources as they are optional based on functionality such as remote control, custom device application protocol configuration, and in-field software updates (software packages / OTA Updates).

Device data such as sensor values, is sent to the platform using the data_in resource. config_io is used to describe the data being sent. Details for this interface are as follows.

Device Channel Data (data_in)¶

ExoSense uses a concept of channels for the flow of data from a connected device. Channels typically are specific sensors (e.g. temperature, humidity) but may also be status information. Formats include numeric, string, JSON, and boolean. Channels can also be used for sending requests down to the device, known as control channels. These channels in ExoSense can be then be subscribed to as the source for an Asset Signal.

Channel data is written to the data_in API resource.

{
  "${device_channel_id_1}" : "${current_channel_1_value}",
  "${device_channel_id_2}" : "${current_channel_2_value}"
}

{
  "temperature1":42,
  "pressure1":135.02,
  "randomnum":-12
}

$ curl -i 'https://<IOT_CONNECTOR_FQDN>/onep:v1/stack/alias' \
    -H 'X-Exosite-CIK: 22596363b3de40b06f981fb85d82312e8c0ed511' \
    -d 'data_in={"temperature1":42,"pressure1":135.02,"randomnum":-12}'

POST /onep:v1/stack/alias HTTP/1.1
Host: <IOT_CONNECTOR_FQDN>
{X-Exosite-TOKEN: <token>}
{Authorization: Basic <base64-encoding of identity:password>}
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: 80

data_in=%7B%22temperature1%22%3A42%2C%22pressure1%22%3A135.02%2C%22randomnum%22%3A-12%7D

Channel Configuration (config_io)¶

In order to have an agreement or 'contract' between ExoSense and the device, a channel configuration is shared between the device and ExoSense. This configuration agreement keeps parameters like type, units and other information consistent and known throughout the full application end to end, like a source of truth.

The configuration is stored in the config_io resource.

Here is an example of a very simple configuration value with minimum of properties set.

{
  "last_edited": "2018-03-28T13:27:39+00:00",
  "last_editor": "user",
  "meta": {
    "description": "example config for my device"
  },
  "channels": {
         "randomnum" : {
      "display_name" : "Random Number",
      "description" : "random generated number",
      "properties" : {
        "data_type" : "NUMBER",
        "min": -100,
        "max": 100,
        "precision" : 2
      }
    },
    "pressure1" : {
      "display_name" : "Pressure 1",
      "description" : "input pressure for filter",
      "properties" : {
        "data_type" : "PRESSURE",
        "data_unit" : "PSI",
        "min": 16,
        "max": 35,
        "precision" : 2
      }
    },
    "temperature1": {
      "display_name" : "Temperature 1",
      "description" : "fluid temperature",
      "properties" : {
        "data_type" : "TEMPERATURE",
        "data_unit" : "DEG_CELSIUS",
        "min" : 0,
        "max" : 300,
        "precision" : 2
      }
    }
  }
}

When a device writes channel data based on this configuration, it will send values for 'temperature1', 'pressure1', and 'randomnum'. The device and the application have the channel configuration defined above as a 'contract' between the two.

The full specification for the channel configuration and for data types / units can be found here: Exosite Industrial IoT Schema repository

Channel Data Types and Units¶

Each channel requires to be set as a specific type which should be the source of truth and therefore allows for allowing down-stream support for conversions, visualizations, etc that can be trusted. In the ExoSense application, Asset Signals inherit type/unit from the channel. Type and units must not be changed for a channel/signal (based on channel id) once created, instead a new channel or signal should be created to handle the change. Each of these types stem from one of the four primitive types.

ExoSense Data Types Specification - Complete List of Data Types

Remote Configuration Support¶

The config_io can be updated from ExoSense. In this use case, the device firmware must support long-polling (http) or subscribing (mqtt) to the config_io resource. For the purposes of this tutorial, this will not be shown as it assumes the device is hard-coded (or configured on device) with the channels it sends for simplicity purposes.

Device Application Interaction¶

Your device will need to talk to the Exosite Device API using your specific IoT Connector endpoint. Examples and references are provided and are a good place to start.

Activation¶

Earlier in this guide, a new device identity (A0001) was created in the IoT Connector. This device will need to provision, receive it's authentication token, and store this token for all further communication.

HTTP Request for Activation

POST /provision/activate HTTP/1.1
Host: c3qzj6bnrzk800000.m2.exosite.io
Content-Type: application/x-www-form-urlencoded;charset=utf-8
Accept: */*
Content-Length: 8

id=A0001

Response:

HTTP/1.1 200 OK
content-length: 40
date: Thu, 09 Sep 2021 20:24:03 GMT
server: Murano

2RfG0aak2KQFQVAsM5D737VguXkZH2GIf9f2YcAl

The response value of 2RfG0aak2KQFQVAsM5D737VguXkZH2GIf9f2YcAl is my token that is required for all further device communication and must be stored safely in non-volatile memory on the device.

We can see in the IoT Connector that the device shows as activated.

Send configuration via config_io¶

Now the device can send it's configuration information via the config_io resource. In this example, the device has the following channels to send: Bearing Temperature, Electrical Current, Flow Rate, Rotation Speed.

{
  "last_edited": "2021-08-19T13:55:36+00:00",
  "channels": {
    "0001": {
      "display_name": "Current Draw",
      "properties": {
        "data_type": "ELEC_CURRENT",
        "data_unit": "AMPERE",
        "report_rate": "10000",
        "description": "Electrical current measured",
        "precision": 2,
        "timeout": "60000",
        "locked": true
      },
      "locked": true
    },
    "0002": {
      "display_name": "Flow Rate",
      "properties": {
        "data_type": "FLOW",
        "data_unit": "GALLONS_PER_MIN",
        "report_rate": "10000",
        "description": "",
        "precision": 2,
        "timeout": "60000",
        "locked": true
      },
      "locked": true
    },
    "0003": {
      "display_name": "Speed",
      "properties": {
        "data_type": "ANGULAR_VEL",
        "data_unit": "ROTATIONS_PER_MIN",
        "report_rate": "10000",
        "description": "",
        "precision": 2,
        "timeout": "60000",
        "locked": true
      },
      "locked": true
    },
    "0004": {
      "display_name": "Motor Bearing Temperature",
      "properties": {
        "data_type": "TEMPERATURE",
        "data_unit": "DEG_FAHRENHEIT",
        "report_rate": "10000",
        "description": "Motor bearing tempearture",
        "precision": 2,
        "timeout": "60000",
        "locked": true
      },
      "locked": true
    }
  },
  "locked": true
}

POST /onep:v1/stack/alias HTTP/1.1
Host: c3qzj6bnrzk800000.m2.exosite.io
Content-Type: application/x-www-form-urlencoded
X-Exosite-CIK: 2RfG0aak2KQFQVAsM5D737VguXkZH2GIf9f2YcAl
Accept: */*
Content-Length: 1403

config_io=%7B%22last_edited%22%3A%222021-08-19T13%3A55%3A36%2B00%3A00%22,%22channels%22%3A%7B%220001%22%3A%7B%22display_name%22%3A%22Current%20Draw%22,%22properties%22%3A%7B%22data_type%22%3A%22ELEC_CURRENT%22,%22data_unit%22%3A%22AMPERE%22,%22report_rate%22%3A%2210000%22,%22description%22%3A%22Electrical%20current%20measured%22,%22precision%22%3A2,%22timeout%22%3A%2260000%22,%22locked%22%3Atrue%7D,%22locked%22%3Atrue%7D,%220002%22%3A%7B%22display_name%22%3A%22Flow%20Rate%22,%22properties%22%3A%7B%22data_type%22%3A%22FLOW%22,%22data_unit%22%3A%22GALLONS_PER_MIN%22,%22report_rate%22%3A%2210000%22,%22description%22%3A%22%22,%22precision%22%3A2,%22timeout%22%3A%2260000%22,%22locked%22%3Atrue%7D,%22locked%22%3Atrue%7D,%220003%22%3A%7B%22display_name%22%3A%22Speed%22,%22properties%22%3A%7B%22data_type%22%3A%22ANGULAR_VEL%22,%22data_unit%22%3A%22ROTATIONS_PER_MIN%22,%22report_rate%22%3A%2210000%22,%22description%22%3A%22%22,%22precision%22%3A2,%22timeout%22%3A%2260000%22,%22locked%22%3Atrue%7D,%22locked%22%3Atrue%7D,%220004%22%3A%7B%22display_name%22%3A%22Motor%20Bearing%20Temperature%22,%22properties%22%3A%7B%22data_type%22%3A%22TEMPERATURE%22,%22data_unit%22%3A%22DEG_FAHRENHEIT%22,%22report_rate%22%3A%2210000%22,%22description%22%3A%22Motor%20bearing%20tempearture%22,%22precision%22%3A2,%22timeout%22%3A%2260000%22,%22locked%22%3Atrue%7D,%22locked%22%3Atrue%7D%7D,%22locked%22%3Atrue%7D

HTTP/1.1 204 No Content
date: Thu, 09 Sep 2021 20:41:34 GMT
server: Murano

Looking at the device resources now in the IoT Connector will show this updated config_io.

Send channel data via data_in¶

At this point, the device application may begin sending data using data_in.

{"0001":0,"0002":21.73,"0003":0,"0004":73.05}

POST /onep:v1/stack/alias HTTP/1.1
Host: c3qzj6bnrzk800000.m2.exosite.io
Content-Type: application/x-www-form-urlencoded
X-Exosite-CIK: 2RfG0aak2KQFQVAsM5D737VguXkZH2GIf9f2YcAl
Accept: */*
Content-Length: 101

data_in=%7B%220001%22%3A0,%220002%22%3A21.73,%220003%22%3A0,%220004%22%3A73.05%7D

HTTP/1.1 204 No Content
date: Thu, 09 Sep 2021 20:48:11 GMT
server: Murano

In the IoT Connector, we can see data_in with the channel data.

Using in ExoSense¶

Now that the device is connected and sending data, it's time to use it with ExoSense. The data_in messages sent up to this point are not stored. An event is generated but if no application solution (such as ExoSense) is subscribed to the connector, they go un used.

Add the IoT Connector to ExoSense¶

Your IoT Connector was automatically published private as a service in your business account marketplace. It can now be used with ExoSense by managing your ExoSense instance and clicking on Add IoT Connector.

Find your new connector service.

Add this IoT Connector service element to your ExoSense instance.

The connector will now be shown in the list of enabled IoT Connectors for your ExoSense instance.

Assign the Device¶

Log in to your ExoSense instance and go to the Devices page.

Click on the 'Unused Devices' tab. These are devices that have not been assigned ownership. Your device identity should be shown here.

Select it and pick the group where it will be assigned to for ownership. Then click the ASSIGN TO GROUP button.

Click back to the Devices tab, the device will be listed here with it's owner group.

Click on the device to see it's overview. The channels that were previously configured with config_io along with the last values and timestamps will be shown for each channel.

The LOG tab will show the last ~100 data_in and config_io messages.

Data is now flowing into the ExoSense pipeline from your device.

Create an Asset from the Device¶

The last step is to create an asset that uses the device's channel data. Channels are assigned to Asset Signals, which then store the data historically and can be used with analytics, transformations, rules, and actions in the ExoSense pipeline along with visualizations.

On the Device Overview tab, use the 'CREATE ASSET FROM DEVICE' button.

The default settings can be used, customize your Asset name, description, and icon. Assuming no Asset templates have been created yet, these steps will create a new Asset directly from the device's existing channels. Click the 'CREATE ASSET' button.

Your new asset has been created with signals mapped to the device's channels.

The signals can now be used in Asset dashboards, rules can be added, data transformed, and Insight analytic functions can be used.