MQTT Protocol

MQTT, which stands for MQ Telemetry Transport, is a lightweight communication protocol that targets low-power devices with limited connectivity. MQTT is a mechanism that allows for:

MQTT Clients

WEGnology provides MQTT clients that easily wrap up the communication between WEGnology and a device for the following languages:

If you are not working in one of the languages above, you can use the WEGnology MQTT Broker directly with any MQTT client. See below for more information.

Learning MQTT

The core concept of MQTT involves publishing and subscribing to topics. Clients can publish any data they choose to any topics they choose. Other clients can then subscribe to those topics to receive that data.

What facilitates this communication is a central service called a message broker. All clients open a connection to the message broker and the broker is responsible for properly routing messages to subscribers.

The WEGnology Message Broker

In order to support the existing MQTT implementations, WEGnology provides an MQTT message broker that can be used for any arbitrary topics and payloads. To make use of WEGnology features including data collection, visualization, and workflows, WEGnology provides an opinionated MQTT implementation that must be followed.

The WEGnology Message Broker can be reached using several transports:

  • TCP — mqtt://broker.app.wnology.io:1883
  • TLS — mqtts://broker.app.wnology.io:8883
  • WebSockets — ws://broker.app.wnology.io:80
  • TLS WebSockets — wss://broker.app.wnology.io:443

Note: For TLS connections, WEGnology only supports TLS 1.2 or TLS 1.3. SSL 3, TLS 1, and TLS 1.1 are NOT supported (they are no longer considered secure). Certain older devices may only support older versions of TLS by default or without upgrades. If you run into issues connecting your device to WEGnology over TLS, ensure that your device supports either TLS 1.2 or TLS 1.3.

Broker Authentication

WEGnology requires the client ID, username, and password fields be correctly set on all MQTT connect calls:

  • client id—Must be set to a valid Device ID that is already registered with the WEGnology Platform.
  • username—Must be set to a WEGnology Access Key.
  • password—Must be set to a WEGnology Access Secret, which is generated when creating an Access key.

For example, a connect call using the JavaScript MQTT client is displayed below:

var client = mqtt.connect('mqtts://broker.app.wnology.io', {
  clientId: 'my-device-id',
  username: 'my-access-key',
  password: 'my-access-secret',
})

Access Control

To connect your devices to the WEGnology MQTT Broker, you must use Access Keys. By default, access keys only allow access to the device-specific topics (e.g. state and commands for every device you have allowed.

For additional control, see Additional MQTT Topics Access.

Message Limits

WEGnology’s MQTT broker usage is subject to a few limits:

  • 30 messages in a 15-second window per topic (or, on average, two per second).
  • 300 messages in a 15-second window per client connection (or, on average, 20 per second).
  • 300 new client connections in a 15-second window per application (or, on average, 20 per second).
  • 1MB per message.

Note: In this context, a “client connection” is any type of device that has authenticated against and is connected to the WEGnology MQTT broker.

Limits are applied individually per direction. For example, a device may receive two messages per second and publish two messages per second on the same topic without exceeding the per-topic rate limit.

If a device exceeds either of the message rate limits, it will be banned for 30 seconds from the broker. If the device reconnects and exceeds the rate limits again within 15 minutes, the ban time will double. This ban time will continue to double after each violation until a maximum ban time of 1 hour is reached. If at any point the device, after connecting, does not violate message limits for 15 minutes, the ban time for the next violation resets to 30 seconds.

Root CA Certificates

If your device fails to connect over a secure channel (via mqtts or wss protocols) with a certificate error, you may need to either update the root certificate package on your device (often named ca-certificates), or manually add the the certificate authorities that WEGnology uses for secure connections to our MQTT broker. If you need to manually add the certificate authorities, the two required certificates to add are the following:

MQTT Version and Limitations

WEGnology supports MQTT version v3.1.1 with the following exceptions:

  • Clients may only subscribe to topics using QoS 0. Clients may publish messages to the broker using QoS 0 or QoS 1.
  • Retained messages are not supported.
  • CleanSession 0 is not supported.
  • Maximum message payload size is 1MB.

WEGnology MQTT Topics

A WEGnology topic is anything that starts with wnology. Messages published to WEGnology topics gain access to the full features of the WEGnology Platform, including data collection, visualization, and workflows.

For WEGnology to properly parse and understand these messages, a defined JSON-based payload format must be followed.

Publishing Device State

Device State is likely the most commonly published message. When thinking in terms of sensor data, the device state is typically the value of one or more sensors.

State Topic Form

wnology/DEVICE_ID/state

State Payload Form

The payload (message body) of a state report is a JSON object that takes the following shape:

{
  "data" : {
    "aStringAttribute": "The attribute value",
    "aNumberAttribute": 42
  },
  "time": "2022-10-27T12:34:56.789Z",
  "flowVersion": "ver 1.0",
  "meta": {
    "firstBoot": true
  }
}

  • data (Required): An object whose keys are device attribute names, and the value of each key is the telemetry data to record for that attribute.

    • Any attribute (object key) that does not have an attribute of the same name configured on the device will be ignored.
    • Each value’s data type must match the attribute data type as it is configured on the device. If the provided value cannot be parsed to match the attribute’s data type, that value will be ignored and will not be written to the time series database.
  • time (Optional): The timestamp at which to record the state report’s attribute values. When not included, this defaults to the current time. The value can be sent in several time formats, and the inclusion of a timestamp can be beneficial when batch reporting data, overwriting previously recorded data, or reporting historical data.

  • flowVersion (Optional): Specifies which workflow version to run when triggered by the payload. For each workflow containing a Device: State Trigger targeting the reporting device …

    • If flowVersion is included, any Application Workflow with a version matching the provided name will fire - assuming the version has a Device: State Trigger targeting the reporting device. If no version of a workflow matching the provided flowVersion is found, no version of that workflow will fire.
    • If flowVersion is not included, the default version of any Application Workflow will fire if that default version includes a Device: State Trigger targeting the reporting device.
  • meta (Optional): Additional information to expose on the initial payload of any Device: State Triggers that fire because of the state report. This may take any shape – string, object, number, etc. The value is not recorded with the state report; it is only available in these workflow payloads and cannot be retrieved later.

Publish State Example

You’ll generally have an attribute for each sensor attached to your device. For example, if a device with ID 575ecf887ae143cd83dc4aa2 has a temperature sensor, you might report a state that has an attribute named “temperature” by publishing to the topic below with the following payload:

wnology/575ecf887ae143cd83dc4aa2/state
{
  "data": {
    "temperature": 72
  },
  "time": { "$date": "2016-11-04T19:42:06.710Z" }
}

When a device publishes data in this format, WEGnology automatically stores the data and makes it available in our Dashboards as well as exposing it through Workflows. The attributes you send must be configured on the device before WEGnology will accept the data.

Subscribing to Commands

Device Commands instruct your device to perform a specific action. Commands are typically initiated using WEGnology Workflows. Commands include a name and an optional payload.

Command Topic Form

wnology/DEVICE_ID/command

Payload Topic Form

{
  "name": "command-name",
  "payload": {}
}

name—Command name.

payload—Any JSON value that provides necessary arguments to your command.

Commands do not have to be pre-registered with WEGnology for them to be received. What commands your device supports is entirely up to your specific application and your device’s firmware.

Example Command Subscription

Below is a command example that instructs a thermostat associated with the device ID 575ecf887ae143cd83dc4aa2 to set itself to a specific temperature. The following payload is published on the topic below, and the device is listening on that topic for command messages:

wnology/575ecf887ae143cd83dc4aa2/command
{
  "name": "set-temperature",
  "payload": {
    "temperature": 72
  }
}

Custom Topics

The WEGnology Broker also supports custom topics. Custom topics must be valid MQTT topics, and they cannot be an MQTT system topic (topics that start with “$SYS”) or a WEGnology device-specific topic. Further, they cannot be topics that begin with ’$‘. For example, $myTopic/subtopic is not an accepted custom topic.

Example:

alert/machine

Custom topics can trigger workflows with the MQTT Trigger, and you can publish to custom topics using the MQTT Output Node.

Custom Topic Access Control

By default, access keys only allow access to the WEGnology device-specific topics (e.g. state and commands) for every device you have allowed. Optionally, you can give access to all custom topics or specific custom topics. See Additional MQTT Topics Access for more information.

Wildcard Topics

The WEGnology Broker supports wildcard topics. Both single-level and multi-level wildcards are supported in Application Workflows:

Single-level: custom/+/temperature

Multi-level: custom/#

Gateway Edge Agent MQTT Broker

The Gateway Edge Agent exposes a local MQTT broker for local machine-to-machine (M2M) communication, or to trigger Edge Workflows using the MQTT Trigger, which can then process and forward sensor data to the cloud.

You may learn more in the Gateway Edge Agent broker documentation.

Was this page helpful?

Still looking for help? You can also search the WEGnology Forums or submit your question there.