 |
The Xentara MQTT client v2.0
User Manual
|
|
The Xentara MQTT client v2.0
User Manual
|
Topics are Xentara elements that represent a single MQTT topic published by an MQTT client element. Topic elements must always be children of client elements.
Each topic element has the following properties:
Generally, subscribed clients will only receive messages from the broker as they are published. Newly subscribed clients will not know about any previous messages, and thus will not have access to any data until the next time it is published. Sometimes, especially when using event-based publishing, this can be undesirable. In order to mitigate this problem, MQTT supports so called retained messages. Retained messages are stored by the broker, and are sent to any new client once it subscribes to the topic. This allows new clients to receive the last message published on a particular topic.
Retained messages are retained even after the client disconnects. This can cause stale, out of date messages to be sent to newly subscribed consumers by the broker. If you are using retained messages, it is strongly recommended that you implement a state-based lifetime strategy. Otherwise, it will be impossible for consumers to determine whether the retained messages are still valid, or if they are out of date because the Xentara MQTT client is no longer connected to the broker. This may cause consumers to operate on stale data, which is undesirable.
If you are only using a single topic with retained messages, then you can alternatively use a message to discard any stale messages, as described in Using the Will to Discard Stale Messages.
MQTT topic elements have a task named publish that must be inserted into a Xentara execution pipeline in order to schedule when the topic should be published to the broker. If you do not schedule this task, then the topic will never be published.
The publish task of a topic can be inserted into a pipeline attached to an arbitrary combination of Xentara events and/or timers. Commonly, however, one of the two strategies described below are used.
The simplest way to publish a topic is to attach the publish task to a timer. The topic will be published whenever the timer expires.
Optionally, the task can also be attached to the connected event of the client it belongs to, so that it will be published immediately after the connection to a broker has been established. This is especially useful if the timer has a longer period, like one or more minutes. This will ensure that the data will be available as soon as possible after the connection has been established, without having to wait for timer to expire.
Topics attached to a timer need not necessarily be retained. If the topic is not retained, then a newly subscribed consumer will not receive any messages for the topic until the next time the timer expires. This may be undesirable for timers with a long period, as it may take a long time for a new consumers to receive the first message.
A topic can also be published as a response to one or more Xentara events. For topics publishing the data of one or more data points, the topic is typically published in response to the changed events of some or all of the data points in question. Alternatively, the data can be attached to the change event belonging to one or more of the attributes contained within the payload, or to any other arbitrary event.
When publishing a topic using events, it is almost always necessary to attach the publish task to the connected event of the client it belongs to, in addition to the regular events. This will ensure that the initial values of the topic will be published as soon as the connection to the broker is established. Otherwise, the values will not be available until one of the regular events occur, which might take a very long time. In case of a topic attached to a change event, for example, the topic would not be published until the value actually changes, which may only happen a long time after the connection to the broker has been established. In the case of very static data, like error states or set points, the change event may never be raised, and hence the topic not be published at all.
Likewise, it is almost always necessary to retain messages related to an event-based topic. Otherwise, a newly subscribed consumer will not receive any messages for the topic until the next time the topic is published, which may take an arbitrarily long time.
If you are using retained messages, it is strongly recommended that you implement a state-based lifetime strategy. Otherwise, it will be impossible for consumers to determine whether the retained messages are still valid, or if they are out of date because the Xentara MQTT client is no longer connected to the broker. This may cause consumers to operate on stale data, which is undesirable.
If you are only using a single topic with retained messages, then you can alternatively use a message to discard any stale messages, as described in Using the Will to Discard Stale Messages.
| key | The topic’s primary key. | ||||||||
| name | The topic’s name. The name is the last component of the primary key. | ||||||||
| UUID | The unique UUID of the topic. | ||||||||
| type | The topic’s element type. For MQTT topics, this is always “MQTT Topic”. | ||||||||
| category | The topic’s category. For MQTT topics, this is always “transaction”. | ||||||||
| brokerAddress | The host name or network address of the broker the topic’s client connects to. | ||||||||
| portNumber | The port number of the broker the topic’s client connects to. | ||||||||
| clientID | The MQTT client identifier the topic’s client advertises to the broker on connection. | ||||||||
| topic | The MQTT topic the data is published to. | ||||||||
| QoS | The numeric value of the MQTT QoS (quality of service) used for the messages. MQTT defines the following three QoS values:
| ||||||||
| retained | Whether the broker is instructed to retain messages for this topic. | ||||||||
| state | A Boolean value denoting whether the topic is being published successfully. This attribute will be true if the topic is being published successfully, or false if there is a problem. | ||||||||
| error | This attribute contains an error message denoting the error if the “state” attribute is false. |
| published | This event is raised whenever the topic has been published successfully. |
| publish | Publishes the topic’s payload to the broker. |