Skip to main content

mqtt-in

Subscribe to MQTT topics and receive messages from brokers.

mqtt-in
input v1.0.0

Subscribe to MQTT topics and receive messages. Supports wildcards, QoS levels, and automatic JSON parsing.

mqtt subscribe iot messaging
Inputs
0
Outputs
1

Overview

The mqtt-in node subscribes to MQTT topics and outputs messages received from the broker. MQTT is the most popular protocol for IoT devices due to its lightweight nature and publish/subscribe model.

  • Wildcard subscriptions - Subscribe to multiple topics with + and # wildcards
  • QoS support - Choose reliability level for message delivery
  • Auto JSON parsing - Automatically parse JSON payloads
  • TLS encryption - Secure connections to cloud brokers
  • Retained messages - Receive last known value on subscribe

This node is essential for receiving data from IoT sensors, smart home devices, and any system that publishes to MQTT.

Properties

Property Type Required Default Description
name string - - Display name for this node in the editor.
broker config - MQTT broker configuration node containing connection details.
topic string - MQTT topic to subscribe to. Supports wildcards: + (single level) and # (multi-level).
qos number - 0 Quality of Service level: 0 (at most once), 1 (at least once), 2 (exactly once).
datatype string - auto Output data type: auto (detect), utf8 (string), buffer (raw bytes), json (parsed object).
nl boolean - false No Local - if true, messages published by this client will not be received.
rap boolean - true Retain As Published - keep the retain flag from the original message.
rh number - 0 Retain Handling: 0 (send retained on subscribe), 1 (send if new subscription), 2 (do not send).

Broker Configuration

The MQTT broker configuration is shared between mqtt-in and mqtt-out nodes. Configure it once and reuse across your flows.

Property Type Required Default Description
broker string localhost Hostname or IP address of the MQTT broker.
port number 1883 Port number (1883 for plain MQTT, 8883 for MQTT over TLS).
clientid string - - Client ID for the connection. Leave blank for auto-generated ID.
usetls boolean - false Enable TLS/SSL encrypted connection.
username string - - Username for broker authentication.
password string - - Password for broker authentication.
keepalive number - 60 Keep-alive interval in seconds.
cleansession boolean - true Start with a clean session (no persistent subscriptions).
Security Note

Always use TLS (port 8883) when connecting to cloud MQTT brokers. Store credentials in environment variables, not directly in node configuration.

Topic Wildcards

MQTT supports two wildcard characters for flexible subscriptions:

Wildcard Name Description
+ Single-level Matches exactly one topic level
# Multi-level Matches any number of levels (must be last character)

Wildcard Examples

sensors/+/temperature Matches: sensors/living-room/temperature, sensors/kitchen/temperature
sensors/# Matches: sensors/temp, sensors/humidity, sensors/room1/temp
home/+/+/state Matches: home/floor1/light1/state, home/floor2/sensor1/state

QoS Levels

Quality of Service (QoS) determines the delivery guarantee for messages:

0 At most once (Fire and forget)

Fastest, no acknowledgment. Messages may be lost. Best for frequently-updated sensor data where occasional loss is acceptable.

1 At least once

Guaranteed delivery with acknowledgment. Messages may be duplicated. Good balance of reliability and performance.

2 Exactly once

Guaranteed single delivery with 4-way handshake. Slowest but most reliable. Use for critical commands and billing data.

Outputs

When a message is received, the node outputs:

Output Message Format

{`{
  "topic": "sensors/living-room/temperature",
  "payload": 23.5,
  "qos": 0,
  "retain": false,
  "messageId": 12345,
  "_msgid": ""
}`}

Output Properties

Property Type Description
topic string The actual topic the message was received on
payload any Message content (string, number, object, or Buffer)
qos number QoS level the message was published with
retain boolean Whether this is a retained message

Examples

Basic Sensor Data

Subscribe to a temperature sensor and display readings in the debug panel.

Temperature Monitor

Receives temperature data from a DHT22 sensor publishing to MQTT.

View Flow JSON 
[
  {
    "id": "mqtt1",
    "type": "mqtt-in",
    "name": "Temperature",
    "topic": "sensors/dht22/temperature",
    "qos": "0",
    "datatype": "auto",
    "broker": "broker1",
    "wires": [["debug1"]]
  },
  {
    "id": "debug1",
    "type": "debug",
    "name": "Output",
    "active": true
  },
  {
    "id": "broker1",
    "type": "mqtt-broker",
    "name": "Local Mosquitto",
    "broker": "localhost",
    "port": "1883"
  }
]

Wildcard Subscription

Subscribe to all sensors in a building using wildcards.

Building Sensor Hub

Receives data from all sensors across multiple floors and rooms.

View Flow JSON 
[
  {
    "id": "mqtt2",
    "type": "mqtt-in",
    "name": "All Sensors",
    "topic": "building/+/+/sensors/#",
    "qos": "1",
    "datatype": "json",
    "broker": "broker1",
    "wires": [["switch1"]]
  },
  {
    "id": "switch1",
    "type": "switch",
    "name": "Route by Type",
    "property": "topic",
    "rules": [
      {"t": "cont", "v": "temperature"},
      {"t": "cont", "v": "humidity"},
      {"t": "cont", "v": "motion"}
    ],
    "outputs": 3
  }
]

JSON Parsing with Validation

Receive JSON sensor data, validate it, and store in a database.

JSON Sensor Pipeline

Parses JSON, validates required fields, and stores valid readings.

View Flow JSON 
[
  {
    "id": "mqtt3",
    "type": "mqtt-in",
    "name": "Sensor JSON",
    "topic": "sensors/+/data",
    "qos": "1",
    "datatype": "json",
    "broker": "broker1",
    "wires": [["function1"]]
  },
  {
    "id": "function1",
    "type": "function",
    "name": "Validate",
    "func": "if (msg.payload.value !== undefined && msg.payload.unit) {\n  msg.payload.timestamp = Date.now();\n  msg.payload.sensor = msg.topic.split('/')[1];\n  return msg;\n}\nnode.warn('Invalid sensor data');\nreturn null;"
  },
  {
    "id": "sqlite1",
    "type": "sqlite",
    "name": "Store",
    "db": "sensors.db"
  }
]

Troubleshooting

Not receiving any messages
  1. Verify the broker is running and accessible
  2. Check the topic spelling matches exactly (topics are case-sensitive)
  3. Use an MQTT client like mosquitto_sub to verify messages are being published
  4. Look for connection errors in the EdgeFlow log
  5. Check firewall rules allow connections on port 1883/8883
Connection keeps dropping
  • Ensure each client has a unique Client ID (or leave blank for auto-generated)
  • Increase the keep-alive interval if on a slow network
  • Check if another client is using the same Client ID (causes disconnection)
  • Verify network stability between EdgeFlow and the broker
Payload shows as Buffer instead of text

Change the Output property from "auto" to "a parsed JSON object" or "a UTF-8 string". If the data is binary (images, protobuf), keep it as Buffer and process accordingly.

TLS connection fails
  • Verify the port is correct (usually 8883 for TLS)
  • Check if the broker's certificate is valid and not expired
  • For self-signed certificates, upload the CA certificate in broker config
  • Ensure the system clock is accurate (TLS requires correct time)
Receiving duplicate messages

This is expected behavior with QoS 1. For exactly-once delivery, use QoS 2. Alternatively, implement deduplication in your flow using the message ID or a function node with context storage.

Related Nodes

mqtt-out output

Publish messages to MQTT topics.
function logic

Process and transform MQTT messages.
json logic

Parse JSON payloads from MQTT.