MQTT in practice on Poseidon2/Damocles2

How MQTT works

MQTT works at the TCP layer in a way similar to SNMP Traps. There is no request-response communication; instead, data are sent ("published") and acknowledged. This reduces network load: individual “input” devices (sensors, detectors etc.) actively send only short TCP messages to a specified address (to a “broker”).

The advantage is that the input devices only transmit whenever they need to – in regular intervals, or according to other manufacturer-specified criteria (input closed or open, a threshold exceeded, a value increase or decrease, etc.).
Each message begins with a “Topic” that identifies, characterizes or groups the data.

Broker

A MQTT broker primarily acts as a server, that is, it receives and stores data. However, it can also act as a client (input device) towards other brokers and forward data to all subscribed subscribers. Such a subscriber can be, for example, a web service, an application, or another broker.

End devices send data to specified broker addresses, subscribers subscribe to brokers (just like customers sign up to receive e-mail newsletters). When a broker receives a message with a Topic corresponding to a subscription, the message is stored and distributed to the subscribers.

Topic

The MQTT topic is always a text string. The slash (/) sign can be used to form a tree structure. The topic can look like this:

Poseidon/1-Wire/temperature/856275
GTS/nagano/room1/temperature

A subscriber can subscribe to a particular topic, to a tree branch, or to the entire tree.
The following wildcard characters can be used in the topic: “#”, “+” and “$”.

• “+” stands for a whole level (Poseidon/+/temperature/856275).
• “#” stands for several levels (Poseidon/#);
  „#“ can only be used at the end of the string.
• Topics that begin with a “$” (dollar sign) are special – usually system topics.
• When a topic begins with “$”, it is a special topic (such as $SYS/broker/uptime).

The Topic also includes a QoS flag that specifies whether the message must be delivered. 0 means that successful delivery is not required; 1 allows duplicate delivery (if there is no acknowledgement, the message is resent); and 2 indicates that successful delivery is required but without any duplicity.

Payload

MQTT payload is the actual message content. The message content is normally assumed to be textual. However, the MQTT protocol is not restrictive and it is up to the broker and the subscribers to handle the payload. So, the payload can be binary, or can consist e.g. of images. Message size and type are specified by the broker. Many brokers prefer XML or JSON because these formats are less resource-consuming for larger volumes of data than many short “topic” messages.

Security

By default, the MQTT protocol communicates via TCP at port 1883. Security can be enhanced with SSL/TLS; in this case, the communication takes place at port 8883.

MQTT in Poseidon2 and Damocles2

Poseidon2 and Damocles2 units include a MQTT client implementation with optional SSL support.

• MQTT enable – Enables or disables MQTT support in Poseidon2 and Damocles2 devices.
• Server – IP address or domain name of the MQTT broker (server).
• Port – TCP port where the broker listens.
• Username – Username for authenticating TCP communication.
• Password – Password for authenticating TCP communication.
• Secure SSL mode – Enables/disables SSL mode.                           
• Client ID – ID of the client for use in MQTT. Users enter their IDs themselves in their profile. A user can use multiple IDs in order to filter messages in their account.                        
• Publish Period – Period for transmitting measured data. In this the interval (in seconds) Poseidon2 periodically connects to the broker to transmit the values.
• Topic Prefix Name – Topic prefix. The entire Topic is then formed by concatenating the prefix + the topic below.
• Publish – Selects information to be sent.
• User Topic umožňuje vytvoření uživatelského topicu (zprávy) obsahujícího data jaké požaduje uživatelská aplikace (JSON, XML, CSV a pod.). K tomu slouží makropříkazy uvedené níže
  • User Topic Enable – zapne zasílání uživatelské zprávy
  • Topic Name - Název zprávy
  • Topic Value – šablona uživatelské zprávy
  • Topic Test – náhled výsledné zprávy po přeložení maker

Macros for User topic:

%ID_IN_*% - Start of sequence of the inputs with firmly defined ID’s %ID_IN_END% - End of the fixed sequence of the inputs
%LOOP_IN% - Beginning of the sequence of the inputs that passes all ID’s %LOOP_IN_END% - End of the complete sequence of the inputs
%ID_OUT_*% - Start sequence of the outputs with firmly defined ID’s %ID_OUT_END% - End of fixed sequence of the outputs
%LOOP_OUT% - Start sequence outputs that passes all ID’s
%LOOP_OUT_END% - End of the complete sequence of the outputs
%ID_SENSOR_*% - Start sequence with sensors firmly defined ID’s %ID_SENSOR_END% - End of fixed sequence sensors
%LOOP_SENSOR% - Start sequence of sensors that passes all ID’s %LOOP_SENSOR_END% - End of the complete sequence of sensors
%VAL_ID% - Variable ID item
%VAL_NAME% variable name item
%VAL_VALUE% - variable values of the item
%VAL_STATE% - state variables of the item

Username and password are optional. For example, broker.mqttdashboard.com does not require them yet.

MQTT in practice

There are many public MQTT brokers where data can be sent and topics can be subscribed to. A list of the most well-known ones is available at: https://github.com/mqtt/mqtt.github.io/wiki/public_brokers

For our example, we have chosen broker.mqttdashboard.com. First, configure the Poseidon2 device:

Fill in the Server address, Port, Client ID (any value) and Topic Prefix Name (anything that can be used to distinguish the device). Using the Publish checkboxes, select the data to be published.
Then, Poseidon2 or Damocles2 needs to be restarted.  

Start the TT3 tool. It is essentially a MQTT Broker. It is available at: https://github.com/mqtt/mqtt.github.io/wiki/public_brokers

Set the broker (Server) address and Port (both values must be the same as in the Poseidon2), and a Client ID (must be different from the Poseidon Client ID). Then click Connect. The green status field in the lower right-hand corner will show Connected.

Then, in the Topic field, fil in the address that interests you. For example, “Poseidon2/#” means all messages whose Topic begins with Poseidon2/. Click Subscribe to start receiving messages.