View source for Luup Declarations

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&nbsp;will not&nbsp;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.