MQTT Integration

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:

Replacing the value with a hashed version of itself
Masking the value
Dropping the associated event

Cloud Brokers#

PlaceOS can integrate with MQTT Brokers including the major service providers listed below.

MQTT brokers' logos