Clients

Table of Contents

• TLS Connections
• Reconnecting Clients
• Will Messages
• Birth Messages
  • Preconditions for Publishing the Birth Message
• Accessing Clients

See also

Xentara Elements in the Xentara user manual

Clients are Xentara elements that represent a client connection to an MQTT broker. The client must contain a topic element for each MQTT topic it publishes to the broker.

A client will typically have a structure similar to this:

Each MQTT client element maintains one connection to an MQTT broker.

TLS Connections

The Xentara MQTT client supports secure MQTT connections using TLS (formerly SSL). The MQTT client only supports TLS versions 1.2 and 1.3. It does not support TLS 1.1, TLS 1.0, SSL 3.0, SSL 2.0, or SSL 1.0, as these versions are no longer considered secure.

The Xentara MQTT client always checks the server certificate provided by the broker. Server certificates that were issued by a trusted certificate authority known to the operating system will verify automatically without any additional configuration. Untrusted certificates, or certificates that contain the wrong hostname, can be trusted explicitly by copying them to the Xentara host and specifying the corresponding file path in the configuration of the client element.

The Xentara MQTT client can also optionally present a client certificate to the broker. The client certificate and the corresponding private key file must be copied to the Xentara host, and the corresponding paths specified in the configuration of the client element.

Reconnecting Clients

If the communication with a broker is disrupted, then the Xentara MQTT client can no longer communicate with it. Once the client becomes available again, the connection to the broker must be reestablished, so that the communication can be resumed.

The Xentara MQTT client does not automatically attempt to reestablish the connection to the broker, because this may require DNS lookups, ARP/NDP discovery, or other operations that may produce undesired network traffic. It may therefore be desirable to attempt to reestablish the connection at a greater interval than the normal publishing interval. The Xentara MQTT client therefore allows you to schedule the reconnection attempts of an MQTT client separately from the publishing of topics. MQTT client elements have a task named reconnect that must be inserted into a Xentara execution pipeline in order to schedule the reconnection attempts. If you do not schedule this task, then communication with the broker will not resume if the broker ever goes offline, even if it comes back online.

Will Messages

See also

Lifetime Strategies Using Birth and Will Messages

The MQTT protocol supports a so called “will” message, sometimes also called “last will & testament” or “LWT” message. This message is automatically published by the broker if the connection to a client is closed or lost. This allows other client to subscribe to the the will topic and be notified if the publisher is disconnected. The subscriber can then perform error handling that might be necessary, like invalidating all data associated with the client.

The Xentara MQTT client can optionally be configured to use a will message. The properties of the will message are taken from the client element’s configuration. The configuration contains the following information:

1. The topic the will message should be published to, as described in chapter 3.1.3.3 Will Topic in the MQTT specification. The topic can be shared with one of the topic elements of the client, or it can be an entirely separate topic. The topic can also be shared with the birth message
2. The payload of the will message, as described in chapter 3.1.3.4 Will Payload in the MQTT specification. The format of the payload is described in Message Payloads.
3. The QoS to be used for the will message, as described in chapter 3.1.2.6 Will QoS in the MQTT specification.
4. An option specifying whether the will message should be retained by the broker, as described in chapter 3.1.2.7 Will Retain in the MQTT specification.
5. An option specifying whether the will message should only be sent if the connection terminates abnormally. By default, the will message is sent whenever the connection is closed, whether this happened normally as a result of Xentara shutting down or being suspended, or whether this happened due to an error.

As with all MQTT messages, if the will message is retained, then the broker will store the message and send it to all clients that subscribe to it later. If the will message is not retained, then only clients that are subscribed at the time the message is published will receive it.

Please note that an MQTT broker will not forward or retain any message with an empty payload. An empty will payload is only useful to discard a retained message, as described under Using the Will to Discard Stale Messages.

Will messages are generally used to implement lifetime strategies for the client.

Note

Since the will message is published by the broker rather than by the Xentara MQTT client, it cannot contain any data point or attribute values.

Birth Messages

See also

Lifetime Strategies Using Birth and Will Messages

In addition to the will message, the Xentara MQTT client also supports a birth message. Birth messages are not a built-in MQTT feature, but are supported by many MQTT clients to notify subscribers that the client has started up successfully. Birth messages are used by the Sparkplug specification, for example.

The properties of the birth message are taken from the client element’s configuration. The configuration contains the following information:

1. The topic the birth message should be published to, as described in chapter 3.3.2.1 Topic Name in the MQTT specification. The topic can be shared with one of the topic elements of the client, or it can be an entirely separate topic. The topic can also be shared with the will message
2. The payload of the birth message, as described in chapter 3.3.3 PUBLISH Payload in the MQTT specification. The format of the payload is described in Message Payloads.
3. The QoS to be used for the birth message, as in chapter 3.3.1.2 QoS in the MQTT specification.
4. An option specifying whether the birth message should be retained by the broker, as described in chapter 3.3.1.3 RETAIN in the MQTT specification.

As with all MQTT messages, if the birth message is retained, then the broker will store the message and send it to all clients that subscribe to it later. If the birth message is not retained, then only clients that are subscribed at the time the message is published will receive it.

Birth messages are generally used to implement lifetime strategies for the client.

Preconditions for Publishing the Birth Message

The birth message is published to the broker once two conditions have been fulfilled:

1. The connection to the broker has been established correctly, and
2. All retained topics (other that the birth and will topics) have been published at least once.

The second condition is necessary to ensure that no stale retained messages remain when the birth message is published.

A retained topic is a topic for which at least one topic element exists that is configured to use retained messages. Individual topic elements can also be included and excluded from this condition in the respective topic configuration independent of whether they are retained or not.

Accessing Clients

See also

Accessing Xentara Elements in the Xentara user manual

MQTT clients have the following members:

Attributes

key	The client’s primary key.
name	The client’s name. The name is the last component of the primary key.
UUID	The unique UUID of the client.
type	The client’s element type. For MQTT clients, this is always “MQTT Client”.
category	The client’s category. For MQTT clients, this is always “external interface”.
brokerAddress	The host name or network address of the broker the client connects to.
portNumber	The port number of the broker the client connects to.
clientID	The MQTT client identifier the client advertises to the broker on connection. If the client does not have a client identifier configured, but is using a randomly generated client identifier, this attribute contains an empty string.
deviceState	A Boolean value denoting whether the client is functioning properly. This attribute will be true if the client is operation correctly, or false if there is a problem.
connectionTime	The time stamp of the time the connection with the broker was established or lost, depending on the value of the deviceState attribute.
birthMessageTime	The time stamp of the time the time that the birth message for this session was sent. If the birth message has not been sent yet, then this time is set to a time infinitely far in the past (often displayed as “never (-infinity)”). This attribute only exists for clients that have a birth message configured.
error	This attribute contains an error message denoting the error if the “deviceState” attribute is false.

Events

connected	This event is raised when the connection to the broker has been established successfully.
disconnected	This event is raised when the connection to to broker has been lost.
birth	This event is raised whenever the birth message has been published successfully. This event only exists for clients that have a birth message configured.

Tasks

reconnect

Attempts to reestablish the connection to the broker if it is down.