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

**NOTE:** this is plugin API version 1 and is deprecated. Version 2 of the plugin API will be included in XTension version 9.3.4. If you have done any work with this API please contact us and I will help you convert to the new API. The new protocol solves all the problems with threading and other concurrency that this first API suffered from. If you are about to being a project please contact me first as well. The JSON layout and interface systems are the same as well as the constants for getting data out of the XTension Unit dictionaries. The commands to XTension have not changed but the method of receiving updates from XTension has changed significantly.\\
\\

Download sample plugin [[http://machomeautomation.com/files/xtensiondimmer6.zip|6 Channel PWM Dimmer Kit Driver]]\\
\\

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

<code>
  tell xUnit “name of plugin unit” to doPythonHandler( withData, andMoreData)
</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.\\
\\
NEXT: [[plugins:01_files|]]
Mac Home Automation

User Tools

Site Tools

Page Tools
