Luup Lua extensions

Revision as of 21:41, 8 August 2009

In addition to the [Lua] commands described in the [Lua reference manual], you can also reference in your Lua code variables and functions from modules which the Luup engine provides as follows:

Module: luup

These are general purpose functions and variables. Call them by using the luup. module, such as:

luup.log('Now running version: ' .. luup.version)

variable: version

Contains the version of the luup engine, such as "1.0.843", as a string.

variable: longitude

Contains the longitude as a number, as found on the location tab in the setup UI.

variable: latitude

Contains the latitude as a number, as found on the location tab in the setup UI.

variable: timezone

Contains the timezone as a number, as found on the location tab in the setup UI.

variable: city

Contains the city as a string, as found on the location tab in the setup UI.

variable: devices

Contains all the devices in the system as a table indexed by the device number. The members are: room_num (number), device_type (string), category_num (number), device_num_parent (number), ip (string), mac (string), id (string), description (string), udn (string). See also: Lua Device Structure. Example to log device #5's IP addess and it's internal ID:

 luup.log('Device #5 ip: ' .. luup.devices[5].ip .. ' id: ' .. luup.devices[5].id)

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

device_type: 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.

This code will 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

variable: rooms

Contains all the rooms as a table of strings indexed by the room number. Example:

 luup.log('Room #1 is called: ' .. luup.rooms[1])

variable: scenes

Contains all the scenes in the system as a table indexed by the device number. The members are: room_num (number), description(string)

variable: remotes

Contains all the remotes in the system as a table indexed by the remote id. The members are: remote_file (string), room_num (number), description(string)

function: log

parameters: what_to_log (string), log_level (optional, number)

return: nothing

Writes what_to_log to the log, /var/log/cmh/LuaUPnP.log, with the given log_level, which is 50 by default. See: Luup_Loglevels

function: call_delay

parameters: function_name (string), seconds (number), data (string)

returns: result (number)

The function 'function_name', which must be passed as a string, will be called in 'seconds' seconds, and will be past the string 'data'. The function returns 0 if successful. See: Luup_Declarations#timed_function_callback for the names and syntax of the parameters that will be passed to function_name. function_name will only be called once and you must call call_delay again if you want it called again, or use call_timer instead.

function: call_timer

parameters: function_name (string), type (number), time (string), days (string), data (string)

returns: result (number)

The function 'function_name', which must be passed as a string, will be called when the timer is triggered, and will be past the string 'data'. The function returns 0 if successful. See: Luup_Declarations#timed_function_callback for the names and syntax of the parameters that will be passed to function_name.

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 after 30 minutes.
    -- Note that if you want it to "recur" then you need to call this function again
    -- at the end of the refreshCache() implementation.
    --
    lu_CallFunctionTimer("refreshCache", 1, "30m", "", "SomeStuff")
end

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 after 30 minutes.
    -- Note that if you want it to "recur" then you need to call this function again
    -- at the end of the refreshCache() implementation.
    --
    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