Luup Lua extensions

Revision as of 01:32, 9 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

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.

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

lu_chdev_append

lu_chdev_start

lu_chdev_sync

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