Luup Intro

From MiOS
Revision as of 18:45, 9 June 2009 by Micasaverde (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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.

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.

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

1. 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 cetain 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 a snippets of Lua code which will run whenever the scene is activated. The Lua code can use "if then" conditions to do custom actions, and can 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 setup a wiki page where when users figure out how to do something with Lua code in their scenes and events they 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 still copy and paste the sample Lua code in their own scenes and events and just replace any variables.

For more information see: [Luup_Scenes_Events]

2. Write 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]

3. Create 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. 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 use 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 use case #1 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 #1. 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 rain and frost.

For more information see: [Luup_Plugins]

Personal tools