MQTTKit application

About

A generic distributed monitoring platform for collecting sensor data in wide area network setups and multi-node, multi-sensor environments ¹.

It emphasizes MQTT as communication protocol and JSON as data serialization format but implements different other protocols and formats.

Configuration

Application section

The core of each data acquisition application is its configuration object. The file etc/examples/mqttkit.ini can be used as a configuration blueprint.

This configuration snippet will create an application object defined as [mqttkit-1].

 1; ------------------------------------------
 2; Name:     mqttkit
 3; About:    A generic distributed monitoring platform for
 4;           collecting sensor data in wide area network setups.
 5; Channel:  Transport: MQTT over TCP; Format: JSON
 6; Storage:  InfluxDB
 7; See also: https://getkotori.org/docs/handbook/configuration/mqttkit.html
 8; ------------------------------------------
 9
10[mqttkit-1]
11enable      = true
12type        = application
13realm       = mqttkit-1
14mqtt_topics = mqttkit-1/#
15application = kotori.daq.application.mqttkit:mqttkit_application

Multiple MQTT brokers

It is possible to make Kotori connect to an individual MQTT broker per application. On behalf of this example, you would create a separate configuration section [mqttkit-1:mqtt], where mqttkit-1 reflects the value of the realm attribute of the main application settings section.

 1[mqttkit-1]
 2enable      = true
 3type        = application
 4realm       = mqttkit-1
 5mqtt_topics = mqttkit-1/#
 6application = kotori.daq.application.mqttkit:mqttkit_application
 7
 8# How often to log metrics
 9metrics_logger_interval = 60
10
11# [mqttkit-1:mqtt]
12# ; Configure individual MQTT broker for this application.
13# ; The option group prefix `mqttkit-1` reflects the value of
14# ; the `realm` attribute of the application settings.
15# host        = mqtt.example.org
16# port        = 1883
17# username    = foobar
18# password    = secret

Addressing

To successfully publish data to the platform, you should get familiar with the MQTTKit addressing scheme. We call it the »quadruple hierarchy strategy« and it is reflected on the mqtt bus topic topology.

The topology hierarchy is made up of four identifiers:

realm / network / gateway / node

The realm will be configured within the server configuration file while all other parameters designate the data acquisition channel and can be assigned by the user.

The topology identifiers are specified as:

  • “realm” is the designated root realm. You should prefix the topic name with this label when opting in for all features of the telemetry platform.

  • “network” is your personal realm, it designates the owner. Choose anything you like or use an Online UUID Generator to gain maximum uniqueness.

  • “gateway” is your gateway identifier, it designates a sensor node location or group. Choose anything you like.

  • “node” is your node identifier. Choose anything you like. This usually gets transmitted from a sensor device.

In the following examples, this topology address will be encoded into the variable CHANNEL.

Sending data

In the following examples, the topology address will be encoded into the variable CHANNEL.

# Define channel and data.
CHANNEL=mqttkit-1/testdrive/foobar/42
DATA='{"temperature": 42.84, "humidity": 83.1}'

# Publish telemetry data to MQTT topic.
echo "$DATA" | mosquitto_pub -t $CHANNEL/data.json -l

Receiving data

# Receive telemetry data by subscribing to MQTT topic
mosquitto_sub -t mqttkit-1/#

¹ The design of MQTTKit is derived from vendor Hiveeyes.