Update 2: dzVents 2.3.0 is now included in the various downloads and tarballs and is also included when you do an ./updatebeta. Yay!
-----------------------------------------------------------------------------------------------------------
Update: for now you have to either download the sources from github or download the tarballs from the Domoticz website. If you use updatebeta you may not get all the necessary files yet. Sorry for that but it surely will be fixed anytime soon.
-----------------------------------------------------------------------------------------------------------
Hiya folks,
I'm proud to tell you that dzVents 2.3.0 has been merged into Domoticz v3.8551. Thanks to the hard work of jvandenbroek and myself we have brought event scripting in Domoticz to an even higher and easier level. Before showing the long list of changes let's start with a few highlights of this great release:
Group- and scene-events
Long awaited and finally there: as of now you can write event scripts for group and scene changes. This can be very handy if you want to write an event script when you trigger a scene from a z-wave device (like double tapping a wall-switch). Earlier you had to create dummy switches that were part of your scene and create an event script for that dummy device. No longer! simply do this in your script:
Code: Select all
return {
on = {
groups = { 'myGroup1' },
},
execute = function(domoticz, group)
-- do you thing
end
}
Code: Select all
return {
on = {
scenes = { 'myScene1' },
},
execute = function(domoticz, scene)
-- do you thing
end
}
Extended event triggering and command options
Earlier there were quite some situations where devices/variables etc. were updated but no follow-up events were triggered. That is no longer the case. If you update a device or a variables, group, scene etc., dzVents is now always notified so follow-up event scripts are directly triggered. Of course you may not always want this so we added the .silent() option. More on that later. Anyway, it is no longer needed to use the web API to update stuff from your event scripts only to make sure that your event scripts will be triggered afterwards! Oh... and beware that you don't create event-loops where scripts trigger themselves endlessly! This was already possible so check your logs if your systems stops responding
.Now that we enhanced the underlying event-system in Domoticz we also made sure that the command options that were already there in Domoticz are now fully exposed to dzVents (traditionally the FOR, AFTER, RANDOM stuff you put in your command-array):
Code: Select all
-- switch on after 1 minute for 10 seconds and repeat that 5 times with 1 minute in between:
myDevice.switchOn().afterMin(1).forSec(10).repeatAfterMin(1, 5)
myUserVar.set(12).afterMin(3)
As a bonus there is also the option .checkFirst():
Code: Select all
mySwitch.switchOn().checkFirst()
As mentioned earlier, all updates and changes will now trigger the event system but in some situations you may not want this to happen. Fear no more: .silent() comes to rescue. You can silently turn on a switch, update a sensor or variable like this:
Code: Select all
mySwitch.switchOn().withinMin(5).silent() -- will not trigger an event
See the documentation for more examples.
More timer rules
A timer rule is added: 'between xx and yy'. You can now create rules like these:
Code: Select all
return {
on = {
timer = {
'between 12:45 and sunset'
}
},
...
}
Code: Select all
return {
on = {
timer = {
'every 10 minutes between 20 minutes before sunset and 30 minutes after sunrise on mon,fri,tue'
}
},
...
}
See timer trigger options in the documentation.
Boilerplate scripts for dzVents in GUI editor
A handful of handy boilerplate script tempates are made available in Domoticz' GUI script editor. On the right side, pick dzVents as the language and you will see them in third select box (you may have to press the New button after you picked a template):
- guieditor-dzvents.png (25.02 KiB) Viewed 3810 times
- guieditor-boilerplates.png (37.29 KiB) Viewed 3810 times
Work with times
One of the goals of dzVents has always been to make working with timestamps as simple as possible. To make it even simpler, a compare function is added so you can quickly compare two time objects and see how far apart they are:
Code: Select all
local Time = require('Time')
local tA = Time('2016-12-12 07:35:00')
local tB = Time('2016-12-12 08:35:00')
print(tB.compare(tA).minutes) -- prints 60
print(tB.compare(tA).compare) -- 0 = both are equal, 1 = time is in the future, -1 = time is in the past.
Documentation
The documentation in the wiki is updated as well with a lot more examples to get you started even faster. A whole new troubleshooting section is added as well.
New location
Previously dzVents' runtime files were located inside the scripts folder. That turned out to be not so handy as the scripts folder is intended for the user and not for runtime files. So we moved these files to a new location (/path/to/domoticz/dzVents). At startup the old runtime files are removed. Your scripts will remain in /path/to/domoticz/scripts/dzVents/scripts. So now you can just backup and restore your entire scripts folder without running the risk of overwriting the latest and greatest of dzVents runtime stuff with an older version from your backups.
Change log
Here is the full list of changes:
- Added 'active' attribute to devices (more logical naming than the attribute 'bState'). 'myDevice.active' is true or false depending on a set of known state values (like On, Off, Open, Closed etc). Use like 'if mySwitch.active then .. end'
- Added 'domoticz.urlEncode()' method on the 'domoticz' object so you can prepare a string before using it with 'openURL()'.
- Updating devices, user variables, scenes and groups now always trigger the event system for follow-up events.
- Added support for groups and scenes change-event scripts. Use 'on = { scenes = { 'myScene1', 'myScene2' }, groups = {'myGroup1'} }'
- Added adapter for the new Temperature+Barometer device.
- Added 'domoticz.startTime' giving you the time at which the Domoticz service was started. Returns a Time object.
- Added 'domoticz.systemUptime' (in seconds) indicating the number of seconds the machine is running. Returns a Time object.
- Added more options to the various commands/methods: e.g. 'myDevice.switchOff().silent()', '.forSec()', '.forHour()', '.afterHour()', '.repeatAfterSec()', '.repeatAfterMin()', '.repeatAfterHour()', '.withinHour()' and '.checkFirst()'. This now works not only for devices but also scenes, groups and user variables. See documentation about command options.
- Added '.silent()' option to commands like 'switchOn().afterSec(4).silent()' causing no follow-up events to be triggered. This also works when updating non-switch-like devices, scenes, groups and user variables. If you do not call 'silent()'`, a follow-up event is *always* triggered (for devices, scenes, groups and user variables).
- Added time rule 'between xx and yy'. You can now do things like: 'between 16:34 and sunset' or 'between 10 minutes before sunset and sunrise'. See the doc.
- Added support for milliseconds in 'Time' object. This also gives an ms part in the time-stamp for historical persistent data. You can now do 'msAgo()' on time stamp when you inspect a data point from an history variable.
- Added 'daysAgo()' to 'Time' object.
- Added 'compare(time)' method to 'Time' object to calculate the difference between them. Returns a table. See documentation.
- Added 'domoticz.round()' method to 'domoticz' object.
- Added 'text' property to alert sensor.
- 'active' section is now optional in your dzVents script. If you don't specify an 'active = true/false' then true is assumed (script is active). Handy for when you use Domoticz' GUI script editor as it has its own way of activating and deactivating scripts.
- Added 'humidityStatusValue' for humidity devices. This value matches with the values used for setting the humidity status.
- 'Time' object will initialize to current time if nothing is passed: 'local current = Time()'.
- Added the lua Lodash library (http://axmat.github.io/lodash.lua, MIT license).
- Fixed documentation about levelNames for selector switches and added the missing levelName.
- Moved dzVents runtime code away from the '/path/to/domoticz/scripts/dzVents' folder as this scripts folder contains user stuff.
- Added more trigger examples in the documentation.
- You can now put your own non-dzVents modules in your scripts folder or write them with the Domoticz GUI editor. dzVents is no longer bothered by it. You can require your modules in Lua's standard way.
- Added '/path/to/domoticz/scripts/dzVents/scripts/modules' and '/path/to/domoticz/scripts/dzVents/modules' to the Lua package path for custom modules. You can now place your modules in there and require them from anywhere in your scripts.
- Added dzVents-specific boilerplate/templates for internal web editor.
- Fixed the confusing setting for enabling/disabling dzVents event system in Domoticz settings.
- Fixed a problem where if you have two scripts for a device and one script uses the name and the other uses the id as trigger, the id-based script wasn't executed.
