====== MQTT ======

In Mervis IDE, the MQTT protocol is technically implemented as a **client driver**. However, because Mervis RT can both publish (provide) and subscribe to (receive) data, it effectively operates in both ways. It is included in the server protocols section because it acts as a data provider to other systems via the central Broker.

Data is organized using "Topics," which are hierarchical structures that act as paths where data is published. For example, a base folder could be ''building/hvac'', with sub-folders like ''building/hvac/temp''. 

//(Note on Organization: Mervis supports Prototypes to help you systematically organize your naming conventions across large projects. While we won't cover them deeply here, they are highly recommended for keeping your variables clean.)//

===== Step 1: Setting Up the Broker Connection =====

First, we need to establish the communication link between your Mervis device and the MQTT broker.

{{:en:mervis-ide:35-help:mqtt1.png?400|Setting the TCP and MQTT device parameters}}

==== 1. Configure TCP Parameters ====
  * **For Testing**: You can point Mervis to a public broker like ''broker.emqx.io'' on port 1883. Please note: This is for testing only and should never be used for production data.
  * **For Production (Crucial)**: Use encrypted and authenticated communication. Set your private broker's address, enable TLS/SSL, and use port 8883.

==== 2. Configure Device Parameters ====
  * Make sure you have chosen the correct MQTT version for your application (e.g., MQTT v5.0).
  * Define your Client ID (e.g., MervisClient). Typically, there would be API access for credentials if your broker requires a login.
  * Set your Base Topic (Main Data Folder) to ''building/hvac''.

**Useful Macros**
When setting up your Client ID or Topics, you can use case-insensitive macros to automatically pull in system data. Using these ensures you have the full context without typing repetitive names.

^ Macro ^ Description ^
| ''%%ClientId%%'' | Injects the defined MQTT Client ID. |
| ''%%PlcName%%'' | Injects the assigned name of the PLC. |
| ''%%system.rtc%%'' | Injects the system's Real-Time Clock (local time). |
| ''%%system.rtcutc%%'' | Injects the system's Real-Time Clock in Coordinated Universal Time (UTC). |

==== 3. Set a Sensible Read/Write Interval (CRITICAL) ====
  * By default, the Read/Write interval might be set to 0ms. 
  * You must change this to a sensible interval (e.g., 1m or 2m). 
  * Leaving it at 0ms will flood the broker and constantly throw communication errors.

===== Step 2: Organizing Read and Write Groups =====

Mervis RT organizes communication by separating incoming data from outgoing data.

{{:en:mervis-ide:35-help:mqtt2.png?600|The Variable Browser showing datapoints cleanly separated into Read_Group and Write_Group}}

==== 1. Read Group (Subscribing) ====
Mervis RT uses Read Groups to subscribe to a topic, parse the document, and update values in your program. 

{{:en:mervis-ide:35-help:mqtt3.png?300|Read Group Properties}}

  * Create a group named ''Read_Group''. 
  * Set your Payload Format based on what the broker is sending. 
  * For reading and subscribing, Mervis natively supports parsing JSON, CSV, and Plain Text.

==== 2. Write Group (Publishing) & Templates ====
Mervis RT uses this group to create a document and send it out to the broker. 

{{:en:mervis-ide:35-help:mqtt4.png?300|Write Group Properties}}

  * Create a group named ''Write_Group''. 
  * Here, you define a Publish Template to control exactly how the outgoing data structure will look. 
  * You can write whatever you want in this template field—JSON, CSV, XML, etc. 
  * While the ''%%foreach%%'' control block is incredibly useful for looping through multiple variables, it is not mandatory. You can write out your template entirely manually if you prefer.

===== Step 3: Creating and Mapping Data Points =====

//(Note for new users: The process of mapping data points and handling Enums here is a general feature of Mervis client channels. If you have used Modbus or other protocols in Mervis before, this process will be very familiar.)//

==== 1. Map Incoming Variables ====
Inside your ''Read_Group'', create a data point for your input.

{{:en:mervis-ide:35-help:mqtt5.png?300|Mapping incoming MQTT data to the internal variable}}

  * **Map to Internal Variable**: Set ''IO => ST'' to your target variable.
  * **Data Locator**: Use the Value Path (e.g., ''$.temp'' for JSON) to tell Mervis exactly where to look in the incoming payload. If using CSV, use the Index property to specify the exact position of the value (using a 1-based index).
  * **Skip Missing Data**: Set Ignore Missing Data to True. This ensures that if a value is missing from the payload, the system simply skips it without throwing a communication fault.

==== 2. Map Outgoing Variables ====
Inside your ''Write_Group'', create a data point for your result (e.g., Total).

{{:en:mervis-ide:35-help:mqtt6.png?300|Mapping the calculated internal variable out to the MQTT broker}}

  * **Map to Output**: Map your internally calculated variable to the output by setting ''ST => IO'' to your target variable. 
  * It is important to emphasize that the variable you are mapping here needs to be a global variable to function properly.

===== Step 4: Function Block Logic =====

With your communication variables mapped, you can use them in standard IEC 61131-3 logic. 

{{:en:mervis-ide:35-help:mqtt7.png?600|A simple FBD program adding logic block inputs together}}

In a practical application, you might map two similar MQTT inputs (for example, adding ''Power_Zone_1'' and ''Power_Zone_2'' together to calculate a facility's total power consumption). The math block computes the sum, and the result is written directly to your global MQTT output variable (''Calculated_Total'').

===== Step 5: Testing the Setup with MQTTX =====

To ensure everything is working smoothly, use a desktop client like MQTTX to simulate real-world data traffic. This lets you see the direct results of the custom Publish Templates you created in Step 2.

{{:en:mervis-ide:35-help:mqtt8.png?600|Simulating sensor data in MQTTX}}

  * **1. Connect**: Connect MQTTX to the broker (''broker.emqx.io:1883'').
  * **2. Subscribe**: Subscribe to ''building/hvac/#'' so you can monitor all data passing through your base topic.
  * **3. Simulate Input**: Publish a payload to ''building/hvac/temp''. Use the format you configured (e.g., JSON: ''{"temp":5,"humidity":50}'' or a standard CSV line).
  * **4. Verify Output**: Watch the incoming messages in MQTTX. You should see Mervis instantly publish a new message containing the calculated value formatted exactly as your template defined.