HiveMQ

HiveMQ is an MQTT broker and a client based messaging platform which uses MQTT protocol for fast, reliable and efficient bi-directional data transfer to and from IoT devices.

HiveMQ provides its own client library, but it can be used with any MQTT compliant client library. It can be deployed on a private, hybrid or public cloud. You can integrate HiveMQ with existing enterprise systems thanks to its open API and a flexible extension framework.

HiveMQ also offers an open source tool called MQTT CLI, which provides a command line interface to interact with MQTT brokers. This tool can be used in a shell mode, allowing you to use multiple MQTT clients simultaneously.

This guide contains the instructions to use HiveMQ CLI tool in a shell mode for subscribing and publishing to topics used by The Things Stack MQTT Server.

The examples in this guide are suitable for The Things Stack Open Source deployment. If you are using a different The Things Stack deployment, make sure your read a Note on Using the tenant ID.

Prerequisites

1. HiveMQ MQTT CLI installed on your system.

Connecting to MQTT Server in MQTT CLI Shell Mode

Learn how to connect to The Things Stack MQTT Server by reading the MQTT Server guide.

Enter the HiveMQ MQTT CLI shell mode by typing the following command in your terminal:

mqtt shell

Once in shell mode, you can connect to The Things Stack MQTT Server by using the following command:

con -h <hostname> -p <port> -V 3 -u <username> -pw <password>

Keep in mind that password is the value of the authentication API key. For more info, see Creating an API Key.

The -V 3 flag is used here because the The Things Stack MQTT Server supports the 3.1.1 MQTT protocol version, as mentioned in the MQTT Server guide. For detailed descriptions of other parameters used with the con command, see the official MQTT CLI documentation.

For example, you can connect to The Things Stack MQTT Server over its public address with the following command:

con -h "thethings.example.com" -p "1883" -V 3 -u "app1" -pw "NNSXS.VEEBURF3KR77ZR.."

To use TLS for additional security, change the port from 1883 to 8883 and use the --cafile option to provide the PEM encoded CA file of your The Things Stack deployment.

Once you have successfully connected to The Things Stack MQTT Server, continue with subscribing or publishing to topics exposed by it by following the sections below.

Subscribe to Upstream Traffic

Use the sub command to subscribe to topics and listen to messages being sent from your end device.

For example, if you want to listen to the uplink messages being sent from dev1 device in app1 application, use the following command:

sub -t "v3/app1/devices/dev1/up" -s

-s flag is used to subscribe with a context to the given topic, e.g. to stop the console being blocked by subscribing without a context. For detailed descriptions of all the available sub command parameters, see the Subscribe section of the HiveMQ MQTT CLI documentation.

See the Subscribing to Upstream Traffic section of the MQTT Server guide for a full list of available topics you can subscribe to.

Schedule Downlink Messages

Use the pub command to publish to topics, e.g. to schedule downlink messages to be sent to your end device.

For example, to push an unconfirmed downlink message with the hexadecimal payload BE EF on FPort 15 with normal priority to the dev1 device, use the following command:

pub -t "v3/app1/devices/dev1/down/push" -m '{"downlinks":[{"f_port": 15,"frm_payload":"vu8=","priority": "NORMAL"}]}'

For detailed descriptions of the pub command parameters, see the Publish section of the MQTT CLI documentation.

See the Publishing Downlink Traffic section to learn about using /replace instead of /push.