MQTT Integration

Guide on integrating PlaceOS with MQTT messaging

PlaceOS supports publishing module state information via MQTT. This provides environment information to external systems such as Amazon MQTT Service

MQTT messages consist of a header and a payload and typically have low bandwidth usage. The header declares the topic of the message, and the payload carries data as key-value pairs. PlaceOS uses two types of message sent over MQTT: State Changes and Metadata.

State Change

Changes to module state propagate in real time. All change messages share the following topic structure:

placeos/<org>/state/<bld>/<lvl>/<area>/<sys>/<drv>/<mod>/<idx>/<state>

In this structure, each section is a unique identifying tag to represent part of the system.

<org>: Organization ID
<bld>: Building ID
<lvl>: Level ID
<area>: Area ID
<sys>: System ID
<drv>: Driver ID
<mod>: Module ID
<idx>: Module Index
<state>: State Key

On a state change, the module will publish a message with the payload containing the new state value as a JSON entity. The associated driver defines the structure and frequency of this state change.

Some systems may not have a building, level, or area. If they generate a state change, the missing topic level will be an underscore character (_).

State Change Payload

The payload is the value of the status variable paired with a timestamp

{
  "time": unix_integer_milliseconds,
  "value": "payload is a serialized json string"
}

Metadata

Metadata is available for building, level, area, system and driver tiers. The format is this persistent topic:

placeos/<org>/metadata/<id>

Metadata Payloads

Metadata payloads are JSON objects that contain model info for the publishing entity. This includes the human-readable "friendly name", e.g.

{
  "name": "Cisco VC"
}

{
  "name": "Level 24"
}

Wildcard Subscriptions

Wildcards can replace any topic level to catch state information across different services. Some common examples are:

All events within a building:

placeos/<org>/state/<bld>/#

Connected status of all devices:

placeos/<org>/state/+/+/+/+/+/+/+/connected

Power status for all displays:

placeos/<org>/state/+/+/+/+/+/Display/+/power

Call status information for Cisco VC endpoints (dep-123 is the driver ID for Cisco VC):

placeos/<org>/state/+/+/+/+/dep-123/+/+/call_status

Privacy

Some deployment requirements may include filtering of sensitive information. The system parses state changes for content such as email addresses or user IDs before they propagate. A match can lead to actions such as: