# 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 guide 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 [Cybus::Mapping](https://docs.cybus.io/2-0-6/documentation/services/service-commissioning-files/resources/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](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/mqtt/mqttendpoint).

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](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/mqtt/mqttendpoint).

[Connection Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/mqtt/mqttconnection)

[Endpoint Properties](https://docs.cybus.io/2-0-6/documentation/industry-protocol-details/mqtt/mqttendpoint)

#### 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 behavior causing duplicate messages. As an example, if there is one subscription (such as a [Cybus::Mapping](https://docs.cybus.io/2-0-6/documentation/services/service-commissioning-files/resources/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 behavior of the internal MQTT broker and cannot be avoided, as it is an allowed behavior of the MQTT 3.1 specification.

## Service Commissioning File Example

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

{% file src="<https://639096190-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfDpOJO2upcq5EpoSahvK%2Fuploads%2Fgit-blob-ad875fa7022fc32f1e61b653ac730cddebdbf87b%2Fmqtt-test1.yml?alt=media>" %}

{% code title="mqtt-test1.yml" lineNumbers="true" %}

```yaml
---
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
```

{% endcode %}