Luup Declarations

Revision as of 04:25, 26 September 2009

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: Luup_Plugins_ByHand#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)
  lu_log('device: ' .. tostring(lul_device) .. ' value: ' .. tostring(lul_settings.newTargetValue))
  return false
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. See Luup_Plugins_ByHand#run.2Fjob.2Fincoming.2Ftimeout this for details.

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

function SendProntoCode_job(lul_device,lul_settings,lul_job)
  lu_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 (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 Luup_Plugins_ByHand#run.2Fjob.2Fincoming.2Ftimeout this 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)
  lu_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 function 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: success? (boolean), comments (string), module_name (string)

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'