Difference between revisions of "MQTTBROKER"
(45 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | This driver acts as an MQTT broker for Hsyco. | + | This driver acts as an MQTT broker for Hsyco, it fully supports MQTT version 3.1.1. This broker is also ready to communicate with MQTT version 5.0 although full support to this version will be introduced later. |
[[Category:I/O Server]] | [[Category:I/O Server]] | ||
Line 7: | Line 7: | ||
=== Authentication === | === Authentication === | ||
− | *''' | + | *'''User''': optional default username for clients |
*'''Password''': optional default password for clients | *'''Password''': optional default password for clients | ||
Line 15: | Line 15: | ||
<pre><clientid>:username=<username>,password=<password></pre> | <pre><clientid>:username=<username>,password=<password></pre> | ||
+ | <pre><clientid>:password=<password>,username=<username></pre> | ||
+ | <pre><clientid>:username=<username></pre> | ||
+ | <pre><clientid>:password=<password></pre> | ||
+ | <pre><clientid></pre> | ||
E.g. | E.g. | ||
<pre>client123:username=homesensor,password=abc123</pre> | <pre>client123:username=homesensor,password=abc123</pre> | ||
+ | <pre>client123:password=abc123,username=homesensor</pre> | ||
+ | <pre>client123:username=homesensor</pre> | ||
+ | <pre>client123:password=abc123</pre> | ||
+ | <pre>client123</pre> | ||
Line 24: | Line 32: | ||
*if default username and password are specified in "hsyco.ini" they will be used by the authentication mechanism | *if default username and password are specified in "hsyco.ini" they will be used by the authentication mechanism | ||
*if default username and password are not specified in "hsyco.ini" the authentication mechanism is disabled | *if default username and password are not specified in "hsyco.ini" the authentication mechanism is disabled | ||
+ | |||
+ | Client identifiers are considered as case insensitive when they are registered to the MQTTBROKER, so there can't be two identifiers with the same sequence of characters in upper/lower case, e.g. "MQTT_Client" and "mqtt_client" are considered the same so they cannot be registered both on the MQTTBROKER. | ||
=== Options === | === Options === | ||
Line 59: | Line 69: | ||
|<portNumber> | |<portNumber> | ||
|local port for incoming client connection | |local port for incoming client connection | ||
+ | |||
+ | |- | ||
+ | |||
+ | |maxthreads | ||
+ | |64 | ||
+ | |n > 0 | ||
+ | |max number of clients connected simultaneously | ||
|} | |} | ||
+ | |||
+ | === MQTTBroker Utility === | ||
+ | |||
+ | Use the [[MQTTBroker Utility]] to automatically discover new clients or configure existing ones. | ||
== Datapoints == | == Datapoints == | ||
Line 75: | Line 96: | ||
|online | |online | ||
|R | |R | ||
− | |the broker | + | |the broker is ready to accept connections from clients |
|- | |- | ||
|offline | |offline | ||
Line 94: | Line 115: | ||
|- | |- | ||
− | |client.<clientId>. | + | |client.<clientId>.publish.<topicName> |
|<message> | |<message> | ||
|R | |R | ||
|clientId published a message on topicName | |clientId published a message on topicName | ||
+ | |||
+ | |- | ||
+ | |||
+ | |client.<clientId>.willpublish.<topicName> | ||
+ | |<message> | ||
+ | |R | ||
+ | |MQTTBROKER published the will message of clientId, on topicName, because of connection problems or protocol violations | ||
+ | |||
+ | |- | ||
+ | |||
+ | |client.<clientId>.lastseen | ||
+ | |<ts> | ||
+ | |R | ||
+ | |timestamp of the last message or ping sent by clientId to the broker | ||
+ | |||
+ | |- | ||
+ | |||
+ | |rowspan="2" |client.<clientId>.subscribe.<topicName> | ||
+ | |subscribed, <n> | ||
+ | |R | ||
+ | |clientId subscribed to topicName with QoS = <n> | ||
+ | |- | ||
+ | |unsubscribed | ||
+ | |R | ||
+ | |clientId unsubscribed from topicName | ||
+ | |||
+ | |- | ||
+ | |||
+ | |publish.<topicName> | ||
+ | |<message> | ||
+ | |R/W | ||
+ | |MQTTBROKER published a message on topicName | ||
|} | |} | ||
+ | |||
+ | <clientId> field in datapoints will be reported with whitespaces replaced with '_' | ||
+ | |||
+ | <topicName> field is case insensitive and will be reported in lower case, furthermore the MQTT broker will replace every whitespace present in the topic name with '_'. E.g. if a client publishes a message or subscribes to "Topic Test", the MQTT broker 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 informations about client sessions are not persistent so they will be lost in case of driver restart. The MQTT broker can maintain up to 1024 client sessions and up to 1024 retain messages in memory, every new item will replace the oldest one. | ||
+ | |||
+ | The MQTT broker can manage up to 10000 in/out MQTT messages every seconds. | ||
+ | </span> | ||
+ | |||
+ | == Release Notes == | ||
+ | |||
+ | === 3.7.0 === | ||
+ | *initial release |
Latest revision as of 08:45, 12 October 2020
This driver acts as an MQTT broker for Hsyco, it fully supports MQTT version 3.1.1. This broker is also ready to communicate with MQTT version 5.0 although full support to this version will be introduced later.
Contents
HSYCO Configuration
Add the MQTTBROKER I/O Server in the I/O Servers section of the Settings and set its parameters:
Authentication
- User: optional default username for clients
- Password: optional default password for clients
Authentication file
Under the hsyco root directory must be present a file named "mqttbroker.ini" which can contain a series of line, each line represents the credentials of a client and can have the following format:
<clientid>:username=<username>,password=<password>
<clientid>:password=<password>,username=<username>
<clientid>:username=<username>
<clientid>:password=<password>
<clientid>
E.g.
client123:username=homesensor,password=abc123
client123:password=abc123,username=homesensor
client123:username=homesensor
client123:password=abc123
client123
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:
- if default username and password are specified in "hsyco.ini" they will be used by the authentication mechanism
- if default username and password are not specified in "hsyco.ini" the authentication mechanism is disabled
Client identifiers are considered as case insensitive when they are registered to the MQTTBROKER, so there can't be two identifiers with the same sequence of characters in upper/lower case, e.g. "MQTT_Client" and "mqtt_client" are considered the same so they cannot be registered both on the MQTTBROKER.
Options
ID | Default | Values | Description |
---|---|---|---|
startupevents | true | 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 | ||
acceptunknown | false | true | accept connection from clients whose id isn't specified in mqttbrokerauth.ini |
false | doesn't accept connection from clients whose id isn't specified in mqttbrokerauth.ini | ||
localport | 1883 | <portNumber> | local port for incoming client connection |
maxthreads | 64 | n > 0 | max number of clients connected simultaneously |
MQTTBroker Utility
Use the MQTTBroker Utility to automatically discover new clients or configure existing ones.
Datapoints
ID | Value | R/W | Description |
---|---|---|---|
connection | online | R | the broker is ready to accept connections from clients |
offline | R | initialization of the driver failed or loop cycle failed | |
client.<clientId>.connected | 1 | R | clientId is connected to the broker |
0 | R | clientId isn't connected to the broker | |
client.<clientId>.publish.<topicName> | <message> | R | clientId published a message on topicName |
client.<clientId>.willpublish.<topicName> | <message> | R | MQTTBROKER published the will message of clientId, on topicName, because of connection problems or protocol violations |
client.<clientId>.lastseen | <ts> | R | timestamp of the last message or ping sent by clientId to the broker |
client.<clientId>.subscribe.<topicName> | subscribed, <n> | R | clientId subscribed to topicName with QoS = <n> |
unsubscribed | R | clientId unsubscribed from topicName | |
publish.<topicName> | <message> | R/W | MQTTBROKER published a message on topicName |
<clientId> field in datapoints will be reported with whitespaces replaced with '_'
<topicName> field is case insensitive and will be reported in lower case, furthermore the MQTT broker will replace every whitespace present in the topic name with '_'. E.g. if a client publishes a message or subscribes to "Topic Test", the MQTT broker will convert this value in "topic_test" and this change will be reflected in <topicName> field present in datapoints
- Note
All the informations about client sessions are not persistent so they will be lost in case of driver restart. The MQTT broker can maintain up to 1024 client sessions and up to 1024 retain messages in memory, every new item will replace the oldest one.
The MQTT broker can manage up to 10000 in/out MQTT messages every seconds.
Release Notes
3.7.0
- initial release