Skip to content
Nodelets

Add an MQTT device

The MQTT driver reads and writes a device’s properties through an MQTT 3.1.1 broker, using topics written by hand in the definition.

What MQTT support covers

Section titled “What MQTT support covers”

MQTT support is limited for now. Check these before you start:

  • Properties only. An MQTT definition cannot declare actions or events.
  • No live values. An MQTT property cannot be observed, so it has no live values and no history.
  • No credentials or TLS. The bridge connects without a username or password and without TLS. Use a broker that accepts anonymous clients, on a network you trust.
  • Literal topics. Topics have no + or #, so each physical device needs its own definition.

Write the definition

Section titled “Write the definition”

Each property has a read binding, a write binding, or both.

  • A read publishes request.payload once to request.topic, then takes the value at reply.pointer from the next message on reply.topic that has a value there.
  • A write places the value at request.valuePointer and publishes once. An empty pointer sends the value itself, and /brightness sends {"brightness": value}. The write succeeds only when a message on confirm.topic carries the same value at confirm.pointer. For an object, every written field must be present and equal; extra fields do not prevent a match.

This definition drives one lamp through a bridge that publishes the lamp’s state on lights/porch and takes commands on lights/porch/set and lights/porch/get:

{
  "formatVersion": 1,
  "id": "porch-lamp",
  "title": "Porch lamp",
  "driver": "mqtt",
  "properties": {
    "state": {
      "type": "string",
      "enum": ["ON", "OFF"],
      "title": "Power"
    },
    "brightness": {
      "type": "integer",
      "minimum": 0,
      "maximum": 254,
      "title": "Brightness"
    }
  },
  "bindings": {
    "properties": {
      "state": {
        "readproperty": {
          "request": { "topic": "lights/porch/get", "payload": { "state": "" } },
          "reply": { "topic": "lights/porch", "pointer": "/state" }
        },
        "writeproperty": {
          "request": { "topic": "lights/porch/set", "valuePointer": "/state" },
          "confirm": { "topic": "lights/porch", "pointer": "/state" }
        }
      },
      "brightness": {
        "readproperty": {
          "request": { "topic": "lights/porch/get", "payload": { "brightness": "" } },
          "reply": { "topic": "lights/porch", "pointer": "/brightness" }
        },
        "writeproperty": {
          "request": { "topic": "lights/porch/set", "valuePointer": "/brightness" },
          "confirm": { "topic": "lights/porch", "pointer": "/brightness" }
        }
      }
    }
  }
}

Install it:

Terminal window
nodelets definition install porch-lamp.json

Add the device

Section titled “Add the device”
Terminal window
nodelets thing add

Choose the MQTT definition, give the device a name, and enter the broker address when asked: mqtt://10.0.4.5, or mqtt://10.0.4.5:1884 when the port is not 1883.

How the bridge decides what happened

Section titled “How the bridge decides what happened”
  • Only a message that arrives after a request starts waiting counts. A retained message, or one received before the publish, never answers a read or confirms a write.
  • A message that is not JSON, or that lacks the value, is ignored. A message over 256 KiB is discarded.
  • Every message is sent at QoS 0 with retain clear, and nothing is resent.
What happened Code Outcome
Broker unreachable, or session refused THING_UNAVAILABLE not-executed
No reply to a read before the deadline TIMEOUT not-executed
No confirmation of a write before the deadline, or the session dropped after the publish OUTCOME_UNKNOWN unknown

An unknown write may still happen. Some bridges queue a command for a device that is out of reach and run it when the device returns.

If the device’s messages carry no request ID, a read can take its value from a message that something else caused. That value is still the device’s latest reported one.

Section titled “Related”