Topics
Topics
In order to send data to MQTT network, PublishTopic elements must to be added to MQTTClient. On the other hand, to receive data from MQTT network, SubscribeTopic elements must to 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 single-channel topic element to send or receive one channel (i.e signal) value per topic. Choose 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). |
| 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. |
| Retain | For publish topics only. Defines if the broker should retain last message sent. If true, for any new subscriber on this topic, retained message will be sent immediately. |
| MessageCount | Sent message total count (read-only). |
| MessageBytes | Sent message total bytes (read-only). |
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 |
|---|---|
| TriggerOnStartup<bool> | When set, message will be published immediately at system startup (at first successful connect to broker). Default is to publish message on startup. |
| TriggerOnTimeout<double> | Interval in seconds to wait before automatically publishing new message. Default is 0 (zero) that means no automatic time-based publishing. |
| TriggerOnChange<bool> | When set, message will published on channel value change (or single-channel topic value change). 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 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 CM_TEXTCOMMAND 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 CM_TEXTCOMMAND message to override the Topic, channel names (in the case of the multi-channel topic) or Payload (in the case of the single-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 CM_TEXTCOMMAND message with IOTrigger text command that contains semicolon-separated name=value pairs for Topic, Payload or channel names (in the case of the multi-channel topic) plus topic relative path name as a IOTriggerURI parameter.
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 in 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 kitchen (home/kitchen/light/brightness etc)
Topic can have many sub-elements like Translators, ValueMaps, Channels and SubTopics.
Following image shows 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 translator, specified in Translator element. When no Translator is specified, default TextTranslator is used, that results sending and receives channel values in text format, line by line. Since this Channel sub-element can also contain ChannelGroups, complex tree-like structure can also be created. Channel-trees are 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 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 in 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.