HS4 specific

There are two versions of Big5. Big5 and Big5_HS4. Big5 is the legacy version and does work with both HS3 and HS4. Big5_HS4 is dedicated to HS4 and does work with HS4 only. They are separate and independent of each other and you can have them both running if for any reason you like one better than the other for certain tasks.

The documentation here was written for Big5. Most of it is applicable to Big5_HS4. We will outline the differences here as well as some unique Big5_HS4 features. Applicable to Big5_HS4 version 3.5 and later

1. Design change – Big5_HS4 has totally different design and GUI, however the meanings of the fields are the same and any other minor changes are self-explanatory.
2. oAuth2 support for HTTP profiles. The modern world of devices is API driven. Actually each of the many HS4 plug-ins available does address one API to manage one kind of device. Big5_HS4 is an universal tool allowing the user to address various devices and environments. In order to protect privacy many device/API vendors require so called “authorization token” for the API to work. The modern framework for obtaining such token is called oAuth2. One can obtain such token manually, however as an extra precaution the tokens tend to expire and the manual process of obtaining one is quite cumbersome. Here is where the automated process of oAuth2 of Big5_HS4 takes place. It obtains and stores the token for subsequent use automatically so that using API is a breeze with Big5. With that said please keep in mind that the process is somewhat difficult for the novices to comprehend. Please get familiar with the process of oAuth2 in order to understand and use the oAuth2 feature of Big5_HS4. There are many online sources for that here is just one of them http://www.bubblecode.net/en/2016/01/22/understanding-oauth2
   
   Examples of how to use oAuth2 are provided here
   
   
   
3. Root/features for devices. In case you didn’t notice HS4 introduced two layer structure for devices. Each device in HS4 is a root. Each root device can have multiple features. Big5_HS4 does support root/feature concept creating root devices with multiple features, but also supports plain root devices with no features if the user so desires.

New fields were introduced in the profiles to address root/features functionality.

The names/name expressions of the root devices go in a separate box and they are separated by &&&

Example: “Sensor1″&&&”Sensor2″&&&”Sensor3”

The names are fixed in the above example, however as it always has been the case with Big5 the names of the root devices can be retrieved from the incoming message like that

Example: JSON(input,”sensor[0].name”)&&&JSON(input,”sensor[1].name”)&&&JSON(input,”sensor[2].name”)

The value expressions do not change, and they are separated with && as normal, however they are separated by &&& for different root devices

Example: JSON(input,”sensor[0].temp”)&&JSON(input,”sensor[0].hum”)&&JSON(input,”sensor[0].light”)&&&JSON(input,”sensor[1].temp”)&&JSON(input,”sensor[1].hum”)&&JSON(input,”sensor[1].light”)&&&JSON(input,”sensor[2].temp”)&&JSON(input,”sensor[2].hum”)&&JSON(input,”sensor[2].light”)

In this example 3 features will be created and values imported in HS4 for each root device . Please note the &&& separator.

Above examples are designed around this JSON input

4. URL parameters create root/features device

This feature is HTTP profile specific and addresses some older fashioned way of communication that is still widely used. Some devices report their status or are subject to control by URL parameters a.k.a. Query strings.

Example: http://192.168.1.248:89/wireless.asp?temp=72.1&name=Kitchen&hum=48&wind=3&app=0

Big5HS4 makes it easy to create HS4 device with all parameters as features of the device. In order to do that create HTTP “listening” profile with URL

Example: http://192.168.1.248:89/wireless.asp?

Find the box named “Root name Id” and put the parameter there that will give the name of the Root device.

Example: name

Leave all other boxes blank but do not forget to check the “listen” box.

To test it enter the above URL in any browser on your network and voila Big5_HS4 will create Root device “Kitchen” with features temp, hum, wind, app and the respective values imported in HS4.

5. Improved MQTT use of wild cards (+).

Example: Each device of many creates it’s own MQTT topic like that

home/dimmers/dimmer1/report
home/dimmers/dimmer2/report
home/dimmers/dimmer3/report

Legacy Big5 does support wild cards in the topic. So one can subscribe to all of the above with one MQTT profile like that

home/dimmers/+/report

It does work for the legacy Big5, however it creates/updates one HS4 device only. Say for example I picked the name “Power” for the device. It will create and update only one HS4 device

Big5 MQTT Power

What Big5_HS4 does better is that it creates 3 different devices (for the example above) depending on the topic over which message arrives.

Big5HS_4 MQTT dimmer1Power
Big5HS_4 MQTT dimmer2Power
Big5HS_4 MQTT dimmer3Power

6. Big5_HS4 error can trigger an HS4 event now.

There is new line “Big5_HS4-LogTrigger” in the HS4 trigger menu. If you select it than the HS4 event will be triggered each time a Big5_HS4 error occurs

7. Embed wait in the action

As a convenient feature Big5HS4 allows wait within the action. Pls. note that wait was available in the legacy version for Serial profiles only and in sharp brackets <wait xxxx>. Brackets are square in HS4 version and wait is available for ALL profiles.

[wait xxxx] , where xxxx is the wait time in milliseconds

Example: The following action performed at 1:00:00 PM will produce the results below at the specified time

AUX11?[wait 1000]AUX12[wait 3000]AUX13

1:00:00 AUX11

1:00:01 AUX12

1:00:04 AUX13

8. Selective log output

Big5_HS4 does allow selective log for easier troubleshooting effective version 3.10.0.0 and later. Active Big5 users know that the Big5 log can become overwhelming when multiple Big5 profiles run simultaneously in real world applications. If you just added a new Big5 profile and what to troubleshoot just it, than you don’t need to get lost in too may details form other profiles that don’t need your attention. Here is where the selective log comes in place.

There is a new check box “Enable log” in each and every profile that is unchecked by default. Check it iif you want to troubleshoot this particular profile. Go to

Plugins–>Big5_HS4–>Profiles configuration–>Utilities–>Debug Outputs

and select the option “Show errors and debug for specific (selected) profiles”.

9. MQTT output using profiles with wild cards

If your MQTT profile contains topic with wild cards than your MQTT output command needs to “know” how to modify the wild cards before sending out the payload. Up to 3 wild cards are supported

Example:

Topic in the MQTT Profile cmnd/+/+/+

In your Big5_HS4 MQTT action you will find 3 fileds for wild card substitution

If you fill those like that

Wild card1: Dimmers

Wild card2: FirstFloor

Wildcard3: Living

and if your payload is 29

Than Big5 will send 29 to MQTT Topic

cmnd/Dimmers/FirstFloor/Living

10. New expression RegexReplace

New command is available

RegexReplace(Input,Regex1,x,Regex2,y)

Where Regex1 is the first Regex to find a particular string and Regex2 is to find the replacement string and replace it. x and y are optional values for the position if requered by the Regex.

Example:

Find the first 3 digit number and replace it with the second 3 digit number

Input: 67 4 33 654 7 897 098765 65 11

Expression: RegexReplace(Input,“\b\d{3}\b”,0,“\b\d{3}\b”,1)

in this example x=0 (first number) and y=1 (second number) Counting starts from 0 in Regex

11. Migration of legacy Big5 Profiles to Big5_HS4 profiles.

Look for the tab marked ++ in the Big5_HS4 menu in order to migrate legacy Big5 profiles to the new Big5_HS4 profiles. Due to significant differences (for example Big5_HS4 supports root/features) the migration happens one profile at a time for you to stay in control and modify profiles if and as needed.

Please note that migration of profiles does NOT include migration of related events. You need to re-create your events due to completely different event engine in HS4.

12. Validation of entries in HTTP profiles

Big5 users make some common mistakes when they create their HTTP profiles. This leads to frustration and waste of time. In order to avoid all that now Big5 checks automatically for common mistakes and issues Error and Warning messages along with instructions how to correct.

13. New expression PowerReplace

As the name implies, this is one of the most powerful expressions to use within Big5. It allows to use the power of RegEx to pinpoint the desired portion of the incoming string with surgical precision. Once it is done than it uses the versatility of Big5 expressions to replace the selected part.

Syntax: PowerReplace(Input, RegEx, x, Big5Expression)}

where RegEx is any Regular Expression as explained here

where x is optional integer number starting from 0 used in conjunction with RegEx to select a match if more than one

where Big5Expression is any of the Big5 expressions listed here

Example:

Find the third 3 digit number in the input and replace it with 99999

Input: 8 777 7 66 77 6543 888 6 823

PowerReplace(Input, “\b\d{3}\b”,2,”99999″)

Result: 8 777 7 66 77 6543 888 6 99999