Home Control Assistant Newsletter for August 2
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.
OK, as I promised: another one-day-build
Today's one day build comes from a user request. They wanted to track the total time a device was ON for today. And since HCA already keeps track of that- the whole "power track" facilities – he expected it would be possible to get the data from that. Well, not so simple. But in answering the request I created a program that had some interesting "learning possibilities" in it, so here goes.
As usual we start with a statement of what we want to accomplish.
A lot of pieces there!
- Keep track of ON time for today and at midnight save that as "yesterday's ON time".
- Be able to clear the on-time accumulator at any time.
- Be able to designate any device as wanting this feature. We don't want to build a system to track ON time for a single device, but to operate on multiple devices and make it easy to add a new device to this system without changing the program.
- Be able to view the ON time and be able to access that in other programs, if wanted. So not just a "report" but data collection and storage.
In today's adventure we will be using these tools from the HCA toolbox::
- State change triggers
- Generic triggers
- Program parameters
- A method to enumerate objects in your design and modify ones that match a criterion
- Object tags
- Online library
The main tool used to build this is the "state change trigger". This type of trigger starts a program running when some other object changes state – from OFF to ON or from ON to OFF. When something goes ON we can start a timer, and when it goes OFF we can stop the timer. Then having that time interval, add it to what we have already accumulated for the device for today.
Version 17 alert: You could create a program that has a state-change trigger for each device we want to track. And if we wanted a new device added to this system, we would add a trigger for it. And that would work. But in HCA 17 the state change trigger has been expanded to say "ANY device that changes state". I'm going to use that feature in this program, as V17 is soon to be and you can get the open beta if you want.
Suppose then we have a program triggered on a state change for ANY device. There are two problems to solve: First how does the program know which program changed state, and second, is it a device that wants this ON time tracking?
In other programs we have dissected we have covered programs with parameters. If this is new or you forgot the details, technical note #xxx has a good introduction.
This program has a single parameter which is the device that changed state.
Then we add the state change triggers:
Don't worry about those last two "Generic" triggers, we will cover them in a bit. Promise.
One nice feature of the state-change trigger is that it provides what device changes state to the program when triggered. Sometimes this isn't important, for example, if you have a trigger for only one device then you already know what device you are working with. But for this, since it triggers on ANY device, HCA helpfully supplies the device as the value of the parameter. When the program starts, we then know what device changed state.
The next task is to see if it is a device we want to track this ON time for. If only we had a way to "mark" a device saying we want this – and we do have that! Again, in a topic covered previously, we use a TAG on a device. To review: A TAG is like a variable – has a name and a value – but unlike a global variable it is attached to a single device. You can see the tags on a device if you open the properties of the device and look on the tags tab.
If a device has the "Track Time" tag, then we want to track its ON time and if it doesn't then we don't. A Compute-Test element does that easily:
We see if the device parameter – which holds the device we are working on – has that Tag. If not, the program just exits.
Next, we need to determine if the device went ON or went OFF so we can know if the timer should be started or stopped. We could do that by testing on the trigger or by testing the device. I'll go the device route:
The IsON function takes a second optional argument and if supplied, and if is "no", then the device isn't queried for its status and that is what we want.
If the device is ON we want to make a note of the current time. But where to put that?
We will use the "Track Time" tag. That gives it dual purpose. If the tag exists, then we want to track the ON time of the device and its value can be used to store the time it went on. No reason to waste a resource when we already have a tag and can use its value.
If the device has gone OFF, then we can determine how long it was on with some simple functions.
All that remains is to add that amount to the accumulated ON time and save it in another tag:
OK, this one is a bit more complex. The first statement gets the value of the "Time Today" tag. That is the number of seconds that the device has already been on today. But as the comments say, there are two parts: the # seconds, a comma, and then a readable image of how many seconds that is. To split the string into the two parts, the TextPiece function does exactly that. Then it is a simple matter to add to the accumulated time this new time interval.
Last part saves the new ON time into the tag for the device.
Hey, where did that "elapsedImage" come from you ask? In the library there is a package that has a function that creates a readable image of a time interval, so why reinvent something that works. I imported it form the library and used it. You can see how it was used when you look at the final program.
Done, right? Well no, we did say in the specifications that we wanted a way to clear the accumulated time and to copy "today's time" to "yesterday's time" at midnight.
We could create other programs to do this – and I usually argue for decomposing a single task into sub-tasks - but as this is both a useful program and a way to show new techniques, I opted to keep it all in one.
Back at the top I showed the triggers that made this work - the state-change triggers – but the program also has a Generic ON and a Generic OFF trigger. A "Generic trigger" is just a way for a program to be controlled ON and OFF. For device specific triggers – like Insteon – you can have the program start when a ON event happens and when an OFF event happens. When someone turns a light ON or OFF at the switch.
A Generic Trigger does the same thing but all internally to HCA. For example, when right clicked in the user interface, a program with Generic ON and OFF triggers shows ON and OFF in the popup menu. And when scheduling the program it could be scheduled for ON for 1am, or OFF at 8am, rather than to just "start" at that time.
For this program we will repurpose ON to mean copy from today to yesterday, and OFF to mean clear the accumulated time for today. To make this "today to yesterday" copy, the program can be scheduled to "start by ON" at midnight.
These actions both happen in a similar manner and use the DesignOpen, DesignName, and DesignClose functions. What these functions do is provide a mechanism to look at elements in your design and perform actions on them. What we want is to find all the devices that have the "Track time" tag and then, depending upon being started by an ON or OFF, copy the saved ON time for today to yesterday, or clear it.
You can find the complete documentation of these three functions in the user guide expressions chapter, but for this program we use these features.
What this does is to start enumerating all the devices – that's the "1" for the 1st argument – in any room – the "" for the 2nd argument – that has the "Track Time" tag – the 3rd argument. Like opening a file, you get back what we call a "handle" that you use in subsequent functions.
To get the first device that matches that criterion, the DesignName function is used:
The next step must check that we did get a name. As we are going through all the devices one at a time, eventually we will run out of devices that
match the criterion, and so DesignName gives us back "" when at the end. In that case we must close the design "handle" with DesignClose.
If we do get a valid device name, then we can do what is needed. In the copy case we do this:
Clearing the accumulated times is done similarly.
Is that really all there is for this program? Well, no there never is an end. There are a few points that I didn't go into detail on. Here are some:
Any program has these sorts of questions to investigate. I've solved them in the way I think best, and if you want to see the complete program, send me a message and I'll send you an export. I will not put this into the online library until V17 ships as it uses V17 features.
- What happens if we get an OFF for a device that we never got an ON for? When something goes OFF we do the calculations for the duration of the time it was ON but that needs the ON time and we don't have that.
- What happens if there is no ON time for today. Do we want to copy that into yesterday's time or preserve that?
V17 Open beta now available - beta 21
The HCA 17 open beta this week stays at 17.0.21.
Please remember after installing to carefully read the release notes for the changes in this build and previous builds if you skipped any.
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.
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.
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.