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:

• 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

• Cloud MQTT

• Google Cloud

• MyQTTHub

• Heroku CloudMQTT

• HiveMQ

• Azure

• AWS

*[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

• JS: https://github.com/mqttjs/MQTT.js

• Explorer: https://mqtt-explorer.com/

Example configuration for explorer

MQTT Client Configuration