renamed settings file for easier updating of your system with a new v…

…ersion of dzVents

Added some instructions for the Time object.

README.md

@@ -15,20 +15,23 @@
     - [Iterators](#iterators)
     - [Contants](#contants)
   - [Device object API](#device-object-api)
+    - [Fetching http data](#fetching-http-data)
     - [Device attributes](#device-attributes)
     - [Device methods](#device-methods)
     - [Switch timing options (delay, duration)](#switch-timing-options-delay-duration)
   - [Variable object API](#variable-object-api)
     - [Variable attributes](#variable-attributes)
     - [Variable methods](#variable-methods)
+  - [Create your own Time object](#create-your-own-time-object)
+    - [Time Properties:](#time-properties)
 - [Persistent data](#persistent-data)
   - [Script level persistent variables](#script-level-persistent-variables)
     - [Size matters and watch your speed!!](#size-matters-and-watch-your-speed)
   - [Global persistent variables](#global-persistent-variables)
   - [A special kind of persistent variables: *history = true*](#a-special-kind-of-persistent-variables-history--true)
     - [Historical variables API](#historical-variables-api)
       - [Defining](#defining)
-      - [Setting](#setting)
+      - [Add](#add)
       - [Getting. It's all about time!](#getting-its-all-about-time)
       - [Interacting with your data: statistics!](#interacting-with-your-data-statistics)
         - [Index](#index)
@@ -117,7 +120,7 @@ Form the extracted zip folder copy the following to the Domoticz script folder (
  -  The `dzVents` folder. This folder contains all the dzVents logic
  - `script_time_main.lua`
  - `script_device_main.lua`
- - `dzVents_settings.lua` and 
+ - `dzVents_settings_example.lua` and 
  - the folder `scripts` 
 
 After doing so you will have this structure:
@@ -132,10 +135,10 @@ After doing so you will have this structure:
     			scripts/
     			script_time_main.lua
     			script_device_main.lua
-    			dzVents_settings.lua
+    			dzVents_settings_example.lua
     			... <other stuff that was already there> ...
 
-Edit the file `dzVents_settings.lua` and enter the ip number and port number of your Domoticz instance. Make sure that you don't need a username/password for local networks (see Domoticz settings) or dzVents will not be able to fetch additional data like battery status and device type information! If you don't want  or need this then you can set `['Enable http fetch']` to `false`.
+Now **rename** the file `dzVents_settings_example.lua` to `dzVents_settings.lua`, open the file in an editor and enter the ip number and port number of your Domoticz instance. Make sure that you don't need a username/password for local networks (see Domoticz settings) or dzVents will not be able to fetch additional data like battery status and device type information! If you don't want  or need this then you can set `['Enable http fetch']` to `false` but you will miss some of the handy features if you do so!
 
 The scripts folder is where you put your new Lua event scripts. You can give them any name with the `.lua` extension (no need for *script_device* nor *script_time* prefixing).
 
@@ -512,6 +515,40 @@ User variables created in Domoticz have these attributes and methods:
 
  - **set(value)**: *Function*. Tells Domoticz to update the variable. *No need to cast it to a string first (it will be done for you).*
 
+## Create your own Time object
+dzVents comes with a Time object that my be useful to you. This object is used for the various time attributes like `domoticz.time`, `device.lastUpdate`. You can easily create such an object yourself:
+
+    local Time = require('Time')
+    local t = Time('2016-12-12 7:35:00') -- must be this format!!
+
+You can use this in combination with the various dzVents time attributes:
+
+    local Time = require('Time')
+    local t = Time('2016-12-12 7:35:00')
+
+	local tonight = Time(domoticz.time.rawDate .. ' 20:00:00')
+	print (tonight.getISO())
+	-- will print something like: 2016-12-12T20:00:00Z
+
+In the future I plan to add some date/time arithmetric
+
+### Time Properties:
+
+ - **day**: *Number*
+ - **getISO**: *Function*. Returns the ISO 8601 formatted date.
+ - **hour**: *Number*
+ - **hoursAgo**: *Number*. Number of hours since the last update.
+ - **isToday**: *Boolean*. Indicates if the device was updated today
+ - **month**: *Number*
+ - **min**: *Number*
+ - **minutesAgo**: *Number*. Number of minutes since the last update.
+ - **raw**: *String*. Generated by Domoticz
+ - **rawDate**: *String*. Returns the date part of the raw data.
+ - **rawTime**: *String*. Returns the time part of the raw data.
+ - **sec**: *Number*
+ - **secondsAgo**: *Number*. Number of seconds since the last update.
+ - **year**: *Number*
+
 # Persistent data
 
 In many situations you need to store some device state or other information in your scripts for later use. Like knowing what the state was of a device the previous time the script was executed or what the temperature in a room was 10 minutes ago. Without dzVents you had to resort to user variables. These are global variables that you create in the Domoticz GUI and that you can access in your scripts like: domoticz.variables['previousTemperature']. 
@@ -880,7 +917,7 @@ If you dare to you can watch inside these files. Every time some data is changed
 
 # Settings
 
-As mentioned in the install section there is a settings file: dzVents_settings.lua. There you can set a couple of parameters for how dzVents operates:
+As mentioned in the install section there is a settings file: dzVents_settings_example.lua. **Rename this file to dzVents_settings.lua**. There you can set a couple of parameters for how dzVents operates:
 
  - **Domoticz ip**: *Number*. IP-address of your Domoticz instance.
  - **Domoticz port**: *Number*. Port number used to contact Domoticz over IP.

dzVents/EventHelpers.lua

@@ -25,7 +25,11 @@ local function EventHelpers(settings, domoticz, mainMethod)
 	end
 
 	if (settings == nil) then
-		settings = require('dzVents_settings')
+		ok, settings = pcall(require, 'dzVents_settings')
+		if (not ok) then
+			utils.log('Error reading the settings file dzVents_settings.lua. Make sure you have it. You can rename dzVents_settings_example.lua and use that as an example.', utils.LOG_ERROR)
+			utils.log(settings, utils.LOG_ERROR)
+		end
 	end
 
 	_G.logLevel = settings['Log level']

dzVents/QUICKREF.md

@@ -18,6 +18,8 @@
 - [Variable object API](#variable-object-api)
   - [Variable attributes](#variable-attributes)
   - [Variable methods](#variable-methods)
+- [Time object API](#time-object-api)
+  - [Time Properties:](#time-properties)
 - [Persistent data](#persistent-data)
   - [Script level persistent variables](#script-level-persistent-variables)
   - [Global persistent variables](#global-persistent-variables)
@@ -304,6 +306,35 @@ User variables created in Domoticz have these attributes and methods:
 
  - **set(value)**: *Function*. Tells Domoticz to update the variable. *No need to cast it to a string first (it will be done for you).*
 
+# Time object API
+
+You can create dzVents time objects like this:
+
+    local Time = require('Time')
+    local t = Time('2016-12-12 7:35:00')
+
+	local tonight = Time(domoticz.time.rawDate .. ' 20:00:00')
+	print (tonight.getISO())
+	-- will print something like: 2016-12-12T20:00:00Z
+
+
+## Time Properties:
+
+ - **day**: *Number*
+ - **getISO**: *Function*. Returns the ISO 8601 formatted date.
+ - **hour**: *Number*
+ - **hoursAgo**: *Number*. Number of hours since the last update.
+ - **isToday**: *Boolean*. Indicates if the device was updated today
+ - **month**: *Number*
+ - **min**: *Number*
+ - **minutesAgo**: *Number*. Number of minutes since the last update.
+ - **raw**: *String*. Generated by Domoticz
+ - **rawDate**: *String*. Returns the date part of the raw data.
+ - **rawTime**: *String*. Returns the time part of the raw data.
+ - **sec**: *Number*
+ - **secondsAgo**: *Number*. Number of seconds since the last update.
+ - **year**: *Number*
+
 # Persistent data
 
 ## Script level persistent variables

dzVents/dzVents history.txt

@@ -2,7 +2,9 @@
 * Deprecated setNew(). Use add() instead. You can now add multiple values at once in a script by calling multiple add()s in succession.
 * Fixed printing device logs when a value was boolean or nil
 * Fixed WActual/total/today for energy devices.
-* Added updateSetPoint method on devices for dummy thermostat devices
+* Added updateSetPoint method on devices for dummy thermostat devices and EvoHome setpoint devices
+* Added couple of helper properties on Time object. See README.
+* Renamed the file dzVents_settings.lua to dzVents_settings_example.lua so you don't overwrite your settings when you copy over a new version of dzVents to your system.
 
 [1.0-beta1]
 * Added data persistence for scripts between script runs (see readme for more info)