Luup Scenes Events

Revision as of 05:02, 6 November 2009

Adding Lua code to scenes and events

You can add Lua script to scenes and events for simple tasks, like making a scene or event conditional. Conditional meaning "do something only if some condition is met", such as attaching a condition to your "Come Home" scene so it is only run if the temperature is over 70 degrees. Basic conditional expressions are easy, and, if that's all you're looking to do, skip to the walk-through below.

If you're more technically inclined you can also do very advanced things too. For an overview of all the advanced things you can do with Vera's Luup engine, and how scenes and events fit in, see the Luup_Intro page.

To add Lua code to a scene, create the Scenes and click 'Luup scene'. Fill in your Lua code in the input box. To do a simple condition, see the sample below. Or if you want to do advanced scripting you can use any [Lua] commands as described in the [Lua reference manual] as well as the variables and functions that the Luup engine adds to Lua documented here: Luup_Lua_extensions. The Lua code will be run every time the scene is activated either by the user or a scene or a timer. The Lua code is run before the commands that you included in the scene. If your Lua code ends with this: "return false" then the commands in the scene will not be run.

You can also add Lua code to an event by clicking 'Luup event'. Since events are attached to scenes anyway, there is usually little difference between adding the code to an event, or to the scene the event is part of. If the Lua code in an event returns false, then the event is aborted, meaning the scene that the event is attached to will not be triggered by the event. The main reason for attaching Lua code to an event is if you have multiple events to a scene. For example, you may have a scene called "Turn lights on in hallway" which is triggered by 2 events: 1) The front door opens, and 2) the motion sensor in the hallway is tripped. Perhaps whenever the front door opens you always want the scene to be activated, but you only want the motion sensor to activate the scene before 10:00. In this case, you would add Lua code to the motion sensor's event which does something like (pseudo-code): "if time>10:00 return false". That way the event from the motion sensor will be aborted if it's after 10:00, but the event from the front door will always activate the scene regardless.

When you edit the Lua code in a scene or event you must click 'Save' before the code is saved. Then you can activate the scene or trigger the event to see what happens when your code is run. If you're doing some advanced scripting that you'll need to debug this can be tedious, but there are easy ways to test your Lua script immediately without saving first as explained in Lua_Debugging.

If you're doing advanced Lua scripting, you should note that all the Lua code in your scenes and events run in a single Lua instance, which is separate from any Lua plugins. This means if you set a global variable in one scene, or create a function inside the Lua code in a scene, then in another scene's Lua code you can use that global variable or call that function. You do not need to worry about conflicting with a Luup plugin, though, since they have their own Lua instance, meaning they have their own global variables and functions.

Walk-through #1 -- At 12 noon, turn off the interior lights if the temperature is over 80 degrees

Before you start, in Vera's setup interface go to 'Devices' and click the '+' button next to the thermostat. Make note of the Device #. In this walkthrough we'll assume it's Device #3, but use the actual device number of your thermostat. Next, visit this page: Luup Variables. That lists all the variables for devices. A variable is basically a piece of information about the current state of a device, such as whether it's on or off, what temperature, etc. Look down at thermostats, and copy the name of the service/variable which corresponds to the current temperature, namely: urn:upnp-org:serviceId:TemperatureSensor1 CurrentTemperature

Notice that it states the CurrentTemperature is in celsius. So type in "80 degrees fahrenheit to celsius" in google and you'll see that it's 26.6 degrees celsius.

Now, the first step is to create the scene that turns off the lights. In Vera's setup interface, click 'Scenes', and click 'Add Scene' to add a new scene to one of the rooms. It's not important which room you choose. Scenes are categorized in rooms just to help you keep track of them if you have a lot of scenes. You can also put the scene in 'Global Scenes', or, you can create dummy rooms on the 'Rooms' tab if you want to have more "rooms" to organize your scenes with. After you click 'Add Scene', type in a description to remember your scene by, such as "Lights off 12:00 if 80". Under the 'Commands' area you'll see all the rooms. Click '+' next to the rooms that have lights you want to control, and choose "Off" in the pull-down. At this point, you have a normal scene, and, if you were to save your changes now, whenever you click the scene on the dashboard or on a remote control, the lights should turn off.

Second, next to the scene's description click 'add timer'. You can give the timer a description too so that if you have multiple timers you can see in the logs which one is activating the scene. Choose "Day of week based". If you want this scene to only run on certain days of the week, just check off which days you want this scene to run on. Otherwise, you can leave them all unchecked (or check them all) to do it every day. Leave the pull-down at "a certain time of day", and choose 12 : 00 : 00 from the pull-downs. At this point, if you were to save your changes, the lights would turn off automatically at 12 noon.

Third, the last step is to add the condition. To the right of the scene's description you'll see the button "Luup Scene". Click it and in the code box, copy and paste the following:

 local lul_temp=luup.variable_get("urn:upnp-org:serviceId:TemperatureSensor1","CurrentTemperature",3)
 if( tonumber(lul_temp)<26.6 ) then
   return false
 end

Don't forget to change the "3" to whatever is the actual device number of your thermostat. Assign the result of luup.variable_get to a variable first, rather than putting it directly in the tonumber(), because luup.variable_get actually returns 2 values: the value of the variable, and the time when the variable was modified. The 'tonumber' is needed because all of a device's variables are stored as plain text--not numbers--so if you want to do arithmetic or numeric comparison of a variable, you need to put tonumber() around luup.variable_get. luup.variable_get is documented in Luup Lua extensions.

Now click 'Update', and then click 'Save' to save everything. The "return false" means "don't run this scene". So if the current temperature is <26.6, the scene will be aborted and won't run. The timer will make it trigger every day at 12 noon.

To test it, you can click the scene button on the dashboard. The lights will turn off only if the temperature is over 80 degrees. If it's less than 80 degrees, the scene won't do anything. Since this scene is something that happens automatically and you probably won't execute manually, you can go to the scene again and check the "Hidden" box so the scene doesn't show up on Vera's 'Dashboard' and on your remote controls, like the iPhone. If you want to have a scene that turns off the lights which you can run whenever you want from 'Dashboard or your remote control, you should create another scene that has the same commands and simply don't add the timers and Luup conditions, and don't check the "Hidden" box.

You can substitute other service/variables and device ID's to make other types of conditions. The "if" statement above also supports nesting with ( and ), as well as the keywords 'and' and 'or'. So the following means the scene would abort if the temperature is <26.6 and >25, unless it's <23:

 local lul_temp=luup.variable_get("urn:upnp-org:serviceId:TemperatureSensor1","CurrentTemperature",3)
 if( (tonumber(lul_temp)<26.6
   and tonumber(lul_temp)>25)
   or tonumber(lul_temp)<23 ) then
     return false
 end

If the scene doesn't run, it's possible there is a syntax error. The easiest way to test this is to copy the Lua code from the scene, then go to Devices, Luup Plugins, and "Test Luup code". Paste the code in the box and click 'go'. If the info box above the 'go' button has a check and says "Message sent successful", your code is okay. If there's an error, it says: "Code failed".

To see if that's true, use putty, or telnet or ssh to log-in to Vera, as explained in detail in Lua Debugging, and type:

  cd /var/log/cmh
  tail -f LuaUPnP.log | grep '^01'

Now click 'Save' in Vera's setup page, even if it's gray, as that will cause Vera to restart the Luup engine and log any syntax errors. See: Lua Debugging for in-depth details on how to debug.

Samples

This page is a wiki which anyone can edit. If you have some Lua code you think other users might find useful, feel free to add it here.

Misc actions

Did you see the sample here already: http://wiki.micasaverde.com/index.php/Luup_Scenes_Events

Turn an appliance switch or a Danfoss thermostat on for device #5

 luup.call_action("urn:upnp-org:serviceId:SwitchPower1","SetTarget",{ newTargetValue="1" },5)

Turn an appliance switch or a Danfoss thermostat off

 luup.call_action("urn:upnp-org:serviceId:SwitchPower1","SetTarget",{ newTargetValue="0" },5)

Do something if switch device #5 is on

 local lul_tmp = luup.variable_get("urn:upnp-org:serviceId:SwitchPower1","Status",5)
 if( lul_tmp=="1" ) then
    --something to do goes here
 end

Dim switch #6 to 30%

 luup.call_action("urn:upnp-org:serviceId:Dimming1","SetLoadLevelTarget",{ newLoadlevelTarget="30" },6)

Arm motion sensor #7

 luup.variable_set("urn:micasaverde-com:serviceId:SecuritySensor1","Armed","1",7)

Disarm motion sensor #7

 luup.variable_set("urn:micasaverde-com:serviceId:SecuritySensor1","Armed","0",7)

Note, arming and disarming isn't a concept within UPnP or Z-Wave. It's just a flag that the Luup engine uses, and is stored in a variable we created called "Armed".

Run Scene #5

 luup.call_action("urn:micasaverde-com:serviceId:HomeAutomationGateway1","RunScene",{ SceneNum="5" })

In this case we left the device number off (the 4th parameter to luup.call_action), because the "RunScene" action is handled by the Luup engine itself--not by some device within Z-Wave, etc.

However, normally you don't need to luup.call_action in Lua code. Rather, whatever actions, or commands, you want to run, you put into the scene itself, and the only Lua code is to simply check if some condition is true and abort the scene if the condition isn't met.

Change the Temperature on Thermostat (Cool) device #19

 luup.call_action("urn:upnp-org:serviceId:TemperatureSetpoint1_Cool",
                  "SetCurrentSetpoint", { NewCurrentSetpoint="68" },
                  19)

Change the Temperature on a Thermostat (Heat) device #19

 luup.call_action("urn:upnp-org:serviceId:TemperatureSetpoint1_Heat",
                  "SetCurrentSetpoint",{ NewCurrentSetpoint="68" },
                  19)

a scene if the temperature is outside of a range

add snippets here...