Advanced Topic Notation

JSONPath

Note

Easy MQTT has a simplified implementation of JSONPath and only supports $ and . — please leave a comment here if you need more advanced options

For some devices, the desired values in the MQTT messages are embedded within a JSON object. For example, here is the MQTT message for my door lock that is received when the door is locked:

{ "time": 1750870005853, "state": 255 }

Since the value (255) that I need is embedded within JSON, I can use JSONPath syntax to tell the parser how to find the value.

So, in this example I would define my topic as:

zwave/1/door_lock/currentMode$.state

The $.state at the end tells the parser to grab the value using the key "state".

This can be arbitrarily complicated and several layers deep. For example,

{
  "time":1750870005853,
  "state": {
    "number": {
      "value": 255
    }
  }
}

would use the topic

zwave/1/door_lock/currentMode$.state.number.value

You can do the same for the set topic if the device is expecting a JSON object rather than a raw value.

If, for example, your device is expecting this message:

{
  "target": "away"
}

instead of just the raw value "away" you can use:

zwave/4/security/set$.target

Again, the $.target at the end tells the MQTT client to wrap the value a JSON object.

As with get topics, you can have an arbitrarily complex chain. So if, for example, you want this object:

{
  "target": {
    "mode": {
      "value": "away"
    }
  }
}

then you would use the topic

zwave/4/security/set$.target.mode.value

Topic Transformer

There are situations where the topic needs to be adjusted or altered entirely before publishing.

For example, you may have a switch that expects different topics for "on" (myswitch/on) and "off" (myswitch/off)

You can use variable substitution notation (${}) within the topic to transform it based on the value.

myswitch/${value === 1 ? 'on' : 'off'}

Note that value is a reserved keyword here, which may be used to determine how to modify the topic.

You will likely also need to combine this with Value Transformer (see below) to send the appropriate message.

myswitch/${value === 1 ? 'on' : 'off'}|1

This will publish 1 to topic myswitch/on to turn the switch on, and publish 1 to topic myswitch/off to turn it off

Value Transformer

There are situations where the value needs to be adjusted or altered entirely.

For example, you may have an Air Quality Sensor that measures Nitrogen Dioxide in ppm (parts per million) instead of µg/m³ (micrograms per cubic meter) which HomeKit expects. In this case, you need to multiply by the arbitrary number 1883 to get the correct result.

Using the pipe (|) notation, you may add a transformer:

airquality/no2|value * 1883

This will multiply the value by 1883 to get the desired result.

Note that value is a reserved keyword here to indicate the incoming value you'd like to transform.

You can also do the same thing on the publish side to transfer it back to ppm. In this case, you would need to divide by 1883.

airquality/no2|value / 1883

Transformer Keywords

There are two additional special keywords you may use within topic and value transformers.

properties

The properties object allows you to access the stored properties for the current accessory using "dot" notation.

Let's say, for example, that you wanted to transform the current mode (topicGetCurrentHeatingCoolingState) for a Heater/Cooler based on the current temperature. You can get the current temperature with properties.CurrentTemperature:

heatercooler/mode|properties.CurrentTemperature > 72 ? 'COOL' : 'OFF'

This says that if the current temperature is greater than 72, then the mode should be 'COOL'; otherwise, it should be 'OFF'.

It is also possible to set these properties, but altering properties can lead to unintended behavior.

Instead, you can get and set using arbitrary property names, i.e., properties.hello='world'.

storage

The storage object allows you to share data between accessories that are using the same MQTT broker. As with properties, you can use "dot" notation to get or set primitive values with arbitrary property names, i.e., storage.foo='bar'

Both JSONPath + Transformer

You may combine both JSONPath and Transformer notation into a single entity

airquality$.no2|value * 1883