Difference between revisions of "V2/Integrate/Others"

From Senfi Docs
Jump to: navigation, search
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
<h1 class="main-heading">Connectors for 3rd Party Applications</h1>
+
<h1 class="main-heading">Implementing a connector</h1>
  
−
Senfi monitors and stores time series data from your existing systems. At the moment, Senfi provides a [https://mqtt.org/ MQTT] interface for receiving data from your systems. To start sending data to Senfi, you need to do the following:
+
Senfi monitors and stores time series data from your existing systems. At the moment, Senfi provides two methods of receiving data from your systems:
 +
* [https://mqtt.org/ MQTT] interface. See [[V2/Integrate/Others/MQTT|Publish to MQTT]].
 +
* [https://www.senfi.io/docs/api/1/1/ Senfi API]
  
−
# Create an [[V2/CMS_Tutorial/Developer_Tools/Integration/Key|integration key/secret pair]] in the CMS.
+
=== Supported Metric Data Types ===  
−
# Design and create a [[V2/CMS_Tutorial/User_Tools/Creating_Content/Measurement|measurement]] in the CMS.
 
−
# Write a program to read from your system and send it to [[#Publish to MQTT|Senfi's MQTT endpoint]].
 
−
 
 
−
=== Publish to MQTT ===
 
−
A typical integration follows this pattern:
 
−
 
 
−
External system --> Your application --> Senfi MQTT endpoint
 
−
 
 
−
Either the external system you are monitoring pushes to your application, or your application polls the external system for its current values. Either way, once your application has the values of its measurement, you can prepare to send it to Senfi's MQTT endpoint.
 
−
 
 
−
==== MQTT Endpoint ====
 
−
; Host: mqtt.senfi.io
 
−
; Port: 1883
 
−
; Username: ''<Your integration key>''
 
−
; Password: ''<Your integration secret>''
 
−
; MQTT topic: ingestor/1/0/live/text/array/ems/''<your integration key>/<your measurement code>''
 
−
 
 
−
==== Message Format ====
 
−
The message body should be in valid [https://www.json.org/ JSON] format.
 
−
 
 
−
Single measurement
 
−
  {
 
−
    "data": [
 
−
      {
 
−
        "tm_source": xxxxxxxxxx,
 
−
        "site_id" xxxxxxxx,
 
−
        "tag1": "xxxxxxxx",
 
−
        "tag2": "xxxxxxxx",
 
−
        "metric1": xxxxxxxxx,
 
−
        "metric2": xxxxxxxxx
 
−
        ...
 
−
      }
 
−
  }
 
−
 
 
−
Multiple measurements
 
−
  {
 
−
    "data": [
 
−
      {
 
−
        "tm_source": xxxxxxxxxx,
 
−
        "site_id" xxxxxxxx,
 
−
        "tag1": "xxxxxxxx",
 
−
        "tag2": "xxxxxxxx",
 
−
        "metric1": xxxxxxxxx,
 
−
        "metric2": xxxxxxxxx
 
−
        ...
 
−
      },
 
−
      {
 
−
        "tm_source": xxxxxxxxxx,
 
−
        "site_id" xxxxxxxx,
 
−
        "tag1": "xxxxxxxx",
 
−
        "tag2": "xxxxxxxx",
 
−
        "metric1": xxxxxxxxx,
 
−
        "metric2": xxxxxxxxx,
 
−
        ...
 
−
      }
 
−
    ]
 
−
  }
 
−
 
 
−
You must indicate which [[V2/Concepts/Site|Site]] the measurement is meant for. Hence, you need to include the site ID (site_id) in your MQTT message. If your measurement has other tags, you must send them in the message as well.
 
−
 
 
−
<div class="important">Note: '''All''' tags and metrics must be sent in your message body, or they will be treated as invalid data and discarded.</div>
 
−
 
 
−
==== Metric Data Types ====  
 
 
Senfi supports the following data types
 
Senfi supports the following data types
 
* Float  
 
* Float  
Line 105: Line 44:
 
:Any valid JSON String is accepted.
 
:Any valid JSON String is accepted.
  
−
==== Sample Application ====
+
=== Publishing Strategy ===
−
You can take a look at [https://github.com/gelement-com/mqtt-ingestor-sample this GitHub repository] for a sample application to send data to Senfi's MQTT endpoint.
 
−
 
 
−
==== Publishing Strategy ====
 
 
You can either choose to publish data to Senfi regularly (eg. every second), or only do so upon a change in the metrics. In practice, it is recommended that you publish regularly. This is so that the system is able to tell when data has stopped coming in.
 
You can either choose to publish data to Senfi regularly (eg. every second), or only do so upon a change in the metrics. In practice, it is recommended that you publish regularly. This is so that the system is able to tell when data has stopped coming in.
  
−
In addition, you can choose to batch the sending of measurements to Senfi. For example, collect 50 measurements and then publish it in a single message. This may be useful if you have fast changing metrics. However, note that tm_source should represent when the measurement is sampled and not when it is sent.
+
In addition, you can choose to batch the sending of measurements to Senfi. For example, collect 50 measurements and then publish it in a single message. This may be useful if you have fast changing metrics. However, note that tm_source (see [[V2/Integrate/Others/MQTT#Message Format|Message Format]]) should represent when the measurement is sampled and not when it is sent.

Latest revision as of 17:50, 9 May 2022

Implementing a connector

Senfi monitors and stores time series data from your existing systems. At the moment, Senfi provides two methods of receiving data from your systems:

Supported Metric Data Types

Senfi supports the following data types

  • Float
  • Integer
  • Boolean
  • String
Float
Only valid JSON Number is accepted.
  • 0
  • 0.1
  • 1.0e+10
Invalid examples:
  • 1.0.0
  • "1.0"
Integer
Only valid JSON Number is accepted. Decimal values are truncated.
  • 0
  • -15
  • 1e10
Invalid examples:
  • Same as Float
Boolean
Only JSON Boolean is accepted.
  • true
  • false
Invalid examples:
  • "true"
  • "FALSE"
  • 0
  • "1"
String
Any valid JSON String is accepted.

Publishing Strategy

You can either choose to publish data to Senfi regularly (eg. every second), or only do so upon a change in the metrics. In practice, it is recommended that you publish regularly. This is so that the system is able to tell when data has stopped coming in.

In addition, you can choose to batch the sending of measurements to Senfi. For example, collect 50 measurements and then publish it in a single message. This may be useful if you have fast changing metrics. However, note that tm_source (see Message Format) should represent when the measurement is sampled and not when it is sent.

Retrieved from "https://www.senfi.io/docs/index.php?title=V2/Integrate/Others&oldid=3760"