MQTT

MQTT (Message Queue Telemetry Transport) is an ISO standard publish-subscribe-based messaging protocol, which is becoming the de-facto standard protocol for accessing IoT data from the internet.

Overview

Publishing means that data is uploaded to a well-defined place (called topic) on a central server (called message-broker). Subscribing means that data is downloaded from a topic of the message broker once it was published there. Hence, MQTT is an event-driven communication protocol notifying a subscriber once a data message has arrived on its topic.

This article describes the properties of an MQTT client connection to an external broker. To get information about topic mapping on the internal Connectware MQTT broker see the article Cybus::Mapping.

Usage

To send or receive data via MQTT, a connection resource of the protocol MQTT has to be defined. The most simple configuration requires a host name of the broker and the port of the broker. The full list of connection parameters which can be configured is available at Connection Properties.

To receive data from a broker, an endpoint resource with the property subscribe has to be defined. In the other direction, to send data to the broker, an endpoint with the property write has to be defined. An endpoint can only have one of the two properties. The properties which define the respective configuration are listed under Endpoint Properties.

Connection Properties

host (string, required)

The host name of the broker

Example: "test.mosquitto.org"

port (integer)

The port of the broker

Default: 1883

Example: 1883

scheme (string, enum)

The protocol scheme

This element must be one of the following enum values:

• mqtt

• mqtts

• tcp

• tls

• ws

• wss

Default: "mqtt"

Example: "mqtt"

url (string)

Complete connection string (takes precedence over host, port and scheme)

Examples: "mqtt://some.host.org:1883", "mqtts://some.host.org:8883"

keepalive (integer)

Time to keep the connection alive without any message send (in seconds)

Default: 0

Example: 60

reschedulePings (boolean)

Whether to reschedule pings after sending packets

Default: true

clientId (string)

The client id used when connecting to the broker

Example: "mqttjs_13462"

connectionId (string)

DEPRECATED - this is probably going to be removed soon, right? The id of the connection

Example: "MQTT"

protocolVersion (integer)

The protocol version used for the connection to the broker

Example: 4

clean (boolean)

Set to false to receive QoS 1 and 2 messages while offline

Default: true

reconnectPeriod (integer)

Interval between two reconnections (milliseconds)

Default: 1000

connectTimeout (integer)

Time (in ms) to wait before a CONNACK is received

Default: 30000

username (string)

The username required by your broker, if any

Example: ""

password (string)

The password required by your broker, if any

Example: ""

queueQoSZero (boolean)

If connection is broken, queue outgoing QoS zero messages

Default: true

filterOverlappingWildcardSubscriptions (boolean)

If true, wildcard subscriptions that are overlapping with other subscriptions will be filtered to avoid additional duplicated messages, additional to the duplicates the broker is sending. Can be set to true if the MQTT broker already sends multiple duplicates on overlapping subscriptions (e.g. vernemq) but only if you need at most one target topic or Mapping, otherwise some targets do not get the message anymore. Should be left at false for brokers that do not do this (e.g. mosquitto).

Default: false

trustAllCertificates (boolean)

If true, all broker certificates will be accepted, regardless of whether they can be validated or not. Use this option if self-signed server certificates should be accepted, or if there are other reasons which prevent this client to validate the certificates.

Default: false

mutualAuthentication (boolean)

If true, a full certificate chain including client certificate is expected to connect properly with validated certificates.

Default: false

caCert (string)

The root CA certificate as Base64 encoded PEM file content

clientCert (string)

The device certificate as Base64 encoded PEM CRT file content

clientPrivateKey (string)

The device private key as Base64 encoded PEM CRT file content

will (object)

Properties of the will object:

topic (string, required)

Last will topic (LWT)

Example: "last/will/topic"

payload (string, required)

Last will message payload

Example: ""

qos (integer, enum)

Last will message quality of service

This element must be one of the following enum values:

• 0

• 1

• 2

Default: 0

Example: 1

retain (boolean)

Retain last message (Last-Value-Cached)

Default: false

contentType (string)

String describing the content of the Application Message (mqtt5 only)

correlationData (string)

The Correlation Data is used by the sender of the Request Message to identify which request the Response Message is for when it is received (mqtt5 only)

messageExpiryInterval (number)

Lifetime in seconds of the Will Message (mqtt5 only)

payloadFormatIndicator (boolean)

Will Message is UTF-8 Encoded Character Data or not (mqtt5 only)

responseTopic (string)

String which is used as the Topic Name for a response message in a request/response context (mqtt5 only)

userProperties (object)

Application specific key value pairs (mqtt5 only)

willDelayInterval (number)

Delay in seconds until the server publishes the Client’s Will Message (mqtt5 only)

authenticationMethod (string)

Identifier of the Authentication Method (mqtt5 only)

authenticationData (string)

Binary data containing authentication data (mqtt5 only)

maximumPacketSize (number)

Maximum Packet Size in bytes the Client is willing to accept (mqtt5 only)

receiveMaximum (number)

The Client uses this value to limit the number of QoS 1 and QoS 2 publications that it is willing to process concurrently (mqtt5 only)

requestResponseInformation (boolean)

The Client uses this value to request the Server to return Response Information in the CONNACK (mqtt5 only)

requestProblemInformation (boolean)

The Client uses this value to indicate whether the Reason String or User Properties are sent in the case of failures (mqtt5 only)

sessionExpiryInterval (number)

Session Expiry Interval in seconds (mqtt5 only)

topicAliasMaximum (number)

The Client uses this value to limit the number of Topic Aliases that it is willing to hold on this Connection (mqtt5 only)

userProperties (object)

Application specific key value pairs (mqtt5 only)

Endpoint Properties

topic (string, required)

Any valid topic name addressing a single data-point

Example: "path/of/endpoint"

qos (integer, enum)

Quality of service (QOS) level for this subscription at the external MQTT broker. Watch out: If the internal message forwarding should continue with the same non-zero QOS level, this must additionally be configured by specifiying the same qos value also in the general Endpoint properties (one level higher in the commissioning file), and in the subscribe and publish side of each involved Mapping, too.

This element must be one of the following enum values:

• 0

• 1

• 2

Default: 0

Example: 1

retain (boolean)

Whether the last message should be retained (last-value-cached) on the broker (default: false)

Default: false

Example: false

burstInterval (integer)

Interval in ms during which incoming data-point values are aggregated (default: 0 = no aggregation)

Default: 0

Example: 1000

nl (boolean)

Controls whether a message should be forwarded to a connection with a ClientID equal to the ClientID of the publishing connection

Default: true

rap (boolean)

Controls whether a message with the retain flag set to true maintains the flag when being forwarded

Default: false

rh (number, enum)

Controls whether retained messages are sent when subscription is established

This element must be one of the following enum values:

• 0

• 1

• 2

Default: 0

properties (object)

MQTT v5 specific properties

Properties of the properties object:

correlationData (string)

The Correlation Data is used by the sender of the Request Message to identify which request the Response Message is for when it is received

contentType (string)

String describing the content of the Application Message

messageExpiryInterval (number)

Lifetime in seconds of the Application Message

payloadFormatIndicator (boolean)

Indicates whether the payload is UTF-8 encoded or not

responseTopic (string)

String which is used as the Topic Name for a response message in a request/response context

subscriptionIdentifier (number)

Represents the identifier of the subscription

topicAlias (number)

A Topic Alias is an integer value that is used to identify the Topic instead of using the Topic Name. This reduces the size of the PUBLISH packet

userProperties (object)

Application specific key value pairs

Output Format on Write

The MQTT protocol does not output results to the /res endpoint.

Output Format on Read

When data is read from MQTT, via a subscription Endpoint, the messages arriving to the target MQTT server are passed through unmodified.

Input Format on Write

When data is written to MQTT, via a write Endpoint, no special format is required and data is published to the target MQTT server unmodified.

Duplicates on overlapping subscriptions

In the case of multiple overlapping topic subscriptions with wildcards, there is a somewhat unexpected behaviour causing duplicate messages. As an example, if there is one subscription (such as a Cybus::Mapping) to topic topic/something and another to topic/#, each connected target (Mapping or Endpoint) will then receive two messages instead of one. This is caused by the behaviour of the internal MQTT broker and cannot be avoided, as it is an allowed behaviour of the MQTT 3.1 specification.

Example Configuration

The following example demonstrates how to configure a simple MQTT connection and endpoint that subscribes to the topic some/test1.

Download: mqtt-test1.yml

---
description: >

  MQTT Connection Test

metadata:

  name: MQTT Connection Test

parameters:

  mqttHost:
    type: string
    description: "IP or hostname of the broker"

  mqttUsername:
    type: string
    description: "MQTT Username"

  mqttPassword:
    type: string
    description: "MQTT Password"

resources:

  mqttConnection:
    type: Cybus::Connection
    properties:
      protocol: Mqtt
      connection:
        host: !ref mqttHost
        port: 8883
        scheme: mqtts
        username: !ref mqttUsername
        password: !ref mqttPassword
        trustAllCertificates: false # choose true to allow self-signed certificates

  testEndpoint1:
    type: Cybus::Endpoint
    properties:
      protocol: Mqtt
      connection: !ref mqttConnection
      subscribe:
        topic: some/test1