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.

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 sent 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. If you are unable to work with the default API payload format you can write your own custom JavaScript payload conversion function using inbound connectors.

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 an MQTT client the following configuration can be used:

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. See our HTTP API docs for all the details about the expected format of the message body. This is exactly similar for MQTT. If you are unable to work with the default payload format you can write your own custom JavaScript payload conversion function using inbound connectors.

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 using your default MQTT inbound connector configuration in your project settings.

This is an example of a valid message:

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

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 non-empty 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"
  }
}

When you remove a property value, either from a subject or entirely, a message containing an empty string will be produced. Take note that in the end this information is cleaned up, so when you resubscribe, it might not be sent as a retained message anymore and the topic might no longer be there.

CoAP

BETA Constrained Application Protocol (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:

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"

Inbound connectors

Inbound connectors are custom integrations to ingest measurements into the Blockbax Platform. This is very useful when the payload format is different from the standard integrations. A payload conversion script is defined as a plain JavaScript function. An overview of all the configuration possibilities via the web client can be found in the project settings section of this documentation.

Besides the payload content and format, the setup for sending data is similar to the respective standard integrations for HTTP, MQTT and CoAP except for the endpoint (in case of HTTP or CoAP) or topic (in case of MQTT). Based on the protocol of your inbound connector these are as follows:

Integration templates

Inbound connectors can also be configured from a integration template. To make integrating with Blockbax as easy as possible we provide integration templates that can integrate any available third party platform or device with a few clicks. We use integration templates in most of our connection guides.

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 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. View docs
	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. View docs

Connection guides

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

• connectivity platforms and networks
• automation protocols
• device gateways and platforms
• sensors
• generic payload formats
• streaming platforms
• external data providers

Connectivity platforms and networks

Network	Description
	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 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 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 operates its own end-to-end low-power wide area network (LPWAN). You can easily integrate the Sigfox Backend to the Blockbax Platform. View tutorial
	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. View tutorial
	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. View tutorial
	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 protocols are typically connected to our platform via gateways and/or special-purpose software of which some are featured in the section below.

Device gateways and platforms

Gateway	Description
	BACE IoT Platform by Evalan is an IoT building block to manage your devices in the cloud. From the BACE Cloud you can ingest measurements in Blockbax with a few clicks. View tutorial
	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. View tutorial
	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. View tutorial
	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. View tutorial
	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. View tutorial
	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). View tutorial

Sensors

Manufacturer	Description
	Airthings offers devices used for radon and indoor air quality monitoring. View tutorial
	Aranet offer wireless sensors and a IoT ecosystem for indoor, horticulture, livestock and retail monitoring. View tutorial
	Digital Matter offers a large portfolio of LPWAN, integration-ready and battery-powered asset tracking devices across a range of connectivity technologies. View tutorial
	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). View tutorial
	Milesight offers a variety of indoor and outdoor LoRaWAN Environment Monitoring Sensors. View tutorial
	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. View tutorial

Generic payload formats

Streaming platforms

Platform	Description
	Apache Kafka is an open-source distributed event streaming platform for high-performance data pipelines. You can easily setup integrations to let your data flow in and out of Kafka. View tutorial
	Amazon Kinesis is a fully managed platform for streaming data on Amazon Web Services. You can easily setup integrations to let your data flow in and out of Kinesis. View tutorial
	Azure Event Hub is a fully managed platform for streaming data on Azure. You can easily setup integrations to let your data flow in and out of Azure Event Hub. View tutorial
	Besides the MQTT API which can be used to integrate MQTT clients, our platform can also directly connect with an MQTT broker. You can easily setup integrations to let your data flow in and out of an MQTT broker. View tutorial

External data providers

Provider	Description
	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.

Embed charts

Sometimes it can be helpful to show charts with your measurement data on another web page. Our Embed API offers a convenient way to render interactive charts on any web page. See for example the chart below, which displays real-time data from a Blockbax project. If you want to learn how to embed charts on your own web page, refer to the Embed API documentation.

SSO

ENTERPRISE Manage user access centrally through your preferred identity provider (IDP). We currently support integrating using the SAML 2.0 protocol which is supported by most IDPs. Just-in-time (JIT) provisioning is enabled by default. This means that user accounts are created the first time users successfully log in to the Blockbax Platform through an IDP. In order to help you get started quickly we created the following guides:

IDP	Description
	Azure Active Directory (Azure AD) is a cloud-based identity and access management service. You can easily setup by using our prebuilt template from the Azure AD Gallery. View tutorial
	Okta Single Sign-On is a secure cloud-based single sign-on solution that can be used to easily setup SSO for everybody in your organization. View tutorial