 |
The Xentara MQTT client v2.0
User Manual
|
|
The Xentara MQTT client v2.0
User Manual
|
A JSON object describing an MQTT client element has the following syntax:
| name | A string value containing the name of the client. The name is used to construct the client’s primary key. |
| UUID | A string value containing the unique UUID of the client. |
| ACL | An optional JSON object containing the element ACL of the client. The format of the object is described under JSON Format for ACLs in the Xentara user manual. |
| brokerAddress | A string value containing the network address of the broker to connect to. This can be a host name or an IP address, with or without a port number. If the address does not contain a port number, then the standard MQTT port will be used. The standard MQTT port is 8883 for secure (TLS) connections, and 1883 for insecure (non-TLS) connections. The format of the string is described under JSON Format for Network Addresses in the Xentara user manual. |
| TLS | An optional JSON object describing the TLS configuration for secure broker connections. The format of the block is described here. If you do not specify this parameter, then an insecure, unencrypted connection will be used. |
| clientID | An optional string value containing the MQTT client identifier the client should advertise to the broker on connection. The client identifier must not be empty. If you do not specify this parameter, a suitable client identifier will be generated by Xentara. |
| MQTTVersion | An optional string value containing the MQTT protocol version to use. Must be one of "5", "3.1.1", or "3.1". If you do not specify this parameter, then MQTT version 5 will be used. |
| username | An optional string value containing the username to use for the MQTT connection. If you do not specify this parameter, then no username will be used. |
| password | An optional string value containing the password to use for the MQTT connection. If you do not specify this parameter, then no password will be used. Please note than MQTT versions 3.1.1 and 3.1 do not support a password without a username. If you specified "3.1.1" or "3.1" as MQTT version, then a password can only be specified if a username is also specified. |
| keepaliveInterval | An optional string value containing the interval at which Xentara sends keep-alive messages to the broker if no other traffic was sent. The keepalive interval must not be less than 5s. The format of the string is described under JSON Format for Time Intervals in the Xentara user manual. If you do not specify this parameter, then a keepalive interval of 60s will be used. |
| birth | An optional JSON object describing the birth message to be sent. The format of the block is described here. If you do not specify this parameter, then no birth message will be sent. |
| will | An optional JSON object describing the will message to be sent. The format of the block is described here. If you do not specify this parameter, then no will message will be sent. |
| children | A JSON array containing the topics of the client. The individual child elements are each represented by a double nested JSON object, as described in Element Blocks under Structure of the Model File in the Xentara user manual. The outer object has a single member whose name is the type of element, and whose value is another JSON object that contains the actual properties of the element. |
A JSON object describing the TLS configuration for an MQTT client has the following syntax:
| enabled | An optional Boolean value specifying whether to establish a secure connection using TLS or not. If you do not specify this parameter, then an insecure, unencrypted connection will be used. |
| clientCertificate | An optional JSON object containing the paths to the client certificate and private key file to present to the broker. The format of the object is described under JSON Format for Certificates in the Xentara user manual. If you do not specify this parameter, then no client certificate will be presented. |
| serverCertificate | An optional string value containing the path to the server certificate the broker is expected to present. The certificate file is searched for as described under Certificate File Location. The certificate file must be a PEM encoded file containing the certificate, as described in Certificate And Private Key File Structure. This member should only be specified if the certificate of the broker is untrusted, or if it contains the wrong hostname. Server certificates issued by a trusted certificate authority are automatically accepted, even without this parameter. See Certificates for details. If you specify this parameter, then the certificate presented by the broker must match the specified certificate exactly. |
A JSON object describing the birth message for an MQTT client has the following syntax:
| topic | A string value containing the topic of the birth message. This can, but need not, be shared with one of the topic elements of the client. See 3.1.3.3 Birth Topic in the MQTT specification for details. |
| payload | A JSON string value or a JSON object containing the payload of the birth message. The format of the value is described under JSON Format for Message Payloads. See 3.3.3 PUBLISH Payload in the MQTT specification for details. |
| extraAttributes | An optional JSON array containing additional attributes that should be included in data point value payloads. The value and quality attributes are always included automatically, and must not appear in the array. It is not considered an error if the data point included in the payload does not provide all of the additional attributes. Any attributes not provided by the data point will simply be omitted from the payload. This allows you to include attributes like “error” or “writeTime” in this list, that may not be supported by all data points. |
| QoS | An optional numeric value containing the quality of service to use for the birth message. The QoS must be 0, 1, or 2. See 3.3.1.2 QoS in the MQTT specification for details. If you do not specify this parameter, then a QoS of 0 will be used. |
| retained | An optional Boolean value specifying whether the birth message should be retained by the broker. See 3.3.1.3 RETAIN in the MQTT specification for details. If you do not specify this parameter, then the birth message will not be retained. |
A JSON object describing the will message for an MQTT client has the following syntax:
| topic | A string value containing the topic of the will message. This can, but need not, be shared with one of the topic elements of the client. See 3.1.3.3 Will Topic in the MQTT specification for details. |
| payload | A JSON string value or a JSON object containing the payload of the will message. The format of the value is described under JSON Format for Message Payloads. Please note that an MQTT broker will not forward or retain any message with an empty payload. An empty will payload is useful to instruct the broker to discard a retained message, as described in Using the Will to Discard Stale Messages. See 3.1.3.4 Will Payload in the MQTT specification for details. |
| QoS | An optional numeric value containing the quality of service to use for the will message. The QoS must be 0, 1, or 2. See 3.1.2.6 Will QoS in the MQTT specification for details. If you do not specify this parameter, then a QoS of 0 will be used. |
| retained | An optional Boolean value specifying whether the will message should be retained by the broker. See 3.1.2.7 Will Retain in the MQTT specification for details. If you do not specify this parameter, then the will message will not be retained. |
| abnormalDisconnectOnly | An optional Boolean value specifying whether the will message should be sent on abnormal disconnect only. If you enable this option, then no will message will be sent if Xentara is shut down normally. If you do not specify this parameter, then the will message will be sent on normal and abnormal disconnect.
|