'''[http://apps.mios.com apps.mios.com]''' is the new MiOS plugins marketplace for plugins compatible with UI5+. It allows developers to easily create and publish their plugins.

== Documentation ==

=== Plugin Info ===

==== Plugin Information ====

*Description: The description that will appear next to the title in the Marketplace.
*Instructions URL: URL to the documentation page of this plugin, which should contain instructions for plugin configuration and usage notes.
*Visibility: For plugins intended to be made available to the public, the visibility should be '''''public'''''. '''Note:''' the other visibility types are not implemented yet. 
*License: [http://en.wikipedia.org/wiki/Gpl GPL3], [http://en.wikipedia.org/wiki/BSD_licenses BSD], [http://en.wikipedia.org/wiki/Proprietary_software proprietary]

==== UPnP Data ====

This is the necessary information for creating the plugin device.  If your plugin will have more than one device file, MiOS will use the information here to create the main plugin device.  For the ''Elk Alarm Panel Plugin'' the main device is the panel device.

[[Image:UPnP Data.png]]

=== UPnP ===

==== Plugin Devices ====

*The first three fields are the ones from UPnP Data.  This is the necessary information for creating the plugin device.  If your plugin will have more than one device file, MiOS will use the information here to create the main plugin device.  For the ''Elk Alarm Panel Plugin'' the main device is the panel device.
*Invisible: An invisible device is ''for internal use only'' and won't be presented to the user. An example for this is the ''Insteon Network'' device.

 

=== Plugin Files ===

Here you can add, remove, edit, upload and download the files used by the plugin.  This is an interface for the SVN repository where the files are stored.  To revert the files to a previous version, open the log and select which version to revert to.

'''IMPORTANT:''' When you add .lua files to the plugin, add them as '''Miscellaneous files'''.  Do not add them as Lua files because if you do, LuaUPnP will load them into their lua state and run them as stand alone files in addition to merging them into the implementation.

[[Image:Apps mios plugin files.png]]

Pressing the Edit button will open the editor. For the device, service and implementation files there are wizards available for editing the files.

=== Versions ===

==== Releases ====

This is the list with all the released or pending for approval plugin versions.

==== Add Release ====

*Platform: The target platform for the plugin. While most plugins will very likely target all the platforms, some plugins need separate versions for different platforms.
*Compatible firmware: Some plugins require features present only in newer firmwares versions to run. Others did things that were later incorporated in MiOS, so are now obsolete. These versions must be specified here.
*Dev, Alpha, Beta, RC: these are some of the software development phases. Only '''RC (Release Candidate)''' versions can be submitted for approval. '''Note:''' the other release types are not implemented yet. 

After the version has been added to the Releases list, RC versions can be submitted for approval. Someone from Mi Casa Verde will have a look at the plugin and check for malicious code, and test it a little to make sure that it doesn't affect the stability or proper functioning of MiOS. If everything is OK, the plugin will be approved and it will become available to install for the targeted public (selected in the ''Visibility'' drop-down).

==== Versions ====

Versions are snapshots of the plugin, i.e. how the plugin looked at a particular SVN revision. It's recommended to create a version for every milestone or development phase reached, so that you can go back to it if something went wrong in the subsequent revisions.

==== Publish ====

Here you can publish the plugin in its current state and assign it a version. The comments will be added after the version so that you can create versions like ''1.4 Holiday Edition''. If a file contains sensitive data (e.g. a PIN code) it is recommended to encrypt it.

The '''Destination path''' is were the file will be downloaded on Vera. The path is relative to '''/etc/cmh-ludl''', which is the default path.

'''Note:''' The path '''must''' start and end with ''''/''' '.

e.g. If I want a file to go in ''/www/cmh/skins/default/icons'', the path will be: '''''/../../www/cmh/skins/default/icons/'''''
 
 
== Steps for releasing a plugin ==

#After you created the plugin and uploaded the files, open the '''Versions''' page.
#On the bottom of the page enter the ''Major'' version number, the ''Minor'' version number and optionally a version ''comment'', then click '''Publish'''. The published version will appear in the ''Versions'' box.
#In the '''Add Release''' box select the published version from the '''RC''' drop-down list. Leave ''Platform'' to ''Any'', and the ''Compatible firmware'' fields empty. Click '''Add Release'''. The release will appear in the ''Releases'' box.
#In the '''Releases''' box click on '''Request approval'''.
#Someone from MiOS will check the plugin for malicious code or poorly written code that will affect the Vera stability, and if everything is OK it will be approved.
 

== How to install an unreleased plugin version on UI7 ==

On UI7 it's not possible to install an unreleased plugin version directly from apps.mios.com.

However, it's possible to install a specific plugin version on your Vera by using the CreatePlugin action documented on [[Luup UPnP Variables and Actions|this page]].

http://VERA_IP/port_3480/data_request?id=action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=CreatePlugin&PluginNum=PLUGIN_ID&Version=VERSION_ID

To get the plugin ID and the version ID, follow these steps:

# Go to apps.mios.com and edit your plugin (press the '''Edit''' button on the '''My plugins''' page).
#: The plugin ID can be found at the top of the page:
#: [[File:plugin_number.png]]
# Open the '''Versions''' page.
#: [[File:versions_button.png]]
# In the '''Versions''' section of the page, click the '''Show files''' button next to the version you want to install.
#: [[File:show_files_button.png]]
#: The ID of the version can be found in the URL:
#:: http://apps.mios.com/download-plugin.php?PK_Version=7768
#: The ID of the version is ''7768''.

The command for installing the plugin will be:

http://VERA_IP/port_3480/data_request?id=action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=CreatePlugin&PluginNum=1448&Version=7768

[[Category:Plugins]]
[[Category:Development]]

Apps.mios Developer's Guide

2018-01-05T07:58:45Z

Mcvflorin: /* How to install an unreleased plugin version on UI7 */

'''[http://apps.mios.com apps.mios.com]''' is the new MiOS plugins marketplace for plugins compatible with UI5+. It allows developers to easily create and publish their plugins.

== Documentation ==

=== Plugin Info ===

==== Plugin Information ====

*Description: The description that will appear next to the title in the Marketplace.
*Instructions URL: URL to the documentation page of this plugin, which should contain instructions for plugin configuration and usage notes.
*Visibility: For plugins intended to be made available to the public, the visibility should be '''''public'''''. '''Note:''' the other visibility types are not implemented yet. 
*License: [http://en.wikipedia.org/wiki/Gpl GPL3], [http://en.wikipedia.org/wiki/BSD_licenses BSD], [http://en.wikipedia.org/wiki/Proprietary_software proprietary]

==== UPnP Data ====

This is the necessary information for creating the plugin device.  If your plugin will have more than one device file, MiOS will use the information here to create the main plugin device.  For the ''Elk Alarm Panel Plugin'' the main device is the panel device.

[[Image:UPnP Data.png]]

=== UPnP ===

==== Plugin Devices ====

*The first three fields are the ones from UPnP Data.  This is the necessary information for creating the plugin device.  If your plugin will have more than one device file, MiOS will use the information here to create the main plugin device.  For the ''Elk Alarm Panel Plugin'' the main device is the panel device.
*Invisible: An invisible device is ''for internal use only'' and won't be presented to the user. An example for this is the ''Insteon Network'' device.

 

=== Plugin Files ===

Here you can add, remove, edit, upload and download the files used by the plugin.  This is an interface for the SVN repository where the files are stored.  To revert the files to a previous version, open the log and select which version to revert to.

'''IMPORTANT:''' When you add .lua files to the plugin, add them as '''Miscellaneous files'''.  Do not add them as Lua files because if you do, LuaUPnP will load them into their lua state and run them as stand alone files in addition to merging them into the implementation.

[[Image:Apps mios plugin files.png]]

Pressing the Edit button will open the editor. For the device, service and implementation files there are wizards available for editing the files.

=== Versions ===

==== Releases ====

This is the list with all the released or pending for approval plugin versions.

==== Add Release ====

*Platform: The target platform for the plugin. While most plugins will very likely target all the platforms, some plugins need separate versions for different platforms.
*Compatible firmware: Some plugins require features present only in newer firmwares versions to run. Others did things that were later incorporated in MiOS, so are now obsolete. These versions must be specified here.
*Dev, Alpha, Beta, RC: these are some of the software development phases. Only '''RC (Release Candidate)''' versions can be submitted for approval. '''Note:''' the other release types are not implemented yet. 

After the version has been added to the Releases list, RC versions can be submitted for approval. Someone from Mi Casa Verde will have a look at the plugin and check for malicious code, and test it a little to make sure that it doesn't affect the stability or proper functioning of MiOS. If everything is OK, the plugin will be approved and it will become available to install for the targeted public (selected in the ''Visibility'' drop-down).

==== Versions ====

Versions are snapshots of the plugin, i.e. how the plugin looked at a particular SVN revision. It's recommended to create a version for every milestone or development phase reached, so that you can go back to it if something went wrong in the subsequent revisions.

==== Publish ====

Here you can publish the plugin in its current state and assign it a version. The comments will be added after the version so that you can create versions like ''1.4 Holiday Edition''. If a file contains sensitive data (e.g. a PIN code) it is recommended to encrypt it.

The '''Destination path''' is were the file will be downloaded on Vera. The path is relative to '''/etc/cmh-ludl''', which is the default path.

'''Note:''' The path '''must''' start and end with ''''/''' '.

e.g. If I want a file to go in ''/www/cmh/skins/default/icons'', the path will be: '''''/../../www/cmh/skins/default/icons/'''''
 
== Steps for releasing a plugin ==

#After you created the plugin and uploaded the files open the '''Versions''' page.
#On the bottom of the page enter the ''Major'' version number, the ''Minor'' version number and optionally a version ''comment'', then click '''Publish'''. The published version will appear in the ''Versions'' box.
#In the '''Add Release''' box select the published version from the '''RC''' drop-down list and optionally select a ''Platform'' and enter a ''Compatible firmware''. Click '''Add Release'''. The release will appear in the ''Releases'' box.
#In the '''Releases''' box click on '''Request approval'''.
#Someone from MiOS will check the plugin for malicious code or poorly written code that will affect the Vera stability, and if everything is OK it will be approved.
 
== How to install an unreleased plugin version on UI7 ==

On UI7 it's not possible to install an unreleased plugin version directly from apps.mios.com.

However, it's possible to install a specific plugin version on your Vera by using the CreatePlugin action documented on [[Luup UPnP Variables and Actions|this page]].

http://VERA_IP/port_3480/data_request?id=action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=CreatePlugin&PluginNum=PLUGIN_ID&Version=VERSION_ID

To get the plugin ID and the version ID, follow these steps:

# Go to apps.mios.com and edit your plugin (press the '''Edit''' button on the '''My plugins''' page).
#: The plugin ID can be found at the top of the page:
#: [[File:plugin_number.png]]
# Open the '''Versions''' page.
#: [[File:versions_button.png]]
# In the '''Versions''' section of the page, click the '''Show files''' button next to the version you want to install.
#: [[File:show_files_button.png]]
#: The ID of the version can be found in the URL:
#:: http://apps.mios.com/download-plugin.php?PK_Version=7768
#: The ID of the version is ''7768''.

The command for installing the plugin will be:

http://VERA_IP/port_3480/data_request?id=action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=CreatePlugin&PluginNum=1448&Version=7768

[[Category:Plugins]]
[[Category:Development]]

File:Show files button.png

2018-01-05T07:55:28Z

Mcvflorin:

File:Versions button.png

2018-01-05T07:54:24Z

Mcvflorin:

2017-06-16T12:39:16Z

Mcvflorin: /* (callback) */

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

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>==

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.

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

<source lang="lua">function SetTarget_run(lul_device, lul_settings)

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

end</source>

==<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 <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.

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''': 

<source lang="lua">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</source>

==<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 [[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''': 

<source lang="lua">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</source>

==<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 [[Luup_Lua_extensions#function:_call_delay|luup.call_delay]] or [[Luup_Lua_extensions#function:_call_timer|luup.call_timer]] (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 [[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>==

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:
# 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.

Refer to [[Luup_IR]] also.

Luup Declarations

2017-06-16T12:37:20Z

Mcvflorin: /* (callback) */

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

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>==

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.

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

<source lang="lua">function SetTarget_run(lul_device, lul_settings)

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

end</source>

==<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 <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.

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''': 

<source lang="lua">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</source>

==<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 [[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''': 

<source lang="lua">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</source>

==<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 [[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>==

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:
# 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.

Refer to [[Luup_IR]] also.