Topics
Topics
In order to send data to MQTT network, PublishTopic elements must be added to MQTTClient. On the other hand, to receive data from MQTT network, SubscribeTopic elements must be added.
Single-channel (of any CDP signal type) and/or multi-channel (of type string) PublishTopic and/or SubscribeTopic topic elements can be added to MQTTClient for sending and receiving messages. Choose a single-channel topic element to send or receive one channel (i.e. signal) value per topic. Choose a multi-channel (string) topic element to send or receive many channel (i.e. signal) values under one topic.
Topics (SubscribeTopic and PublishTopic) have the following properties:
| Property | Description |
|---|---|
| Topic | MQTT topic string to be used for communication in MQTT network. Note: In case of multi-channel PublishTopic the Topic property will be processed by the FormatTranslator before send. That can be useful for sending channel values as part of a Topic string (note that values can also be ValueMap translated to any string). |
| ResponseTopic | When filled, indicates a topic that the request publisher expects the response to be published to. Can be used only when MQTTClient ProtocolVersion is set to v5 (or higher) and the broker also supports MQTT v5 (or higher). |
| CorrelationData | When filled, identifies the specific request and should be echoed back by repsonder when it responds to ResponseTopic. Can be used only when MQTTClient ProtocolVersion is set to v5 (or higher) and the broker also supports MQTT v5 (or higher). |
| QoS | Quality of service level of broker communication. Possible values are 0 (Deliver at most once), 1 (Deliver at least once) or 2 (Deliver exactly once). Use 1 or 2 to ensure that messages will be received even after connection failures. |
| MessageCount | Sent message total count (read-only). |
| MessageBytes | Sent message total bytes (read-only) (including MQTT message header). |
SubscribeTopics have the following additional read-only properties:
| Property | Description |
|---|---|
| ReceivedTopic<string> | Actual MQTT topic value, that was used by the sender to send the most recent payload (useful in case of a wildcard subscribe) |
PublishTopics have the following additional properties to control publishing:
| Property | Description |
|---|---|
| Retain<bool> | Defines if the broker should retain the last message sent. If true, any new subscriber on this topic, retained message will be (re)sent immediately. |
| AutoAlias<bool> | Generate MQTT v5 topic alias on first publish to save network traffic on consequent sends when the same Topic string is used. Can be used only when MQTTClient ProtocolVersion is set to v5 (or higher) and the broker also supports MQTT v5 (or higher). |
| TriggerOnStartup<bool> | When set, a message will be published immediately at system startup (at first successful connect to broker). The default is to publish a message on startup. |
| TriggerOnTimeout<double> | Interval in seconds to wait before automatically publishing a new message. The default is 0 (zero), which means no automatic time-based publishing. |
| TriggerOnChange<bool> | When set, the message will be published on channel value change (or single-channel topic value change). The default is to send messages on any value change. |
| TriggerRouting<string> | Routed signal, property or parameter whose value edge change (i.e change from zero to non-zero or contrary) triggers a new message to be published. |
Publishing can also be triggered by messages using two different options.
To use the topic-based option add a MessageArgument resource as a SendOnMessage sub-element to the topic and then send a matching message to it to trigger the topic publish.
To use the IOServer-based option send a message with the IOTrigger text command to the MQTTClient object directly. With this option mandatory IOTriggerURI parameter has to be included with the message, specifying the topic element's relative name to publish.
With both options, semicolon-separated name=value pairs can also be added to the message to override the Topic, ResponseTopic, CorrelationData, Payload (the MQTT payload to send) or channel names (in the case of the multi-channel topic) values for the publish.
SubscribeTopics on the other hand can have a MessageArgument resource to be added as a MessageOnReceive sub-element, that can be connected to any external object (via configurable RoutingList receiver list), to send a message with IOTrigger text command that contains semicolon-separated name=value pairs for Topic, Payload (the MQTT payload that was received), ResponseTopic, CorrelationData or channel names (in the case of the multi-channel topic), plus topic relative path name as a IOTriggerURI parameter.
When sending and receiving messages CM_TEXTCOMMAND is used by default. With this message type message is sent in text format and can contain named arguments (like Topic or Payload or channel names) in any order. With other message types message arguments are sent in binary format (it can be useful when binary payload needs to be forwarded), then fixed argument order Topic and Payload is used.
SubscribeTopics can also be wildcard topic, in cases they will receive messages sent to several different topics. There are two types of wildcard topics:
- single level wildcards created with plus + sign
For example SubscribeTopic with Topic value
home/+/temperature
will receive temperature messages sent by any temperature sensor at home (home/kitchen/temperature etc)
- multi level wildcards created with hash # sign
For example SubscribeTopic with Topic value
home/kitchen/#
will receive messages sent by any sensor or device in the kitchen (home/kitchen/light/brightness etc)
Note: When MQTTClient is set to support MQTT version 5 (i.e. MQTTClient ProtocolVersion is set to 5) and the broker also supports MQTT version 5, then MQTTClient can benefit from the MQTT v5 Subscription Identifier feature and internally eliminate the possible duplicate message receiving, in cases when overlapping wildcard topics are subscribed by different SubscribeTopics at the same time.
Topic can have many sub-elements like Translators, ValueMaps, Channels and SubTopics.
The following image shows the hierarchy of PublishTopic/SubscribeTopic sub-elements:
Note: The length of PublishTopic<string> and SubscribeTopic<string> is limited only to MQTT payloads of 255 symbols or less. When longer string payloads are needed use the complex topic type like PublishTopicChannelGroup or SubscribeTopicChannelGroup as described below - they provide support for unlimited MQTT payload length.
Channels
Multi-channel topics (PublishTopicChannelGroup and SubscribeTopicChannelGroup) have a Channel sub-element where multiple channels can be added into. These channels will then be used to receive or send the actual MQTT topic payload using the translator, specified in the Translator element. When no Translator is specified, default TextTranslator is used, which means that channel values are sent and received in the text format, line by line. Since this Channel sub-element can also contain the ChannelGroups, a complex tree-like structure can also be created. The channel tree is most useful for JSONTranslator, where it will be used to send or receive channel values in JSON format.
Sub-topics
Sub-topics (SubTopic elements) can be added below every Topic. Nesting sub-topics allows user to group related topics together for easier management. Sub-topics are just like ordinary topics except that they inherit some of their parent properties:
| Property/Element | How sub-topic inherits from the parent |
|---|---|
| Topic property | Sub-topic Topic string is relative to parent Topic string. F.e if parent Topic="/somedevice/command" and sub-topic Topic="currentstate" then actual SubTopic MQTT topic will be Topic="/somedevice/command/currentstate". |
| Translator element | Sub-topic inherits parent Translator (if left unspecified). |
| ValueMap elements | Sub-topic inherits parent topic ValueMaps. However, ValueMaps can be overridden at the sub-topic level. For example, if parent has mapped values 0<=>OFF and 1<=>ON, then sub-topic can possibly override only ValueMap 100<=>ON, to have mapped values 0<=>OFF and 100<=>ON. |
Get started with CDP Studio today
Let us help you take your great ideas and turn them into the products your customer will love.