ExoSense® Device Interface

Overview for building connected products to use with ExoSense

To build products for ExoSense use, they need to connect to an IoT Connector (directly or through a cloud to cloud version) and send data using a specific data schema. Developers must follow this ExoSense data schema which is summarized in this document and more fully detailed in Exosite's Industrial IoT Data Schema and Specification repository.

Overview of requirements for device data in ExoSense:

IoT Connector API Resources

ExoSense requires the following API Resources. Additional resources are used for non-standard functionality. These are automatically available when using the standard ExoSense IoT Connector template from Exchange.

Resource Name

Editor

Description

data_in

Device

Used to send data from device to cloud in the format defined in Section 4

config_io

Device / App

Used to share the complete configuration for a channels in the product. This should be a 2-way synchronization meaning in the case of a self-configuring gateway, this would be written to by the gateway. In a gateway that requires manual configuration from the application, this would be read by the gateway and cached locally.

data_out

App

Used for Device Control

config_applications

Device / App

Specifies configuration for the interfaces used by gateway protocol/fieldbus applications (i.e. “interface = /dev/tty0”)

Note: Generally do not recommend using custom resources with prefix of config_.

The full specification can be found here

Device Channels

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.

Data Format Sent by Device

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

Example Data Packet sent by Device

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

Channel Configuration

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 API resource.

The channel configuration uses JSON format and is stored in the config_io resource in the IoT Connector to allow the both the application side and the device to read and write to it. Note that the device must always acknowledge a change to the configuration, meaning the device is the source of truth for what it is sending.

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

Basic example config_io with minimum properties

{
"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.

Channel Definitions Overview

Each of the unique channels that a device plans to send to the application must be defined in the config_io configuration. In addition to the absolute requirements (display_name, data_type, data_unit, min, max, and precision) additional properties can be defined which are used by the device application for remote configuration.

The full specification for the channel configuration and for data types / units can be found here:

Exosite Industrial IoT Schema repository

Here is a summary of the configuration information.

Channel identifiers

Channel identifiers must be unique to the device context, in the device's config_io and recommend using no special characters or spaces, but must be a valid string. ExoSense uses a "###" scheme starting at "001". For devices that hard code their configuration and are not remotely configurable, any string can be used and can be more descriptive (e.g. "humidity"). Identifiers are not made viewable by users of the application, the display name is what users will see.

Data types / units

The data type definitions are detailed below. Each channel has a unique type and unit tied to the channel identifier that can not be changed after set. The ExoSense application UI will not allow this. Technically a device could overwrite a channel type, but this will have unknown consequences and will likely result in signals not functioning properly. Information about primitive types is also in the Data Types Definition section.

Data types and units for channels and signals are defined in the ExoSense™️ Channel and Signal Data Types document.

Display Name and Description

Used by the application to show the user a friendly name and description (optional) of the channel, which will provide them with better context to help map to asset signals.

Locked channels

The 'locked' property is not required and is optional for use. The entire configuration can be locked or channels can individually be locked. If not set, defaults to 'false'. A locked channel means that it is read-only on the application side. Assumes the configuration (config_io) has been set by the device and the device has no ability to take action based on changes on the application / cloud side.

Locked channels and full configurations generally are used by devices that have a hard coded configuration, the channels are all defined and the config_io is uploaded by the device. Devices can use a combination of locked and configurable channels, thus why the locked field can be found at both the full config level and per channel.

Report Rate

The interval for the device to report values to the cloud (ExoSense). May be used in the application to determine gaps in data.

Timeout

The interval that is considered a timeout for a channel. Can be the same as report rate but typically set at a larger interval to provide room for network slowness and reconnections. Typically not used by the device but used by an Asset signal in the application to generate timeout events for the asset / device UI's, timeout events in the asset logs, and future possibilities. E.g. The device reports a channel every 1 minute but if it hasn't reported for 5 minutes, this is an event that may need to have a call to action for.

Control Channels

Channels can also be used to 'control' a device. A simple example of this is to turn on/off a valve. By default channels are not enabled to be controlled, but by setting the control property to true, ExoSense and the device will allow for sending commands from the application to the device. A control channel uses all of the same schema in this document and devices must write the last state to the data_in resource, but the use of control channels requires the additional use of data_out resource.

Protocol configuration

Optionally used by the device to determine what application (protocol / interface) will be used and the specific details to get / set the information for the channel. Used for fieldbus protocols (e.g. Modbus RTU) or custom applications such as a custom wireless handler or one that gathers data from local I/O on the hardware. The protocol configuration parameters are optional to use, devices that are not configurable may not use this at all and therefore would not be specified.

Devices that are configurable should use the protocol configuration properties to get / set data, convert it, and determine how often to sample (read locally) and report (to cloud).

Channel to Asset Signal Relationship

Device channels are mapped as the source of Asset signals. When signals are created, they inherit the properties from the channels such as data_type, data_unit, precision, report_rate, and timeout. After creation, signal properties other than data_type and data_unit can be edited, but there is no synchronization back to the source channel. The same is true for channels, if they are edited on the device side (which is the source of truth), the signals do not synchronize.

Recommendations for Device Interface Developers

  • Channel IDs should never be changed. Delete, create new if a channel is needed that is a different type / unit.

  • Channel type and units should never be changed for a given Channel. The channel is the source of truth. If a signal was created mapped to a pressure type and the channel was changed to temperature type, the signal would still be pressure but have temperature values.

  • Users should be aware that if changes are made to device channel properties such as timeout, report_rate, and precision - these changes are not automatically updated by any signals mapped to the channel and will need to be updated at the signal level.

Channel Data Types and Units

ExoSense Data Types Specification - Complete List of Data Types

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.

Primitive Types

A primitive type describes the actual underlying encoding / format used for values. Declaring the primitive type in a channel is optional as the primitive type can be derived from the data type. There are four primitive types: NUMERIC, STRING, JSON, BOOLEAN. Primitive Types are used to describe the format of the data type and allows visualizations, transforms, and rules to accept multiple types based on the format.

Units

Generic Data Types For data that may not have units, anything that is dimensionless, or no supported unit types exist. Includes numeric, string, boolean, and JSON structured data generic types. Generic types do not support a measurable unit but does allow developers to add one in the config_io for the channel. Standard unit conversions are not supported in the application for generic data types whether or not a unit is provided - they are marked as 'custom' using an asterisk in the ExoSense UI.

Unit Originated Data Types Physically measurable types of data that include a unit of measure (UOM). Examples include temperature, electrical current, memory, etc.

Many of these types will represent base physical measurements (temperature, length, etc), or derived measurements (velocity), as noted in this Wikipedia article. The list is assumed to never be complete and future types / units could be added. Some physical quantities have simply been left off the list for simplicity and assumed lack of need for Industrial IoT applications.

Application Protocol Interfaces (optional use)

The protocol configuration parameters of the channel configuration provide information that can be used by the device's firmware / application. This allows the application to show users more details about where the data is coming from but also allow the device's channels to be remotely configured.

A part of the protocol configuration is the application interface that's used for the channel.

Supported out of the box Application Interfaces:

  • Modbus RTU

  • Modbus TCP

  • CANopen

  • Custom (contact us)

Each application interface, such as Modbus TCP, has specific protocol settings that go under the app_specific_config parameter in each channel definition.