Luup Declarations

From MiOS
(Difference between revisions)
Jump to: navigation, search
m ()
 
(18 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
[[Category:Development]]
 
[[Category:Development]]
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
+
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:3480/data_request?id=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]]:
+
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|The Luup XML implementation file]].
  
 
==<run>==
 
==<run>==
  
variables: lul_device is a number that is the device id. lul_settings is a table with all the arguments to the action.  
+
variables: <code>lul_device</code> is a number that is the device ID. <code>lul_settings</code> 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.  
+
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:<br>
+
Sample; including the function/end lines, which the Luup engine '''adds automatically''':<br>
  
 
<source lang="lua">function SetTarget_run(lul_device, lul_settings)
 
<source lang="lua">function SetTarget_run(lul_device, lul_settings)
     lu_log('device: ' .. tostring(lul_device) .. ' value: ' .. tostring(lul_settings.newTargetValue))
+
 
     return false
+
     luup.log('device: ' .. tostring(lul_device) .. ' value: ' .. tostring(lul_settings.newTargetValue))
 +
     return false -- function failed
 +
 
 
end</source>
 
end</source>
  
 
==<job>==
 
==<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.  
+
variables: <code>lul_device</code> is a number that is the device ID. <code>lul_settings</code> is a table with all the arguments to the action. <code>lul_job</code> 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.  
+
return value: return 2 values with the syntax <code>return a,b</code>. The first is the job status and is a number from 0-5, and the second is the timeout in seconds.
  
Sample, including the function/end lines which the Luup engine adds automatically:<br>
+
For more detail see:
 +
*[[Luup_Lua_extensions#Module:_luup.job|Luup Lua extensions: Module luup.job]]
 +
*[[Luup_Plugins_ByHand#.3Crun.2Fjob.2Fincoming.2Ftimeout.3E|Luup Plugins ByHand: <run/job/incoming/timeout>]]
 +
*[[UI_Notes#Job_status|UI Notes: Job status]]
 +
 
 +
Sample; including the function/end lines, which the Luup engine '''adds automatically''':<br>
  
 
<source lang="lua">function SendProntoCode_job(lul_device, lul_settings, lul_job)
 
<source lang="lua">function SendProntoCode_job(lul_device, lul_settings, lul_job)
     lu_log('device: ' .. tostring(lul_device) .. ' value: ' .. tostring(lul_settings.newTargetValue) .. ' job ID#: ' .. lul_job)
+
 
 +
     luup.log('device: ' .. tostring(lul_device) .. ' value: ' .. tostring(lul_settings.newTargetValue) .. ' job ID#: ' .. lul_job)
 
     -- 5 = job_WaitingForCallback
 
     -- 5 = job_WaitingForCallback
 
     -- and we'll wait 10 seconds for incoming data
 
     -- and we'll wait 10 seconds for incoming data
     return 5, 10  
+
     return 5, 10
 +
 
 
end</source>
 
end</source>
  
Line 36: Line 45:
 
variables: same as for job above, plus lul_data which is a binary string with the data received  
 
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.  
+
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/job/incoming/timeout>|<run/job/incoming/timeout>]] for details.  
  
Sample, including the function/end lines which the Luup engine adds automatically:<br>
+
Sample; including the function/end lines, which the Luup engine '''adds automatically''':<br>
  
 
<source lang="lua">function SendProntoCode_incoming(lul_device, lul_settings, lul_job, lul_data)
 
<source lang="lua">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)
+
 
 +
     luup.log('device: ' .. tostring(lul_device) .. ' value: ' .. tostring(lul_settings.newTargetValue) .. ' job ID#: ' .. lul_job .. " received data: " .. lul_data)
 
     -- 4 = jobDone
 
     -- 4 = jobDone
 
     -- nil = n/a on the timeout since the job is done
 
     -- nil = n/a on the timeout since the job is done
 
     -- true = the incoming data was for us
 
     -- true = the incoming data was for us
 
     return 4, nil, true
 
     return 4, nil, true
 +
 
end</source>
 
end</source>
  
Line 82: Line 93:
 
return values: lul_data,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.
+
When you call [[Luup_Lua_extensions#function:_register_handler|luup.register_handler]] 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.
 
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==
+
==<timed> (callback)==
  
 
variables: lul_data
 
variables: lul_data
Line 92: Line 103:
 
return values: none
 
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.
+
When you pass a Lua function to be called at a later time with [[Luup_Lua_extensions#function:_call_delay|luup.call_delay]] or [[Luup_Lua_extensions#function:_call_timer|luup.call_timer]], the function is called with the data (a string) you past.
  
==<watch> callback==
+
==<watch> (callback)==
  
 
variables: lul_device, lul_service, lul_variable, lul_value_old, lul_value_new
 
variables: lul_device, lul_service, lul_variable, lul_value_old, lul_value_new
Line 100: Line 111:
 
return values: none
 
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.
+
When you watch a variable with [[Luup_Lua_extensions#function:_variable_watch|luup.variable_watch]], and the variable changes, your callback is called with the information on the variable that changed.
  
 
==<startup>==
 
==<startup>==
Line 108: Line 119:
 
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
 
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'
+
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: <source lang="lua">return false,'Cannot get state','gc100'</source> or <source lang="lua">return true,'ok','gc100'</source>
  
 
==<ir>==
 
==<ir>==
 +
There are two parts to the equation here:
 +
# the device holding the IR codes for all the different IR commands to be used
 +
# 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.
  
A pronto code is placed between the <ir> tags. Executing the action will transmit the ProntoCode via the associated IR device. Refer to [[Luup_IR]]
+
Refer to [[Luup_IR]] also.

Latest revision as of 12:57, 16 June 2017

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:3480/data_request?id=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.

Contents

[edit] <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

[edit] <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:

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

[edit] <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

[edit] <timeout>

variables: same as for job above.

return value: same as for job above

[edit] <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

[edit] <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.

[edit] <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.

[edit] <request>

variables: lul_request,lul_parameters,lul_outputformat

return values: lul_data,lul_outputformat

When you call luup.register_handler 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.

[edit] <timed> (callback)

variables: lul_data

return values: none

When you pass a Lua function to be called at a later time with luup.call_delay or luup.call_timer, the function is called with the data (a string) you past.

[edit] <watch> (callback)

variables: lul_device, lul_service, lul_variable, lul_value_old, lul_value_new

return values: none

When you watch a variable with luup.variable_watch, and the variable changes, your callback is called with the information on the variable that changed.

[edit] <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'

[edit] <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.

Personal tools