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.)

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

• 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.

• 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.

• 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.

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

Mervis RT uses Read Groups to subscribe to a topic, parse the document, and update values in your program.

• 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.

Mervis RT uses this group to create a document and send it out to the broker.

• 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.

(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.)

Inside your Read_Group, create a data point for your input.

• 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.

Inside your Write_Group, create a data point for your result (e.g., Total).

• 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.

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

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).

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.

• 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.