Topics

Terminology

Dataristix uses the term “Topic” as a term for “Tag Containers”. Connector topics and tags are connected in Tasks to define data flows.

MQTT uses the term “Topic” as an “address” where application messages are stored or retrieved. Publishing clients send payloads with an MQTT topic “address” to the broker and subscribing clients receive these payloads when subscribing to such MQTT topics.

In the context of the MQTT Connector, “Connector Topics” are configured for each MQTT client either as “Publish” or “Subscribe” topics and refer to the topics in the Dataristix sense; “Tags” contained in a Publish or Subscribe “Connector Topic” represent MQTT topics. MQTT topics within a Connector Topic share the same settings.

Add Topic

To send data to an MQTT broker, add a publisher connector topic by selecting the “Publish” navigation node for an MQTT client, then press the “Add” toolbar button. To receive data from an MQTT broker, add a subscriber connector topic by selecting the “Subscribe” navigation node instead. This will add a new connector topic with default settings. Rename the topic to suit and adapt settings in the property panel.

../_images/mqtt-add-client-topic.png

“Subscribe” Topic Settings

Configure the following topic settings.

  • Name
    Any connector topic name
  • Set ‘Bad’ status for empty values
    By default empty values (null values or empty strings) are forwarded in tasks with a ‘Good’ status. Tick this option to mark empty values with a ‘Bad’ status to, for example, filter such values in other connectors.
  • Use MQTT wildcard topic to subscribe
    When checked then, instead of sending a “subscribe” message to the broker for each MQTT topic (tag) within the connector topic, only one subscribe request is sent using the defined wildcard topic. The wildcard topic should be defined so that the broker will return data for all contained MQTT topics (tags) within the connector topic but not more.
  • Quality of Service
    The quality of service level the client will request from the broker when sending messages related to MQTT topics. Please see the MQTT specification for differences in quality of service levels.
  • Payload format
    This settings determines how payloads within MQTT messages are interpreted. If “Text” is selected, then the MQTT connector assumes that payloads contain an UTF-8 encoded string and attempts to decode the text. If “Binary” is selected then the MQTT connector will process the payload as an array of bytes.

“Publish” Topic Settings

Configure the following topic settings.

  • Name

    Any connector topic name

  • Quality of Service

    The quality of service level the client will request from the broker when sending messages related to MQTT topics. Please see the MQTT specification for differences in quality of service levels.

  • Payload format

    This settings determines how payloads within MQTT messages are interpreted. If “Text” is selected, then the MQTT connector assumes that payloads contain an UTF-8 encoded string and attempts to decode the text. If “Binary” is selected then the MQTT connector will process the payload as an array of byte.

  • Retain messages

    If checked then the broker is requested to retain messages even when the client is disconnected.

  • Make this a generic connector topic

    If checked then the connector topic is not expected to contain any tags and Tasks may send any tag to this topic for processing. MQTT topic names that are sent to the broker are generated automatically based on the connector topic name, the connected topic name, and the connected tag name within tasks (see example).

    When this option is checked then the following settings are also available:

    • Normalize generated MQTT topic Identifiers
      Generated MQTT topic names are converted to lower case characters and hyphen characters.
    • Use custom MQTT topic path
      When checked, then, instead of using the default generated topic name, a custom topic path may be defined. The final MQTT topic name is the defined custom topic path with the connected tag name appended.

Remove Topics

Remove topics by selecting the MQTT client in the navigation panel, then select one or more topics to remove in the content panel, and finally click on the “Remove” toolbar button to remove selected topics. You can also right-click on a topic and select “Remove” from the context menu.

Warning

Note that topics are also removed from any task using the topics.