MQTT Controller

The PowerHome MQTT controller gives you the ability to utilize the MQTT (Message Queuing Telemetry Transport) protocol which has become very popular with a multitude of IOT devices. MQTT is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol. It was designed as an extremely lightweight publish/subscribe messaging transport. This PowerHome controller supports devices created in the Analog IO screen as well as the new MQTT Publish and MQTT Subscribe screens in the PowerHome Explorer. To learn more about MQTT, please visit the homesite at http://mqtt.org

The PowerHome MQTT controller (as well as the PowerHome MQTT plugin) 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.

Once you have an MQTT broker properly setup and configured (either your own or a web based one), you will next need to configure the controller in the PowerHome Explorer under Setup->Controllers by pressing the "Settings" button for your MQTT controller entry. Doing so will bring up the following screen with the defaults pictured below:



The first section describes the MQTT broker that you will be connecting to. You'll enter either the IP address of your broker or the URL if you are using a web based broker. If you installed a broker on your PowerHome machine, you can use the default IP of 127.0.0.1.

Next enter the Port that your broker is configured to use. The default port for MQTT brokers is typically 1883. If your MQTT broker is configured to use secure connections (SSL or TLS), then check the SSL / TLS box. If your broker does not use secure connections, leave this box unchecked. Doing so will automatically set the SSL Protocol to "None". If you are using secure connections, next select the SSL Protocol that your broker uses. You'll also need to supply the CA Certificate and Client Certificate as full path and filenames to X509 certificates.

The next section to configure is the "Client" section. This has to do with how PowerHome will connect to the MQTT broker. You must have a unique ID (unique with respect to all other clients connected to your chosen broker) and you can use the default if you're hosting your own broker or change it to something that identifies your particular PowerHome installation. If your broker requires a userid/password to connect, you'll enter those values in the appropriate boxes.

The next configuration area are the "Prefixes". The Prefixes area allows you to define prefixes to the MQTT topics that you will publish or subscribe to. You have a set of publish and subscribe fixes that handles devices created in the Analog IO screen and you have a set of publish / subscribe prefixes that are used in the MQTT Publish and MQTT Subscribe screens in the PH Explorer. Since MQTT topics can get quite long and often you're subscribing and publishing to a heirarchy that is the same at the upper levels, you can put these upper level "prefixes" in this screen and won't need to enter the redundant information in the Analog IO or MQTT Publish / Subscribe screens. Whatever is entered in the prefix fields in the Settings window will be prefixed to the topics that you configure within the Analog IO and MQTT screens within PowerHome. On the off chance that you need to publish or subscribe to a topic that is outside of the heirarchy that is described in the prefix fields, you can add a "$" character as the first character of a topic in the MQTT Publish / Subcribe screens or in the Analog IO screen. Adding a "$" as the first character of either a subscribe or publish topic will cause PowerHome to drop the "$" character and NOT prepend the relevant prefix to the topc. While the "$" character is a valid topic character at the beginning of an MQTT topic, these topics are not typically used for client communication and is therefore used by PowerHome as a "Don't apply prefix" flag for a topic. Don't be confused by the MQTT protocol specification for the use of "$" as the first character of a topic and PowerHomes internal use of "$" at the beginning of topics.

Once your MQTT controller is properly configured in PowerHome, restart or reinit (changes to the Setup section of PH Explorer requre a reinint or restart to take effect). You are now ready to either defined devices in the Analog IO screen or the MQTT screens to take advantage of the MQTT controller.

To define Analog IO devices for use with MQTT, you need to create and configure them in the Analog I/O Units screen of PowerHome Explorer. The MQTT controller supports analog device types of IOT Input, IOT Output, IOT Input (Calc), and IOT Output (Calc). The difference between the IOT Input/Output and IOT Input/Output (Calc) device types are that the (Calc) device types will actually send the Analog Calculated value to the broker vs sending the normal Raw value. Messages received on the Subscribe topic will also be treated as Calc values and the Raw value will be updated from the Calc value vs the other way around for non-(Calc) device types. Enter the Subscribe Topic for the Analog device into the "ROM ID / IP / Topic / Channel" column. Messages received from the broker on this topic will update the raw and calc values for the Analog device. While the MQTT protocol allows you to use wildcard characters (+ #) in Subscribe topics, you CANNOT do so in the Analog IO screen and must fully qualify the Subscribe topic that will update the Analog IO device. If your chosen device type is an Output device, you have the option to Publish messages (setting an Analog Output device from within PowerHome) to a separate MQTT topic from the Subscribe Topic. If you have defined an Output device and wish to have the separate Publish topic, enter the Publish topic in the "P Topic / O Channel" column. The MQTT protocol does NOT allow wildcard characters (+ #) in Publish Topics. The Unit and Point columns in the Analog IO screen for MQTT controlled device types works a little different from other controllers and instead hold details upon how topics are configured with the broker. Set the Unit column to 0 to have topic messages NOT be retained. Any other value will cause topic messages to be retained (see MQTT documentation for more information on these details). Set the Point column to the QOS (Quality Of Service) level you desire for the topic messages. Valid values are 0, 1, or 2. Any other value will be treated as a QOS level of 0. While MQTT allows for using different QOS levels for Subscribe and Publish messages, the Analog IO devices will use the same Point value for QOS for both Publish and Subscribe messages. 

Controlling an Analog IO device from within PowerHome (setting the device to a new value using the Device Status screen, ph_setanalogout function, etc) will Publish the Raw value for normal IOT Input/Output device types or the Calc value for the IOT Input/Output (Calc) devices to the Publish topic WITHOUT any formatting or conversion to JSON, XML, or similar. The Publish message will ONLY contain the Raw or Calc value. Receiving values from the MQTT broker on the Subscribe Topic for the Analog IO device default expects the message to ONLY contain the Raw or Calc value. This can be overridden though by placing a "check" in the JSON column for the Analog IO device. Checking the JSON column will cause PowerHome to interpret the incoming message as JSON data and will attempt to extract the raw or calc value from a name:value pair where the name matches one of the following: (value | status | state | set).

When controlling Analog IO devices (from PowerHome) associated with the MQTT controller, the Analog IO device will NOT have it's Raw or Calc values updated in the table. An Analog Out trigger will ALSO NOT be fired. Controlling an MQTT Analog IO device from PowerHome merely publishes a message to the Publish topic. The Published message will be received by the broker and then echoed back on the Subscribe Topic of the Analog IO device if the Publish and Subscribe topics are the same. If they differ, then the results of the Publish message are expected to ultimately be reflected back to the Subscribe topic by the remote controlled device. You WILL get an Analog In trigger on the received Subscribe topic. This is what will update the Raw and Calc values for the Analog IO device. If you have an IOT Output device type and left the Publish topic blank and entered only a Subscribe topic, controlling this device from PowerHome will Publish a message with the data to the Subscribe topic (Subscribe and Publish are the same). The broker receives this message which then sent out to all clients that have subscribed to that topic of which PowerHome is one. The message that was just sent will come in on the Subscribe topic, update the Analog IO device and then fire an Analog In trigger.

If the design of how Analog IO devices works with MQTT cannot be applied to your situation, you still have the flexibility to adapt to nearly any scenario. In this case, you can create Analog IO devices with a device type of Input or Output and assign them to the PowerHome Virtual controller (must be setup in the Controllers screen). You can then place a call to the ph_mqttpub function in either the RawtoCalc formula, CalctoRaw formula, or an Analog Out trigger to publish the appropriate message containing data structured exactly how you want. You would also create a record in the MQTT Subscribe screen of PowerHome Explorer using your preferred Subscribe topic (including wildcards if you desire) and place a call to the ph_setanalogvalue ( ) function in the "Formula" column to update the respective Analog IO device. A little more work than just declaring the device in the Analog IO screen but full control over the Publishing and Subscribing of MQTT messages.

In addition to using the Analog IO screen to setup MQTT associated devices, you can also interact with the PowerHome MQTT controller through the MQTT Subscribe and MQTT Publish screens in the PowerHome Explorer under the MQTT section. The MQTT Subscribe screen allows you to define topic filters (including wildcards) that you would like to Subscribe to. When a message is received matching the Topic Filter that was Subscribed to, the "Formula" for that particular line will be queued and executed allowing you to act on the incoming message however you like. 

The MQTT Publish screen allows you to define topics that you would like to Publish messages to. A Publish Topic cannot contain wildcards (+ #) and so must be fully specified in the Publish Topic column. You also can specify the QOS and whether messages should be retained or not on a per topic basis. The "sending" of messages a particular Publish Topic in this screen is done via the ph_mqttpub ( ) function using the "(MQTT table)" syntax (3 parameters).

Using the PowerHome MQTT controller, you also have the option to Publish messages to topics that have not been predefined and do not appear in the MQTT Publish screen. You do this using the ph_mqttpub ( ) function using the "(General)" syntax that takes 6 parameters.

You also have the ability to Subscribe to topics of your choice that are NOT defined within the MQTT Subscribe screen or in the Analog IO screen. You do this by calling the ph_ctlrcmd ( ) function and using a "command" value of 9997. You supply the Topic filter you wish to subscribe to in the "parm3" parameter and the QOS in the "parm1" parameter. When an incoming message is received on a Subscribed Topic, if the topic DOES NOT match any Analog IO device topics AND does not match any Topic Filters in the MQTT Subscribe screen, then a Generic Controller trigger will be fired on Command 1, Option 1 with details of the topic and message.

To Unsubscribe from messages previously Subscribed to, use the ph_ctlrcmd ( ) function with a "command" value of 9996. The topic you wish to Unsubscribe from will be in "parm3".