Difference between revisions of "OpcLabs.Mqtt communication package"

From OPC Labs Knowledge Base
Jump to navigation Jump to search
(5 intermediate revisions by the same user not shown)
Line 4: Line 4:
 
See [[Using communication packages]] for instructions on how to select the communication package, and configure it. The type name of the message channel object is:  
 
See [[Using communication packages]] for instructions on how to select the communication package, and configure it. The type name of the message channel object is:  
 
'''{{Style=Identifier|OpcLabs.Mqtt.MqttClientMessageChannel,OpcLabs.Mqtt}}''' .
 
'''{{Style=Identifier|OpcLabs.Mqtt.MqttClientMessageChannel,OpcLabs.Mqtt}}''' .
== URL string ==
+
== Opening the channel ==
 +
 
 +
=== URL string ===
 +
If the URL string can be parsed as an URL, and it has "mqtt", or "tcp" scheme, TCP protocol (without SSL/TLS) will be used. In this case, various pieces of information are extracted from the URL. The syntax is:
 +
 
 +
<code>''scheme'':[//[''username''[:''password'']@]''host''[:''port'']][/clientId=''clientId'']</code>
 +
 
 +
The username and password from the URL are used for client credentials.
 +
The "mqtt" and "tcp" schemes are equivalent.
 +
 
 +
Using the clientId query parameter you can override the default clientId supplied by host software. Additional query parameters can be specified, and are ignored.
 +
 
 +
Examples:
 +
<pre>
 +
mqtt://test.mosquitto.org
 +
tcp://test.mosquitto.org
 +
</pre>
 +
 
 +
If the URL string can be parsed as an URL, and it has "ws" scheme, the communication packet will attempt to use the WebSocket protocol (without SSL/TLS). There are some indications that support for WebSocket is in plans for the underlying library, but in reality it does not work in the end and you will get an error.
 +
 
 +
If the URL string can be parsed as an URL, and it has "mqtts", "ssl" or "wss" scheme, an error occurs, indicating that the client has no binding for these schemes. If the URL string cannot be parsed as an URL, or it has a scheme that is not listed here, the message channel will still open, using the URL string as the host address, clientId and cleanSession flag provided by the host software, and all other parameters given by the configuration properties.
 +
 
 +
=== Interface name ===
 +
The interface name, if provided by the host software, is ignored.
 +
 
 +
=== Certificates ===
 +
Since the underlying library does not support secure communication, the parameters for server certificate validation, and client certificates, if provided by the host software, are irrelevant and are ignored.
  
 
== Configuration ==
 
== Configuration ==
Line 19: Line 45:
 
|ErrorWaitDelay
 
|ErrorWaitDelay
 
|System.Int32
 
|System.Int32
|
+
|How long the client will wait before attempting to reconnect after an unexpected error on the endpoint. In milliseconds.
 
|-
 
|-
 
|MqttConfiguration
 
|MqttConfiguration
Line 32: Line 58:
 
|System.Int32
 
|System.Int32
 
|Size in bytes of the receive buffer of the underlying transport protocol. Only use it when the property applies to the undelrying protocol used.
 
|Size in bytes of the receive buffer of the underlying transport protocol. Only use it when the property applies to the undelrying protocol used.
 +
Default value is 8192.
 
|-
 
|-
 
|MqttConfiguration.ConnectionTimeoutSecs
 
|MqttConfiguration.ConnectionTimeoutSecs
Line 48: Line 75:
 
|System.Int32
 
|System.Int32
 
|Port to connect a Client to a Server.
 
|Port to connect a Client to a Server.
 +
Default value is 1883. This get overridden by a value from the URL string, if the string can be parsed and the port is specified in its authority part.
 
|-
 
|-
 
|MqttConfiguration.WaitTimeoutSecs
 
|MqttConfiguration.WaitTimeoutSecs
Line 55: Line 83:
 
|OpenFailureWaitDelay
 
|OpenFailureWaitDelay
 
|System.Int32
 
|System.Int32
|
+
|How long the client will wait before attempting to reconnect after failing to open. In milliseconds.
 
|-
 
|-
 
|RemoteDisconnectedWaitDelay
 
|RemoteDisconnectedWaitDelay
 
|System.Int32
 
|System.Int32
|
+
|How long the client will wait before attempting to reconnect after a remote disconnection produced by the server. In milliseconds.
 
|}
 
|}

Revision as of 14:28, 13 December 2019

This communication package is based on System.Net.Mqtt library by Xamarin (Microsoft). See MQTT communication packages for a summary of the communication package and the library. The library supports Client and Server roles; the communication package only supports the Client role.

See Using communication packages for instructions on how to select the communication package, and configure it. The type name of the message channel object is: OpcLabs.Mqtt.MqttClientMessageChannel,OpcLabs.Mqtt .

Opening the channel

URL string

If the URL string can be parsed as an URL, and it has "mqtt", or "tcp" scheme, TCP protocol (without SSL/TLS) will be used. In this case, various pieces of information are extracted from the URL. The syntax is:

scheme:[//[username[:password]@]host[:port]][/clientId=clientId]

The username and password from the URL are used for client credentials. The "mqtt" and "tcp" schemes are equivalent.

Using the clientId query parameter you can override the default clientId supplied by host software. Additional query parameters can be specified, and are ignored.

Examples:

mqtt://test.mosquitto.org
tcp://test.mosquitto.org

If the URL string can be parsed as an URL, and it has "ws" scheme, the communication packet will attempt to use the WebSocket protocol (without SSL/TLS). There are some indications that support for WebSocket is in plans for the underlying library, but in reality it does not work in the end and you will get an error.

If the URL string can be parsed as an URL, and it has "mqtts", "ssl" or "wss" scheme, an error occurs, indicating that the client has no binding for these schemes. If the URL string cannot be parsed as an URL, or it has a scheme that is not listed here, the message channel will still open, using the URL string as the host address, clientId and cleanSession flag provided by the host software, and all other parameters given by the configuration properties.

Interface name

The interface name, if provided by the host software, is ignored.

Certificates

Since the underlying library does not support secure communication, the parameters for server certificate validation, and client certificates, if provided by the host software, are irrelevant and are ignored.

Configuration

The table below lists the available properties, their types, and descriptions. Many properties come from configurable options of the underlying library. Most properties can usually stay at their defaults, and those that cannot are usually overridden from the host software (as noted). We will emphasize specific properties if they are important.

Property Type Description
ClientWaitTimeout System.Int32 Determines the maximum wait time for the client to open before publishing a message. In milliseconds.
ErrorWaitDelay System.Int32 How long the client will wait before attempting to reconnect after an unexpected error on the endpoint. In milliseconds.
MqttConfiguration System.Net.Mqtt.MqttConfiguration General configuration used across the protocol implementation.
MqttConfiguration.AllowWildcardsInTopicFilters System.Boolean Determines if multi level (#) and single level (+) wildcards are allowed on topic filters. Default value is true.
MqttConfiguration.BufferSize System.Int32 Size in bytes of the receive buffer of the underlying transport protocol. Only use it when the property applies to the undelrying protocol used.

Default value is 8192.

MqttConfiguration.ConnectionTimeoutSecs System.Int32 Seconds to wait for a channel connection until the operation timeouts. This value is generally used to wait for the MQTT channel to open. Default value is 5 seconds.
MqttConfiguration.KeepAliveSecs System.UInt16 Seconds to wait for the MQTT Keep Alive mechanism until a Ping packet is sent to maintain the connection alive. Default value is 0 seconds, which means Keep Alive disabled.
MqttConfiguration.MaximumQualityOfService System.Net.Mqtt.MqttQualityOfService Maximum Quality of Service (QoS) to support. Default value is AtMostOnce, which means QoS 0.
MqttConfiguration.Port System.Int32 Port to connect a Client to a Server.

Default value is 1883. This get overridden by a value from the URL string, if the string can be parsed and the port is specified in its authority part.

MqttConfiguration.WaitTimeoutSecs System.Int32 Seconds to wait for an incoming required message until the operation timeouts. This value is generally used to wait for Server or Client acknowledgements. Default value is 5 seconds.
OpenFailureWaitDelay System.Int32 How long the client will wait before attempting to reconnect after failing to open. In milliseconds.
RemoteDisconnectedWaitDelay System.Int32 How long the client will wait before attempting to reconnect after a remote disconnection produced by the server. In milliseconds.