Plugin: MQTT
Launch Data (ActiveX
Classname):
PH_Mqttpi.phmqttpi
Initialization Data: A full path and filename to the plugin INI
file. A base configuration INI file can be found in the plugins directory
at c:\powerhome\plugins\phmqttpi.ini. Details on how to configure the INI are provided
below.
This plugin provides support
for MQTT (Message Queue Telemetry Transport) protocol. This technology is in use
by a large number of IOT (Internet Of Things) devices and even be implemented in
your own DIY projects such as those based upon Arduino or ESP8266/ESP32 devices.
Before using this plugin, you must first have setup and configured an MQTT
broker. To learn more about MQTT, please visit the homesite at
http://mqtt.orgThe PowerHome MQTT plugin
(as well as the PowerHome MQTT controller) make use of the open source M2Mqtt C#
code written by Paolo Patierno to handle the low level MQTT transactions and
protocol. You can find the M2Mqtt sourcecode repository here:
https://github.com/eclipse/paho.mqtt.m2mqtt and
you can find the M2Mqtt homepage here:
https://m2mqtt.wordpress.com/In order to use the MQTT
protocol in your environment, you must first install and setup an appropriate
MQTT Broker (Server) which acts as a central hub for all MQTT incoming and
outgoing messages. There are a number of free brokers available for a
variety of platforms. One of the most popular ones is Mosquitto and can be
installed on the PowerHome machine itself. You can learn more about this broker
at its homesite at
https://mosquitto.org. As an alternative to
installing and running your own MQTT broker, you can make use of any number of
brokers that are available on the web.
PowerHome supports MQTT via
this plugin and the
PowerHome MQTT
controller. You can use one or the other or both of them at the same time. A
common use would be to use the PH MQTT controller for device status/update in
the Analog IO screen and
the MQTT Plugin for all other tasks.
INI File
Configuration:
The base configuration INI
file contents will appear like this:
[setup]
host=192.168.0.125
port=1883
secure=0
cacert=
clientcert=
sslprotocol=0
clientid=PH MQTT Plugin
userid=
password=
willflag=
willtopic=
willqos=
willretain=
willmessage=
cleansession=
keepaliveperiod=
publishprefix=
subscribeprefix=
subscribecount=4
options=0
[subscribe_1]
topicfilter=#
qos=0
actiontype=1
action=
[subscribe_2]
topicfilter=ph/lights/+
qos=0
actiontype=9
action=ph_msgbox("Variables",ph_returnallvars(6),90)
[subscribe_3]
topicfilter=ph/test/+/light
qos=0
actiontype=1
action=
[subscribe_4]
topicfilter=+/+/#
qos=0
actiontype=1
action=
A number of the parameters in
the [Setup] section of the INI file are the same as for the MQTT Controller. The
Host and Port parameters should be set to the IP and Port of your MQTT broker.
If your broker is configured for secure communications (SSL/TLS), then set the
Secure parameter to 1. Otherwise set to 0. If you set the Secure parameter to 1,
then you must supply the CA Certificate and Client Certificate in the CACert and
ClientCert parameters. If the Secure parameter is 0 (for no secure
communications), then set the SSLProtocol parameter to 0. If the Secure
parameter is 1, then set the SSLProtocol parameter to the number representing
the SSL/TLS protocol in use by the broker (0 - None, 1 - SSL v3, 2 - TLS v1.0, 3
- TLS v1.1, 4 - TLS v1.2)
Set the ClientID to a unique identifier (unique
within the broker) to identify your the plugin instance of the
MQTT client. If you are also running the MQTT Controller (or
multiple instances of the MQTT Plugin, you must make the ClientID different
within each instance if they are connecting to the same broker). If your broker requires a userid/password, then set those
values in the UserID and Password parameters.
The MQTT
protocol allows for a "Will" message for a client. More information can be found
on the MQTT site. Basically it is a topic/message that is
the last data that will be sent when the client disconnects.
If you want a "Will" message, set the WillFlag parameter to 1.
In not, then set it to 0. If you set the WillFlag to 1, then you need to specifiy values
for the WillTopic, WillQOS, WillRetain, WillMessage parameters.
Set the CleanSession as
appropriate to either 1 (CleanSession = true) or 0 (CleanSession = false). Basically, setting
the CleanSession flag to false means that the broker will save the
client session on disconnection (subscribed topics, messages for these topics delivered on
reconnection). If you set the CleanSession flag to true (usually the default), the broker will NOT retain data to be
sent to the client when it reconnects.
Set the
KeepAlivePeriod to an appropriate value in seconds. Setting this parameter to
0 disables the Keep Alive mechanism. The default value is 60 (seconds).
This parameter is the maximum amount of time for no communication (either way) between the broker and the client to
occur before the client will be disconnected.
Set the PublishPrefix and SubscribePrefix
parameters to appropriate values if you always want to have a set "prefix" for your topics. If you don't want
prefixes, you can leave these parameters blank.
The Options parameter is not a
part of MQTT and instead controls how the plugin works. This parameter is a
flags parameter where you add the desired values together to a total. A value of 1 indicates that the plugin will fire "Status"
triggers when they occur. Status triggers are fired when the MQTT connection is closed, a message is
published, a topic is subscribed, or a topic is unsubscribed. This value would
typically be used during initial debugging to determine if these events are occurring properly. A value
of 2 tells the plugin to fire "Exception" triggers. An exception trigger occurs whenever
an exception occurs within the plugin. Normally there shouldnt be exceptions but
this option may be handy for debugging purposes or to catch
when an exception occurs in normal use. In normal use scenarios, you
would usually set the Options parameter to either 0 or 2. In a debug scenario, a value of 3 (1
+ 2) would be the preferred setting.
The
last parameter to be concerned with is the SubscribeCount. Set this
parameter to the number of topics you wish the plugin to subscribe
to and to be configured in the following [subscribe_?] sections. If you wish to subscribe to 4 topics, then you'll
have [subscribe_1], [subscribe_2], [subscribe_3], and [subscribe_4] sections.
Each [subscribe_?] section has
4 parameters with the TopicFilter and QOS parameters being self explanatory if
you're familiar with the basics of the MQTT protocol. The ActionType and Action
parameters instruct the plugin what to do when a message is received on one of
the subscribed topics. The ActionType parameter is a flags parameter where you
the values together to get the desired total value. A value of 2 indicates that
the Action is a Device Control string. A value of 4
indicates that the Action is a Macro ID. A value of 6 indicates that the Action
is a Formula ID. A value of 8 indicates that the Action is a raw formula.
You will ONLY use 1 value from the 2, 4, 6, 8
action option values. To the action value you've chosen, you may add a 1 to have
the plugin also fire a trigger within PowerHome. If you ONLY want a trigger to be
fired when a message is received on a topic, set the
ActionType to 1. If you wanted to fire a trigger AND execute
a Device Control string, set the ActionType to 3, etc. The Action
parameter will be set to the value that corresponds with your chosen ActionType (blank if you didnt choose an action
type option (2, 4, 6, or 8).
Controller Commands supported:
| Command |
Parm1 |
Parm2 |
Parm3 |
Parm4 |
Description |
| 0 |
0 |
|
|
|
Return details on all
Subscribed topics |
| 0 |
1 thru SubscribeCount |
|
|
|
Return details on Subscribed
topic number specified in Parm1 |
| 1 |
0 |
|
|
|
Return all configuration INI
parameters in the [Setup] section (except for Password) |
| 1 |
1 |
|
|
|
Return the [Setup]Host
parameter |
| 1 |
2 |
|
|
|
Return the [Setup]Port
parameter |
| 1 |
3 |
|
|
|
Return the [Setup]Secure
parameter |
| 1 |
4 |
|
|
|
Return the [Setup]CACert
parameter |
| 1 |
5 |
|
|
|
Return the [Setup]ClientCert
parameter |
| 1 |
6 |
|
|
|
Return the [Setup]SSLProtocol
parameter |
| 1 |
7 |
|
|
|
Return the [Setup]ClientID
parameter |
| 1 |
8 |
|
|
|
Return the [Setup]UserID
parameter |
| 1 |
9 |
|
|
|
Return the [Setup]WillFlag
parameter |
| 1 |
10 |
|
|
|
Return the [Setup]WillTopic
parameter |
| 1 |
11 |
|
|
|
Return the [Setup]WillQOS
parameter |
| 1 |
12 |
|
|
|
Return the [Setup]WillRetain
parameter |
| 1 |
13 |
|
|
|
Return the [Setup]WillMessage
parameter |
| 1 |
14 |
|
|
|
Return the [Setup]CleanSession
parameter |
| 1 |
15 |
|
|
|
Return the
[Setup]KeepAlivePeriod parameter |
| 1 |
16 |
|
|
|
Return the [Setup]PublishPrefix
parameter |
| 1 |
17 |
|
|
|
Return the
[Setup]SubscribePrefix parameter |
| 1 |
18 |
|
|
|
Return the
[Setup]SubscribeCount parameter |
| 1 |
19 |
|
|
|
Return the [Setup]Options
parameter |
| 2 |
1 thru SubscribeCount |
0 |
|
|
Return the Subscribed Topic for
the [Subscribe_?] specified in Parm1 |
| 2 |
1 thru SubscribeCount |
1 |
|
|
Return the Subscribed QOS
for the [Subscribe_?] specified in Parm1 |
| 2 |
1 thru SubscribeCount |
2 |
|
|
Return the Action Type for the
[Subscribe_?] specified in Parm1 |
| 2 |
1 thru SubscribeCount |
3 |
|
|
Return the Action for the
[Subscribe_?] specified in Parm1 |
| 3 |
0 |
|
|
|
Unsubscribe from all topics and
then Subscribe to all topics |
| 3 |
1 |
|
|
|
Unsubscribe from all
topics |
| 3 |
2 |
|
|
|
Subscribe to all topics |
| 3 |
3 |
1 thru SubscribeCount |
|
|
Unsubscribe from topic
specified in Parm2 |
| 3 |
4 |
1 thru SubscribeCount |
|
|
Subscribe to topic specified in
Parm2 |
| 4 |
0, 1, or 2 (QOS) |
ActionType value |
Topic filter |
Action string |
Adds an "on the fly" topic
subscription (not described in the INI file) to the current list of
subscribed topics. See the INI configuration info above for the values to
use for the Parm? fields |
| 5 |
1 thru SubscribeCount |
ActionType value |
Topic filter |
Action string |
Update/Change the Subscribe
parameters for the Subscribe topic number specified by Parm1. The QOS will
be 0 |
| 6 |
1 thru SubscribeCount |
ActionType value |
Topic filter |
Action string |
Update/Change the Subscribe
parameters for the Subscribe topic number specified by Parm1. The QOS will
be 1 |
| 7 |
1 thru SubscribeCount |
ActionType value |
Topic filter |
Action string |
Update/Change the Subscribe
parameters for the Subscribe topic number specified by Parm1. The QOS will
be 2 |
| 8 |
|
|
Topic filter |
|
Searches the subscribed topic
filters for a match with the topic filter specified in Parm3 and returns
the index number if found. If not found, returns 0 |
| 10 |
0 |
|
|
|
Returns 1 if the MQTT client is
connected, 0 otherwise |
| 10 |
1 |
|
|
|
Returns 1 if CleanSession is
true, 0 if false |
| 10 |
2 |
|
|
|
Returns the Client ID |
| 10 |
3 |
|
"get" |
|
Returns 3 if the MQTT client
version in use is 3.1. Returns 4 if the MQTT client version in use is
3.1.1 |
| 10 |
3 |
3 or 4 |
"set" |
|
Sets the MQTT client version to
3.1 if Parm2 = 3 and 3.1.1 if Parm2 = 4 |
| 10 |
4 |
|
|
|
Return the MQTT client Attempts
On Retry value |
| 10 |
5 |
|
|
|
Return the MQTT client Delay On
Retry value |
| 10 |
6 |
|
|
|
Return the MQTT client InFlight
Queue size |
| 10 |
7 |
|
|
|
Return the MQTT client
Port |
| 10 |
8 |
|
|
|
Return the MQTT SSL Port |
| 10 |
9 |
|
|
|
Return the MQTT client Timeout
on Connection value |
| 10 |
10 |
|
|
|
Return the MQTT client Timeout
on Receiving value |
| 10 |
11 |
|
|
|
Return the MQTT client Will
Flag value |
| 10 |
12 |
|
|
|
Return the MQTT client Will
Topic |
| 10 |
13 |
|
|
|
Return the MQTT client Will
QOS |
| 10 |
14 |
|
|
|
Return the MQTT client Will
Message |
| 100 |
0, 1, or 2 (QOS) |
0 or 1 (Retain flag) |
Publish Topic |
Publish Message |
Publish a message using the
values in the supplied parameters |
Generic Plugin triggers fired:
| Command |
Option |
Description |
| 1 thru
SubscribeCount |
1 |
This trigger is fired if the ActionType for
the Topic filter that is matched to an incoming message is set to fire a
trigger (Action Type values 1,3,5,7,9). The Command parameter will be set
to the [subscribe_?] index number that matches the incoming message. An
incoming message MAY match multiple subscribed topics and a trigger (with
the appropriate Command value) will be fired for each match. |
| 255 |
1 |
Fired when the MQTT client connection is
closed |
| 255 |
2 |
Fired whenever the plugin MQTT client
successfully Publishes a message to a Topic |
| 255 |
3 |
Fired whenever the MQTT client successfully
Subscribes to a Topic |
| 255 |
4 |
Fired whenever the MQTT client successfully
UnSubscribes from a Topic |
| 256 |
1 |
Fired when an exception occurs when trying to
determine the plugin local IP |
| 256 |
2 |
Fired when an Invalid Topic Filter exception
occurs |
| 256 |
3 |
Fired when an exception occurs with creating
the MQTT client object |
| 256 |
4 |
Fired when an exception occurs with
the MQTT client connecting to the broker |
| 256 |
5 |
Fired when an exception occurs with the MQTT
client disconnecting from the broker |
| 256 |
6 |
Fired when an exception occurs with
destroying the MQTT client object |
| 256 |
7 |
Fired when an exception occurs when
Subscribing to an MQTT Topic |
| 256 |
8 |
Fired when an exception occurs when
UnSubscribing to an MQTT Topic |