Luup Declarations

Revision as of 15:38, 7 January 2016

When the Luup engine calls your Lua code it will pass your code some variables relevant to whatever the code is supposed to do. You can see how your code looks with the full function declarations by bringing up this page in a web browser: http://ip_of_vera:49451/data_request?id=lu_lua&DeviceNum=8

Here is a list of the variables that are passed to your Lua code, and also a list of what return values the Lua code should send back. The tag names are explained here: The Luup XML implementation file.

<run>

variables: lul_device is a number that is the device ID. lul_settings is a table with all the arguments to the action.

return value: true or false where true means the function ran ok, false means it failed.

Sample; including the function/end lines, which the Luup engine adds automatically:

function SetTarget_run(lul_device, lul_settings)
 
    luup.log('device: ' .. tostring(lul_device) .. ' value: ' .. tostring(lul_settings.newTargetValue))
    return false -- function failed
 
end

<job>

variables: lul_device is a number that is the device id. lul_settings is a table with all the arguments to the action. lul_job is the id number of the job.

return value: return 2 values with the syntax return a,b. The first is the job status and is a number from 0-5, and the second is the timeout in seconds.

For more detail see:

• Luup Lua extensions: Module luup.job
• Luup Plugins ByHand: <run/job/incoming/timeout>
• UI Notes: Job status

Sample; including the function/end lines, which the Luup engine adds automatically:

function SendProntoCode_job(lul_device, lul_settings, lul_job)
 
    luup.log('device: ' .. tostring(lul_device) .. ' value: ' .. tostring(lul_settings.newTargetValue) .. ' job ID#: ' .. lul_job)
    -- 5 = job_WaitingForCallback
    -- and we'll wait 10 seconds for incoming data
    return 5, 10
 
end

<incoming> (returned by a job)

variables: same as for job above, plus lul_data which is a binary string with the data received

return value: return 3 values with the syntax return a,b,c. The first two are the same as with job, and the 3rd is a true or false indicating if the incoming data was intended for this job. See <run/job/incoming/timeout> for details.

Sample; including the function/end lines, which the Luup engine adds automatically:

function SendProntoCode_incoming(lul_device, lul_settings, lul_job, lul_data)
 
    luup.log('device: ' .. tostring(lul_device) .. ' value: ' .. tostring(lul_settings.newTargetValue) .. ' job ID#: ' .. lul_job .. " received data: " .. lul_data)
    -- 4 = jobDone
    -- nil = n/a on the timeout since the job is done
    -- true = the incoming data was for us
    return 4, nil, true
 
end

<timeout>

variables: same as for job above.

return value: same as for job above

<incoming> (general, not for a job)

variables: lul_device is a number that is the device id. lul_data is a binary string with the data received

return values: none

<scene>

variables: none

return values: boolean (true or false)

This is how the Lua code in a scene is called. The code is ran before the commands in the scene and if the code returns false, the scene is aborted and the command don't run. If anything else is returned, including true or nothing at all, the scene's commands run as normal.

<event>

variables: lul_value

return values: boolean (true or false)

This is how the Lua code in an event is called. The code is run before the event is processed and the commands in the scene are executed. If the code returns false, the event is aborted and the command(s) in the scene will not run. If anything else is returned, including true or nothing at all, the scene's commands run as normal. lul_value is the new value that is being assigned to the variable which the event is monitoring.

<request>

variables: lul_request,lul_parameters,lul_outputformat

return values: lul_data,lul_outputformat

When you call lu_RegisterHandler (see Luup_Lua_extensions) to handle a request on a URL, you pass in a function name that will handle the request. This function is called with lul_request as a string containing the request ID, lul_parameters is a table with all the arguments on the URL, and lul_outputformat is the requested format of the data passed on the &output_format= in the URL.

You return lul_data which is a string containing the response which is forwarded to the client, and optionally lul_outputformat, which is the document type put in the HTML response.

<timed> (callback)

variables: lul_data

return values: none

When you pass a Lua function to be called at a later time with lu_CallFunctionDelay or lu_CallFunctionTimer (see Luup_Lua_extensions), the function is called with the data (a string) you past.

<watch> (callback)

variables: lul_device, lul_service, lul_variable, lul_value_old, lul_value_new

return values: none

When you watch a variable with lu_WatchVariable (see Luup_Lua_extensions), and the variable changes, your callback is called with the information on the variable that changed.

<startup>

variables: lul_device

return values: return 3 variables with the syntax return a,b,c where the first is true if the startup was successful or false if not, followed by 2 strings for the comments and the name of the module

If this function is called in the startup sequence specified in the 'startup' XML tag, return true if the startup was ok, false if it wasn't, followed by some comments and the name of the module, like this: return false,'Cannot get state','gc100' or return true,'ok','gc100'

<ir>

There are two parts to the equation here:

1. the device holding the IR codes for all the different IR commands to be used
2. a device associated with 1) above that understands the codes and knows how to emit them via a specific piece of hardware

In the user interface for device one above, you can select the hardware device, two above, that will emit the IR codes.

Each <ir> tag hold an IR code - which can be in any format. In device one, you associate the hardware driver (device two). Device number two must understand the format, as found in the <ir> tag and will automagically receive the IR code via the function SendProntoCode(). The hardware is then manipulated to emit the IR code.

Note that many of the IR devices used by Vera use ProntoCodes, hence the handling function was named SendProntoCode. However this is a misnomer, as the function just receives what is located in the <ir> tag. The hardware driver computer code just needs to emit the IR code it receives, whether that be a prontcode or otherwise.

Refer to Luup_IR also.