Publish and subscribe via MQTT¶

This page contains the steps to interact with a public DSH stream, and to publish and consume messages via MQTT. The example shows how to create MQTT tokens for 2 MQTT clients:

A temperature sensor in the kitchen that can only send data to the MQTT topic house/kitchen/sensor.
A heating, ventilation and air conditioning (HVAC) system that can subscribe to all MQTT topics related to the house, with a wildcard: house/#.

You will consume messages from a public DSH stream, and publish messages to it.

Prerequisites¶

Before you can follow this tutorial, you need the following:

On the DSH:
- Access to a tenant on a DSH platform
- A public DSH stream with a steady stream of messages. Make sure that the DSH has an API client defined that has “PUB” permission and “SUB” permission on the MQTT topics for this public DSH stream.
- You can use the Kafka producer described in Publish to DSH stream to publish messages.
- The example assumes that your public stream contains messages with the MQTT topic house/kitchen/sensor.
On your machine:
- A Unix-based system, for example Linux, MacOS or Windows Subsystem for Linux
- Eclipse Mosquitto
- jq

Tip

The Messaging API and its Authentication mechanism provide more background information about interacting with the DSH via MQTT and HTTP.

Create a working directiory¶

Open the Terminal, create a directory for this tutorial, and enter it:

Terminal

mkdir mqtt-pub-sub
cd mqtt-pub-sub

Request REST tokens¶

In this step, you create the REST tokens that you will use to request MQTT tokens for the HVAC and kitchen sensor.

Tip

See REST token for detailed information about REST tokens.

In order to request REST tokens, you need to acquire the API key for the REST API client that exists on the DSH for the public DSH stream in question:

Click “Resources” > “Secrets” in the menu bar of the DSH Console.
You can find the API key in the “api-key” secret.
Click the “Inspect” button to see the secret.

It’s strongly recommended to request REST tokens with very specific claims. In this case, the REST token should only give access to a specific DSH stream, and a specific MQTT topic, for specific MQTT clients. In the sections below, you create a REST token for the sensor, and a REST token for the HVAC system.

Warning

Treat the API key as a password. It’s strongly recommended to set up your own authentication service that handles all requests for REST tokens and MQTT tokens, and to make sure that only the authentication service holds the API key. See Authentication mechanism for more information.

Sensor¶

Create the file sensor-rest-body.txt with the following contents:

rest-body.txt
{
    "tenant": "<your-tenant-name>",
    "claims": {
        "datastreams/v0/mqtt/token": {
            "id": "kitchen-sensor",
            "claims": [
                {
                    "action": "publish",
                    "resource": {
                        "type": "topic",
                        "prefix": "/tt",
                        "stream": "<public-DSH-stream-name>",
                        "topic": "house/kitchen/sensor"
                    }
                }
            ]
        }
    }
}

Fill out the correct values for the placeholders <your-tenant-name> and <public-DSH-stream-name>. If the full name of your public DSH stream is stream.getting-started, then you need to use the value getting-started.

Once you have the API key and the file in place, execute the following command in your Terminal:

Terminal

curl -X POST "https://api.<DSH-platform-name>.kpn.com/auth/v0/token" -H "apikey: <your-api-key>" -d "`cat sensor-rest-body.txt`" > sensor-rest-token.txt

The command contains the following placeholders:

<DSH-platform-name>: the name of the DSH platform that contains your tenant and the public DSH stream that you want to subscribe and publish to
<your-api-key>: the API key that you retrieved for the API client that is connected to the public DSH stream

You can then inspect the contents of the REST token and check that it follows the claims that you specified:

Terminal

cat sensor-rest-token.txt | sed "s/[^.]*\.\([^.]*\)\.[^.]*/\1===/;s/\(\(....\)*\).*/\1/" | base64 -d | jq .

HVAC¶

Create the file hvac-rest-body.txt with the following contents:

rest-body.txt
{
    "tenant": "<your-tenant-name>",
    "claims": {
        "datastreams/v0/mqtt/token": {
            "id": "hvac",
            "claims": [
                {
                    "action": "subscribe",
                    "resource": {
                        "type": "topic",
                        "prefix": "/tt",
                        "stream": "<public-DSH-stream-name>",
                        "topic": "house/#"
                    }
                }
            ]
        }
    }
}

Fill out the correct values for the placeholders <your-tenant-name> and <public-DSH-stream-name>. If the full name of your public DSH stream is stream.getting-started, then you need to use the value getting-started.

Once you have the API key and the file in place, execute the following command in your Terminal:

Terminal

curl -X POST "https://api.<DSH-platform-name>.kpn.com/auth/v0/token" -H "apikey: <your-api-key>" -d "`cat hvac-rest-body.txt`" > hvac-rest-token.txt

The command contains the following placeholders:

<DSH-platform-name>: the name of the DSH platform that contains your tenant and the public DSH stream that you want to subscribe and publish to
<your-api-key>: the API key that you retrieved for the API client that is connected to the public DSH stream

You can then inspect the contents of the REST token and check that it follows the claims that you specified:

Terminal

cat hvac-rest-token.txt | sed "s/[^.]*\.\([^.]*\)\.[^.]*/\1===/;s/\(\(....\)*\).*/\1/" | base64 -d | jq .

Request MQTT tokens¶

Now that you have the REST tokens, you can request MQTT tokens. In the sections below, you request an MQTT token for the kitchen sensor, and an MQTT token for the HVAC system.

Tip

See MQTT token for detailed information about MQTT tokens.

Sensor¶

Execute the following command in your Terminal to request an MQTT token for the sensor from the DSH:

Terminal

curl -X POST "https://api.<DSH-platform-name>.kpn.com/datastreams/v0/mqtt/token" -H "Authorization: Bearer `cat sensor-rest-token.txt`" -d '{"id":"kitchen-sensor"}' > sensor-mqtt-token.txt

Some aspects of this command are worth noting:

<DSH-platform-name>: This is the name of the DSH platform that contains your tenant and the public DSH stream that you want to subscribe and publish to.
The command passes the REST token in the header of the request.
The command only passes the ID of the device (kitchen-sensor), in line with the contents of the REST token.

You can then inspect the contents of the MQTT token, and check that it contains the claims specified in the REST token:

Terminal

cat sensor-mqtt-token.txt | sed "s/[^.]*\.\([^.]*\)\.[^.]*/\1===/;s/\(\(....\)*\).*/\1/" | base64 -d | jq .

HVAC¶

Execute the following command in your Terminal to request an MQTT token for the sensor from the DSH:

Terminal

curl -X POST "https://api.<DSH-platform-name>.kpn.com/datastreams/v0/mqtt/token" -H "Authorization: Bearer `cat hvac-rest-token.txt`" -d '{"id":"hvac"}' > hvac-mqtt-token.txt

Some aspects of this command are worth noting:

<DSH-platform-name>: This is the name of the DSH platform that contains your tenant and the public DSH stream that you want to subscribe and publish to.
The command passes the REST token in the header of the request.
The command passes the ID of the device (hvac), which is in line with the contents of the REST token.

You can then inspect the contents of the MQTT token, and check that it contains the claims specified in the REST token:

Terminal

cat hvac-mqtt-token.txt | sed "s/[^.]*\.\([^.]*\)\.[^.]*/\1===/;s/\(\(....\)*\).*/\1/" | base64 -d | jq .

In your Terminal, execute the following command to subscribe to the public DSH stream:

Terminal

mosquitto_sub -h mqtt.<DSH-platform-name>.kpn.com -p 8883 -t "/tt/<public-DSH-stream-name>/house/#" --capath /etc/ssl/certs/ -u "hvac" -P "`cat hvac-mqtt-token.txt`"

Some aspects of this command are worth noting:

<DSH-platform-name>: This is the name of the DSH platform that contains your tenant and the public DSH stream that you want to subscribe and publish to.
<public-DSH-stream-name>: If the full name of your public DSH stream is stream.getting-started, then you need to use the value getting-started.
The command passes the client ID “hvac” as a user, and the MQTT token as a password.

If all goes well, you should see the messages in the stream appear in your Terminal.

Tip

Use the Kafka producer described in Publish to DSH stream to publish messages to the public DSH stream.

Publish to public DSH stream¶

Execute the following command in a new tab or window of your Terminal:

Terminal

mosquitto_pub -h mqtt.<DSH-platform-name>.kpn.com -p 8883 -t "/tt/<public-DSH-stream-name>/house/kitchen/sensor" --capath /etc/ssl/certs/ -u "kitchen-sensor" -P "`cat sensor-mqtt-token.txt`" -m "`date`: 25"

Some aspects of this command are worth noting:

<DSH-platform-name>: This is the name of the DSH platform that contains your tenant and the public DSH stream that you want to subscribe and publish to.
<public-DSH-stream-name>: If the full name of your public DSH stream is stream.getting-started, then you need to use the value getting-started.
The command passes the client ID “kitchen-sensor” as a user, and the MQTT token as a password.

If you return to the tab or window of your Terminal that has the MQTT subscription running for the HVAC, then the message should appear.

Tip

You can also use the Kafka consumer described in Consume from DSH stream to publish messages to the public DSH stream.

Congratulations! You have now consumed messages from a public DSH stream, and published a message to it.

Publish and subscribe via MQTT¶

Prerequisites¶

Create a working directiory¶

Request REST tokens¶

Sensor¶

HVAC¶

Request MQTT tokens¶

Sensor¶

HVAC¶

Subscribe to public DSH stream¶

Publish to public DSH stream¶