Differences

This shows you the differences between two versions of the page.

--- plugins [2017/06/10 16:09] – external edit 127.0.0.1
+++ plugins [2018/08/11 16:02] – James Sentman
@@ Line 1: / Line 1: @@
-=====The XTension Plugin API=====
+=====The XTension Plugin API v2=====
-Download sample plugin [[http://machomeautomation.com/files/xtensiondimmer6.zip|6 Channel PWM Dimmer Kit Driver]]\\
+**NOTE:** This documentation is in a transitional phase of updating from v1 to v2 of the plugin API. Please contact me for more info if you need to work on a plugin while I’m updating the docs. (8/11/2018)
 \\
-Introduced in XTension version 9.3 you can now create new interfaces for otherwise unsupported devices using the Python language. For most types of communications via TCP sockets or Serial Ports the communication can be completely handled by the host application allowing you to concentrate on handling the actual logic of talking to the device. For simpler protocols that have an end of line at the end of each packet the host can do the parsing for you sending your script individual packets. In the case of more complex protocols the parsing of the data will be up to your script. \\
 \\
-Complex dynamic interfaces can be defined in 4 different places. Firstly on the interface level you can create a custom interface for interface level controls. These are things for the device itself and not the individual units associated with it. Here is the custom interface associated with the XTension 6 Channel PWM dimmer kit:
-{{ :plugin_interface_example.png?400 |}}\\
-For Unit level configuration you can embed configuration for individual controls on the first tab of the [[xtension_manual:editunitdialog|Edit Unit]] dialog. In this example the GPIO Type popup shown below is defined by the plugin.\\
-{{ :unit_dynamic_interface.png?400 |}}\\
-Lastly there are 2 hooks for creating custom control interfaces. Every unit line in XTension can bring up a HUD style control window. There are 2 different HUD windows, for simple control as well as “advanced” control. A plugin can define separate interfaces for both the Simple and Advanced windows. In this example you’re seeing the RGB color looping controls which are similar on both windows but can be completely different or even absent on one or the other window.\\
-{{:plugin_advanced_hud.png?200|}} {{:plugin_small_hud.png?200|}}
-\\
-For less used control options your plugin may also define contextual menus for each unit type that will call back into the plugin script. In this case I’ve defined 2 contextual menu options for Start Color Loop and Stop Color Loop. They are available when control or right clicking on a unit in any unit list and also from the gear icon in both HUD control displays.\\
-{{:plugin_contextual_menu.png|}} {{:plugin_hud_contextual_menu.png|}}\\
-Lastly you can also define methods of your Python script to expose to the in application AppleScript system. At a point in the future when we expand the in system scripting to include python or other options those same methods will be available to them as well. Currently you can execute any defined Python function from AppleScript in 2 places. At the Interface level and at the Unit level. For an interface wide function use an applescript tell block to talk directly to the xInterface object:\\
-<code>
+Introduced in XTension version 9.3 you can now create new plugins for otherwise unsupported devices using Python. The plugins run as separate processes and communicate to XTension through a TCP socket. All direct communications and parsing of XTension packets are handled by the plugin include files so you don’t have to handle any of that. You can send commands to XTension to control units, update data or displays and the plugin classes provide events you can use to receive commands or be alerted to other changes to information.
-  tell xInterface “name of plugin interface” to doDefinedHandler( withData, andMoreData)
-</code>
-If your Python script defines a doDefinedHandler function it will be called and the passed data will be passed to it in the form of a tuple or python list.\\
+====Language Support====
-\\
+At this moment I have plugin connectors for Python and for [[http://xojo.com/|Xojo]]. All examples on this site are using python 2.7. I also have an alpha level build of the connectors for NodeJS though that is problematic due to the necessity of also having node js installed on the Mac in question. It may be an option if no python or other libraries are available for performing whatever you need to do. I have also documented the raw [[plugins:rawprotocol|XTension Interapplication Communications Protocol]] given that it should be possible to implement that in any modern language and provide a plugin in C++, Lua, PHP or whatever you prefer. Contact me if you wish the Xojo examples or want to discuss the implementation of a different language.
-The unit level access works the same way but you tell the specific xUnit object to execute the handler. In this case in addition to the list of data that is supplied with the function call the units address, address prefix, unique ID and current level will be included in the passed data so that you can decide what action to take based on the call.
+====Plugin Custom Interfaces====
+You can create plugin interfaces in the Edit Interface dialog for individual interface level settings. You can add controls to the Edit Unit dialog for unit level interfaces and you can also add controls to the advanced and simple unit control popups for actually sending commands to a unit. All controls are defined in the info.json file that must accompany the application. You can create them by hand or better yet using the interface builder app linked to in that section of the wiki. On my todo list are other places that interfaces can be inserted and popped up in response to other actions. If anything like that would be helpful please let me know and I can bump them up the priorities list.
+While there is no current interface to creating plugin specific menu items beyond the contextual ones mentioned below, you can create a submenu in the Global Scripts menu and add items to that if you wish. This is the mechanism used in the Database Sharing when a global script is shared to a receiving XTension implementation. Your script can add items to this menu though the interface might be slightly confusing depending on what the script will be doing. Adding a plugin menu that you can add submenus to is also on my list, if that is something you need sooner please let me know.
+====Plugin Units vs Database Sharing====
+There are 2 modes that a plugin can operate in. The regular mode is for providing an interface to some physical device. This lets you create units in XTension that are linked to a specific plugin instance. You do not have access to the rest of the database but can only control your units.
+You can add the Database Sharing option to your info.json file and in that case the user will be presented with options for choosing what units will be sent to your interface instance. This is for plugins that might wish to provide a bridge to some other functionality like sharing units to an Alexa or HomeKit or just creating a PubSub or MMQT interface to portions of the database. As of V2.0 of the API you can ask for Units and Global Scripts to be shared. The user will be able to select either to share the entire database or to select from lists of Units and select individual Global Script. This is the interface that is used for the built in [[supported_hardware:databasesharing|Database Sharing]] plugin.
+====Sharing well known ports or UDP sockets with other plugins====
+This is particularly a problem with programs that want to respond to or listen for things like UPNP packets. Only one program on a machine can be listening the specific UDP socket that UPNP happens over. XTension gets around this problem by providing for certain networking functions in the App itself. You can send commands to XTension that request a UDP port be opened and added to a broadcast group and then your app will receive any receptions of packets over the XTension API and so will any other plugins that have asked for that particular socket or broadcast group. You can also broadcast packets the same way by wrapping them in a command to XTension. This way many plugins may service different kinds of UPNP devices, or even provide UPNP sharing of XTension units.
+====Contextual Menu Handlers====
+You can add contextual menu handlers to any unit through your plugin. You can define these in the info.json handler for the specific unit type. When the user selects them an execute handler command will be sent to your plugin with the name of the function selected. These menu items are also available as buttons in the advanced unit control windows though I may separate the two things in a future API version.
+====Adding Script Commands====
+While Python is used for plugin development, internal to XTension AppleScript is used as the scripting language. XTension supports the AppleScript Object Model and any unit may be wrapped in a tell block. There are many commands and settings that can be sent to a unit this way. Any commands received through such a script that are not one of the reserved commands or well known handlers that are built into XTension will be sent to the Units On script. The user can create their own handlers there to extend functionality themselves. Any handler request that is not handled by the unit’s ON script will be forwarded to the plugin instance that the unit belongs to. These events can be trapped in your subclass of the xtUnit object of your plugin code. The same mechanism is used for Interface level scripting. If the Interface object in XTension is told to do something and the handler name is not a known command then the request to handle it is passed to the AppleScript attached to the Interface. If the command is not handled there by the user then it will also be forwarded to the plugin code. You can trap those in a similar way by adding a handler to the root XTension object. This enables you to extend the scripting dictionary by doing something like:
 <code>
-  tell xUnit “name of plugin unit” to doPythonHandler( withData, andMoreData)
+tell xUnit “name of a plugin unit” to doSomethingPluginSpecific( withSomeData)
+tell xInterface “name of the plugin instance” to doAPluginTask( withSomeData)
 </code>
-\\
-This should provide a plugin interface and it’s associated unit types to operate fully on par with built in XTension devices and fully support any and all functions that you would wish to implement.\\
+====Installing and Un-Installing Plugins====
-\\
+XTension provides a mechanism to install a plugin. Once the user has downloaded your plugin file and decompressed it or mounted the disk image they can select “Install Plugin” from the Database menu. That will open a select folder dialog which they can use to select your plugin folder. XTension will copy the folder into the Plugins folder in the database and load all it’s info.json file so that it will be available in the popup of interface types in the Edit Interface window. If the user us upgrading a plugin the older version will be moved to the trash and replaced with the new folder. Any interfaces that are currently running that older version will be recycled so that they come back up with the new version.
+The XTension interface to managing plugins is a work in progress, there is no way as of 9.4.8 to check plugins for available updates or to install or remove them. To remove a plugin select “Reveal Plugins Folder In This Database” from the Database menu and the database bundle will be opened and the Plugins folder within it highlighted. Drag the plugin you wish to remove out of that folder to the trash. Then delete any configured instances of that plugin.
+====Blocking and Non-Blocking Functions====
+Since the plugin runs as a separate process from XTension you can use any combination of blocking or threaded operations without worrying about blocking the host app. If you perform a blocking action in response to a received command from XTension that should be bumped out to a separate thread to await it’s return. XTension will regularly send a ping to your interface that needs to be returned or it will recycle your interface thinking it had hung up. You should not block in any event received from XTension.
 NEXT: [[plugins:01_files|]]