MQTT & IoT Guide

Muxit's built-in MqttBridge driver lets you connect IoT devices that communicate over MQTT — ESP32, Arduino, Tasmota smart plugs, Home Assistant, Node-RED, and anything else that speaks MQTT.

What Is MQTT?

MQTT is a lightweight messaging protocol used by IoT devices. Devices publish messages to topics (like sensors/temperature), and other devices subscribe to those topics to receive the messages. A central broker (like Mosquitto) routes messages between publishers and subscribers.

ESP32 sensor  ──publish──►  MQTT Broker  ◄──subscribe──  Muxit
  (temperature)                │                          (reads values)
                               │
Smart plug    ◄──subscribe──   │  ──publish──►  Muxit
  (turns on/off)                                (sends commands)

Muxit acts as both a subscriber (reading sensor data) and a publisher (sending commands to devices).

Quick Start

1. Set Up a Broker

You need an MQTT broker running on your network. If you don't have one, install Mosquitto:

Linux:

bash

sudo apt install mosquitto mosquitto-clients
sudo systemctl enable mosquitto

macOS:

bash

brew install mosquitto
brew services start mosquitto

Windows: Download from mosquitto.org/download

Already have Home Assistant? It includes an MQTT broker — enable it in Settings > Add-ons > Mosquitto broker.

2. Create the MQTT Connector

Create workspace/connectors/mqtt.js:

javascript

export default {
  driver: "MqttBridge",
  config: {
    host: "127.0.0.1",   // Your broker's IP address
    port: 1883,
    topics: ["sensors/#"],  // Subscribe to all sensor topics on connect
  },
  poll: ["connected", "messageCount", "lastTopic", "lastPayload"],

  methods: {
    connect:    [c => c.connect(), "Connect to the MQTT broker"],
    disconnect: [c => c.disconnect(), "Disconnect from the broker"],

    subscribe: {
      fn: (c, args) => {
        const topic = typeof args === "string" ? args : args?.topic;
        return c.subscribe({ topic, qos: args?.qos ?? 0 });
      },
      description: "Subscribe to an MQTT topic",
    },

    publish: {
      fn: (c, args) => {
        return c.publish({
          topic: args.topic,
          payload: typeof args.payload === "object"
            ? JSON.stringify(args.payload)
            : String(args.payload ?? ""),
          qos: args.qos ?? 0,
          retain: args.retain ?? false,
        });
      },
      description: "Publish a message to a topic",
    },

    getValue: {
      fn: (c, args) => {
        const topic = typeof args === "string" ? args : args?.topic;
        return c.get({ topic });
      },
      description: "Get the last value from a topic",
    },
  },
};

3. Enable and Connect

Restart the Muxit server (or reload connectors in the Hardware panel)
Enable the mqtt connector in the Hardware panel
The driver initializes but does not auto-connect — call the connect action:

javascript

// In a script or via AI chat
const mqtt = connector("mqtt");
await mqtt.connect();
log.info(`Connected: ${await mqtt.connected()}`);

Or use the AI Chat: "Connect to the MQTT broker"

4. Verify

After connecting, the Hardware panel shows:

connected: true
messageCount incrementing as messages arrive
lastTopic and lastPayload showing the most recent message

Subscribing to Topics

In the Connector Config

Use the topics config option to auto-subscribe when connecting:

javascript

config: {
  host: "192.168.1.50",
  topics: ["sensors/#", "home/+/state"],
},

From a Script

javascript

const mqtt = connector("mqtt");
await mqtt.connect();

// Subscribe to specific topics
await mqtt.subscribe("sensors/temperature");
await mqtt.subscribe("sensors/humidity");

// Wildcards work too
await mqtt.subscribe("home/#");        // all topics under home/
await mqtt.subscribe("sensors/+/value"); // single-level wildcard

MQTT Wildcards

Wildcard	Matches	Example
`#`	All subtopics (multi-level)	`sensors/#` matches `sensors/temp`, `sensors/room1/temp`
`+`	One level	`sensors/+/value` matches `sensors/temp/value` but not `sensors/room1/temp/value`

Reading Sensor Data

Get the Last Value

The MqttBridge stores the last payload received on each topic:

javascript

const mqtt = connector("mqtt");
const temp = await mqtt.getValue("sensors/temperature");
log.info(`Temperature: ${temp}`);

Computed Properties

Create computed properties in your connector that read specific topics:

javascript

properties: {
  temperature: {
    get: c => c.get({ topic: "sensors/temperature" }),
    description: "Temperature from MQTT sensor",
    poll: true,
  },
  humidity: {
    get: c => c.get({ topic: "sensors/humidity" }),
    description: "Humidity from MQTT sensor",
    poll: true,
  },
},

These properties are now available in scripts (await mqtt.temperature()) and can be bound to dashboard widgets.

Monitor in Real-Time

javascript

const mqtt = connector("mqtt");

while (script.running) {
  const temp = await mqtt.getValue("sensors/temperature");
  const humidity = await mqtt.getValue("sensors/humidity");

  log.info(`Temp: ${temp}°C, Humidity: ${humidity}%`);

  if (temp > 30) {
    log.warn("Temperature too high!");
    await mqtt.publish({
      topic: "alerts/temperature",
      payload: JSON.stringify({ temp, timestamp: timestamp() }),
    });
  }

  await delay(5000);
}

Publishing Messages

Send commands to MQTT devices:

javascript

const mqtt = connector("mqtt");

// Simple payload
await mqtt.publish({ topic: "home/light/set", payload: "ON" });

// JSON payload
await mqtt.publish({
  topic: "home/thermostat/set",
  payload: JSON.stringify({ temperature: 22, mode: "heat" }),
});

// With QoS and retain flag
await mqtt.publish({
  topic: "config/device1",
  payload: "reset",
  qos: 1,
  retain: true,
});

Displaying MQTT Data on Dashboards

Bind Computed Properties to Widgets

If your connector has computed properties (like temperature and humidity above), bind them to dashboard widgets just like any other connector property:

json

{
  "type": "gauge",
  "config": {
    "label": "Temperature",
    "connector": "mqtt",
    "property": "temperature",
    "min": -10,
    "max": 50,
    "unit": "°C"
  }
}

Monitor the Message Stream

Use a terminal widget to see all MQTT messages in real-time:

json

{
  "type": "terminal",
  "config": {
    "label": "MQTT Messages",
    "stream": "mqtt:message",
    "maxLines": 200,
    "fontSize": "small"
  }
}

Build a Complete Sensor Dashboard

Combine gauges, charts, and indicators:

json

{
  "name": "IoT Sensors",
  "widgets": [
    {
      "id": "w1", "type": "gauge",
      "layout": { "x": 0, "y": 0, "w": 4, "h": 4 },
      "config": {
        "label": "Temperature",
        "connector": "mqtt",
        "property": "temperature",
        "min": -10, "max": 50, "unit": "°C"
      }
    },
    {
      "id": "w2", "type": "gauge",
      "layout": { "x": 4, "y": 0, "w": 4, "h": 4 },
      "config": {
        "label": "Humidity",
        "connector": "mqtt",
        "property": "humidity",
        "min": 0, "max": 100, "unit": "%"
      }
    },
    {
      "id": "w3", "type": "indicator",
      "layout": { "x": 8, "y": 0, "w": 4, "h": 2 },
      "config": {
        "label": "Broker Connected",
        "connector": "mqtt",
        "property": "connected"
      }
    },
    {
      "id": "w4", "type": "chart",
      "layout": { "x": 0, "y": 4, "w": 12, "h": 4 },
      "config": {
        "label": "Sensor History",
        "bindings": ["mqtt.temperature", "mqtt.humidity"],
        "duration": 60, "yMin": 0, "yMax": 100
      }
    }
  ]
}

Examples

ESP32 Temperature Sensor

A typical ESP32 running Arduino or ESPHome publishes sensor readings like:

Topic: sensors/temperature    Payload: 23.5
Topic: sensors/humidity       Payload: 67

Connector config:

javascript

export default {
  driver: "MqttBridge",
  config: {
    host: "192.168.1.50",
    topics: ["sensors/#"],
  },
  poll: ["connected", "messageCount"],

  methods: {
    connect:    [c => c.connect(), "Connect to broker"],
    disconnect: [c => c.disconnect(), "Disconnect"],
  },

  properties: {
    temperature: {
      get: c => c.get({ topic: "sensors/temperature" }),
      description: "Temperature (°C)",
      poll: true,
    },
    humidity: {
      get: c => c.get({ topic: "sensors/humidity" }),
      description: "Humidity (%)",
      poll: true,
    },
  },
};

Auto-connect script:

javascript

const mqtt = connector("mqtt");
await mqtt.connect();
log.info("MQTT connected — listening for sensor data");

while (script.running) {
  const temp = await mqtt.temperature();
  const hum = await mqtt.humidity();
  if (temp !== null) log.info(`Temp: ${temp}°C, Humidity: ${hum}%`);
  await delay(5000);
}

Tasmota Smart Plug

Tasmota devices use topics like cmnd/plug/POWER and stat/plug/POWER:

javascript

const mqtt = connector("mqtt");
await mqtt.connect();

// Turn ON
await mqtt.publish({ topic: "cmnd/plug/POWER", payload: "ON" });

// Turn OFF
await mqtt.publish({ topic: "cmnd/plug/POWER", payload: "OFF" });

// Read current state
await mqtt.subscribe("stat/plug/POWER");
await delay(1000);
const state = await mqtt.getValue("stat/plug/POWER");
log.info(`Plug is: ${state}`);

Home Assistant Integration

If Home Assistant is running with the Mosquitto add-on:

Set host to your Home Assistant IP
Use the username/password from the Mosquitto add-on config
Subscribe to Home Assistant topics like homeassistant/sensor/+/state

javascript

export default {
  driver: "MqttBridge",
  config: {
    host: "192.168.1.100",
    port: 1883,
    username: "mqtt_user",
    password: "mqtt_password",
    topics: ["homeassistant/#"],
  },
  poll: ["connected"],

  methods: {
    connect: [c => c.connect(), "Connect to Home Assistant MQTT"],
  },
};

Node-RED Integration

Node-RED can publish data to topics that Muxit subscribes to, and subscribe to topics that Muxit publishes to. Use the same broker for both.

Node-RED flow: Sensor node → MQTT out (sensors/data) → Muxit reads it

Muxit → Node-RED: Muxit publishes to muxit/commands → MQTT in → Node-RED processes it

Broker Authentication

If your broker requires authentication:

javascript

config: {
  host: "192.168.1.50",
  port: 1883,
  username: "muxit",
  password: "your-password",
},

For cloud MQTT brokers (HiveMQ, CloudMQTT, etc.), use the provided hostname, port, and credentials.

Troubleshooting

"Not connected" error — Call the connect action first. The driver initializes but does not auto-connect.

No messages arriving — Check that:

Your broker is running (mosquitto process)
The host IP is correct (try ping <ip>)
You've subscribed to the right topics (check wildcards)
Your IoT device is publishing (test with mosquitto_sub -t "sensors/#")

Connection refused — The broker may require authentication. Add username and password to the config.

Messages arrive but properties show null — Make sure your computed properties use the exact topic string that messages are published to. Topic matching is case-sensitive.

High latency — Reduce the polling interval or adjust QoS. QoS 0 is fastest (no acknowledgment), QoS 1 guarantees delivery at least once.

Full Driver Reference

See the MqttBridge driver reference for the complete list of properties, actions, streams, and config options.

MQTT & IoT Guide ​

What Is MQTT? ​

Quick Start ​

1. Set Up a Broker ​

2. Create the MQTT Connector ​

3. Enable and Connect ​

4. Verify ​

Subscribing to Topics ​

In the Connector Config ​

From a Script ​

MQTT Wildcards ​

Reading Sensor Data ​

Get the Last Value ​

Computed Properties ​

Monitor in Real-Time ​

Publishing Messages ​

Displaying MQTT Data on Dashboards ​

Bind Computed Properties to Widgets ​

Monitor the Message Stream ​

Build a Complete Sensor Dashboard ​

Examples ​

ESP32 Temperature Sensor ​

Tasmota Smart Plug ​

Home Assistant Integration ​

Node-RED Integration ​

Broker Authentication ​

Troubleshooting ​

Full Driver Reference ​

MQTT & IoT Guide

What Is MQTT?

Quick Start

1. Set Up a Broker

2. Create the MQTT Connector

3. Enable and Connect

4. Verify

Subscribing to Topics

In the Connector Config

From a Script

MQTT Wildcards

Reading Sensor Data

Get the Last Value

Computed Properties

Monitor in Real-Time

Publishing Messages

Displaying MQTT Data on Dashboards

Bind Computed Properties to Widgets

Monitor the Message Stream

Build a Complete Sensor Dashboard

Examples

ESP32 Temperature Sensor

Tasmota Smart Plug

Home Assistant Integration

Node-RED Integration

Broker Authentication

Troubleshooting

Full Driver Reference