User variables

General

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 > More Options > 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: Domoticz_API/JSON_URL#User_variables

Events

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 Events

Lua

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 the uservariables array to Lua, at that point they may be converted. Date, time and strings user variables are passed as strings with no modification. Integer and float user variables are converted to Lua number type. When you want to change the value of any user variable, you must convert it to string before passing it in the commandArray.

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. So the following code should work for either an integer, float or a string MyVar. 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 even if uservariables["MyVar"] is 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 = os.date("*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"
     end
     return season
end

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


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


----------------------------------------------------------------------------------------------------------
-- 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(os.date("%Y"));
month 	= tonumber(os.date("%m"));
day 	= tonumber(os.date("%d"));
hour 	= tonumber(os.date("%H"));
min 	= tonumber(os.date("%M"));
weekday = tonumber(os.date("%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 .. ' ');
	end

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

dzVents

User variables can be accessed using the Domoticz object API domoticz.variables() funcion. See the dzVents documentation: DzVents:_next_generation_LUA_scripting#Variable_object_API_.28user_variables.29