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

===== The "Central Switchboard" Model =====

To understand how MQTT works in the Mervis system, imagine a **Central Switchboard** rather than a direct phone call. 

In traditional systems, devices often "call" each other directly. If one side is busy or offline, the call fails. MQTT is different. It uses a central hub (the Broker) that acts like a switchboard operator. 

  * **The Publishers (Your Devices)**: These are like workers in the field reporting data. They don't call the manager directly; they simply call the Switchboard and leave a report.
  * **The Broker (Mervis Server)**: This is the Switchboard. It accepts all the reports, organizes them into specific "folders" (Topics), and securely holds them.
  * **The Subscribers (Mervis Internal)**: In our system, we use **internal subscribers** to maintain maximum security and control. While Mervis can act as a subscriber, we do not allow external, unauthorized subscribers to access your data streams.

===== Connection Architectures =====

There are two ways to connect, but for security and simplicity, we strongly recommend the **Embedded Broker**.

==== 1. Mervis Embedded Broker (Recommended) ====
In this mode, the Switchboard is built directly inside the Mervis Cloud.
  * **Security**: It is a closed loop. There are **no external subscribers** allowed. Only the Mervis system can access the data, ensuring high control and privacy.
  * **Simplicity**: You do not need to manage an external server.
  * **Workflow**: The Device sends data directly to `mqtt.mervis.info`.

==== 2. External Broker (Client Mode) ====
In this mode, you use your own 3rd party broker. Mervis acts as just another subscriber.
  * **Risk**: This is less secure because Mervis has less control over who else is listening to that broker.
  * **Use Case**: Best suited for integration with already existing infrastructure (e.g., connecting specific devices from a larger, established network).

===== Connection Workflow (Embedded) =====

To set up the secure Embedded connection, follow these steps:

  - **1. Portal Registration (The DataNode)**:
    * Log in to the Mervis Portal at **[[https://portal.mervis.info/|portal.mervis.info]]**.
    * Create a **DataNode** for your project. This is your digital twin in the cloud.
    * Select your device type.
    * The Portal will generate your **DeviceID**, **Username**, and **Password**.

  - **2. Device Configuration**:
    * Open your device's web administration.
    * **Broker Address**: Set to ``mqtt.mervis.info``.
    * **Port**: Use the Secure TLS port.
    * Enter the credentials provided by the Portal.

  - **3. Mervis Generator**:
    * Once the DataNode is active, go to **[[https://generator.mervis.info|generator.mervis.info]]**.
    * It will automatically scan your DataNodes and generate the SCADA project for you, linking all tags without manual typing.
===== Supported Embedded Drivers =====

The following devices have dedicated `EmbeddedBroker` drivers in Mervis. 

  * **BMR PLA34 / PLA44**: Power Quality Analyzers. ([[https://www.bmr-trading.com|Visit BMR]])
  * **Shelly Pro 3EM**: 3-Phase Energy Meters. ([[https://www.shelly.com|Visit Shelly]])
  * **Wago PFC Series**: Programmable Logic Controllers. ([[https://www.wago.com|Visit Wago]])
  * **Weintek**: HMI Panels and Gateways. ([[https://www.weintek.com|Visit Weintek]])
  * **Kornfeil**: Industrial Ovens. ([[https://www.kornfeil.cz|Visit Kornfeil]])

**Specialized Sensors**
  * **IAQ03**: Indoor Air Quality Sensors. ([[https://www.iaq.cz|Visit IAQ]])

===== Data Structure & Payloads =====

==== The Train Analogy ====
Think of MQTT packets as a train:
  * **The Protocol (The Tracks)**: This is MQTT itself.
  * **The Payload (The Cargo)**: This is the actual data inside the train cars.
  
While MQTT is the transport method, the "Cargo" can be anything. Common types include:
  * **JSON** (Preferred in Mervis)
  * **XML**
  * **Text / String**
  * **JPEG Images**
  * **Binary Data**

==== Payload Requirements ====
The MQTT standard strictly defines how the data is transported (the Topic and Payload), but the content inside is flexible.

  * **Format**: JSON is the preferred standard because it is human-readable, making integration easier than binary data. However, **using JSON does not guarantee immediate compatibility**; the internal structure can still be unique and may require specific driver support.
  * **Topic**: The message must be clearly identified by a "Topic" (the address or folder where the file belongs).
===== Troubleshooting Common Issues =====

^ Symptom ^ Possible Cause ^ Solution ^
| **No Connection** | Firewall Blocking | Ensure outbound traffic to **mqtt.mervis.info** is allowed on your network. |
| **Auth Failed** | Credential Mismatch | Ensure the ID, Username, and Password in the **Device** exactly match the **Portal**. |
| **Offline Status** | Heartbeat Missing | Check that your device is sending a "Keep Alive" signal every 60 seconds. |
| **Wrong Values** | Missing Scaling | Apply the required scaling factor (e.g., /10) in your Mervis tag settings. |
===== Advanced Reference: JSON Structures =====

For developers manually integrating Wago or Weintek devices, use these reference payloads.

===== Supported formats =====

==== Wago compatible format ====

=== Registration of available variables ===

  * Informs the subscribers of available variables
  * Publish message with “At least once delivery”
  * Topic: deviceId/TagConfiguration
  * Combination of the collection ID and Tag must be unique for every device!
  * Payload: UTF-8 JSON document
    * /FormatId: (string), message ID
    * /ApiVersion(int), version of API
    * /Complete (bool), must be true now
    * /Collections (Array of collection elements)
      * /Id (int), ID of the collection
      * /CollectionName (string)
      * /SampleRate (int), collection sample rate in ms
      * /PublishInterval (int), collection publish interval in ms
      * /TagData (Array of variable descriptions)
        * /Tag (string), ID of the variable
        * /Unit (string), unit of the variable
        * /ValueType (string), ST type; only simple types are supported

**Example**

<code json>
{
	"FormatId": "TagConfiguration",
	"ApiVersion": 1,
	"Complete": true,
	"Collections": [{
		"Id": 1,
		"CollectionName": "Building 1",
		"SampleRate": 60000,
		"PublishInterval": 60000,
		"TagData": [{
			"Tag": "Temperature1",
			"Unit": "ºC",
			"ValueType": "real"
		},
		{
			"Tag": "Humidity",
			"Unit": "%",
			"ValueType": "word"
		}]
	},
	{
		"Id": 2,
		"CollectionName": "Building 2",
		"SampleRate": 120000,
		"PublishInterval": 240000,
		"TagData": [{
			"Tag": "Water flow",
			"Unit": "m3/h",
			"ValueType": "byte"
		},
		{
			"Tag": "Current phase L1",
			"Unit": "A",
			"ValueType": "lreal"
		}]
	}]
}
</code>

=== Variable values ===
  * Publishes values of variables
  * Publish message with “At least once delivery”
  * Topic: deviceId/TagValues
  * Payload: UTF-8 JSON document
    * /FormatId: (string), message ID
    * /ApiVersion(int), version of API
    * /CollectionId (int), identification of the collection
    * /TagData (Array of value items)
      * /Time (datetime), timestamp in ISO format (YYYY-MM-DDTHH:MM:SSZ), ideal is a UTC form
      * /Values (Collection of Tag and value tuples)

**Example**

<code json>
{
	"FormatId": "TagValues",
	"ApiVersion": 1,
	"CollectionId": 1,
	"TagData": [{
		"Time": "2018-03-27T17:19:23.720+02:00",
		"Values": {
			"Temperature1": 15.52,
			"Humidity": 21
		}
	}]
}

</code>
==== Weintek compatible format ====
  * We assume that all datetime values are in **UTC**
  * Print screens are from EasyBuilder Pro SW
=== Variable values ===
  * Publishes values of variables
  * Publish message with “At least once delivery”
  * Topic: $deviceId/mervis/values or $deviceId/mervis/values/*
  * Payload: UTF-8 JSON document
    * /d: root element
      * "property_name": value - property name, can contain metada(not required). Always use array [...] for value of property
        * metadata format:
          * "name" name of property
          * "type" property type(we supported only [[https://kb.mervis.info/doku.php/en:mervis-scada:80-mqtt#our_supported_types|our list of types]])
          * "unit" information about unit of value

**Example**

<code json>
{
    "d" : {
        "name:MyHomeTemperature, type:generic_sint64, unit:°C" : [ 0 ],
        "number C" : [ 0 ],
        "Bit" : [ false ],
        "My array" : [ 0, 10, 20 ]
    },
    "ts" : "2020-08-27T07:10:24.360316"
}

</code>
{{ :en:mervis-scada:annotation_2020-08-27_120101.png?600 |}}
=== Command registration ===
  * Topic: $deviceId/mervis/cmd_reg or $deviceId/mervis/cmd_reg/*
  * Format:
    * /d root element
      * "propertyName" must include some informations(separate by ","). Value is ignored.
        * "id" what is command id and define subscribe topic ($deviceId/mervis/command/change_temperature)
        * "name" just for customer info
        * "params" parameters with informations to command (**must include all parameters of supscribe topic**)
          * "name" parameter name in json
          * "type" type of parameter (we supported only [[https://kb.mervis.info/doku.php/en:mervis-scada:80-mqtt#our_supported_types|our list of types]])
          * "unit" information about unit of parameter
        * "ts" time span 
<code>
{
    "d" : {
        "id:change_temperature, name:change temperature in house ,params:[{name: temperature, type:generic_float64, unit:°C}, {name: date, type:generic_datetime, unit:UTC}]" : false
    },
    "ts" : "2020-08-27T07:10:11.356013"
}
</code>
choose/create $deviceId/mervis/cmd_reg/
{{ :en:mervis-scada:annotation_2020-08-27_110112.png?400 |}}
set general tab by screenshot
{{ :en:mervis-scada:annotation_2020-08-27_121338.png?400 |}}
add commands
{{ :en:mervis-scada:annotation_2020-08-27_115716.png?400 |}}
===Our supported types===
              * "generic_bool"
              * "generic_sint8"
              * "generic_uint8"
              * "generic_sint16"
              * "generic_uint16"
              * "generic_sint32"
              * "generic_uint32"
              * "generic_sint64"
              * "generic_uint64"
              * "generic_float32"
              * "generic_float64"
              * "generic_string"
              * "generic_datetime"
===Create a subcribe topic for executing command===
  * for previous command example
  * create topic $deviceId/mervis/command/change_temperature
  * with two addresses:
    * temperature(32-bit float)
    * date(string)
{{ :en:mervis-scada:annotation_2020-08-27_110134.png?600 |}}