The Message Queuing Telemetry Transport (MQTT) is a lightweight, publish-subscribe network protocol that transports messages between devices. The MQTT protocol defines two types of network entities: a message broker and a number of clients. An MQTT broker is a server that receives all messages from the clients and then routes the messages to the appropriate destination clients. Users are required to setup their own MQTT servers and head ends. This FAQ does not cover that part of an MQTT implementation.
To get started with MQTT in the cloud you should first upload a certificate to be used for authentication with the MQTT server. Certificates can be uploaded through the Key store view located under the Site section of grid view. An MQTT server may not require a certificate but typically utilise them.
From there it is very simple and straight forward to upload a certificate. To create a new row just type in a label for the certificate in the bottom row. Once created the upload cell should become editable. Begin editing the upload cell by double clicking or pressing the return key whilst the cell is highlighted to bring up the file explorer. Navigate and select the certificate you want to upload and click open. You should see the Key type, Fingerprint and Length columns become populated with data. This means the upload was successful.
A valid certificate must meet the following criteria:
- It must be in a valid x509 format
- It must be in a PEM certificate container format
- It must contain a Subject Alternative Name (SAN) section which (currently) can only contain IP addresses
After your certificate is successfully uploaded to the cloud, MQTT settings can then be setup from the MQTT view under the Add-ons section. MQTT needs to be enabled by clicking the first checkbox in order to change the subsequent settings. You can only enable MQTT if you have a green tick under the license column. If you have a red cross then you must first purchase an MQTT license by contacting email@example.com. Once enabled you can then configure the MQTT settings.
The Host and Port columns should match the IP address and port that the MQTT server is being hosted on. This will be the endpoint that the control system communicates with and should be setup by the user.
If SSL enabled is checked then data that is sent over MQTT will use SSL encryption for more secure communications. There are two modes that MQTT can be set to. Normal will send MQTT to multiple endpoints/topics. Single endpoint will send MQTT data to a single endpoint/topic.
The certificate you uploaded from the Key store view will appear here. This is typically required to authenticate with the MQTT server though it may not always be needed. If you want to clear the certificate that is currently stored on the control system you can press the Delete button whilst the cell is selected.
If a username and password is required by your MQTT server then you will set those here. The password is not seen and is not sent over the network when reading data from the cloud. If your server does not require a username or password and you want to clear it from the control system you can press the Delete button whilst the cells are selected.