MQTT

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.

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

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

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

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

1. 1. Portal Registration (The DataNode):
   • Log in to the Mervis Portal at 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.

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

1. 3. Mervis Generator:
   • Once the DataNode is active, go to generator.mervis.info.
   • It will automatically scan your DataNodes and generate the SCADA project for you, linking all tags without manual typing.

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

• BMR PLA34 / PLA44: Power Quality Analyzers. (Visit BMR)
• Shelly Pro 3EM: 3-Phase Energy Meters. (Visit Shelly)
• Wago PFC Series: Programmable Logic Controllers. (Visit Wago)
• Weintek: HMI Panels and Gateways. (Visit Weintek)
• Kornfeil: Industrial Ovens. (Visit Kornfeil)

Specialized Sensors

• IAQ03: Indoor Air Quality Sensors. (Visit IAQ)

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

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

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

• 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

{
	"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"
		}]
	}]
}

• 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

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

• We assume that all datetime values are in UTC
• Print screens are from EasyBuilder Pro SW

• 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 our list of types)
        • “unit” information about unit of value

Example

{
    "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"
}

• 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 our list of types)
        • “unit” information about unit of parameter
      • “ts” time span

{
    "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"
}

choose/create $deviceId/mervis/cmd_reg/ set general tab by screenshot add commands

• “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”

• for previous command example
• create topic $deviceId/mervis/command/change_temperature
• with two addresses:
  • temperature(32-bit float)
  • date(string)