Mac Home Automation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====The XTension Plugin API v2=====

**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. (6/6/2023)
\\
\\

Introduced in XTension version 9.3 you can now create new plugins for otherwise unsupported devices using Python 3. The plugins run as separate processes and communicate to XTension through a TCP socket or other appropriate pipe. All direct communications of the low level protocol are handled by the plugin include files to abstract you from that, but are documented in the appendix if you need to refer to them. 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.


====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 a plugin unit” to doSomethingPluginSpecific( withSomeData)

tell xInterface “name of the plugin instance” to doAPluginTask( withSomeData)
</code>


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