As of version v3.8837 dzVents 2.4.0 is available. After many months of programming and testing we are proud to announce this major new release with loads of new cool features that will make your live as an event-scripter even more powerful and most importantly: a lot easier.
Before you read any further I want to emphasize that there is one easy-to-fix breaking change: the second parameter passed to the execute function is no longer nil when the script was triggered by a timer or a security event. Please check your scripts! The second parameter now has checks to determine the type. E.g. execute = function(domoticz, item) .. end. You can inspect item using: item.isDevice, item.isTimer, item.isVariable, item.isScene, item.isGroup, item.isSecurity, item.isHTTPResponse. Please read the documentation about the execute function.
So, without further ado let's go through some of the cool new features:
Asynchronous http requests
Yes, you just read it correctly! With dzVents 2.4.0 you can make an http request AND process the response data in a non-blocking way. So no longer you have to do os.execute('curl...') and do wizardry to process the response and have the results flow back into Domoticz (like virtual devices).
Let's look at this example. Here there's a script that issues an http request every 5 minutes and handles the response. The response is application/json and holds a temperature. The temperature will be passed to a virtual temperature device:
Code: Select all
return {
on = {
timer = {'every 5 seconds'},
httpResponses = { 'sometrigger' }
},
execute = function(domoticz, item)
if (item.isTimer) then
domoticz.openURL({
method = 'POST',
postData = {
location = 'outside' -- some param
},
url = 'http://some.domain/temperature',
callback = 'sometrigger'
})
end
if (item.isHTTPResponse) then
-- we got back some data
if (item.ok) then
-- response is ok, we know it is json:
local temp = item.json.outside.temperature
domoticz.devices('Outside').updateTemperature(temp)
end
end
end
}
dzVents allows you to do POST and GET request with custom headers and parameters. Check out the documentation.
More timer trigger rules
You can now create timer triggers based on dates, date ranges, week numbers, week-number ranges etc:
Code: Select all
on = {
timer = {
'in week 12,44' -- in week 12 or 44
'in week 20-25,33-47' -- between week 20 and 25 or week 33 and 47
'in week -12, 33-' -- week <= 12 or week >= 33
'every odd week',
'every even week', -- odd or even numbered weeks
'on 23/11', -- on 23rd of november (dd/mm)
'on 23/11-25/12', -- between 23/11 and 25/12
'on 2/3-18/3',11/8,10/10-14/10',
'on */2,15/*', -- every day in February or
-- every 15th day of the month
'on -3/4,4/7-', -- before 3/4 or after 4/7
},
}
Many have requested for a way to cancel commands that have been placed in the Domoticz command queue. For instance, if at some point you did mySwitch.switchOn().forSec(2).repeatAfterMin(20, 10) and later on you want to cancel the future switch commands (as this example will go on for more than 200 minutes) you can do mySwitch.cancelQueuedCommands().
Access to all devices in a group or scene
In dzVents 2.4.0 you get a devices collection in a scene or in a group:
Code: Select all
domoticz.scenes('myScene').devices().forEach(function(s)
print(s.name .. ': ' .. s.state)
end)
-- or
domoticz.scenes('myScene').devices('windowLight).switchOn()
Timing options for update commands
You can now use commands like afterSec() or withinSec() for update commands. It is no longer limited to switches but now you can update a temperature device after a couple of seconds.
Better support for RGB(W) devices
You can now do commands like setKelvin(), setRGB(124,33,55), .setWhiteMode().
Easier filtering of devices
Many of you create a Lua table with device names that is used elsewhere in the script to filter devices. Now you can use the existing devices().filter() function to make that even easier:
Code: Select all
local livingLights = { 'window', 'couch', 33, 'table' }
-- loop over these devices:
domoticz
.devices() -- all devices
.filter(livingLights) -- filtered
.forEach(function(light) -- loop over filtered devices
light.switchOn()
end)
-- note that this is one chained command splitted over multiple lines for
-- better readability!
Speed optimizations
We made many optimizations to make execution of scripts with dzVents even faster by grouping events that occure more or less at the same time and hand them over to dzVents at once. That way dzVents only has to initialize once. This significantly speeds up stuff on slower machines.
Updated documentation
In the wiki the documentation has been updated of course. All new features will have a 2.4.0 marker.
So, a lot of cool new stuff but there's more. Here's the full change log for this release:
Change log
- **BREAKING CHANGE**: The second parameter passed to the execute function is no longer `nil` when the script was triggered by a timer or a security event. Please check your scripts. The second parameter has checks to determine the type. E.g. `execute = function(domoticz, item) .. end`. You can inspect `item` using: `item.isDevice`, `item.isTimer`, `item.isVariable`, `item.isScene`, `item.isGroup`, `item.isSecurity`, `item.isHTTPResponse`. Please read the documentation about the execute function.
- Added ``.cancelQueuedCommands()`` to devices, groups, scenes and variables. Calling this method will cancel any scheduled future commands issued using for instance `.afterMin(10)` or `.repeatAfterMin(1, 4)`
- Added `.devices()` collection to scenes and groups to iterate (`forEach`, `filter`, `reduce`, `find`) over the associated devices.
- Added http response event triggers to be used in combination with `openURL`. You can now do `GET` and `POST` request and handle the response in your dzVents scripts **ASYNCHRONICALLY**. See the documentation. No more json parsing needed or complex `curl` shizzle.
- Added a more consistent second parameter sent to the execute function. When a timer is triggered then the second parameter is a Timer object instead of nil. This way you can check the baseType of the second parameter and makes third parameter (triggerInfo) kind of obsolete. Every object bound to the second parameter now has a baseType.
- Added locked/unlocked support for door-locks (locked == active).
- Moved utility functions from the domoticz object to `domoticz.utils` object. You will see a deprecation warning when using the old function like `round()`, `toCelsius()` etc.
- Added `lodash` as a method to `domoticz.utils`: `domoticz.utils._`
- Added `toJSON` and `fromJSON` methods to domoticz.utils.
- Added `afterXXX()` and `withinXXX()` support for device-update commands. E.g.: `myTextDevice.updateText('Zork').afterMin(2)`.
- Added support for Logitech Media Server devices (thanks to Eoreh).
- Added new timer rules: date rules: `on 13/07`, `on */03`, `on 12/*`, `on 12/04-22/09`, `on -24/03`, `on 19/11-`, week rules: `in week 12,15,19-23,-48,53-`, `every even week`, `every odd week`. See documentation.
- Added historical data helper `delta2(fromIndex, toIndex, smoothRangeFrom, smoothRangeTo, default)` to have a bit more control over smoothing. You can specify if want to smooth either the start value (reference) and/or the to value (compared value).
- Added historical data helper `deltaSinceOrOldest(timeAgo, smoothRangeFrom, smoothRangeTo, default)`. This will use the oldest data value when the data set is shorter than timeAgo.
- Added support for Lighting Limitless/Applamp RGBW devices. You can now set Kelvin and RGB values, NightMode, WhiteMode and increase and decrease the brightness and discoMode. See the documentation.
- Added device adapter for Onkyo receiver hardware.
- Added `scriptName` to the triggerInfo object passed as the third parameter to the execute function. This holds the name of the script being executed.
- Fixed bug in Domoticz where using forXXX() with selector switches didn't always work.
- Fixed bug in Domoticz where improper states were passed to the event scripts. This may happen on slower machines where several devices may have been updated before the event-system had a change to operate on them. In that case the event scripts received the current final state instead of the state at the moment of the actual event.
- Added support for webroot. dzVents will now use the proper API url when domoticz is started with the -webroot switch.
- Added support for event-bursts. If (on slower machines) events get queued up in Domoticz, they will be sent to dzVents in one-package. This makes event processing significantly faster.
- Added `domoticz.data.initialize(varName)`. This will re-initialize non-historical variables to the initial value as defined in the data section.
- You now no longer have to provide an initial value for a persistent variable when you declare it. So you can do `data = { 'a', 'b', 'c'}` instead of `data = {a={initial = nil}, b={initial=nil}, c={initial=nil} }`. You have to quote the names though.
- A filter can now accept a table with names/id's instead of only functions. You can now do `domoticz.devices().filter({ 'mySwitch', 'myPIR', 34, 35, 'livingLights'})` which will give you a collection of devices with these names and ids.
- Added and documented `domoticz.settings.url`, `domoticz.settings.webRoot` and `domoticz.settings.serverPort`.
- Removed fixed limit on historical variables if there is a limit specified.
