Building Custom Insights

ExoSense Stream Analytics, Transforms, and Rules

Overview

ExoSense supports a way to plug-in custom asset signal transforms and rules. This plug-in type service is referred to as Insights or Insight Modules. The Insight Module itself is a service that exposes the defined interfaces ExoSense requires and includes one or many functions

High level overview of an Insight transform function

An Insight Module may include many functions of type transform and rule, the available functions are dynamically loaded when users go to add a new transform (shows available transform functions) or rule (shows available rule functions

High level overview of an Insight rule function

End User Experience

End users are presented with a set of transform and rule functions in the Asset Configuration window, this information is loaded dynamically when the user goes to add a new transform or rule.

Basic Concepts

Streaming

  • At their core, Insights are not expected to be stateful; similar to other Transformations like Join and Linear Gain, they operate on the latest value of Signal data.

  • For a given Join on SignalA and SignalB, each time a piece of data comes in from either of those Signals, the Join runs (and returns a joined value).

  • The Join Transform uses the last seen value of any Signal not present in the data sent to the Join at any given time.

Exosite Exchange Element

To use an Insight Module with ExoSense, it must first be added as an element into Exosite's IoT Exchange within your Exosite Account. These elements use a Swagger definition to define the API interface.

The swagger definition for the Service is found in this repository: insight-template.yaml. Use swagger.io to view the incoming and outgoing data format.

Note: it must use the element tag in the swagger definition as shown below for ExoSense to identify it as a service it can consume

tags:
- name: insight
description: Insight Module

Webserver

  • The Exchange Service created for an Insight defines the URL to be requested when ExoSense needs to do any of the following:

    • get high-level information about the Insight

    • get a list of available functions for a group, along with their required parameters

    • get info about a specific function, along with its required parameters process incoming Signal data (i.e. "run the function")

Hosting

The service can be hosted anywhere, including:

  • Exosite's Murano Application Platform

  • Amazon Web Services

  • Microsoft Azure

  • Google Cloud Products

Service

  • The code behind the Insight is entirely up to its creator; as long as it conforms to the Swagger definition, ExoSense will happily send and receive data from it.

  • The code that makes up an Insight can be written in any language available within the chosen host.

Examples

The current list of example ExoSense Insights is as follows:

Requirements

HTTP Web Service

Hosted somewhere with public endpoints

Required Endpoints

GET /info This endpoint is used to get high-level information about an Insight. The name displayed within the ExoSense UI, the Insight description, and whether or not a group_id is required are supplied via this endpoint.

GET /insight/{fn}

This endpoint is used to get all the necessary information about a specific Function, including:

Description Input Signals (inlets) Output Signals (outlets) User-Supplied Constants

POST /insights

This endpoint is used to supply a list of Functions (and their info/requirements/meta-data) available to a specific Group (supplied as a Group ID)

POST /process

This endpoint is used to process Signal data and return a new Signal(s)

Hosted Swagger API definition

Use the following template Insight API Swagger Template and only change the following:

  • info

  • host

  • basePath (in many cases the host URL is sufficient and this should be left as "/")

Reference

The Insights Interface Schema is found here which details the interface details