User variables

From Domoticz
Jump to: navigation, search


User variables enable users to store custom variables in the domoticz database. There are currently five types of variables that can be stored:

0 = Integer, e.g. -1, 1, 0, 2, 10  
1 = Float, e.g. -1.1, 1.2, 3.1
2 = String e.g. On, Off, Hello
3 = Date in format DD/MM/YYYY
4 = Time in 24 hr format HH:MM

Upon storing, domoticz checks the variable value for a correct format according to the type chosen. Storing the variable type with the variable will enable us to safely use these variables elsewhere in the system, this is why the check is always enforced (via user interface, api and event system). The string variable is the easiest one to use since it does not have any checks, but do not expect much intelligence from domoticz on this field later on.

Maximum size is 200 bytes.

Management through the webinterface

To manage these variables, go to Setup > User variables from the main screen. The management screen shows a table of existing variables, plus the option to create, edit or delete. To add a new variable, fill out the required fields and click "Add". To update a variable, first click on it in the list, then edit the fields and click "Update". To delete a variable, click on it in the list and then select "Delete".

Management through the API

See the api documentation: [1]


User variables can trigger events, and can also be read and updated through events. Whenever a variable is changed through the API or the webinterface, the event system is triggered. In Lua, scripts in the format script_variable_name.lua will be run, and Blockly will be checked for the relevant variable as well. In the event logic variables can be used and/or updated, but not added. Therefore if you wish to use variables in events, you have to create them first in the user interface. Note that setting a variable through an event does not trigger the event logic again since this can create a nasty loop.

For more info on using variables in events see [2]


When using user variables in Lua, keep in mind the following: variables are always stored as a string in the Domoticz database, regardless of their type. The variables are passed in arrays to Lua, at that point they will always be strings also. So when you're working with strings in Lua this has no implications, e.g.:

 if ( uservariables["MyVar"] == "On" ) then
  commandArray['Variable:MyOtherVar']= uservariables["MyVar"]

will work: MyVar is a string, and goes back into the commandArray as a string.

Lua is smart enough to convert strings to numbers when a math operation is requested, but when you put it back in a commandArray remember to convert back to string:

 commandArray['Variable:MyVar']= uservariables["MyVar"] +25

will not work. If uservariables["MyVar"] contains a string representing a number it will be increased by 25, but the commandArray will not accept a number.

 commandArray['Variable:MyVar']= tostring(uservariables["MyVar"] +25)

will work. The resulting number is converted to a string.

Lua Example

The following script will update the following user variables (year,month,day,hour,min,weekday,season,weekend,dark) that can be used in other scripts You will have to create the variables first.

-- Script parameters
Debug = "NO"                    -- Turn debugging on ("YES") or off ("NO")

-- Script functions
function WhichSeason()
     local tNow ="*t")
     local dayofyear = tNow.yday
     local season
     if (dayofyear >= 79) and (dayofyear < 172) then season = "Spring"
     elseif (dayofyear >= 172) and (dayofyear < 266) then season = "Summer"
     elseif (dayofyear >= 266) and (dayofyear < 355) then season = "Autumn"
     else season = "Winter"
     return season

function IsWeekend()
     local dayNow = tonumber("%w"))
     local weekend
     if (dayNow == 0) or (dayNow == 6) then weekend = "True"
     else weekend = "False"
     return weekend

function IsDark()
    local dark
    if (timeofday['Nighttime']) then dark = "True"
    else dark = "False"
    return dark

-- CommandArray

commandArray = {}

-- 		Setting the time variables:
--		%a	abbreviated weekday name (e.g., Wed)
--		%A	full weekday name (e.g., Wednesday)
--		%b	abbreviated month name (e.g., Sep)
--		%B	full month name (e.g., September)
--		%c	date and time (e.g., 09/16/98 23:48:10)
--		%d	day of the month (16) [01-31]
--		%H	hour, using a 24-hour clock (23) [00-23]
--		%I	hour, using a 12-hour clock (11) [01-12]
--		%M	minute (48) [00-59]
--		%m	month (09) [01-12]
--		%p	either "am" or "pm" (pm)
--		%S	second (10) [00-61]
--		%w	weekday (3) [0-6 = Sunday-Saturday]
--		%x	date (e.g., 09/16/98)
--		%X	time (e.g., 23:48:10)
--		%Y	full year (1998)
--		%y	two-digit year (98) [00-99]
--		%%	the character `%ยด

year 	= tonumber("%Y"));
month 	= tonumber("%m"));
day 	= tonumber("%d"));
hour 	= tonumber("%H"));
min 	= tonumber("%M"));
weekday = tonumber("%w"));
season  = WhichSeason();
weekend = IsWeekend();
dark    = IsDark();

if Debug=="YES" then
	print(' Year: '  .. year .. ' ');
	print(' Month: '  .. month .. ' ');
	print(' Day: '  .. day .. ' ');
	print(' Hour: '  .. hour .. ' ');
	print(' Minute: '  .. min .. ' ');
	print(' Weekday: '  .. weekday .. ' ');
	print(' Season: ' .. season .. ' ');
	print(' Weekend: ' .. weekend .. ' ');
        print(' Dark: ' .. dark .. ' ');

print("Updating variables if necessary")

if (uservariables["Year"] ~= year) then commandArray['Variable:Year'] = tostring(year)   end
if (uservariables["Month"] ~= month) then commandArray['Variable:Month'] = tostring(month)   end
if (uservariables["Day"] ~= day) then commandArray['Variable:Day'] = tostring(day)   end
if (uservariables["Hour"] ~= hour) then commandArray['Variable:Hour'] = tostring(hour)   end
if (uservariables["Minute"] ~= min) then commandArray['Variable:Minute'] = tostring(min)   end
if (uservariables["Weekday"] ~= weekday) then commandArray['Variable:Weekday'] = tostring(weekday)   end
if (uservariables["Season"] ~= season) then commandArray['Variable:Season'] = tostring(season)   end
if (uservariables["Weekend"] ~= weekend) then commandArray['Variable:Weekend'] = tostring(weekend)   end
if (uservariables["Dark"] ~= dark) then commandArray['Variable:Dark'] = tostring(dark)   end

return commandArray