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 to connect to the Blockbax MQTT server:

Inbound connectors

Inbound connectors are integrations to ingest measurements into the Blockbax Platform. In the case of MQTT, there is a default connector that can be reached by connecting to Blockbax and publishing on the following topic:

v1/projects/<YOUR_PROJECT_ID>/measurements

This topic expects measurements in the format described in our API reference documentation.

If the payload format is different from the default format, you can use a custom inbound connector. A custom inbound connector has a payload conversion script that is defined as a plain JavaScript function. A dedicated page about payload conversion describes how to develop such a function. This also allows you to log certain things about your payload. A custom inbound connector can be reached on the following topic:

v1/projects/<YOUR_PROJECT_ID>/inboundConnectors/<INBOUND_CONNECTOR_ID>/measurements

In addition to a push-based connector where you publish measurements to Blockbax on a certain topic, it is also possible to define a pull-based MQTT connector. This will stream measurements from an external MQTT broker into Blockbax

The following configuration options are available:

Auto-create subjects

Measurements are mapped to subjects and metrics by so-called ingestion IDs. By default, an ingestion ID is derived from the subjects’ external ID and the metrics’ external ID (e.g. MyCar$Location). You can also override this default with a custom ingestion ID. If a measurement with an unknown ingestion ID is encountered, Blockbax tries to find a single metric with an external ID equal to the part after the dollar sign. If this is successful, a subject will be created with an external ID equal to the part before the dollar sign. For example, for the ingestion ID MyCar$Location a subject with external ID MyCar will be created if the metric with external ID Location can be linked to exactly one subject type.

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.

Outbound connectors

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:

1
2
3

{
  "text": "Rotterdam"
}

This is an example of a message containing a number:

1
2
3

{
  "number": 10
}

This is an example of a message containing a location:

1
2
3
4
5
6
7

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

Connection guide

Here you can find the information to help you get started quickly with this integration. In this tutorial we use the HiveMQ as an example. This guide should be usable for self-hosted or other managed MQTT brokers as well, in case you need help contact us.

Stream measurements from HiveMQ to Blockbax

Several steps in both HiveMQ and Blockbax are needed to get the data from your MQTT broker to Blockbax.

1. In HiveMQ’s access management create credentials to subscribe to the (part) the required topic(s) or with a generic ‘Subscribe Only’ permission. Copy the settings, you need it in the following step.
2. Create an inbound connector for MQTT in Blockbax and choose ‘MQTT subscribe’ as protocol.
3. Validate if an info log appears that it is able to connect successfully. This can take up to 30 seconds.