Creating MQTT profile.
Before you start. You need MQTT broker in order to communicate with MQTT devices. “Mosquito” is one of the most popular MQTT brokers. There is plenty of information online of how to download and install it both in Linux and Windows environment. There is public broker that you can use temporarily to get your feet wet with MQTT https://test.mosquitto.org
This is NOT a MQTT tutorial. If you need to learn more about MQTT and to understand better how to fill the third raw of parameters below than there are plenty of online sources for that. From a practical standpoint tough using the default values does work in most cases.
In HS3 go to Plugins –> Big5 –> Configuration
Scroll down to “MQTT Profiles” –> “New Profile”
Name. Pick the name of the MQTT profile. It will be used for all future references and for the names of HS3 devices created by Big5. We will use the name “MyMQTT” in the examples below.
Hostname/IP. Enter here the address of the computer where your mosquito broker is running. Examples: https://test.mosquitto.org or 192.168.1.253
Port: Enter 1883 here which is the default port for MQTT or enter the port number that your mosquito is running on if different than 1883.
Username/Password Enter your credentials here only if your mosquito broker is setup for password protected operations. Leave blank otherwise.
Topic. This is mandatory field essential for MQTT operations.
- In MQTT output profiles the topic must match the topic that your peripheral devices are listening to. Or you can pick any topic name here and go to your MQTT listening devices and enter the same topic there.
- In MQTT input profiles the topic must match exactly the topic that your MQTT devices are publishing to.
Examples of topic names:
home/relays/input
home/relays/output
Keep alive: Default is 10 sec. change if and as needed, but before doing so please make sure that you understand how MQTT works, how is your particular network organized and what will be the effect of changing it.
Connect timeout: Default is 30 sec. Change if and as needed.
Quality of services QoS: There are three levels of QoS in MQTT 0, 1 and 2. Pick the one you like from the drop down box. Level 0 is the most basic, least demanding and least reliable whereas level 2 guarantees delivery but also may consume more resources and bandwidth. For practical purposes level 0 works well especially if your Mosquito broker is on your network. However if your peripheral MQTT devices experience frequent power outages or lousy WiFi connection than level 1 or 2 maybe a better choice. The “Clean start” box must be unchecked if you are going level 1 or level 2 otherwise it will negate the QoS effect.
Retain: This checkbox is valid for output MQTT profiles. If this box is checked than the last message sent will be retained by the MQTT broker to be delivered first to peripheral devices when they connect that were not online when the message was originally sent out. Only the last message sent is retained.
Clean start: If this box is checked than Big5 MQTT client will not try to find and retrieve lost messages and the MQTT broker will not care to store these for later delivery. So this box better be unchecked especially for MQTT Input Profiles. with higher level of QoS.
Big5 uses Regular Expressions (or RegEx) for many of it’s advanced functions. While the full theory of RegEx is quite complex, only a small subset is needed for the practical purposes of home automation, HomeSeer and Big5. Practical examples of most frequently needed RegEx are shown at the bottom of Big5 –> Configuration page. Again you can use happily Big5 without ever needing to touch any RegEx, but they are there for the tough cases when your devices generate information that is tough to tackle otherwise. Please note that all fields are “optional” that use RegEx. Last but not least at the bottom of the Big5 –> Configration page you’ll find RegEx sandbox where you can try RegEx before you use them (highly recommended). Try some of the examples shown at the bottom of the page in the sandbox to get your hands dirty.
“Locked” if checked it will prevent Big5 from creating new HS3 devices, however Big5 will update HS3 devices, previously created.
“Device create expression” is a logical Regular Expression (result is true or false) that if true will allow the creation of a new HS3 devices by Big5. If false than no new HS3 will be created.
This field was renamed “Device affect expression” effective version 1.28 and higher. We’ve made changes to this filter to filter unwanted input not just when Big5 creates HS3 devices but also when Big5 updates devices.
Example: All of the examples below are from Pentair Pool control
All responses by Pentair pool start with !00. This explains the RegEx used for Device Create Expression
${StartsWith(input,”!00)}
Training: Go to the sandbox at the botom of Big5–>Configuration and enter the above RegEx. Also enter this string in the input field
!00 pump=1
and see the result. Must be true. Now enter this string as an input
“Error. Interface Busy.”
The result will be false.
This example shows you how Big5 creates/updates real HS3 devices based on useful information and ignores other information that may not be useful to you.
Both “Locked” and “Device create expression” are designed to prevent a glut of HS3 devices being created by “noise” and “gibberish” that sometimes happen over communication lines. MQTT is less prone to it but we kept these fields for the sake of uniformity across all protocols.
“Device name expression.” This optional box contains RegEx used to determine the name(s) of HS3 devices that Big5 creates. If left blank than Big5 will create only one HS3 device upon receiving MQTT input
Floor: Big5 Room: MQTT Device name: MyMQTT
Device name ( “MyMQTT” in the example) matches the name of the MQTT profile see above.
If our pool however has several pumps and features than one HS3 device won’t do it. This is when device name expression comes handy.
Example: Let’s assume that the pool has Pump and SPA that report their status 1 (on) or 0 (off) by sending this info over the MQTT interface
!00 pump=1
!00 spa=0
The RegEx that will retrieve the names pump and spa respectively will look like this
${Split(Split(input, “=”)[0],” “)[1]}
As we said before RegEx could be quite complex but we are using simple ones in Big5. The above RegEx can be interpreted easily. You first split the input at “=” and take the first part which will be “!00 pump”. Than you split this part again this time by the space ” ” and get the second part “pump”.
Please note that the counting always start from 0 at RegEx. So if you need the first part than you specify [0].
Training: Try this RegEx with the above two input data in the sandbox at the bottom of Big5–>Configuration page.
The above example will produce names “pump” and “spa” respectively and will create/update the following two HS3 devices
Floor: Big5 Room: MQTT Device name: MyMQTT-pump
Floor: Big5 Room: MQTT Device name: MyMQTT-spa
“Device value expression” This optional box can be left empty. It it is left empty Big5 will still create a single HS3 device (see above) and the received information will be put as a device string in the same HS3 device. If it happens to be a number it will show also as the device value in HS3. If the input information is of more complex nature and contains letters and numbers and if only specific numbers are of interest than you use “device value expression”.
Example: Let’s get the values for the devices we’ve created in the above example.
We will use this RegEx
${Numbers( Split(input, “=”)[1] )[0]}
for getting the numerical values from these inputs and put them as values in the HS3 devices
!00 pump=1
!00 spa=0
The RegEx splits along the “=” and takes the second part and than the first number of this second part.
As a result of such operation Big5 will put values 1 and 0 in the devices named Pool-pump and Pool-spa respectively. Each time the pool controller sends updated input the values will change within the HS3 devices automatically. No action needed no HS3 events are needed.
IMPORTANT ! Please note that ${ } are stripped from the RegEx when entered in the last two boxes “Device name creation” and “Device value creation”.
RegEx: ${Numbers( Split(input, “=”)[1] )[0]}
Entry in the box: Numbers( Split(input, “=”)[1] )[0]