Documentation.

Integrations.

You need to set up an integration in order to let your data flow in and out of the platform. Most importantly you want to make sure your sensor data continuously flows into the platform. Additionally you may have other systems, like a work order management system, that you want to integrate. To achieve this you can make use of our HTTP API, receive events in real-time via webhooks or you can use our built-in connectors for a range of commonly used technologies.

Sending measurements

There are multiple ways of sending measurements. Measurements can be sent in batches over HTTP or can be streamed over MQTT. Another option is to install the agent in your own environment which can read several commonly used protocols (like OPC, BACnet, Modbus or I²C).

HTTP

Batches of up to 500 measurements can be send via our HTTP API. To map measurements to subjects and metrics you can specify your own IDs. We call these ingestion IDs, by default these are derived from the subjects’ external IDs and metrics’ external IDs (e.g. subjectExternalId$metricExternalId) but you can also override these with custom ones. More information can be found in the API documentation.

MQTT

MQTT is a reliable, lightweight protocol with a small code and network bandwidth footprint. The platform provides a native MQTT integration to publish individual measurements over MQTT. In order to connect a MQTT client the following properties need to be set as follows:

Property Value
Broker host mqtt.blockbax.com
Port number 8883
Protocol Only TLS version 1.2 connections are accepted.
Username The public ID of your access token.
Password The secret of your access token.
Client ID Must be prefixed with the public ID of your access token.
Topic v1/projects/<YOUR_PROJECT_ID>/measurements
Note: Your project ID can be found in the URL when you open your project in the
web app, e.g. app.blockbax.com/projects/22a0e61c-2209-454c-b8ad-fcebf4341caf/

Messages need to be a JSON UTF-8 encoded string and need to contain the ingestion ID, either derived from the subject’s external ID and metric’s external ID (e.g. subjectExternalId$metricExternalId) or a custom one that has been defined. Additionally, it needs to contain one or more measurements with the date as unix (epoch) timestamp in milliseconds and a value. Providing a date is optional. If no date is provided the receive time will be used. This is an example of a valid message:

{
  "series": [
    {
      "ingestionId": "Pump1$Mode",
      "measurements": [
        {
          "date": 1563049273812,
          "value": 1.356
        }
      ]
    }
  ]
}

Edge Agent

Another option to connect your sensor data is to install and configure the Blockbax Edge Agent. Our Agent is a lightweight reader and transforms measurements, often written in an industry specific protocol, to JSON and sends it over MQTT to our platform. The agent can be installed with one click on a Windows or Linux machine and is easy to configure. And, most important, it does not infringe on the existing OT infrastructure.

Supported protocols

We constantly improve and update the protocols that are implemented in the Edge Agent and we are working on support for other industry specific standards, like BACnet, Modbus, CANbus and I²C. Currently implemented:

Protocol Description
OPC DA OPC Data Access (OPC DA) is a protocol used for communicating real-time data from devices mainly in industrial automation like for example PLCs, HMIs or SCADA systems.
OPC UA OPC Unified Architecture (OPC UA) is OPC DA’s successor.
Configuring the Edge Agent

The configuration of the Edge Agent is pretty straight forward. Download the Agent and you will find a configuration file where you need to fill in several input fields. What you have to fill in depends on the source protocol (e.g. OPA-DA), but there is always some Blockbax specific information you have to fill in.

OPC-DA configuration

Add the right values to the configuration file so the Agent can process the OPC-DA measurements, transform them to JSON and send them over MQTT to the platform.

Configuration field Description
Project ID Your project ID can be found in the URL when you open your project in the web app e.g. app.blockbax.com/projects/22a0e61c-2209-454c-b8ad-fcebf4341caf/
Public ID The public part of the access token
Secret The secret part of the access token
Server_address UA server IP address and port in the for example opc.tcp://localhost:49320
Prog_id DA server Program ID
Poll_frequency_sec Frequency of data readings per second
Item_id The unique item (or node) on the OPC server
Ingestion_id The ID as it will be used in the platform to map measuremnts to the right subject and metric.

Example of a OPC-DA configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
blockbax:
  project_id: "22a0e61c-22h9-454c-b8ad-fcebf4341ekg"
  access_token:
    public_id: "x9pwRj36"
    secret: "tqxOISYvyUNa6wMHTTafV4du03LN0fyA"

opc_da: 
  server_address: "opc.tcp://localhost:49320"
  prog_id: "PDA00123"
  poll_frequency_sec: 1
  tags:
    - item_id: "ns=2;s=Channel1.Device1.Sinus1"
      ingestion_id: "pump1$sinus1"
    - item_id: "ns=2;s=Channel1.Device1.Ramp1"
      ingestion_id: "pump1$ramp1"


OPC-UA configuration

Add the right values to the configuration file so the Agent can process the OPC-UA measurements, transform them to JSON and send them over MQTT to the platform.

Configuration field Description
Project ID Your project ID can be found in the URL when you open your project in the web app e.g. app.blockbax.com/projects/22a0e61c-2209-454c-b8ad-fcebf4341caf/
Public ID The public part of the access token
Secret The secret part of the access token
Server_address UA server IP address and port in the for example opc.tcp://localhost:49320
Cert_file Path to the certification file. This must be a .cert file.
Key_file Path to the key file. This must be a .cert file.
Poll_frequency_sec Frequency of data readings per second
Mode The OPC-UA mode
Policy The OPA-UA policy
Type Subscribe
Item_id The unique item (or node) on the OPC server
Ingestion_id The ID as it will be used in the platform to map measuremnts to the right subject and metric.

Example of a OPC-UA configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
blockbax:
  project_id: "22a0e61c-22h9-454c-b8ad-fcebf4341ekg"
  access_token:
    public_id: "x9pwRj36"
    secret: "tqxOISYvyUNa6wMHTTafV4du03LN0fyA"

opc_ua: 
  server_address: "opc.tcp://localhost:49320"
  cert_file: "blockbax-certification.cert"
  key_file: "blockbax-key.cert"
  poll_frequency_sec: 1
  mode: "None"
  policy: "Basic256"
  type: "subscribe"
  tags:
    - item_id: "ns=2;s=Channel1.Device1.Sinus1"
      ingestion_id: "pump1$sinus1"
    - item_id: "ns=2;s=Channel1.Device1.Ramp1"
      ingestion_id: "pump1$ramp1"

Connecting your apps

You may have other systems, like a work order management system, that you want to integrate. To achieve this you can make use of our HTTP API. Additionally webhooks can be used to receive events in real-time.

HTTP API

The main Blockbax API is a HTTP API which provides programmatic access to all the platforms operations. This part of the documentation is described in a a different section and requires knowledge of HTTP API concepts. In the case of our API this means the URLs are resource-oriented and HTTP status codes are used to indicate success or failure. Data returned from our API will be in JSON format for all requests.

More info can be found in the separate API documentation.

Webhooks

Webhooks are developed to send events to your application(s) in real-time. You can see it as a reversed API: provide your endpoint and the platform makes sure you get the events you are interested in once they occur. The configuration possibilities can be found in the project settings section of this documentation. The message coming from the webhook looks like this:

{
  "id": "06811617-4836-48d1-a09b-42e624db9ekg",
  "eventTriggerId": "cb99d792-e994-4a18-bf75-5d39f09d7ekg",
  "eventTriggerVersion": 10,
  "eventLevel": "WARNING",
  "subjectId": "ad55bc6a-094c-4f6b-9cfe-871168cfeekg",
  "metricId": "ekgc853c-2e61-494e-ba35-d2de3ff75581",
  "date": "2019-09-17T09:33:15.075+0000"
}