LuaUPnP

Revision as of 23:00, 9 April 2009

This page explains how we are implementing our upcoming LuaUpNP feature in Vera. The document gets a bit technical so that users can comment on it and we can make adjustments as the feature comes closer to release. User feedback is appreciated and a stick topic has been created in the 'Vera Developers' section of forum.micasaverde.com for comments.

This new feature is very significant for Vera because it expands the possibilities of Vera greatly, and makes it very simple to create really powerful automation systems. This one module provides Infrared control for a/v devices, serial/usb/ethernet control for any type of device, and a Lua scripting engine that can be used to do just about anything. And it's all based on UPnP, so anything you can create can be controlled from a standard UPnP control point.

Some background information: UPnP allows you to describe any type of device in a generic way, explaining what the device can do and how to control it. Then, there are a variety of UPnP control points, which are remote controls, such as a wall-mounted touch-panel, which are able to scan the network for UPnP devices, find out what those devices can do, and present you with a remote control.

Lua is a fast, lightweight scripting language for creating macros, code snippets, and even stand alone applications.

Our LuaUPnP solution consists of 3 parts: 1) The device builder web site. 2) The LuaUPnP engine. 3) Any number of i/o devices (infrared transmitters/receivers, rs232 ports, etc.).

Here is a general work flow showing how the user creates and uses devices:

Adding a basic infrared a/v device or rs232 that already exists in the database

1. The user adds his infrared transmitter/receiver, such as plugging a Global Cache gc100 into his LAN, or a USBUIRT into the extra USB port on his Vera. The device is recognized and appears automatically on his devices list. If he's talking to a serial/rs232 device, he can also connect a generic USB->RS232 (usb->serial) cable in Vera's spare USB port, or connect the device to one of the serial ports on a gc100.

2. The user goes to the devices tab in Vera's setup UI, choose the 'Add LuaUPnP device', and is presented with a web form to help him locate his device. He can pick the manufacturer, type of device, model #, etc. When he does, he's asked to assign the room, and also to pick the i/o device associated with it (ie the usbuirt or the port on the gc100 or the usb->serial device).

The device is now broadcast as a UPnP device and he can control it from any UPnP control point. He can also go to the 'scenes' tab, and next to the device click 'Add actions', and then pick the actions he wants to send the device as part of the scene (ie TV on, mute, etc.).

Adding a new, basic infrared a/v device or rs232 that does not exist yet

Step 1 above is the same, and step 2 starts out the same. But, when he gets to pick the device, he chooses 'device not on the list'. Then:

1. The user fills in a form with basic information about the device, such as the manufacturer, model, type, etc. The user also picks how to send commands to the device: Infrared codes, RS232 data, network calls, etc., or he picks 'None' if this is purely a logic device that doesn't directly control any other device, such as a "Cold weather logic" device that may wait for sunset, and then check weather.com to see if the temperature is expected to drop below freezing, and if so, turn on the thermostat. This is a "logic" device because it's not directly controlling any device (the Z-Wave module is controlling the thermostat), it's merely providing logic. The user can also indicate if this device will be 'public' for other users to use too, or 'private', just for his Vera. This data is stored in an xml file that is a standard UPnP device description.

2. The user picks one or more of the standard service definitions (ie "TV", "CD Player", etc.). These have a list of actions, like "On", "Off", "Mute", etc. If there is no standard service definition, he has the option of creating a new one, in which case he adds all the actions his device will support "On", "Off", "Dim", etc., and for each action, adds any number of optional arguments. For example, "On" and "Off" may not have any arguments, but "Dim" takes a "Level" argument. This data is stored in an xml file that is a standard UPnP service description.

3. Now the user has a form that lists each action, and next to each action is a pull-down where the user can choose what to do in response to that action. The choices are: a) Send data to the device. There's an input box for the user to type in the data. The format of the data corresponds to the communication method picked above. If the communication is 'infrared', the user types an i/r code in the box. If it's rs232, he types in the data to send to the device. b) Run some Lua code. These can be mixed and matched. For example, this may be an infrared TV and basic commands, like "channel up" just require sending a code. But other commands, like "input #4" may require some logic to toggle inputs, so he wants to write Lua script. If the device is infrared, there's also a button "Learn the i/r code", which learns the code from an infrared learner.

4. The user also has the option of adding, for each action, Lua code to be run when: a) incoming data is received and the command is being executed, b) the command is completed, c) the command is aborted, d) the command times out. There are a couple other options for a command, such as specifying if the command should be aborted when another one of the same or other commands comes in before it's finished (ie if the user wants to turn the device off, but an 'on' command comes in before the device has turned 'off', abort the 'off').

After this is done, the user can add the device like described previously.

Writing the Lua Code

Whenever a command is received, it's assigned an internal job #. This is true whether or not there's any Lua script to be run. If there is, the Lua script the user wrote in step 3 above is

test receive

Pipes replacement in the device data