MQTT

Integration Key: mqtt

TIP

If you are looking to integrate with Home Assistant Coreopen in new window via MQTT take a look at the Home Assistant integration instead.

The MQTT integration will send messages with room-assistant entity update information to an MQTT brokeropen in new window.

Message Format

Entity updates are sent into unique topics for each entity, grouped by instance name and entity type. The topic format is baseTopic/instanceName/entityType/entityId.

Each message will have the following properties:

  • entity - This includes the whole current entity state, like you would see it in the API.
  • hasAuthority - This boolean value shows whether this update message comes from an entity that has authority over the entity. It will be false for distributed entity updates that are emitted from non-leader instances. You may use this to respect the room-assistant leader in your own automations, but you can of course also just pick a single instance to work off.

Optionally the message will also include the following properties:

  • diff - This is an array of changes to the previous entity state. Each array item includes a path to the changed property based off the entity JSON root, the oldValue and the newValue. Could be used to monitor for specific changes only. This property will not be included when instances emit an entity refresh (e.g. after re-connecting to the MQTT broker).
Example Message

This message could have been posted to room-assistant/entity/living-room/bluetooth-low-energy-presence-sensor/ble-some-id:

{
  "entity": {
    "attributes": {
      "distance": 3.6,
      "lastUpdatedAt": "2021-02-28T14:17:33.141Z"
    },
    "id": "ble-some-id",
    "name": "Something Room Presence",
    "distributed": true,
    "stateLocked": true,
    "distances": {
      "bedroom": {
        "lastUpdatedAt": "2021-02-28T14:17:32.605Z",
        "distance": 9.4,
        "outOfRange": false
      },
      "living-room": {
        "lastUpdatedAt": "2021-02-28T14:17:33.141Z",
        "distance": 3.6,
        "outOfRange": false
      }
    },
    "timeout": 180,
    "measuredValues": {
      "bedroom": {
        "rssi": -79.81192947697268,
        "measuredPower": -59
      },
      "living-room": {
        "rssi": -70.40174705168248,
        "measuredPower": -59
      }
    },
    "state": "living-room"
  },
  "diff": [
    {
      "path": "/measuredValues/living-room",
      "oldValue": {
        "rssi": -73.37709762753302,
        "measuredPower": -59
      },
      "newValue": {
        "rssi": -70.40174705168248,
        "measuredPower": -59
      }
    },
    {
      "path": "/distances/living-room",
      "oldValue": {
        "lastUpdatedAt": "2021-02-28T14:17:32.308Z",
        "distance": 3.8,
        "outOfRange": false
      },
      "newValue": {
        "lastUpdatedAt": "2021-02-28T14:17:33.141Z",
        "distance": 3.6,
        "outOfRange": false
      }
    }
  ],
  "hasAuthority": true
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

To get started with your automations based on these topics it is recommended to just explore the data provided in the topics using e.g. a GUI MQTT tool.

Settings

NameTypeDefaultDescription
mqttUrlStringmqtt://localhost:1883Connection string for your MQTT broker.
mqttOptionsMQTT OptionsAdditional options for the MQTT connection.
baseTopicStringroom-assistant/entityBase for the entity update topics.
qosNumber0Quality of Service level that the messages will be sent with.
retainBooleanfalseWhether to mark the messages as to retain or not.

MQTT Options

NameTypeDefaultDescription
usernameStringUsername for authentication
passwordStringPassword for authentication
rejectUnauthorizedBooleantrueWhether MQTTS connections should fail for invalid certificates or not. Set this to false if you are using a self-signed certificate and connect via TLS.
Example Config
global:
  integrations:
    - mqtt
mqtt:
  mqttUrl: mqtt://localhost:1883
  mqttOptions:
    username: youruser
    password: yourpass
  retain: false
1
2
3
4
5
6
7
8
9