Latest revision as of 05:08, 13 April 2010

[edit] Luup beta phase

As explained in our earlier Luup launch announcement, Mi Casa Verde is donating cash and hardware to encourage Luup development and would like to encourage makers of UPnP Control Points to add support for Vera's home automation devices. A list of notable, active Luup development efforts is here: Luup Projects. The software is available here Vera Luup Releases but you should read this document first to know what Luup is for. During the beta phase our developers will be responding daily to posts in the Luup Development board in our forum

[edit] Introduction to Luup development

Luup (Lua-UPnP) is Mi Casa Verde’s new software engine which incorporates Lua, a popular scripting language, and UPnP, the industry standard way to control devices. Vera is built on Luup. See: Vera Luup Releases for info on the latest Luup firmware release for Vera with a summary of known issues and current development, and instructions on upgrading your firmware to the latest version of Luup.

Vera allows users to customize their smarthome solution, add support for new devices, and control Vera from other devices. This document assumes you are already familiar with Vera's basic functionality and what Luup is all about. If not, there's a demo video at micasaverde.com that shows what our product Vera is about. And the Luup launch announcement explains what Luup can do and whom it's for.

There are 4 different ways to use Luup, each requiring a different skill set:

[edit] 1. Controlling infrared devices, like TV's

You don't need any technical skills to add support for infrared-controlled devices and to learn new infrared commands from your existing remote control. See: Luup IR. Note that many high-end audio/video devices have RS232 serial ports specifically for home automation control, and if you have the technical skills to know how the protocol works, you can get better results creating a Luup plugin, as described in use case #4 below.

[edit] 2. Customizing scenes and events by adding snippets of Lua code

This requires the least amount of technical skills and allows users to customize Vera's functionality without knowledge of UPnP and often times without any knowledge of Lua either.

In Vera, a scene is a group of actions, or commands, sent to a device. It is the fundamental way a user can interact with his smarthome system. For example, the "Go to bed" scene can turn off some lights and lower the thermostat. Scenes can be activated 3 ways: 1) by a user manually choosing the scene from the web interface or a remote control, 2) by a timer where the scene is run at set intervals or certain times of the day, or 3) in response to events, such as run the "turn lights in hallway" scene when a motion sensor is tripped. Vera allows you to create a scene and add snippets of Lua code which will run whenever the scene is activated. The Lua code can use "if-then" conditions to perform custom actions, even abort the execution of the scene. For example, you want to turn on a heater in the basement at 8:00pm every night only if the outside temperature is below 40 degrees, and turn on a second heater if the outside temperature is below 20 degrees. This could be done by attaching Lua code to your "turn on heater" scene which has a timer to run at 8:00pm. We have extended Lua with an API that provides hooks into the Luup engine so your Lua code can interact with other smarthome devices.

You can also add Lua code to an event, such as "motion detector tripped", so your Lua code is run every time the event occurs. The Lua code can also abort the event, meaning if the event is supposed to trigger a scene, you can stop that from happening.

We have created a wiki page where users who've figured out how to do something with Lua code in their scenes and events can add the Lua code to the page with a brief description of what it does. This way other users - who may not understand Lua - can copy and paste the sample Lua code into their own scenes and events, replacing variables as necessary.

For more information see: Luup Scenes Events

[edit] 3. Writing an external application that talks to the Luup engine

This is where a developer has some application written in a language like C, Java, etc., and wants to be able to control Luup. The most common example would be a UPnP Control Point that will act as a remote control. Your application can talk to the Luup engine using standard the UPnP protocol, which consists of SOAP/XML requests. Additionally, Luup has a basic web server that will respond to the same commands when passed on a URL. This makes it easy to control Luup without knowing anything about UPnP. For example, to get the status of devices you can either use the UPnP action, which will return the status inside the SOAP response, or you can just open the URL: http://myip:49451/data_request?id=lu_status which is a shortcut to: http://myip:49451/data_request?id=lu_action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=GetStatus&output_format=json

You can specify on the URL the output_format, which is how you want to get the response back. This way you can make a UPnP Control Point entirely in java script or a perl script, for example, without needing to handle SOAP and XML. You can also read the main configuration file and modify it and actually replace Vera's built-in web user interface completely with your own.

For more information see: Luup Control

[edit] 4. Creating your own Luup plug-ins

A Luup plugin appears as a new device in Vera. It can do almost anything. It can be an interface to some external device, such as an alarm panel that has a serial (RS232) control port. Or it can be a virtual, logic device, such as a "Weather device" which fetches weather forecasts from a web site and makes them available. The Luup plugins use the same Lua engine as the custom scenes and events described above in case #1. Therefore anything that you could do with a scene or event you could also do with a Luup plugin. The difference is that a plug-in allows you to create devices that are usable by other devices and UPnP Control Points and which can run on their own and register callback hooks to be executed when events occur, whereas when you add a snippet of code to a scene or event it is only run in response to that scene or event. If your Luup plug-in is created in such a way that it's generic and re-usable you can make that plug-in available in the Luup gallery for other users to use too. Plug-ins also can be open source, or collaboritive, so other users can expand the functionality. In the near future we will also be adding a way to encrypt and protect your Luup plug-ins so that you will be able to offer them for sale in the Luup gallery if you don't want to donate them as free open source.

For example, in case #2 we described having a scene that turns on the heater when the temperature is below 40 degrees. Let's say that instead of using a thermometer to get the current temperature you want to get the temperature from the weather.com web site. There are 2 ways to do this: 1) You could add a snippet of Lua code to the scene which retrieves the temperature from weather.com and checks if it's below 40 degrees as in use case #2. In this case the same Lua code would need to be copied into each scene that wanted to get weather information. Or, 2) you could create a Luup plug-in which is a weather.com interface and which exposes various Actions and Variables like "Wind Direction", "Current Temperature", etc. Then, in your scene you would add some snippet of Lua code that looked like (pseudo code): if "Weather.com interface":"CurrentTemperature"<40 then "Heater":"On". All the logic for communicating with weather.com is in the plug-in, and the plug-in is available for use anywhere in the system. You could also make your weather.com plug-in available to the public in the Luup gallery and, if you make it open source, other users could expand upon it. For example, maybe you only added the "CurrentTemperature" to your plug-in, and another user might extend it to include settings such as rain and frost.

For more information see: Luup Plugins