Apps.mios Developer's Guide

From MiOS
(Difference between revisions)
Jump to: navigation, search
(Documentation)
(Add Release)
 
(34 intermediate revisions by 5 users not shown)
Line 1: Line 1:
apps.mios.com contains a plugin creation wizard that aims to make the plugin creation process easier.
+
'''[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==
+
== Documentation ==
The plugin which will be used as an example in this documentation is the Elk Alarm Panel Plugin.
+
This plugin has 8 files:
+
  
These files are for the panel itself:
+
=== Plugin Info ===
* D_ElkAlarmPanel1.xml
+
* D_ElkAlarmPanel1.json
+
  
These files are for the partitions:
+
==== Plugin Information  ====
* D_ElkAlarmPartition1.xml
+
* D_ElkAlarmPartition1.json
+
  
These are the implementation files, which are used for both the panel and the partitions:
+
*Description: The description that will appear next to the title in the Marketplace.
* I_ElkAlarmPanel1.xml
+
*Instructions URL: URL to the documentation page of this plugin, which should contain instructions for plugin configuration and usage notes.
* L_ElkAlarmPanel1.lua
+
*Visibility: For plugins intended to be made available to the public, the visibility should be '''''public'''''. '''<span style="color: rgb(255, 0, 0);">Note:</span>'''<span style="color: rgb(255, 0, 0);"> the other visibility types are not implemented yet.</span><br>
 +
*License: [http://en.wikipedia.org/wiki/Gpl GPL3], [http://en.wikipedia.org/wiki/BSD_licenses BSD], [http://en.wikipedia.org/wiki/Proprietary_software proprietary]
  
The are the service description files for the panel and the partitions:
+
==== UPnP Data ====
* S_ElkAlarmPanel1.xml
+
* S_AlarmPartition2.xml
+
  
 +
This is the necessary information for creating the plugin device.&nbsp; If your plugin will have more than one device file, MiOS will use the information here to create the main plugin device.&nbsp; For the ''Elk Alarm Panel Plugin'' the main device is the panel device.
  
===Plugin Info===
+
[[Image:UPnP Data.png]]  
====Plugin Information====
+
* Description: The description that will appear next to the title in the Marketplace.
+
* Instructions: Instructions for installing and configuring the plugin. Some plugins require additional steps for installation, steps which should be documented here.
+
* Visibility: For plugins intended to be made available to the public, the visibility should be ''public''.
+
* 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====
+
=== UPnP ===
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]]
+
==== Plugin Devices ====
  
===UPnP===
+
*The first three fields are the ones from UPnP Data.&nbsp; This is the necessary information for creating the plugin device.&nbsp; If your plugin will have more than one device file, MiOS will use the information here to create the main plugin device.&nbsp; For the ''Elk Alarm Panel Plugin'' the main device is the panel device.  
====Plugin Devices====
+
*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.
* 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===
+
<br>
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.
+
  
[[Image:Plugin_Files]]
+
=== Plugin Files  ===
 +
 
 +
Here you can add, remove, edit, upload and download the files used by the plugin.&nbsp; This is an interface for the SVN repository where the files are stored.&nbsp; To revert the files to a previous version, open the log and select which version to revert to.
 +
 
 +
<span style="color: rgb(255, 0, 0);">'''IMPORTANT:''' </span>When you add .lua files to the plugin, add them as '''Miscellaneous files'''.&nbsp; 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.
 
Pressing the Edit button will open the editor. For the device, service and implementation files there are wizards available for editing the files.
  
===Versions===
+
=== Versions ===
====Releases====
+
 
This is the list with all the released or pending for approval plugin versions.
+
==== Releases ====
====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.
+
This is the list with all the released or pending for approval plugin versions.  
* 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.
+
==== Add Release ====
 +
 
 +
*Platform: Leave '''Any'''.
 +
*Compatible firmware: Leave the fields '''empty'''.
 +
*Dev, Alpha, Beta, RC: these are some of the software development phases. Only '''RC (Release Candidate)''' versions can be submitted for approval. <span style="color: rgb(255, 0, 0);">'''Note:''' the other release types are not implemented yet.</span><br>
  
 
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).
 
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 ====
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.
+
 
 +
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.
 +
 
 +
<span style="color: rgb(255, 0, 0);">'''Note:''' The path '''must''' start and end with ''''/''' '.</span>
 +
 
 +
e.g. If I want a file to go in ''/www/cmh/skins/default/icons'', the path will be: '''''/../../www/cmh/skins/default/icons/'''''
 +
<br>
 +
<br>
 +
== 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.
 +
<br>
 +
 
 +
== 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:
  
====Publish====
+
http://VERA_IP/port_3480/data_request?id=action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=CreatePlugin&PluginNum=1448&Version=7768
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.
+
  
==New JSON tags==
+
[[Category:Plugins]]
* ui5_x, ui5_y: When in root, these tags represent the device box dimensions. 1x = 100 pixels, 1y = 24 pixels.
+
[[Category:Development]]
When in ControlGroup, these represent the control's position in the box.
+
* ui5_onDashboard: If the value is "1" the device is pinned on the dashboard at creation.
+
* ui5_inScene: If the value is "1" the device is displayed in the scene creation wizard.
+
* ui5_sceneGroup: This defines how this box is displayed in the scene creation wizard.
+

Latest revision as of 08:25, 9 January 2018

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

Contents

[edit] Documentation

[edit] Plugin Info

[edit] 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: GPL3, BSD, proprietary

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

UPnP Data.png

[edit] UPnP

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


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

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.

[edit] Versions

[edit] Releases

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

[edit] Add Release

  • Platform: Leave Any.
  • Compatible firmware: Leave the fields empty.
  • 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).

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

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

[edit] Steps for releasing a plugin

  1. After you created the plugin and uploaded the files, open the Versions page.
  2. 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.
  3. 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.
  4. In the Releases box click on Request approval.
  5. 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.


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

  1. 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:
    Plugin number.png
  2. Open the Versions page.
    Versions button.png
  3. In the Versions section of the page, click the Show files button next to the version you want to install.
    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