ZENNER Datahub Howto: Setting up Forwardings with the Example of MQTT

1. General

To forward traffic from your own devices, the ZENNER Datahub supports three different network protocols. Depending on your own requirements and the architecture of the target system, you can choose from the following options:

• http forwarding
  • RESTful API POST to self-hosted endpoint
• MQTT
  • forwarding to self-hosted broker
  • Forwarding and subscribing to a broker provided by the platform
• AMQP
  • forwarding to self-hosted broker

2. Setting up Forwarding

The following describes how to configure the three types of forwarding within the platform and what to bear in mind when using them. Regardless of the type of forwarding, this must be set up once initially in the Management menu item under Forwarding by clicking on the “Add new forward rule” button with the access data of the end point.

2.1 Http Forwarding

2.1.1 General

The prerequisite for using http forwarding is an end point that can be reached from the Internet and has a static IP address/URL. If the forwarding rule is active, the platform sends an http POST to the stored URL for every incoming telegram. In the body of this POST there is a json object with the user data and the meta information of the reception. This is structured as follows:

Further, more in-depth meta information has been hidden in the image above for better clarity.

2.1.2 Configuration of the Platform

After clicking on “Add new forward rule” you can freely assign a desired designation in the “Name” field in the mask that opens. “HTTP” is selected as the type. Furthermore, the target URL of your own endpoint must be entered. This is made up as follows, depending on whether authentication to the endpoint is desired or not:

The forwarding must then still be activated for the desired devices (see Section 3: Assigning the Forwarding)

2.1.3 Usage Example with Flask

An easy way to use http forwarding is to set up an API endpoint with flask. With just a few lines of code, a target URL can be defined and the content of the POST body can be further processed in your own Python code. In the Python example shown, each received json document is written to a log file.

In principle, however, all options are open here – from caching, for example, in a MongoDB to triggering an action directly when a specific telegram arrives.

2.2 MQTT

2.2.1 General

If MQTT forwarding is set up, the platform publishes telegrams to a self-hosted broker or a broker provided by the platform. The user can subscribe to the respective broker as a “client”.

The messages are published with QoS 0 (at most once) – they are neither buffered nor repeated if they are not fetched by the client.

A substructure with the respective DevEUI is created for each device below the basic topic. Telegrams from the example Adeunis tester 0018B20000FFFFFF can be found under the topic:

/basic-topic/devices/0018B20000FFFFFF/up

Below this topic, a json object with the data is transmitted for each telegram received. It contains the following keys, for example:

• payload_raw: The decrypted FRMPayload – ie the user data in base64 format

• counter: Frame counter of the LoRaWAN telegram

If a parser is stored in the platform for the device under consideration, other device-specific fields are also transferred as a separate topic. With the Adeunis tester, for example the latitude and longitude parsed from the telegram.

2.2.2 Configuration of the Platform

After clicking on “Add new forward rule” you can freely assign a desired designation in the “Name” field in the mask that opens. “MQTT” is selected as the type. Furthermore, the target URL of the desired broker must be entered. This is made up as follows:

Example:
mqtt://mustermann:Passwort123@mustermannsbroker:1883?base_topic=sensor/lora

As an alternative to using your own broker, there is also the option of using a broker provided by the platform. The access data required for this can be requested via the Community Contact form, stating your own user name.

2.2.3 Subscribing to the Broker

A suitable MQTT client is required to be able to receive the messages. The settings for subscribing to the platform broker are (username and password see 2.2.2):

For example, as a client Mosquitto can be used. The following example call outputs all forwarded messages of the account:

mosquitto_sub -h mqtt.bmz.cloud -p 1883 -t “client name/#” -P “password” -u “username” -v

2.3 AMQP

2.3.1 General

If AMQP forwarding is set up, the platform publishes telegrams to a broker provided by the user, such as rabbitMQ. This must be accessible from the Internet and have a static IP address/URL.

The platform always publishes to a previously set up broker exchange. This exchange can in turn be linked to one or more queues. The data from these queues can be subscribed for further processing.

The individual telegrams are published by the platform as a json object. The objects are structured as follows:

Additional meta information has been hidden in this screenshot for clarity.

2.3.2 Configuration of the Platform

After clicking on “Add new forward rule” you can freely assign a desired designation in the “Name” field in the mask that opens. “AMQP” is selected as the type. Furthermore, the destination URL of the broker must be entered. This is made up as follows:

The forwarding must then be activated for the desired devices (see Section 3: Assigning the forwarding)

2.3.3 Subscribing to the Broker

A suitable AMQP client is required to be able to receive the messages.

For example, as a client pika can be used. The following sample Python script accepts and acknowledges all messages from the “hello” queue:

3. Assigning the Forwarding

There are two different ways to use forwarding:

3.1 Forwarding of all devices of the account

All incoming telegrams from devices within the account are forwarded. To set it up, click on “Add” under the Management/Forwarding menu item for the rule created in the previous section.

The new rule is then displayed under “Already added Forwarding Rules to this Tenant” and can be deactivated again if necessary via “Delete”.

3.2 Assign Forwarding Rules to individual Devices in the Account

As an alternative to global forwarding, the forwarding rule can also be activated for individual devices. To do this, switch from the device list to the detailed view of the desired device. In the Forwarding tab, the rule can then be activated for the respective device by clicking the “Add” button.

Existing entries are displayed under “Already added Forwarding Rules to this Device” and can be deactivated again via “Delete”.

The platform also supports authentication using “Basic Authentication”. Username and password must be transferred in the following notation: