Difference between revisions of "MQTTCLIENT"

From HSYCO
Jump to navigation Jump to search
 
(46 intermediate revisions by 2 users not shown)
Line 12: Line 12:
 
*'''User''': username for authentication with MQTT broker
 
*'''User''': username for authentication with MQTT broker
 
*'''Password''': password for authentication with MQTT broker
 
*'''Password''': password for authentication with MQTT broker
−
If presents, these two fields must be both not empty
 
  
 
=== Options ===
 
=== Options ===
Line 31: Line 30:
 
|false
 
|false
 
|start generating events only after HSYCO is aligned with the current status of the system
 
|start generating events only after HSYCO is aligned with the current status of the system
−
 
−
|-
 
−
 
−
|rowspan="2"|autoreconnect
 
−
|rowspan="2"|false
 
−
|true
 
−
|reconnects automatically to the MQTT broker when connection is lost
 
−
|-
 
−
|false
 
−
|doesn't reconnect to the MQTT broker when connection is lost
 
  
 
|-
 
|-
Line 47: Line 36:
 
|rowspan="2"|false
 
|rowspan="2"|false
 
|true
 
|true
−
|cleans eventually existing previous session held by the MQTT broker
+
|cleans eventually existing previous session held by the MQTT broker. This will remove any previous subscription and unacknowledged messages
 
|-
 
|-
 
|false
 
|false
−
|restores eventually existing previous session held by the MQTT broker
+
|restores eventually existing previous session held by the MQTT broker. This will restore all existing subscriptions and resend any unacknowledged message
  
 
|-
 
|-
Line 75: Line 64:
 
|n >= 0
 
|n >= 0
 
|this value, measured in seconds, defines the maximum time interval this driver will wait for the network connection to the MQTT broker to be established. A value of 0 disables timeout processing meaning the driver will wait until the network connection is made successfully or fails.
 
|this value, measured in seconds, defines the maximum time interval this driver will wait for the network connection to the MQTT broker to be established. A value of 0 disables timeout processing meaning the driver will wait until the network connection is made successfully or fails.
−
 
−
|-
 
−
 
−
|id
 
−
|
 
−
|<alphanumeric text>
 
−
|id of this MQTT client in UTF-8 format. This field is compulsory to establish connection with the MQTT broker
 
  
 
|-
 
|-
Line 100: Line 82:
 
=== Subscriptions file ===
 
=== Subscriptions file ===
  
−
Under the hsyco root directory you could have a file named "mqttsubscriptions-<I/O Server ID>.ini" which can contain a series of line, each line represents a topic to subscribe and the topic's quality-of-service (Qos):
+
Under the hsyco root directory there could be a file named "mqttsubscriptions-<IOServerId>.ini" (e.g "mqttsubscriptions-myclientid.ini") which can contain a series of line, each line represents a topic to subscribe and the topic's quality-of-service (qos). On each line topic and relative qos are separated by a white space:
 +
 
 +
E.g.
 +
 
 +
<pre>/mqtt/test 2
 +
 
 +
home/bathroom 1
 +
 
 +
/outdoor 0</pre>
 +
 
 +
== Datapoints ==
 +
 
 +
{| class="wikitable"
 +
!ID
 +
!Value
 +
!R/W
 +
!Description
 +
 
 +
|-
 +
 
 +
|rowspan="2" |connection
 +
|online
 +
|R
 +
|the client is connected to the MQTT broker
 +
|-
 +
|offline
 +
|R
 +
|initialization of the driver failed or loop cycle failed
 +
 
 +
|-
 +
 
 +
|received.<topicName>
 +
|<message>
 +
|R
 +
|the client received a message on topicName
 +
 
 +
|-
 +
 
 +
|publish.<topicName>
 +
|<message>
 +
|R/W
 +
|the client published a message on topicName
 +
 
 +
|-
 +
 
 +
|rowspan="4" |subscribe.<topicName>
 +
|0
 +
|R/W
 +
|the client subscribes to topicName with qos=0
 +
|-
 +
|1
 +
|R/W
 +
|the client subscribes to topicName with qos=1
 +
|-
 +
|2
 +
|R/W
 +
|the client subscribes to topicName with qos=2
 +
|-
 +
|unsubscribe
 +
|R/W
 +
|the client unsubscribes from topicName
  
−
<pre><clientid>:username=<username>,password=<password></pre>
+
|}
  
−
E.g.  
+
<topicName> field is case insensitive and will be reported in lower case, furthermore the MQTT client will replace every whitespace present in the topic name with '_'. E.g. if this driver publishes a message or subscribes to "Topic Test", the MQTT client will convert this value in "topic_test" and this change will be reflected in <topicName> field present in datapoints
 +
 
 +
 
 +
<span id="note">
 +
;Note :
 +
All the subscriptions and unsubscriptions made at run-time are not persistent so they will be lost in case of driver restart.
 +
 
 +
All publish messages with QoS > 0 are temporarily stored in the directory "qos2store" waiting for the acknowledge by the MQTT broker. Once they are acknowledged they are deleted.
 +
</span>
  
−
<pre>client123:username=homesensor,password=abc123</pre>
+
== Release Notes ==
  
 +
=== 3.8.0 ===
 +
*improved UTF-8 characters support
  
−
Clientid must be present in each line while username and password are optional; if username and password are not present there will be two cases:
+
=== 3.7.0 ===
−
*if default username and password are specified in "hsyco.ini" they will be used by the authentication mechanism
+
*initial release
−
*if default username and password are not specified in "hsyco.ini" the authentication mechanism is disabled
 

Latest revision as of 15:07, 24 December 2020

This driver acts as an MQTT client (publisher/subscriber) for Hsyco, it fully supports MQTT version 3.1.1.

HSYCO Configuration

Add the MQTTCLIENT I/O Server in the I/O Servers section of the Settings and set its parameters:

Communication

  • IP Address: host name or IP address of the MQTT broker
  • IP Port: TCP/IP port of the MQTT broker

Authentication

  • User: username for authentication with MQTT broker
  • Password: password for authentication with MQTT broker

Options

ID Default Values Description
startupevents false true generate IO events also during the driver’s start-up phase
false start generating events only after HSYCO is aligned with the current status of the system
cleansession false true cleans eventually existing previous session held by the MQTT broker. This will remove any previous subscription and unacknowledged messages
false restores eventually existing previous session held by the MQTT broker. This will restore all existing subscriptions and resend any unacknowledged message
messageretain false true with this option true the MQTT broker will save publish messages for future subscribers
false with this option false the MQTT broker will not save publish messages for future subscribers
keepalive 60 n >= 0 this value, measured in seconds, defines the maximum time interval between messages sent or received. It enables this driver to detect if the MQTT broker is no longer available. In the absence of a data-related message during this time period, the client sends a very small "ping" message, which the server will acknowledge. A value of 0 disables keepalive processing in the client.
connecttimeout 30 n >= 0 this value, measured in seconds, defines the maximum time interval this driver will wait for the network connection to the MQTT broker to be established. A value of 0 disables timeout processing meaning the driver will wait until the network connection is made successfully or fails.
messageqos 0 0 every publish message is sent at most one time, so it doesn't receive acknowledge message from the MQTT broker
1 every publish message is sent at least one time, so it waits acknowledge message from the MQTT broker
2 every publish message is sent exactly one time, so there will be a series of acknowledge messages between the MQTT client and broker

Subscriptions file

Under the hsyco root directory there could be a file named "mqttsubscriptions-<IOServerId>.ini" (e.g "mqttsubscriptions-myclientid.ini") which can contain a series of line, each line represents a topic to subscribe and the topic's quality-of-service (qos). On each line topic and relative qos are separated by a white space:

E.g. 

/mqtt/test 2

home/bathroom 1

/outdoor 0

Datapoints

ID Value R/W Description
connection online R the client is connected to the MQTT broker
offline R initialization of the driver failed or loop cycle failed
received.<topicName> <message> R the client received a message on topicName
publish.<topicName> <message> R/W the client published a message on topicName
subscribe.<topicName> 0 R/W the client subscribes to topicName with qos=0
1 R/W the client subscribes to topicName with qos=1
2 R/W the client subscribes to topicName with qos=2
unsubscribe R/W the client unsubscribes from topicName

<topicName> field is case insensitive and will be reported in lower case, furthermore the MQTT client will replace every whitespace present in the topic name with '_'. E.g. if this driver publishes a message or subscribes to "Topic Test", the MQTT client will convert this value in "topic_test" and this change will be reflected in <topicName> field present in datapoints


Note 

All the subscriptions and unsubscriptions made at run-time are not persistent so they will be lost in case of driver restart.

All publish messages with QoS > 0 are temporarily stored in the directory "qos2store" waiting for the acknowledge by the MQTT broker. Once they are acknowledged they are deleted.

Release Notes

3.8.0

  • improved UTF-8 characters support

3.7.0

  • initial release
Retrieved from "https://wiki.hsyco.com/3.8/index.php?title=MQTTCLIENT&oldid=9529"