Documentation

Integrations

Integrations are needed in order to let your data flow in and out of the platform. Blockbax exposes its complete functionality through programming interfaces (APIs). This means that all of the platform’s functionality is available for you to use in different contexts outside of what we directly provide – in your own applications, in your own devices.

Most importantly you want to make sure your sensor data continuously flows into the platform by connecting your devices to our APIs. A wide range of (device) connection guides is available to help you get started quickly. Another important use case is to build custom user-facing applications on top of our platform or synchronizing reference data (such as data from asset management, ERPs, GISs, PLM software, etc.). Applications can either request data using the HTTP API or receive events in real-time via webhooks.

APIs

Blockbax exposes its complete functionality through programming interfaces (APIs). This means that all of the platform’s functionality is available for you to use in different contexts outside of what we directly provide – in your own applications, in your own devices. Our main API is an HTTP API which provides full programmatic access to all the platforms operations. Furthermore there is a MQTT API and a CoAP API which are more focused on device connectivity for sending measurements and/or subscribing to property updates for changing device settings.

Important note about measurement time

We discourage rewriting history as it can become hard to trace why something led to an event. In order to achieve this we recommend that subjects have a strict increasing time order over measurements being sent to the platform. On a series level we go one step further and enforce this time order. We also disallow sending measurements with a future timestamp as timestamps in the distant future could effectively render a series unusable as history can never be rewritten.

To be specific, a measurement is marked invalid when:

  • The timestamp is identical (exact same timestamp in milliseconds) within a series.
  • The timestamp is older compared to the latest measurement within a series.
  • The timestamp is more than an hour in the future.

These best practices and requirements prevent scenarios where old measurements coming in would be able to invalidate an event. As an event could already led to e-mails and webhook calls, invalidating would become highly impractical and hard to follow.

The following example of messages describes how this works in practice:

Message order Series Measurement timestamp Validity
1 Temperature of subject #1 2019-05-11, 09:15 Valid
2 Temperature of subject #1 2019-05-11, 09:17 Valid
3 Temperature of subject #1 2019-05-11, 09:16 Invalid
4 Humidity of subject #1 2019-05-11, 09:15 Valid, but not recommended
5 Temperature of subject #1 2019-05-11, 09:18 Valid

Important to note is that in the example each measurement is sent as a separate message. Better is to make smart use of batching measurements. Within a single message the platform fixes the sorting for you. In this way, when you batch the measurements of all metrics for each subject and one or multiple timestamps, you are able to achieve strict increasing time order per subject. In the example this would mean that at least the first and the fourth message would be batched in the same message.

The platform filters out the invalid measurements but invalid measurement will count for your usage statistics. Make sure you avoid sending invalid measurements to prevent unpleasant surprises in your usage details.

HTTP

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.

A major use case of the API is sending measurements. 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 relevant section of the API documentation.

Another important use case is to build custom user-facing applications on top of our platform or synchronizing reference data (such as data from asset management, ERPs, GISs, PLM software, etc.).

MQTT

MQTT is a reliable, lightweight protocol with a small code and network bandwidth footprint. The platform provides a native integration to publish measurements and subscribe to property updates (e.g. for updating device settings) over MQTT. In order to connect a MQTT client the following configuration can be used:

Property Value
Broker host mqtt.blockbax.com
Port number 8883 (default secure MQTT port)
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. Only one connection is allowed per client ID, when a connection is attempted with another open connection it is refused until the open connection is properly closed or times out after five seconds.
Publishing measurements

Measurements are send to Blockbax by using the connected client to publish on the topic v1/projects/<YOUR_PROJECT_ID>/measurements. Note that your project ID can be found in the URL when you open your project in the web app, e.g. app.blockbax.com/projects/40edc099-7a41-4af3-9fa4-2fa4ac23a87a/.

Messages need to be a JSON UTF-8 encoded string and need to contain a series with 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, the series field needs to contain one or more measurements with the date (as epoch timestamp in milliseconds or as ISO 8601 date string) and a number, location or text value (up to a 100 characters, additional characters will be stripped of). Providing a date is optional and the maximum supported date is 9999-12-31 23:59:59.999 UTC. If no date is provided the receive time of the server will be used.

Blockbax can also automatically create subjects when the ingestion ID is derived from the subject and metric external IDs. When the posted ingestion ID is composed of a known metric external ID that is linked to only one subject type and an unknown subject external ID it creates the subject. You can turn this functionality on or off by setting the autoCreateSubjects field to True or False. If the field is empty this option defaults to False.

This is an example of a valid message:

{
  "autoCreateSubjects" : true,
  "series": [
    {
      "ingestionId": "MyHouse$LivingRoomTemperature",
      "measurements": [
        {
          "date": "2021-01-09T12:00:00.000+00:00",
          "number": 20.3
        }
      ]
    },
    {
      "ingestionId": "MyCar$Location",
      "measurements": [
        {
          "date": 1609502400000,
          "location": {
            "lat": 51.9250768,
            "lon": 4.4735718,
            "alt": 12.1
          }
        }
      ]
    },
    {
      "ingestionId": "MyCar$Status",
      "measurements": [
        {
          "date": "2021-01-09T12:00:00.000+00:00",
          "text": "LowTirePressureAlarm"
        }
      ]
    }
  ]
}
Subscribing to property updates

The connected client can consume properties for one or multiple subjects, to do this you can either subscribe to a specific subject and property combination or use wildcards, denoted with a + symbol, to subscribe to multiple properties or subjects simultaneously. For subscribing to single properties and/or properties you can use your own configured external IDs. This way clients can use their own naming instead of having to know which IDs are used internally by the Blockbax Platform. The topics that can be used are listed below:

  • To subscribe to a specific property and subject combination use: v1/projects/<YOUR_PROJECT_ID>/subjects/<YOUR_SUBJECT_EXTERNAL_ID>/properties/<YOUR_PROPERTY_TYPE_EXTERNAL_ID>
  • To subscribe to all properties of a single subject use: v1/projects/<YOUR_PROJECT_ID>/subjects/<YOUR_SUBJECT_EXTERNAL_ID>/properties/+
  • To subscribe to a single property for all subjects use: v1/projects/<YOUR_PROJECT_ID>/subjects/+/properties/<YOUR_PROPERTY_TYPE_EXTERNAL_ID>
  • To subscribe to all properties for all subjects use: v1/projects/<YOUR_PROJECT_ID>/subjects/+/properties/+

Note that your project ID can be found in the URL when you open your project in the web app, e.g. app.blockbax.com/projects/40edc099-7a41-4af3-9fa4-2fa4ac23a87a/

Important note about wildcards and permissions

You can only make use of wildcards if you use an access token with read access to all properties and/or subjects.

Important note about topics

MQTT topics restrict the use of the following symbols: #, /, + and spaces. If your external subject ID or your external property type ID contains one of these symbols the topics can not be created, so you can not receive property updates for these resources.

Messages consumed by the connected client are JSON UTF-8 encoded strings and contain either a text, number or a location value (see examples below). The latest message per topic is retained by our MQTT broker such that upon connection the client receives the latest property value. Additionally you must design your system in such a way that it automatically reconnects and it can cope with receiving the same update twice (at-least-once delivery semantics). A message can be delivered one or more times due to network problems, rolling broker restarts and the asynchronous nature of the platform.

This is an example of a message containing text:

{
  "text": "Rotterdam"
}

This is an example of a message containing a number:

{
  "number": 10
}

This is an example of a message containing a location:

{
  "location": {
    "lat": "52.37403",
    "lon": "4.88969",
    "alt": "-3.2"
  }
}

CoAP

The Constrained Application Protocol (CoAP) integration is Beta. CoAP is a simple protocol with low overhead, designed for devices with constrained resources such as wireless sensors operating on a battery. The Blockbax Platform provides a native integration to publish measurements over CoAP. To connect your CoAP device the following configuration can be used:

Property Value
CoAP server URL coaps://coap.blockbax.com
Port number 5684 (default CoAP port)
Protocol Only DTLS version 1.2 connections are accepted. Note: DTLS is based on TLS 1.2 but uses UDP instead of TCP. No certificates or pre-shared keys need to be configured for the client. We use one-way authentication using X509 certificates.
URL Path /v0/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/40edc099-7a41-4af3-9fa4-2fa4ac23a87a/
Request method POST
Content type application/json
Query parameters apiKey=<ACCESS_TOKEN_SECRET>. Note: Your ACCESS_TOKEN_SECRET is the secret of your access token.

The body of the POST request is identital to the HTTP API. An example can be found in the HTTP API documentation.

An example of a valid request using the libcoap CLI client looks like as follows:

coap-client -m post -t "application/json" -f ./measurements.json "coaps://coap.blockbax.com/v0/projects/40edc099-7a41-4af3-9fa4-2fa4ac23a87a/measurements?apiKey=dYNpZq48BwBiCfdAmeDzFMRLv9HtyaSg"

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 via the web client can be found in the project settings section of this documentation. Another option is to configure webhooks programmatically via our HTTP API. The message coming from the webhook looks like this:

{
  "sequenceNumber": 25618,
  "deliveryAttempt": 1,
  "eventId": "06811617-4836-48d1-a09b-42e624db9ekg",
  "eventTriggerId": "cb99d792-e994-4a18-bf75-5d39f09d7ekg",
  "eventTriggerVersion": 10,
  "eventLevel": "WARNING",
  "subjectId": "ad55bc6a-094c-4f6b-9cfe-871168cfeekg",
  "date": "2019-09-17T09:33:15.075+0000"
}

Retry logic

In case a call fails (due to receiving a non-2xx response code or exceeding timeout of 5 seconds), we will try 4 more times: after 5 seconds, 1 minute, 5 minutes and 15 minutes. If it still fails for each of those attempts, it is counted as a non-successful delivery. To make this transparent to the receiving system all messages contain the field deliveryAttempt which can be used to monitor at which delivery attempt the call was received. If no retries were needed deliveryAttempt is equal to 1. Retrieving calls that failed, for example to reprocess them after a long period of downtime, can be done programmatically via our HTTP API.

Ordering guarantees

Date ordering is guaranteed for all events related to a specific event trigger and subject. We enforce that calls are made in the right order, however the order of receiving can differ due to network problems and the asynchronous nature of the platform. To make this transparent to the receiving system all messages contain an incrementing sequenceNumber which can be used to derive the order in which messages were sent.

SDKs

Currently there are two SDKs available to speed up and ease the integration with Blockbax:

SDK Description
Node-RED Node-RED is an open-source visual programming tool for wiring together various protocols. A large range of community build nodes (i.e. plugins) are available for various protocols (including Modbus, OPC UA/DA, BACnet, CAN bus and M-Bus). We provide a set of Blockbax nodes to easily interact with our platform via Node-RED.
Python The Python SDK enables developers to speed up and ease the integration with Blockbax. It makes interfacing with our HTTP API even easier where you can easily get, create, update and delete resources without the intricacies of having to deal with HTTP requests and responses.

Connection guides

A wide range of connection guides is available to help you get started quickly. Technologies can range from:

If there is no guide for your device, protocol or platform we are always happy to help out and/or extend our docs, just contact us.

Connectivity platforms and networks

Network Description
3G/4G/5G 3G, 4G or 5G are standards for cellular networks. Devices on these networks can reach our platform’s APIs directly. Possibly your device is covered in one of the other guides.
LTE-M LTE-M is a type of low-power wide area network (LPWAN). The advantage of LTE-M over NB-IoT is its comparatively higher data rate and mobility, but it requires more bandwidth and is more costly. Devices on these networks can reach our platform’s APIs directly. Possibly your device is covered in one of the other guides.
NB-IOT NB-IoT is a type of low-power wide area network (LPWAN). The advantage of NB-IoT over LTE-M is it requires less power and is cheaper, but it has a lower data rate and is only suitable for devices on a fixed location. Devices on these networks can reach our platform’s APIs directly, especially our CoAP API is recommended because of the relatively low data rate. Possibly your device is covered in one of the other guides.
Sigfox Sigfox operates its own end-to-end low-power wide area network (LPWAN). You can easily integrate the Sigfox Backend to the Blockbax Platform.
The Things Network The Things Network is a LoRaWAN connectivity provider. LoRaWAN is also a low-power wide area network (LPWAN). We integrate seamless with their core product the LoRaWAN Network Server.
The Things Industries The Things Industries is a LoRaWAN connectivity provider. LoRaWAN is also a low-power wide area network (LPWAN). We integrate seamless with their core product the LoRaWAN Network Server.
WiFi On WiFi (WLAN, or just LAN) connected to the Internet devices can reach our platform’s APIs directly. Possibly your device is covered in one of the other guides.

Automation protocols

Automation protocols used for the automation of processes (industrial or otherwise), such as for building automation, power-system automation, automatic meter reading, and vehicular automation encompass a large spectrum. Examples of typical protocols connected to our platform are OPC UA (or it predecessor OPC DA), Modbus (over TCP, RS485, RS232 or Profibus), BACnet, CAN bus, M-Bus, etc. These protocol are typically connected to our platform via gateways and/or special-purpose software of which some are featured in the section below.

Edge gateways and software

Gateway Description
Kepware KEPServerEX We integrate seamlessly with Kepware (part of PTC) its main product KEPServerEX. KEPServerEX can be used to connect (mainly over OPC) and control diverse automation devices and software applications.
Milesight gateways Milesight LoRaWAN gateways are easy to install and setup. With minimal effort you can setup your own LoRaWAN network to connect your devices to. When combining Node-RED with our Node-RED SDK on their gateways you can connect a LoRaWAN sensor within minutes.
Option CloudGate Gateways Option CloudGate gateways are set up in a modular way to support a wide range of networks (such as 3G, LoRaWAN, NB-IoT and LTE-M), sockets (such as ethernet, RS232/RS485, analog or digital IOs, I2C, CAN or USB) and protocols (such as BACnet, CAN bus, Modbus and M-Bus). It has active GPS and comes with Luvit-RED for edge computing, which works similarly to Node-RED. Luvit-RED can be used to configure local processing for instance to handle some event rule logic locally or pre-aggregate data before sending it to the Blockbax Platform.
Siemens RUGGEDCOM RX1400 Siemens RUGGEDCOM portfolio is designed specifically for applications in the harshest environmental conditions. The RUGGEDCOM RX1400 is a multi-protocol intelligent node which combines Ethernet switching, routing and application hosting capabilities with various connectivity options (such as 3G, 4G and WiFi). It has multiple ways of accessing data within a network or with serial interfaces. Via its Application Communication Engine it can serve as interface between the Blockbax Platform and protocols such as IEC 61850, Modbus and DNP3.
Teltonika Gateways Teltonika Networks gateways can be connected over Ethernet, 4G, LTE-M or NB-IoT. It can directly connect Modbus devices to the Blockbax Platform (via Ethernet, RS232, RS485 or I/O interfaces).

Sensors

Manufacturer Description
Airthings Airthings offers devices used for radon and indoor air quality monitoring.
Digital Matter Digital Matter offers a large portfolio of LPWAN, integration-ready and battery-powered asset tracking devices across a range of connectivity technologies.
Janitza Janitza has a wide range of energy and power monitoring sensors. These sensors help you gain a comprehensive overview of your energy supplies and introduce widely accepted measures and standards (e.g. EN50160 for power quality).
Milesight Milesight offers a variety of indoor and outdoor LoRaWAN Environment Monitoring Sensors.
Pressac Pressac offers a wide range of smart building sensors for sensing occupancy, environment and energy. With their smart IoT sensor technology you can measure, monitor and detect changes in a building’s environment and assets, and send near real-time data to the Blockbax Platform. They’re easy to install and can be connected to Blockbax using the Blockbax Node-RED SDK.

Streaming platforms

Platform Description
Apache Kafka Apache Kafka is an open-source distributed event streaming platform for high-performance data pipelines. We can easily setup integrations to let your data (such as measurements) flow in and out of Kafka. Currently this can only be configured by us, contact us if you want us to set this up for you.
AWS Kinesis Amazon Kinesis is a fully managed platform for streaming data on Amazon Web Services. We can easily setup integrations to let your data (such as measurements) flow in and out of Kinesis. Currently this can only be configured by us, contact us if you want us to set this up for you.
Azure Event Hub Azure Event Hub is a fully managed platform for streaming data on Azure. We can easily setup integrations to let your data (such as measurements) flow in and out of Azure Event Hub. Currently this can only be configured by us, contact us if you want us to set this up for you.
MQTT message brokers Besides the MQTT API which can be used to integrate MQTT clients, our platform can also directly connect with an MQTT broker. We can easily setup integrations to let your data (such as measurements) flow in and out of an MQTT broker. Currently this can only be configured by us, contact us if you want us to set this up for you.

External data providers

Provider Description
OpenWeather OpenWeather provides weather data for each point on the globe. This data can be used to enrich your subjects with location-aware metrics for historical, current and forecasted weather data. Of course these metrics can also be used as inputs for your calculated metrics and event triggers. Currently this can only be configured by us, contact us if you want us to set this up for you.