Skip to content

Migrating from MQTTThing

Jump to bottom
Martin Patfield edited this page Dec 17, 2025 · 1 revision

This page is intended to provide some tips and examples for users migrating from MQTTThing. It is a work in progress, so please if you have an example of old/new config you'd be willing to share, please post a message on Discord or open a ticket.

Table of Contents:

Notable Differences

Apply -> Value Transformers

In MQTTThing, making adjustments to incoming or outgoing messages is done via apply. In Easy MQTT, these same adjustments are made using Value Transformers defined as part of the topic.

Examples

Aquara Double Rocker Switch

MQTTThing Easy MQTT 
{
  "accessory":"mqttthing",
  "type":"custom",
  "name":"Living Room Lights",
  "manufacturer":"Aqara",
  "model":"E1",
  "serialNumber":"QBKG41LM",
  "firmwareRevision":"07.29.24",
  "url":"mqtt://IP:PORT",
  "username":"***redacted***",
  "password":"***redacted***",
  "services":[
    {
      "type":"lightbulb",
      "name":"Left",
      "topics":{
        "getOn":{
          "topic":"zigbee2mqtt/Living Room Switch",
          "apply":"return JSON.parse(message).state_left === 'ON';"
        },
        "setOn":{
          "topic":"zigbee2mqtt/Living Room Switch/set",
          "apply":"return `{ state_left: ${message?'ON':'OFF'} }`;"
        }
      }
    },
    {
      "type":"lightbulb",
      "name":"Right",
      "topics":{
        "getOn":{
          "topic":"zigbee2mqtt/Living Room Switch",
          "apply":"return JSON.parse(message).state_right === 'ON';"
        },
        "setOn":{
          "topic":"zigbee2mqtt/Living Room Switch/set",
          "apply":"return `{ state_right: ${message?'ON':'OFF'} }`;"
        }
      }
    }
  ]
}

{
    "name": "Easy MQTT",
    "accessories": [
        {
            "info": {
                "id": "",
                "name": "Left",
                "type": "Lightbulb",
                "group": "Living Room Lights",
                "manufacturer": "Aqara",
                "model": "E1",
                "serialNumber": "QBKG41LM",
                "version": "07.29.24"
            },
            "mqtt": {
                "broker": "mqtt://:",
                "username": "",
                "password": ""
            },
            "topicGetOn": "zigbee2mqtt/Living Room Switch$.state_left",
            "topicSetOn": "zigbee2mqtt/Living Room Switch/set$.state_left",
            "valueOn": "ON",
            "valueOff": "OFF"
        },
        {
            "info": {
                "id": "",
                "name": "Right",
                "type": "Lightbulb",
                "group": "Living Room Lights",
                "manufacturer": "Aqara",
                "model": "E1",
                "serialNumber": "QBKG41LM",
                "version": "07.29.24"
            },
            "mqtt": {
                "broker": "mqtt://:",
                "username": "",
                "password": ""
            },
            "topicGetOn": "zigbee2mqtt/Living Room Switch$.state_right",
            "topicSetOn": "zigbee2mqtt/Living Room Switch/set$.state_right",
            "valueOn": "ON",
            "valueOff": "OFF"
        }
    ],
    "platform": "HomebridgeEasyMQTT"
}

Koolnova Thermostat

MQTTThing Easy MQTT 
{
    "type": "thermostat",
    "name": "Bedroom AC",
    "username": "[REDACTED]",
    "password": "[REDACTED]",
    "logMqtt": true,
    "topics": {
        "getCurrentHeatingCoolingState": "koolnova2mqtt/home/zone1/hvacMode",
        "getCurrentTemperature": "koolnova2mqtt/home/zone1/currentTemp",
        "getTargetHeatingCoolingState": "koolnova2mqtt/home/zone1/hvacMode",
        "setTargetHeatingCoolingState": "koolnova2mqtt/home/zone1/hvacMode/set",
        "getTargetTemperature": "koolnova2mqtt/home/zone1/targetTemp",
        "setTargetTemperature": "koolnova2mqtt/home/zone1/targetTemp/set"
    },
    "heatingCoolingStateValues": [
        "off",
        "heat",
        "cool",
        "auto"
    ],
    "minTemperature": 15,
    "maxTemperature": 25,
    "manufacturer": "Koolnova",
    "model": "Smart",
    "accessory": "mqttthing"
}

{
  "info":{
    "name":"Bedroom AC",
    "type":"Thermostat",
    "id":"",
    "manufacturer":"Koolnova",
    "model":"Smart"
  },
  "mqtt":{
    "broker":"mqtt://:",
    "username":"",
    "password":""
  },
  "temperatureUnits":"",
  "topicGetCurrentTemperature":"koolnova2mqtt/home/zone1/currentTemp",
  "topicGetCurrentHeatingCoolingState":"koolnova2mqtt/home/zone1/hvacMode",
  "topicGetTargetHeatingCoolingState":"koolnova2mqtt/home/zone1/hvacMode",
  "topicSetTargetHeatingCoolingState":"koolnova2mqtt/home/zone1/hvacMode/set",
  "topicGetTargetTemperature":"koolnova2mqtt/home/zone1/targetTemp",
  "topicSetTargetTemperature":"koolnova2mqtt/home/zone1/targetTemp/set",
  "valueModeAuto":"auto",
  "valueModeCool":"cool",
  "valueModeHeat":"heat",
  "valueModeOff":"off"
}

Shelly Lightbulb

MQTTThing Easy MQTT 
{
    "type": "lightbulb-OnOff",
    "name": "Garage Lights",
    "url": "mqtt://10.10.10.1:1883",
    "logMqtt": true,
    "topics": {
        "getOn": {
            "topic": "Shelly-Garage-Lights/status/switch:0",
            "apply": "return JSON.parse(message).output;"
        },
        "setOn": {
            "topic": "Shelly-Garage-Lights/rpc",
            "apply": "return JSON.stringify({id: ...});"
        }
    },
    "accessory": "mqttthing"
}

{
    "info": {
        "name": "Garage Lights",
        "type": "Lightbulb",
        "id": "c1a14b2b-6153-44e5-bc6d-a68e87c28052"
    },
    "mqtt": {
        "broker": "mqtt://10.10.10.1"
    },
    "topicGetOn": "Shelly-Garage-Lights/status/switch:0$.output",
    "topicSetOn": "Shelly-Garage-Lights/command/switch:0",
    "valueOn": "on",
    "valueOff": "off"
}

Shelly Switch

MQTTThing Easy MQTT 
{
  "accessory":"mqttthing",
  "type":"switch",
  "name":"3DSystem",
  "url":"http://xxx.xxx.xxx.xxx:1883",
  "username":"***redacted***",
  "password":"***redacted***",
  "mqttOptions":{
    "keepalive":0,
    "clean":false,
    "qos":1
  },
  "mqttPubOptions":{
    "qos":1,
    "retain":true,
    "clean":false
  },
  "topics":{
    "getOnline":"shellies/3dDrucker/online",
    "getOn":{
      "topic":"shellies/3dDrucker/events/rpc",
      "apply":"return JSON.parse(message).params[\"switch:0\"].output;"
    },
    "setOn":{
      "topic":"shellies/3dDrucker/rpc",
      "apply":"return JSON.stringify({method: 'Switch.Set'...});"
    },
    "getWatts":{
      "topic":"shellies/3dDrucker/status/switch:0",
      "apply":"return JSON.parse(message).apower;"
    },
    "getTotalConsumption":{
      "topic":"shellies/3dDrucker/status/switch:0",
      "apply":"return (JSON.parse(message).aenergy.total / 1000);"
    }
  },
  "history":"true",
  "onlineValue":"true",
  "manufacturer":"Shelly",
  "model":"Shelly PLUS 1PM",
  "serialNumber":"4855199BBBC8"
}

{
  "name":"Easy MQTT",
  "accessories":[
    {
      "info":{
        "id":"15d35127-72aa-4f7d-a22a-997429c0c18d",
        "name":"3DSystem",
        "type":"Switch"
      },
      "mqtt":{
        "broker":"mqtt://192.168.xxx.xxx:1883",
        "username":"***redacted***",
        "password":"***redacted***",
        "options":"{ \"keepalive\": 0, \"clean\": false, \"qos\": 1 }"
      },
      "topicGetOn":"shellies/3dDrucker/events/rpc$.output",
      "topicSetOn":"shellies/3dDrucker/command/switch:0",
      "topicGetStatusActive":"shellies/3dDrucker/online",
      "topicGetCurrentConsumption":"shellies/3dDrucker/status/switch:0$.apower",
      "topicGetElectricCurrent":"shellies/3dDrucker/status/switch:0$.aenergy.total",
      "valueOn":"true",
      "valueOff":"false",
      "valueStatusActive":"true",
      "disableLogging":false
    }
  ],
  "platform":"HomebridgeEasyMQTT"
}

Z-Wave Lightbulb

MQTTThing Easy MQTT 
{
    "type": "lightbulb",
    "name": "Kitchen Dimmer",
    "url": "mqtt://mqtt.home:1883",
    "username": "mqttuser",
    "password": "***redacted***",
    "topics": {
        "getOn": {
            "topic": "zwave/dimmer/38/0/currentValue$.value"
        },
        "setOn": {
            "topic": "zwave/dimmer/38/0/targetValue/set",
            "apply": "return Math.round( JSON.parse(message));"
        },
        "getBrightness": {
            "topic": "zwave/dimmer/38/0/currentValue$.value"
        },
        "setBrightness": {
            "topic": "zwave/dimmer/38/0/targetValue/set",
            "apply": "return Math.round( JSON.parse(message));"
        }
    },
    "integerValue": true,
    "onValue": 100,
    "offValue": 0,
    "accessory": "mqttthing",
    "logMqtt": false
}

{
    "info": {
        "id": "d4f8a6b2-2e3c-4d5f-9a0b-1c2d3e4f5a6b",
        "name": "Kitchen Dimmer",
        "type": "Lightbulb"
    },
    "mqtt": {
        "broker": "mqtt://mqtt.home:1883",
        "username": "mqttuser",
        "password": "***redacted***"
    },
    "history": {
        "enabled": false
    },
    "topicGetOn": "zwave/dimmer/38/0/currentValue$.value|(value > 0)",
    "topicSetOn": "zwave/dimmer/38/0/targetValue/set",
    "valueOn": "true",
    "valueOff": "false",
    "topicGetBrightness": "zwave/dimmer/38/0/currentValue$.value",
    "topicSetBrightness": "zwave/dimmer/38/0/targetValue/set",
    "disableLogging": false
}

Home

Migrating from MQTTThing

JSON Configuration

Accessories

MQTT Setup

Matter Support

Eve App Support

Advanced Topic Notation

Custom Characteristics

Logging/Debugging

Clone this wiki locally