Skip to content

Commit 3c140ff

Browse files
rwaarenrwaaren
committed
dzVents Fixed wrong functioname in call and some typos in documents
1 parent 743a0d1 commit 3c140ff

File tree

5 files changed

+108
-94
lines changed

5 files changed

+108
-94
lines changed

‎dzVents/documentation/README.md

Lines changed: 55 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,6 @@ The customEvent object (second parameter in your execute function) has these att
219219
- **xmlEncoding**. *String*. When the response data is `text/xml` See [ xml encoding] ( https://en.wikipedia.org/wiki/XML ).
220220
- **xmlVersion**. *String*. When the response data is `text/xml` See [ xml versions ] ( https://en.wikipedia.org/wiki/XML ).
221221

222-
223222
#### devices = { ... }
224223
A list of device-names or indexes. If a device in your system was updated (e.g. a switch was triggered or a new temperature was received) and it is listed in this section then the execute function is executed. **Note**: update does not necessarily means the device state or value has changed. Each device can be:
225224

@@ -264,12 +263,11 @@ A list of one or more system triggers.
264263
- **start** - fired when Domoticz has started.
265264
- **stop** - fired when Domoticz is shutting down. As you probably can imagine you have only a limited amount of time - also depending on the load on your system - to have Domoticz do stuff when your script has been completed. Some commands will probably not be executed. Just give it a try.
266265
- **Backups** - the trigger item (2nd parameter of the execute function) is a table that holds information about the newly created backup (location, duration in seconds and type). You could use this information to copy the file to some other location or for another purpose.
267-
- **dailyBackupFinished** - automatic backup when set in domoticz
266+
- **dailyBackupFinished** - automatic backup when set in domoticz
268267
- **hourlyBackupFinished** - " "
269268
- **monthlyBackupFinished** - " "
270269
- **manualBackupFinished** - fired when you start a backup using the Domoticz GUI or via **< domoticz IP:domoticz port >**/backupdatabase.php
271270

272-
273271
#### timer = { ... }
274272
A list of one ore more time 'rules' like `every minute` or `at 17:*`. See [*timer* trigger rules](#timer_trigger_rules). If any or the rules matches with the current time/date then your execute function is called. E.g.: `on = { timer = { 'between 30 minutes before sunset and 30 minutes after sunrise' } }`.
275273

@@ -528,9 +526,9 @@ return {
528526
execute = function(domoticz, item)
529527
if (item.isTimer) then
530528
domoticz.executeShellCommand({
531-
command = 'speedtest-cli --json', -- just an example
532-
callback = 'internetspeedRetrieved', -- see shellCommandResponses above.
533-
timeout = 20, -- max execution time in seconds
529+
command = 'speedtest-cli --json', -- just an example
530+
callback = 'internetspeedRetrieved', -- see shellCommandResponses above.
531+
timeout = 20, -- max execution time in seconds
534532
})
535533
elseif (item.isShellCommandResponse) then
536534
if (item.statusCode==0) then
@@ -726,11 +724,11 @@ The domoticz object holds all information about your Domoticz system. It has glo
726724
- **snapshot(cameraID(s) or camera Name(s)<sup>3.0.13</sup>,subject)**: *Function*. Sends email with a camera snapshots if email is configured and set for attachments in Domoticz. Send 1 or multiple camerIDs -names in ; separated string or array.
727725

728726
```Lua
729-
dz.snapshot() -- defaults to id = 1, subject domoticz
730-
dz.snapshot(1,'dz') -- subject dz
731-
dz.snapshot('1;2;3') -- ; separated string
732-
dz.snapshot({1,4,7}) -- table
733-
dz.snapshot('test;test2') -- ; separated string
727+
dz.snapshot() -- defaults to id = 1, subject domoticz
728+
dz.snapshot(1,'dz') -- subject dz
729+
dz.snapshot('1;2;3') -- ; separated string
730+
dz.snapshot({1,4,7}) -- table
731+
dz.snapshot('test;test2') -- ; separated string
734732
dz.snapshot({'test', 'test2'}) -- table
735733
```
736734

@@ -804,7 +802,7 @@ The domoticz object holds all information about your Domoticz system. It has glo
804802
domoticz.utils.leadingZeros(domoticz.utils.numDecimals (12.23,4,4),9) -- => 0012.2300
805803
```
806804
- **osCommand(cmd)**: *Function*: <sup>3.0.13</sup> Execute an OS command and return result and returncode. Note: For long running scripts `domoticz.executeShellCommand()` should be used, See [Asynchronous shell commands](#Asynchronous_shell_command_execution) for more information.
807-
- **osExecute(cmd)**: *Function*: Execute an OS command (no return). Note: For long running scripts `executeShellCommand()` should be used. See [Asynchronous shell commands](#Asynchronous_shell_command_execution) for more information.
805+
- **osExecute(cmd)**: *Function*: Execute an OS command (no return). Note: For long running scripts `executeShellCommand()` should be used. See [Asynchronous shell commands](#Asynchronous_shell_command_execution) for more information.
808806
- **rightPad(string, length [, character])**: *Function*: Succeed string with given character(s) (default = space) to given length.
809807
- **round(number, [decimalPlaces])**: *Function*. Helper function to round numbers. Default decimalPlaces is 0.
810808
- **sceneExists(parm)**: *Function*: returns name when entered with valid scene ^3.0.12^ or sceneID and return ID when entered with valid sceneName or false when not a scene, sceneID or sceneName of an existing scene
@@ -1004,10 +1002,10 @@ Note that if you do not find your specific device type here you can always inspe
10041002
- **updateCounter(value)**: *Function*. **Overwrite current value for managed and standard counters; increment for incremental counters !!**. Supports [command options](#Command_options_.28delay.2C_duration.2C_event_triggering.29).
10051003
- **incrementCounter(value)**: *Function*. (counter incremental) Supports [command options](#Command_options_.28delay.2C_duration.2C_event_triggering.29). To update with a complete new value you will have to do some calculation and take the counter divider into account.
10061004
```Lua
1007-
local newValue = value
1008-
local iCounter = domoticz.devices('device name')
1009-
local counterDivider = x -- x is depending on the counter divider set for the device
1010-
iCounter.incrementCounter( ( -1 * iCounter.counter * counterDivider ) + newValue )
1005+
local newValue = value
1006+
local iCounter = domoticz.devices('device name')
1007+
local counterDivider = x -- x is depending on the counter divider set for the device
1008+
iCounter.incrementCounter( ( -1 * iCounter.counter * counterDivider ) + newValue )
10111009
```
10121010
- **valueQuantity**: *String*. For counters.
10131011
- **valueUnits**: *String*.
@@ -1330,9 +1328,9 @@ Many dzVents device methods support extra options, like controlling a delay or a
13301328
device.switchOn().afterSec(10).forMin(2)
13311329

13321330
-- switch on at a specic time / day
1333-
device.switchOn().at('09:00') -- earliest moment it will be 09:00 hr.
1334-
device.switchOn().at('08:53:30 on fri') -- earliest moment it will be Friday at 08:53:30
1335-
device.switchOn().at('08:53:30 on sat, sun') -- earliest moment it will be Saturday or Sunday at 08:53:30 (whatever comes first)
1331+
device.switchOn().at('09:00') -- earliest moment it will be 09:00 hr.
1332+
device.switchOn().at('08:53:30 on fri') -- earliest moment it will be Friday at 08:53:30
1333+
device.switchOn().at('08:53:30 on sat, sun') -- earliest moment it will be Saturday or Sunday at 08:53:30 (whatever comes first)
13361334

13371335
-- switch on for 2 minutes after a randomized delay of 1-10 minutes
13381336
device.switchOff().withinMin(10).forMin(2)
@@ -1389,7 +1387,6 @@ light.switchOn().checkFirst().forMin(5)
13891387
#### Availability
13901388
Some options are not available to all commands. All the options are available to device switch-like commands like `myDevice.switchOff()`, `myGroup.switchOn()` or `myBlinds.open()`. For updating (usually Dummy ) devices like a text device `myTextDevice.updateText('zork')` you can only use `silent()`. For thermostat setpoint devices and snapshot command silent() is not available. For commands for which dzVents must use openURL, only `at()` and `afterAAA()` methods are available. These commands are mainly the setAaaaa() commands for RGBW type devices.
13911389

1392-
13931390
See table below
13941391

13951392
```{=mediawiki}
@@ -1584,8 +1581,8 @@ local someTime = domoticz.time.makeTime() -- someTime = new domoticz time object
15841581
- **dateToDate( dateString, sourceFormat, targetFormat[ , offSet] )**:<sup>3.0.17</sup> *Function*: Returns a reformatted datestring. dateString is a formatted date and source- and targetFormat are representations of the dateString elements and their locations in the string (see examples in dateToTimestamp) . Offset is a number (default = 0 )
15851582
```Lua
15861583
-- examples:
1587-
domoticz.time.dateToDate('31/12/2021 23:31:05','dd/mm/yyyy hh:MM:ss', 'dddd dd mmmm hh:MM:ss', 1 ) -- > 'Friday 31 December 23:31:06'
1588-
domoticz.time.dateToDate('31/12/2021 23:31:05','dd/mm/yyyy hh:MM:ss', 'ddd dd mmm hh:MM:ss', -3600 * 24 - 3 )) -- > 'Thu 30 Dec 23:31:02'
1584+
domoticz.time.dateToDate('31/12/2021 23:31:05','dd/mm/yyyy hh:MM:ss', 'dddd dd mmmm hh:MM:ss', 1 ) -- > 'Friday 31 December 23:31:06'
1585+
domoticz.time.dateToDate('31/12/2021 23:31:05','dd/mm/yyyy hh:MM:ss', 'ddd dd mmm hh:MM:ss', -3600 * 24 - 3 )) -- > 'Thu 30 Dec 23:31:02'
15891586
```
15901587

15911588
- **dateToTimestamp([ dateString [,control] ] )**: *Function*: Returns *Number* representing time since epoch in seconds. dateString is a formatted date and control is a representation of the dateString elements and their location in the string. Default control is 'yyyy-mm-dd hh:MM'.
@@ -1611,11 +1608,11 @@ local someTime = domoticz.time.makeTime() -- someTime = new domoticz time object
16111608
time -- time (e.g. 23:48:10)
16121609

16131610
-- examples:
1614-
domoticz.time.dateToTimestamp('2020-12-31 23:59')) -- > 1609455540
1615-
domoticz.time.dateToTimestamp('2020-12-31 23:59:01','yyyy-mm-dd hh:MM:ss')) -- > 1609455541
1616-
domoticz.time.dateToTimestamp('December 31, 23:59:02','mmmm dd, hh:MM:ss')) -- > 1609455542
1617-
domoticz.time.dateToTimestamp('2020-12-31 23:59:03','(%d+)%D+(%d+)%D+(%d+)%D+(%d+)%D+(%d+)%D+(%d+)' )) -- > 1609455543
1618-
domoticz.time.dateToTimestamp('20201231235904','(%d%d%d%d)(%d%d)(%d%d)(%d%d)(%d%d)(%d%d)')) -- > 1609455544
1611+
domoticz.time.dateToTimestamp('2020-12-31 23:59')) -- > 1609455540
1612+
domoticz.time.dateToTimestamp('2020-12-31 23:59:01','yyyy-mm-dd hh:MM:ss')) -- > 1609455541
1613+
domoticz.time.dateToTimestamp('December 31, 23:59:02','mmmm dd, hh:MM:ss')) -- > 1609455542
1614+
domoticz.time.dateToTimestamp('2020-12-31 23:59:03','(%d+)%D+(%d+)%D+(%d+)%D+(%d+)%D+(%d+)%D+(%d+)' )) -- > 1609455543
1615+
domoticz.time.dateToTimestamp('20201231235904','(%d%d%d%d)(%d%d)(%d%d)(%d%d)(%d%d)(%d%d)')) -- > 1609455544
16191616
```
16201617

16211618
- **day**: *Number*
@@ -1651,7 +1648,7 @@ local someTime = domoticz.time.makeTime() -- someTime = new domoticz time object
16511648
- **sunriseInMinutes**: *Number*. Minutes from midnight until sunrise.
16521649
- **solarnoonInMinutes**: *Number*. <sup>3.0.11</sup> Minutes from midnight until solarnoon.
16531650
- **time**: *String*. Returns the time part of the raw data as HH:MM
1654-
- **timestampToDate([ [ timestamp ] , [ pattern ] ,[ offSet ] )**: *function*. Returns a datestring. timestamp is number of seconds since epoch (default = now) , pattern is a string as explained in this wiki at the description of the domoticz.time.date2Timestamp function (default = 'yyyy-mm-dd hh:MM:ss'). Offset is a number (default = 0 )
1651+
- **timestampToDate([ [ timestamp ] , [ pattern ] ,[ offSet ] )**: *function*. Returns a datestring. timestamp is number of seconds since epoch (default = now) , pattern is a string as explained in this wiki at the description of the domoticz.time.dateToTimestamp function (default = 'yyyy-mm-dd hh:MM:ss'). Offset is a number (default = 0 )
16551652
```Lua
16561653
-- examples:
16571654
domoticz.time.timestampToDate(10,'date time') --> '01/01/70 01:00:10'
@@ -2413,7 +2410,6 @@ return {
24132410

24142411
# Asynchronous shell command execution
24152412

2416-
24172413
dzVents allows you to make asynchronous shell commands and handle the results. Asynchronous means that you don't block the system while waiting for the response. Earlier you had to use functions like `utils.osCommand()` or `os.Execute()` and some magic to make sure that you didn't block the system for too long after which Domoticz comes with a message that the script took more than 10 seconds.
24182414

24192415
dzVents to the rescue. With dzVents there are two ways to execute a shell command asynchronously and it is determined by how you use the `domoticz.executeShellCommand()` command. The simplest form simply calls `executeShellCommand` on the domoticz object with only the command as the parameter (a string value):
@@ -2457,22 +2453,31 @@ return {
24572453
```
24582454
Of course you can combine the script that issues the request and handles the response in one script:
24592455
```Lua
2460-
return {
2461-
on = {
2462-
timer = {'every 5 minutes'},
2463-
shellCommandResponses = { 'trigger' }
2456+
return
2457+
{
2458+
on =
2459+
{
2460+
timer =
2461+
{
2462+
'every 5 minutes',
2463+
},
2464+
shellCommandResponses =
2465+
{
2466+
scriptVar,
2467+
},
24642468
},
2469+
24652470
execute = function(domoticz, item)
2466-
if (item.isTimer) then
2467-
domoticz.executeShellCommand({
2468-
command = '...',
2469-
callback = 'trigger'
2470-
timeout = 10,
2471+
if item.isTimer then
2472+
domoticz.executeShellCommand(
2473+
{
2474+
command = 'some shell command',
2475+
callback = scriptVar,
2476+
timeout = timeoutinseconds,
24712477
})
2472-
end
2473-
if item.isShellCommandResponse then
2478+
elseif item.isShellCommandResponse and then
24742479
if item.statusCode == 0 then
2475-
...
2480+
... -- process result (in item.json, -item.xml, -item.lines or item.data)
24762481
end
24772482
end
24782483
end
@@ -2539,14 +2544,14 @@ When debug logging is enabled, every time dzVents kicks into action (Domoticz th
25392544

25402545
Example content of `module.log`
25412546
```
2542-
Startdate time - End date time (clk - CPU ) module / scriptname << type: "trigger"
2547+
Startdate time - End date time (clk - CPU ) dule / scriptname << type: "trigger"
25432548
---------------------------------------------------------------------------------------------------------------
2544-
11/27/20 18:40:00 - 11/27/20 18:40:00 (00 - 0.0029) waqi.lua << timer: "every 20 minutes"
2545-
11/27/20 18:40:00 - 11/27/20 18:40:00 (00 - 0.0016) Washer.lua << timer: "every 5 minutes"
2546-
11/27/20 18:40:01 - 11/27/20 18:40:01 (00 - 0.0215) getWaterFromHomewizard.lua << HTTPResponse: "WaterfromHomewizard"
2547-
11/27/20 18:40:03 - 11/27/20 18:40:03 (00 - 0.2472) updateWeatherSensors.lua << HTTPResponse: "WUS_buienradarResponse"
2548-
11/27/20 18:40:03 - 11/27/20 18:40:03 (00 - 0.0290) waqi.lua << HTTPResponse: "waqi_nearby"
2549-
11/27/20 18:41:00 - 11/27/20 18:41:00 (00 - 0.0583) Bathroom humidity.lua << timer: "every minute between 05:15 and 23:30"
2549+
11/27/20 18:40:00 - 11/27/20 18:40:00 (00 - 0.0029) waqi.lua << timer: "every 20 minutes"
2550+
11/27/20 18:40:00 - 11/27/20 18:40:00 (00 - 0.0016) Washer.lua << timer: "every 5 minutes"
2551+
11/27/20 18:40:01 - 11/27/20 18:40:01 (00 - 0.0215) getWaterFromHomewizard.lua << HTTPResponse: "WaterfromHomewizard"
2552+
11/27/20 18:40:03 - 11/27/20 18:40:03 (00 - 0.2472) updateWeatherSensors.lua << HTTPResponse: "WUS_buienradarResponse"
2553+
11/27/20 18:40:03 - 11/27/20 18:40:03 (00 - 0.0290) waqi.lua << HTTPResponse: "waqi_nearby"
2554+
11/27/20 18:41:00 - 11/27/20 18:41:00 (00 - 0.0583) Bathroom humidity.lua << timer: "every minute between 05:15 and 23:30"
25502555
```
25512556

25522557
Every time Domoticz starts dzVents and debug logging is enabled you should see these lines in the domoticz log:
@@ -2607,7 +2612,7 @@ Check out the documentation [here](https://htmlpreview.github.io/?https://github
26072612
- Fixed bug in dumpTable that caused infinite loop for table with self-reference
26082613

26092614
## [3.0.17]
2610-
- Add timestampTodate, dateToTimestamp and date2date functions in Time
2615+
- Add timestampTodate, dateToTimestamp and dateToDate functions in Time
26112616

26122617
## [3.0.16]
26132618
- Add except as keyword in timeRules
@@ -2688,7 +2693,7 @@ Check out the documentation [here](https://htmlpreview.github.io/?https://github
26882693
- Add custom-events triggers as option to the on = { ... } section. You can now send an event trigger to start subscribed dzVents scripts. customEvents can be triggered by:
26892694
- dzVents domoticz.emitEvent(name, data ) -- command (data = optional)
26902695
- JSON: json.htm?type=command&param=customevent&event=MyEvent&data=myData ( data = optional )
2691-
- MQTT: {"command" : "customevent", "event" : "MyEvent" , "data" : "myData" } ( data = opt ional )
2696+
- MQTT: {"command" : "customevent", "event" : "MyEvent" , "data" : "myData" } ( data = opt ional )
26922697
- Add method domoticz.emitEvent()
26932698
- Add attribute `mode` to Evohome controller
26942699
- Add option to dumpTable() and ([device][uservariable][scene][group].dump() to os file

0 commit comments

Comments
 (0)