Search
⌃K

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.
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
*[MQTT]: Message Queuing Telemetry Transport *[VC]: Video Conferencing

Websocket MQTT API

PlaceOS provides an out of the box MQTT solution via the API, delivered over websockets using standard JWTs or X-API-keys for authentication.
Secure WSS available at the route /api/mqtt/ it expects the following MQTT authentication message details:
  • Username: users JWT token or X-API-Key
  • Password: users JWT token or X-API-Key
Example: MQTT Websocket Client (hivemq.com)
Regular users have read and subscribe permissions.

MQTT Clients

We've found the following clients useful
Example configuration for explorer
MQTT Client Configuration