Skip to content
Alex Robenko edited this page Apr 28, 2024 · 6 revisions

MQTT v5 Client Filter Plugin for the CommsChampion Tools

As a prerequisite please read How to Use CommsChampion Tools wiki page first.

Plugin Configuration

The MQTT v5 Client Filter plugin is expected to be listed in the "Filter" list of the available plugins.

image: available mqtt5 filter plugin

For the basic non encrypted connection select "TCP/IP Client Socket" and configure it accordingly. The standard MQTT v5 port is 1883. The MQTT v5 filter plugin is also expected to be configured as needed.

image: tcp config

For the encrypted connection select "SSL Client Socket" instead of the "TCP/IP Client Socket" with an appropriate configuration. The standard encrypted connection MQTT v5 port is 8883.

image: tcp config

To enable reception of the messages the MQTT v5 protocol requires subscription to relevant topics. To do so click on "Add Subscribe" button and fill in subscription details.

image: subscribe config

When the CommsChampion Tools are going to be used to publish messages to the broker as well then there is a need to provide publish topic / QoS configuration. The plugin configuration allows setting the default values

image: publish config

When multiple messages with the same topic are going to be published, it might make sense to use topic aliasing to save some network traffic.

image: publish config

Connecting

Depending on the implemented features the plugin configuration may be missing things to allow extended MQTT v5 configuration features for the CONNECT and SUBSCRIBE functionalities, such as using extra properties. If this is the case please submit the required feature request.

When the plugins are applied there is a need to connect the TCP/IP socket to the broker.

image: connect socket

When the socket is connected the filter plugin sends appropriate CONNECT AND SUBSCRIBE MQTT v5 messages in the background to allow the reception of the messages. If no error pop-up message appeared then the connection is established and the tool is ready to send / receive messages.

Any messages that the broker sends to the tool get processed by the filter and the payload is delivered to the protocol plugin for processing. As the result the reported protocol messages get displayed in the "All Messages" area.

Publishing

The CommsChampion Tools allow selection and configuration of the application protocol message to be sent.

image: publish preparation

When the message is sent, it can be viewed in the "All Messages" area. When selected and the "Extra Info" display is chosen, the used MQTT v5 publish topic and QoS values can be viewed.

image: publish info

It is possible to override the default configuration of the message to be sent out by preparing the JSON object of the "Extra Info" using just properties than need to be overridden. To override the default publish topic use mqtt5.topic property. To override the default publish QoS value, use mqtt5.qos property.

image: publish override

The result of the overriding can be visible when viewing the details of the sent message

image: publish override result

There are many other overrides possible. To send the retained message use mqtt5.retained property:

{
    "mqtt5.retained": true
}

To specify format use mqtt5.format property (0 is Unspecified and 1 is UTF-8 according to MQTT v5 specification):

{
    "mqtt5.format": 1
}

To specify message expiry interval (in seconds) use mqtt5.expiry_interval:

{
    "mqtt5.expiry_interval": 10
}

To specify the response topic use mqtt5.response_topic:

{
    "mqtt5.response_topic": "response/topic"
}

To specify content type use mqtt5.content_type:

{
    "mqtt5.content_type": "some_content_type"
}

To specify binary correlation data use mqtt5.correlation_data. The value is expected to be a string containing hex bytes:

{
    "mqtt5.correlation_data": "0123456789abcdef"
}

To add user properties use mqtt5.user_props with an array of the objects containing key and value properties:

{
    "mqtt5.user_props": [
        {
            "key": "key1",
            "value": "value1"
        },
        {
            "key": "key2",
            "value": "value2"
        }
    ]
}

Handling Topics Containing Protocol Message ID

The MQTT v5 Client Filter Plugin communicates only message payload to the protocol plugin. In cases that some topic element contains the message ID, there is a need to implement a separate filter plugin which will analyse the reported topic from the message properties and will modify the raw data forwarded to the protocol plugin accordingly (such as prefixing it with the appropriate numeric message ID).

In the opposite direction (sending the message) such filter plugin will have to strip the message ID prefix from the raw data received from the protocol plugin before forwarding it to the MQTT v5 Client Filter Plugin and set the mqtt5.topic property to the appropriate value.