HCA Weekly Reader for the week of 19-July-2020

Home Control Assistant Newsletter for July 19

Have you looked over the version 16 release notes? Lots of changes that you can incorporate into your designs right away.

And if you are looking for answers to the most common questions about HCA check out our Frequently Asked Questions page.

One day build
Like many people I watch the "one day builds" on tested.com. This week I thought I would do a "one day build" of an HCA program that may illustrate a few techniques you may not be expert in.

In my own home design I use the messaging element to send email and text messages when something happens I should know about that is "not normal". For example, a motion sensor seeing something when everyone should be in bed. Or a sensor with a low battery. In some cases that notification is via email and in other cases it's a text message and in some cases both. The problem is that I have messaging elements in lots of programs, and there is no consistency in use. I want to clean this up.

The first step of creating anything is to decide what it should do in all cases. This sounds easy but can be surprisingly hard. My first attempt is this:

If this is a high priority message send a text message and email
If this is a low priority send an email

That seems good, but there are some things I would prefer to get a text message about but not have my mobile go "ding" in the middle of the night. One more attempt:

If this is a high priority message send both a text message and email
If this is a medium priory message, and between 5am and 9pm, send both a text message and email. Outside those hours just send an email.
If this is a low priority send an email

I can build that!
They key to this build is creation of a single program that implements that idea. In programs where I want to send a message, I want to give the message sending program the subject, body, and message priority and let it decide how the message should be sent. In programmer-speak I want to "encapsulate" all that logic in one place. That lets me change it in one place if I want to do something differently – maybe change the hours when it is ok to send a text message. Rather than change lots of places to make this change, I need only change one place.

To make this work I need to have the message sending program be told three items: The message subject, message body, and the priority. It needs to look at the priority and decide what to do, and finally it must somehow take the supplied subject and body and insert it into the messaging element.

The key method to make this work is supplying that information as "parameters" to a "parameterized program". All those programmer-speak words mean is that each time the program is started you must supply to the program one or more pieces of information ("parameters") and the program is designed to accept and use them (a "parameterized program").

First, create the program and tick this box on the "Advanced Options" tab.

This tells the Visual Programmer that this program now is a "parameterized program".

Then in the programmer, open the properties of the Begin-Here element. That element only has properties for parameterized programs.

Here are those three pieces of information the program needs: Message subject, message body, and the priority. A parameter can be a value – a number, string, date-time, yes/no – or it can be an "object" – usually a device. For this one-day-build we will only be working with value parameters. There is a technical note that goes into details on object parameters if you want the full story.

Note the grey text below each parameter name. The Begin-Here element has a method where you can supply this, and it is a good idea to do so as you will see later.

That's all we need do with the Begin-here element.

Before we get to the program itself, let's look at how parameters can get incorporated into the properties of elements. Here is a section of the messaging element configured in this program.

First thing to know is how you name a parameter when you use it. You use the name of the parameter prefixed by a '$' character. So, $Subject refers to the subject parameter and $Body refers to the body parameter. And here is the magic: Whenever HCA evaluates an expression that contains the name of the parameter it uses the value of that parameter.

Second fact to know is that in some programmer elements where a string is used – like the body and subject of the messaging element – you can "embed" an expression by enclosing it in the % character. In those programmer elements where this is possible you will see the "Embed Expression" button and you can use that to help build the expression, although you can just type it in yourself.

The expression in this case is very simple: just the name of the parameter. When HCA executes that element, it looks for any embedded expressions, evaluates them, and then uses that text as if it was in the element all along.

For example, if this program was supplied with "Cephalopod attack" as the subject and "High" as the priority, then in this example %$Priority% is replaced with High, %$Subject% is replaced by Cephalopod attack, so the subject becomes High Priority: Cephalopod attack.

Now we finally construct the program itself.

The first element after the Begin-Here tests the priority like this:

That looks at the priority parameter and sees if it is "Low". The other variable-test elements do the same thing but check for "Medium" or "High".

If the priority is "Low" then the "yes" path goes to the messaging element that sends an email, and we saw how to configure that.

The next Variable-Test element checks for priority High. And the "yes" path goes to a message element to send a text message and then to the messaging element to also send an email.

The last variable-test element tests for "medium", and then it uses an additional test element like this:

If this "time between" test succeeds it follows the same path as a high priority message. If the test fails then it operates as a low priority message.

And that's it for this program. Now how to use it in other places. That's even easier!

Anyplace I want to send a message using this method, I replace the messaging element I was using with the start-program element:

All I need do is to supply the values of the three parameters. Two things to note here: First, the gray text below each parameter is that "help text" you can add in the Begin-Here element. Now weeks later when I want to use this program and don't remember all the details, I am reminded of what the parameters are for. Second, the last parameter has a "default" value. That is, if I don't put anything in the box to use as the value for the priority parameter, then it uses "low". That is shown by the "[low]" at the end of the help text. The advantage of default values is that I can change what the default value is, and then anyplace I didn't specify a value for that parameter it then automatically uses the new default value.

Here is a use for that: Suppose I no longer want low priority messages at all. Also suppose instead of putting "Low" on as the priority for those messages in the Start-Program element I left the priority empty. If I change the default priory to "None", then given how the program was constructed, no message would be sent. If I later decided I did want those low priority messages, I can change the default back to "low". This is a change in a single place and not in many different locations. That is a big win.

Going from 90% to 99%

While we are now "done", there are one or two other quick changes that take you a bit further along the road to perfection. Sending a message can take time, and what would happen if the message sending program was started from two different places in your design at the same or nearly the same time?

What you would like is that each use of the message sending program gets to do its job, one task after the other. HCA has a way to do that. In the message sending program on the "Triggers" tab is an option for exactly this:

The other issue is, as I said, message sending takes time. Your program may be doing many more things than just sending a message, and it may be useful to "get on with it" and not have the program wait around for the message to be sent. There is also a way to do that. In the Start-Program element there is this option:

Why only 99% and not 100% in the header of this section? No program is ever complete. There are probably either bugs or improvements to be made (almost surely both bugs and improvements to be made). While I don’t think there are any bugs in this ten-element program, I'm sure there are improvements you can think up.

V17 Open beta now available - beta 20 now available
The HCA 17 open beta this week gets a new release:17.0.20.

If you install this beta build you will save yourself some difficulty if you careful read the release notes for the changes in build 19 and 20. There are some big changes in this build you must be aware of. See changes notes #76 to #90 and pay special attention to #88 and #90.

Want in on the version 17 beta? All you need do is to enter your HCA registration code into the online form as usual, and the resulting page contains a link to the beta page for download. The beta zip file password is the same as your V16 password. Please read fully and carefully the build notes. One suggestion: If you are using SmartThings or Hubitat you really should get on board with the beta as there is new stuff heading your way that needs this beta version.

User-to-User forum

An HCA User who wanted to set up a forum for user-to-user communication. I'm passing this on, but please know that this is not a HCA company project and I will not be spending much time there so I don't know how this will work out. Here is a link to what he set up.

https://www.reddit.com/r/HomeControlAssistant/

Want to take the next step in automation? Want to get started with Amazon Alexa and Google Assistant and control HCA by voice commands? Even if you are a long-time user of HCA, the Getting Started guides have all the info you need on client-server, mobile applications, DDNS, and voice assistants.

All of the Getting Started Guides are available on the support website.