MQTT
MQTT (Message Queuing Telemetry Transport) is an open message protocol for machine-to-machine (M2M) communication. It is well suited to providing information to the central cloud system AnyViz. AnyViz acts as a broker here. All topics provided by the MQTT client can be created and used as tags in AnyViz.
Connection
The MQTT client connects directly to AnyViz, which therefore acts as an MQTT broker. To correctly assign the MQTT client to the AnyViz project, the project number must be provided in the form of the user name. The password set in the MQTT client must be confirmed in AnyViz. Thereafter, incoming publish messages will be accepted by AnyViz.
Connection parameters
| Server |
AnyViz hostname: |
| Port |
8883 (TLS), 1883 (TCP) It is recommended to connect via port 8883 with server certificate validation. The alternative port 1883 is for testing purposes only and is not recommended for lack of encryption. |
| Client ID | The MQTT client ID can be freely defined and is used for identification in AnyViz. The MQTT connection is rejected if no client ID is transmitted or the client ID exceeds the maximum length of 250 characters. As the client ID is used for unique identification within a project, the ID must not change. |
| Username | The user name is used to assign the project. For this reason, the project number must be passed as the user name. |
| Password | A user-defined onboarding password, which must be confirmed later. |
| Certificate | To encrypt communication over port 8883 and to verify the server host, the public AnyViz certificate is used. Client authentication by certificate is not supported at this time. |
| Version |
3.1.1 oder 5.0 AnyViz supports the MQTT protocol in version 3.1.1 and version 5.0. Clients with an older version are not rejected, but compatibility cannot be guaranteed in this case. |
| Will-Topic | The Will-Topic supported by the MQTT protocol is not processed in AnyViz. |
Connection confirmation
As soon as the connection to AnyViz has been established, a new entry appears in the tree. Hover the mouse over the entry and click Edit. The Cloud Adapter dialog opens.
For verification, the same password that was previously entered in the MQTT client must now be entered once. Optionally, a name can be assigned, which is then used for display. If the correct password is entered, the entry changes from yellow to green and all incoming topics are listed below.
| Byte Order | The byte order must be configured correctly if the topic values are transmitted via binary encoding. |
| Connection monitoring | If the connection is interrupted, error badges are displayed and data logging is stopped. This behavior can be prevented for cloud adapters without a permanent connection. |
Topic transmission
The MQTT protocol uses publish messages to transmit values. They consist of a topic name, a byte sequence as payload and a QoS. The topic name is displayed hierarchically in AnyViz. The encoding of the payload itself is not specified in the MQTT protocol. AnyViz supports the following encodings.
Limitations
- The maximum message size is limited to 1MB (Header + Topic + Payload)
-
The maximum number of topics is limited to 10 times of the number of tags of your AnyViz Subscription
(Example: With a 50 tags subscription, the 501st topic is discarded.) - The topic name must not contain any dots
Binary encoding
The values of a topic can be transmitted in raw format. Please ensure that the correct byte order is specified on the cloud adapter (siehe Connection confirmation). The data type must be specified when creating a tag. The following data types are supported:
| Bool | Logical value | 1 Byte |
| Byte | 8 bit integer | |
| SByte | 8 bit signed integer | |
| UInt16 | 16 bit integer | 2 Byte |
| Int16 | 16 bit signed integer | |
| UInt32 | 32 bit integer | 4 Byte |
| Int32 | 32 bit signed integer | |
| Float | 32 bit floating point | |
| UInt64 | 64 bit integer | 8 Byte |
| Int64 | 64 bit signed integer | |
| Double | 64 Bit floating point | |
| String | Text with variable length | X Byte |
Text encoding
Alternatively, the values of a topic can be transferred as a string value. AnyViz then offers the option of converting the string into a number or a logical value. Please note that numbers must be transferred in English format, i.e. with a dot as a decimal separator. The following data types are available when transferring strings:
| String (Text) | Value is used to display text |
| String (Numeric) | Value is converted to a number |
| String (Logical) | Value is converted to Bool |
JSON encoding
The transfer of JSON content is very convenient. JSON content transferred in UTF8 is automatically recognized by AnyViz if it is formatted correctly. All fields of the JSON object are displayed hierarchically as individual symbols in AnyViz. Below is an example:
| Transmitted JSON string | Presentation in AnyViz |
{
"TimeString": "13:43:09",
"CpuUsage": 30.364752,
"AvailableRam": 8505,
"Time": {
"Year": 2023,
"Ticks": 14811562,
"Seconds": 9
},
"Date": [2023, 12, 19],
"DaylightSavingTime": false,
"JsonDateTime": "2023-12-19T12:43:09.8561376Z"
}
|
|
This means that every field of a JSON object can be converted into a tag. It is not necessary to specify the data type. However, the following should be noted when transferring the topics in JSON encoding:
- New fields of a JSON object are only displayed in AnyViz after the MQTT client has reconnected.
- If the referenced field is missing in a transferred JSON object, the value is set to null and a question mark is displayed as value.
- The JSON string must begin with curly brackets and end with curly brackets.
OPC-UA PubSub
The OPC UA PubSub extension enables data sets to be sent via the MQTT protocol. AnyViz automatically recognizes MetaData and DataSet messages and lists all variables of the transmitted data sets as symbols. Both JSON encoding and binary UADP encoding are supported.
Only DataSetWriters are currently supported, so writing variables is not possible. Also, arrays are currently not supported.
Sparkplug B
Sparkplug is a specification for the efficient transfer of data structures via MQTT. AnyViz supports version B of the specification and automatically recognizes Sparkplug structures based on the defined naming scheme.
All metrics are displayed grouped by Group, Node and Device.
Metrics can be written simply by subscribing to the corresponding NCMD or DCMD topic.
Quality of Service
AnyViz supports all QoS methods specified in MQTT:
- At most once (0)
- At least once (1)
- Exactly once (2)
Publish/Subscribe
After a publish message, the topic is displayed as a read-only symbol. After a subscribe message, the topic is shown as a write-only symbol. If a topic is described in both a publish message and a subscribe message, this topic is displayed as a readable and writable symbol. In this way, the values can be read and written.
Compared to the AnyViz protocol, the MQTT protocol provides less functionality. For example, there is no buffering of data in case of connection failure. We therefore recommend using the Universal Cloud Adapter in preference to an MQTT connection.