MQTT Integration
Guide on integrating PlaceOS with MQTT messaging
Last updated
Guide on integrating PlaceOS with MQTT messaging
Last updated
PlaceOS supports publishing module state information via MQTT. This provides environment information to external systems such as
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.
Changes to module state propagate in real time. All change messages share the following topic structure:
In this structure, each section is a unique identifying tag to represent part of the system.
<org>: Organization 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 (_).
The payload is the value of the status variable paired with a timestamp
Metadata is available for building, level, area, system and driver tiers. The format is this persistent topic:
Metadata payloads are JSON objects that contain model info for the publishing entity. This includes the human-readable "friendly name", e.g.
Wildcards can replace any topic level to catch state information across different services. Some common examples are:
All events within a building:
Connected status of all devices:
Power status for all displays:
Call status information for Cisco VC endpoints (dep-123 is the driver ID for Cisco VC):
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
PlaceOS can integrate with MQTT Brokers including the major service providers listed below.
*[MQTT]: Message Queuing Telemetry Transport *[VC]: Video Conferencing
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
Regular users have read and subscribe permissions.
We've found the following clients useful
Example configuration for explorer
<bld>: ID
<lvl>: ID
<area>: ID
<sys>: ID
<drv>: ID
<mod>: ID
Example: MQTT Websocket Client ()
JS:
Explorer:
