Luup Lua extensions

Revision as of 05:15, 30 July 2009

In addition to the [Lua] commands described in the [Lua reference manual], you can also reference in your Lua code global variables the Luup engine provides, or call functions and hooks within the Luup engine, and use local variables which the Luup engine may pass to your Lua code depending on what kind of Lua code you wrote:

Global Variables

The Luup engine provides the following global variables that can be referenced anywhere in your Lua code:

lug_device

This is a table containing information on all the devices in the system. The index is the device number. See: Lua Device Structure for details. Each device has the following attributes:

Room_Num: This is the number of the room the device is in.

DeviceType: This is a number representing the type of device. See: Luup Device Types Categories for a list.

Category_Num: This is a category for the device. See: Luup Device Types Categories

Device_Num_Parent: This is the number of the parent device. See: Lua Device Structure for details.

IP: If this device is IP based, this is the IP address.

MAC: If this device is IP based, this is the MAC address.

ID: If this device has an internal ID that is specific to the device, it is contained here. For example, for Z-Wave devices this is the Node ID, and for Insteon device it is the Insteon ID.

Description: This is the text description for the device as supplied by the user in the web ui.

UDN: This is the UDN for the UPnP device.

Examples:

The description of device 4, the UDN of device 3: lug_device[4].Description, lug_device[3].UDN

Log all the attributes from all the devices:

 for k,v in pairs(lug_device) do
   for k2,v2 in v
     lu_log("Device #" .. k .. ":" .. k2 .. "=" .. "v2")
   end
 end

Luup Functions

General purpose

lu_CallAction

lu_DeviceSupportsService

lu_GetDevicesByService

lu_GetVariable

lu_GetXmlNodeText

lu_log

lu_SetCommFailure

lu_SetVariable

lu_WatchVariable

lu_RegisterHandler

You can register an interceptor to handle a specific URL. Pass in 2 strings. The first is the name of a Lua function to get called back (see Luup Declarations for the parameters that will be passed to that callback function). The second is the name of the request you want to intercept and process. It will be prepended with "lr_" (for LuaRequest). So if you call lu_RegisterHandler("myfunc","myurl") then when http://ip:49451/data_request?id=lr_myurl&parm1=a&parm2=b is requested from Vera, your function 'myfunc' will be called, and it will be passed the parameters on the url, including parm1 and parm2, and whatever string that function returns will be forwarded to the browser as the response. See the L_WapUI.lua file in the Generic WAP plugin for an example.

lu_CallFunctionDelay(Function,Delay,Data)

Call the Lua function Function in Delay seconds.

Data can be a string passed back to the function. The function should be declared so it takes a single argument, which is this data.

lu_CallFunctionTimer(Function,Type,Time,Days,Data)

Call the Lua function Function at a future time. Type is 1=Interval timer, 2=Day of week timer, 3=Day of month timer, 4=Absolute timer. For an interval timer, days is not used, and Time should be a number of seconds, minutes, or hours using an optional 'h' or 'm' suffix. Example: 30=call in 30 seconds, 5m=call in 5 minutes, 2h=call in 2 hours. For a day of week timer, Days is a comma separated list with the days of the week where 1=Monday and 7=Sunday. Time is the time of day in hh:mm:ss format. Time can also include an 'r' at the end for Sunrise or a 't' for Sunset and the time is relative to sunrise/sunset. For example: Days="3,5" Time="20:30:00" means your function will be called on the next Wed or Fri at 8:30pm. Days="1,7" Time="-3:00:00r" means your function will be called on the next Monday or Sunday 3 hours before sunrise. Day of month works the same way except Days is a comma separated list of days of the month, such as "15,20,30". For an absolute timer, Days is not used, and Time should be in the format: "yyyy-mm-dd hh:mm:ss"

Data can be a string passed back to the function. The function should be declared so it takes a single argument, which is this data.

function refreshCache(stuff)
    ....
end

function startup()
    -- Setup an interval-based timer to call refreshCache every 30 minutes.
    lu_CallFunctionTimer("refreshCache", 1, "30m", "", "SomeStuff")
end

lu_wget(URL,Timeout,Username,Password)

This reads the URL and returns 2 variables: The first is a numeric error code which is 0 if successful, and the second is a string containing the contents of the page. If Timeout is specified, the function will timeout after that many seconds. If Username and Password are specified, they will be used for HTTP authentication.

Reporting child devices

These functions are for reporting to the Luup engine the child devices you have. First call lu_chdev_start with the id of the parent device and store the return value in a variable. The return value is a Lua type "userdata", meaning it's a binary object that you can't do anything with in Lua, other than pass it back to the Luup engine. Next call lu_chdev_append for each child device, passing in the device id of th parent, the binary object, a string with an internal ID you use to reference the child, a string with a description of the child, the UPNP device type, the UPNP device filename, the UPNP Luup Implementation filename, any variables you want to set (ie parameters), and a boolean true/false which, if true, means the child is "embedded" within the parent, and will appear in the UI as part of the parent device, rather than a separate device you can put in it's own room. Lastly call lu_chdev_sync passing in the device number of the parent and that same binary object. When you pass in the variables, or parameters, use the syntax:

Service,Variable=value\n

and pass in as many variables as you want, separated with a line feed. There is a sample in the Luup Somfy Walkthrough

lu_chdev_append(int iDevice|string sUDN, Child_Device *pChildDevice,string sID,string sDescription,string sDeviceType,string sUpnpDevFilename,string sUpnpImplFilename,string sParameters,bool bEmbedded)

lu_chdev_start(int iDevice|string sUDN)

lu_chdev_sync(int iDevice|string sUDN, Child_Device *pChildDevice)

I/O data

lu_iop_intercept_incoming

lu_iop_open

lu_iop_recv_block

lu_iop_send

Job Handling

lu_job_set

lu_job_get