A device plugin is a set of XML files:

A Device description file is usually named something like 'D_xxxx.xml'. This format is specified by the UPnP Forum (http://www.upnp.org/resources/documents.asp). It describes the device type and what 'services' it provides. For example, a simple light switch is described by the 'D_BinaryLight1.xml' file (included), which specifies:

• a device type of: "urn:schemas-upnp-org:device:BinaryLight:1"
• a service of type: "urn:schemas-upnp-org:service:SwitchPower:1 ", defined by S_SwitchPower1.xmlM
• a service of type: "urn:schemas-micasaverde-com:service:EnergyMetering:1", defined by S_EnergyMetering1.xml
• a service of type: "urn:schemas-micasaverde-com:service:HaDevice:1", defined by S_HaDevice1.xml

• a boolean state variable called 'Target'
• a boolean state variable called 'Status'
• an Action called 'SetTarget', which takes an input argument called 'NewTargetValue', and is related to the 'Target' state variable.
• an Action called 'GetTarget', which provides an output argument called 'RetTargetValue', and is related to the 'Target' state variable.
• an Action called 'GetStatus, which provides an output argument called 'ResultStatus, and is related to the 'Status' state variable.

An Implementation file is usually named like I_xxxx.xml. This XML files hold one or more Lua scripts, that are run on different situations:

• a 'functions' code block, run at startup, mainly to define Lua functions to be used later.
• a 'startup' code, called at startup. Usually sets the device communications and callback hooks.
• an 'incoming' code block. Called when there's input data on the device's designated communications channel.
• 'action' code blocks, each one tied to an action defined on a Service description. Called when the action is fired.

This kind of plugin is usually just a L_xxxxx.lua file. To execute at startup it has to be added to the 'Extra Lua Files' panel. As said, it's executed at startup, where it usually defines a bunch of private functions and probably sets some of them as callbacks for some interesting events.

One example of this is the "Smartphone Web Inteface" plugin. It registers some functions as URL handlers, so a Smartphone browser gets the HTML produced by these functions.

Another example is the "Energy Monitor" plugin. This one sets callbacks to be fired whenever some energy-related events occur (a light turned on or off, a power meter reading changes), and it is also fired periodically to report the gathered statistics to the MIOS online service.

Luup plugins can also publish and ask for data from any other Luup plugins, allowing easy separation of presentation and content, and the ability to write plugins that aren't seen by users, just used by other plugin developers.

This is a (usually small) Lua snipped typed in the 'Luup' tab on the scene's control panel. It's described in detail on http://wiki.micasaverde.com/index.php/Luup_Scenes_Events. When the scene is activated, it first runs this Lua code, and if it returns a value of false, the scene is not run. This lets an advanced user to set some extra conditions for scene execution. Alternatively, the Lua code can also do any extra manipulation, supplementing or replacing the usual scene actions.

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 that 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:00 p.m. 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:00 p.m. 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

Serial Device Interface

Many users already have devices in their home which can be controlled using simple serial interfaces. Many of the alarm panels on the market, for example, have serial ports for control, as do high-end pool controls, TV's, stereo receivers, even some sprinkler systems, etc. Until now, if you wanted to control them, you would need one of the very expensive home automation systems and a programmer to set everything up, or you would need to be a software coder and develop a plug-in for computer based home automation software.

Luup provides a point and click way to copy and paste the data for the serial interface. It requires a degree of technical skill, of course, to get the user's manual and figure out how the serial communication works. But it doesn't require any programming skills and is a lot easier than writing software plugins, and much cheaper than buying a high-end system. If the creator allows this to be shared on the MiOS Aps Marketplace, then any novice end-user will be able to add this Luup add-on and control his serial device. Naturally Luup turns every one of these simple serial devices into standard UPnP so you can control them from your remote controls and in your scenes.

Writing an external application that talks to the Luup Engine (new page)

This is for developers with an application written in a language like C, Java, etc., that want 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.