MQTT Configuration and Messaging Guide

Overview

MQTT (Message Queuing Telemetry Transport) is a lightweight publish/subscribe messaging protocol designed for constrained devices and low-bandwidth, high-latency networks. It is widely used in IoT applications for efficient device-to-cloud and device-to-device communication.

This guide covers how to configure an MQTT client on a Signetik device, publish messages from the device, and use MQTTX — a cross-platform MQTT client — to subscribe to device messages and publish commands back.

Prerequisites

• A Signetik device with MQTT client firmware flashed and running
• A serial terminal connected to the device (e.g., PuTTY, minicom, or VS Code Serial Monitor)
• MQTTX installed on your PC (available for Windows, macOS, and Linux)
• Network connectivity on both the device and your PC

Device Configuration

The device is configured via + commands sent over a serial interface. Commands follow the format +set,<parameter>:<value>.

Step 1: Disable the MQTT Client Before Configuring

Always disable the MQTT client before changing settings to prevent connection issues:

+set,enabled:0

Step 2: Configure Connection Parameters

Set each parameter in turn:

+set,devid:1234AAAB
+set,clean_session:0
+set,server_address:test.mosquitto.org
+set,server_port:1883
+set,pubtopic:mypub
+set,subtopic1:mysub
+set,proto:mqtt
+set,user:
+set,rawmode:1
+set,payload:json

Parameter Reference

Note: test.mosquitto.org is a public, unauthenticated broker maintained by the Mosquitto project. It is suitable for development and testing but should not be used for production workloads.

Step 3: Enable the MQTT Client

Once all parameters are set, enable the client:

+set,enabled:1

The device will attempt to connect to the broker. Monitor the serial output and wait for a connection confirmation message, such as:

+notify,event:mqtt,connecting:1,host:test.mosquitto.org,devid:1234AAAB,user:NULL,pw:NULL
+notify,event:mqtt,connected:1
+notify,mqtt:sub,topic1:mysub

Tip: If the connection fails, double-check the server_address, server_port, and network connectivity. For persistent sessions (clean_session:0), the broker will remember the device's subscriptions between connections.

Publishing a Message from the Device

Once connected, use the +push command to publish a JSON payload to the configured publish topic (mypub):

+push,queue1,{"message":"hello from Signetik"}

Command Structure

+push,<queue>,<payload>

The device will publish this payload to the topic defined by pubtopic — in this case, mypub.

Additional Payload Examples

+push,queue1,{"sensor":"temperature","value":23.4,"unit":"C"}
+push,queue1,{"device":"1234AAAB","status":"online","rssi":-72}
+push,queue1,{"alert":"threshold_exceeded","level":98.5}

Using MQTTX to Monitor and Communicate with the Device

MQTTX is a feature-rich, cross-platform MQTT client with a clean GUI. It supports MQTT 3.1, 3.1.1, and 5.0, making it a solid choice for development and testing.

Installing MQTTX

Download and install MQTTX from https://mqttx.app/ for your platform. It is also available as a CLI tool (npm install -g mqttx-cli) if you prefer a terminal workflow.

Connecting MQTTX to the Broker

1. Launch MQTTX.
2. Click + New Connection in the left sidebar.

3. Fill in the connection details:

4. Click Connect. The status indicator in the top-left of the connection panel should turn green.

Subscribing to Device Messages (Receiving from the Device)

The device publishes to mypub. Subscribe to this topic in MQTTX to receive those messages.

1. In the connected session, click the + New Subscription button (or the subscribe icon).
2. Enter the topic: mypub
3. Set QoS to 0 (or 1 if you need guaranteed delivery).
4. Click Confirm.

Now trigger a publish from the device:

+push,queue1,{"message":"hello from Signetik"}

You should see the message appear in the MQTTX message panel within seconds:

Wildcard subscriptions: You can also subscribe to mypub/# or +/mypub to catch messages across subtopics, depending on your topic hierarchy.

Publishing a Message to the Device (Sending from MQTTX)

The device subscribes to mysub. Use MQTTX to send commands or data to the device on this topic.

1. In the active MQTTX session, locate the message compose area at the bottom of the chat panel.
2. Set the Topic field to: mysub
3. Set the QoS to 0 (or 1 for confirmed delivery).
4. Set the Payload format to JSON or Plaintext as needed.
5. Type your message in the payload field, for example:

{"command":"reboot"}

or

{"command":"set_interval","value":30}

6. Click the Send button (paper plane icon, or press Ctrl+Enter).

The device will receive the message on mysub and handle it according to its firmware logic.

Two-Way Communication Example

The following sequence illustrates a full round-trip exchange between the device and MQTTX:

[Device → mypub]  {"device":"1234AAAB","status":"online"}
[MQTTX → mysub]   {"command":"get_sensor_data"}
[Device → mypub]  {"sensor":"level","value":74.2,"unit":"%"}
[MQTTX → mysub]   {"command":"set_interval","value":60}
[Device → mypub]  {"ack":"set_interval","status":"ok"}

This pattern — device publishes status/data, host publishes commands — is the standard MQTT IoT control loop.

Using the MQTTX CLI (Optional)

If you prefer the command line, the MQTTX CLI offers equivalent functionality:

Subscribe to device messages:

mqttx sub -h test.mosquitto.org -p 1883 -t mypub -v

Publish a command to the device:

mqttx pub -h test.mosquitto.org -p 1883 -t mysub -m '{"command":"reboot"}'

Subscribe with QoS 1:

mqttx sub -h test.mosquitto.org -p 1883 -t mypub -q 1 -v

Topic Structure Recommendations

For production use, adopt a structured topic hierarchy to support filtering, routing, and access control:

signetik/<devid>/telemetry     # Device → Cloud (sensor data, status)
signetik/<devid>/command       # Cloud → Device (commands, configuration)
signetik/<devid>/ack           # Device → Cloud (command acknowledgments)

Example with the configured device ID:

signetik/1234AAAB/telemetry
signetik/1234AAAB/command
signetik/1234AAAB/ack

To subscribe to all devices in MQTTX, use a wildcard:

signetik/+/telemetry

Troubleshooting

Quick Reference

Device Commands

+set,enabled:0                          # Disable client (before config changes)
+set,devid:<id>                         # Set device/client ID
+set,clean_session:<0|1>                # Session persistence
+set,server_address:<host>              # Broker hostname or IP
+set,server_port:<port>                 # Broker port (1883 or 8883)
+set,pubtopic:<topic>                   # Publish topic
+set,subtopic1:<topic>                  # Subscribe topic
+set,proto:<mqtt|mqtts>                 # Protocol selection
+set,enabled:1                          # Enable client (connect)

+push,queue1,<payload>                  # Publish a message

MQTTX Cheat Sheet