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.
=====Plugin API: v2=====

XTension provides an extensive API for creating plugins. The currently best supported platform is for Python3 but libraries exist for Xojo and some partially unfinished work was also done to support NodeJS plugins. 

=====Busy Units Example Plugin:=====
[[https://machomeautomation.com/files/api/busyunitsplugin.zip|Download the Busy Units Example plugin]] v1.0

This example plugin is written in Python and shows many of the basic techniques for basic plugin creation, info.json requirements, dynamic interface creation an unit management and creation. It will create 1 Unit in XTension and then update it ever few seconds to a new random value. It demonstrates updating Units in XTension as well as receiving commands from XTension to the Unit.

To install the demo plugin download and unzip the file linked above. Inside that you will find the xojo project for the dynamic interface creation, as well as the ‘busyunits.isf’ folder. In XTension pull down the Database menu item and select “Install Plugin” then select the “busyunits.isf” folder from the above. It will be copied to your current database folder and added to the list of available plugins. You can then create a new plugin instance and select “Busy Units Example Plugin” from the plugin popup. Once created you can enable it to start it running.

To make experimental changes to the python code pull down the Database menu in Xtension and select “Show plugin folder for this database” inside there you will find the busyunits.isf folder and inside that you’ll find the example info.json file and the busyunits.py file containing the python code. 

You can edit the python code in place and then disable and re-enable the interface in XTension to run the new code. Any errors or problems will be displayed in the log at startup. Making changes to the info.json file requires quitting and restarting XTension to make those live, editing the source code only requires disabling and re-enabling of the interface. 

To make changes to the dynamic interface elements of the example plugin you can either edit the json file manually, which is a huge pain, or use the Busy Units Interface Buildier Example file. This is a Xojo project. You will need to [[https://xojo.com/|download and install the Xojo IDE]] to use this. Since you only need to run it in debug mode you can use Xojo in it’s free mode. If you haven’t seen Xojo you should check it out as an excellent cross platform development system. Creating binary versions of your program for MacOS, Windows, Linux, Raspberry Pi, iOS and most recently Android platforms! You don’t need to know anything about that to use the example project. Make any changes to the layout in the Xojo IDe and run the app in debug mode. Bring the window you wish to save to the front and select Save from the File menu. It will copy the JSON descriptor for the interface you see in the window to your clipboard and then you can paste it into the info.json file over the current “editControls” list. make sure the JSON formatting is still valid, use an online json validator if you have any doubts, and then save it and restart XTension to make those changes live. There is more detailed explanations of how to use the plugin interface builder app coming in future articles.



=====Overview of Plugin Philosophy:=====

XTension embeds a version of python3 with binary libraries for both Intel and Apple Silicon chips. The plugins are not loaded directly into the XTension application, but run as separate processes. This way they better take advantage of multiple processor cores and system resources but cannot crash the host XTension application if they contain problems. The worst they can do is crash, write a bunch of errors to your log and then be restarted by XTension automatically to keep things going. Any python plugin and any requirements you bring along should be able to be run by the python version included which is currently 3.10. This way no requirement is made of the User to install python on the machine or perform pip installs of the required libraries and helpers. Your plugin should include everything necessary to run unless licensing issues make that impossible in which case clear instructions to the user as to what is needed should be provided.

Unless absolutely unavoidable no editing of configuration files should be required. Any interface data that is needed should be able to be set from the Dynamic Interface creation capabilities of XTension. These are a small subset of a fully implemented interface so if you find that other interface elements or functions are needed please let me know and they can probably be added. 

The settings entered in XTension, both in the overall plugin configuration window with your dynamic interface, as well as the settings entered by any dynamic interface needed for individual unit types are available to the plugin via the XTension object or for Units it’s data object. These structures in the plugin are kept in sync with the database in XTension and any changes to the values by the user in XTension are immediately synced and made available to the plugins, or if the plugin is not running they are saved and made available to the plugin the next time it is enabled.

Communiucations to XTension and several classes for providing local interfaces to XTension Units and other classes are provided by the xtension plugin include files. See the example plugin above for how to include those. Once you create an instance of the XTension class it will handle creating the correct type of pipe to send commands back and forth and you never have to worry about the low level protocols.

-----

A plugin is just a folder. By convention the folder name ends with a “.isf” as a suffix that originally stood for “Internal Service Function” Plugins installed by the User are placed in the Xtension Database in a folder just called “Plugins” you can most easily get to this using the Database menu in XTension and selecting “Reveal Plugin Folder In This Database” The database will be opened in the Finder and the Plugins folder highlighted. Plugins that are part of the standard XTension distribution are included inside it’s application bundle but are otherwise identical and use the same API as documented here.

Inside that folder the requirements are at least, an info.json file that describes the plugin and it’s interfaces as well as at least one python source file that is pointed to by the info,json file. You can also supply compiled python caches to speed up loading, any python includes that are needed by your plugin but not already available in the default included items, and any other resources your plugin needs to run. A list of all the default included python libraries is forthcoming.


To install a downloaded or user created plugin, pull down the Database menu and select “Install Plugin...” then select the pluginname.isf folder. XTension will copy everything in that folder to the Databases Plugins folder and load the plugin making it available to be used in the Interface Status window.


=====The Info.json File=====
Every plugin must include a file named “info.json”. This is where the plugin is described and the binary or python source is linked to. Any unit types the plugin will create are described here. Any interfaces custom to either the plugin itself or the individual units are also included here. These can be more easily created with the Dynamic Interface Builder project, a detailed description of using this is forthcoming.

Please visit the next page for detailed info on the Info.json file: Next: [[pluginapi:infojson|The info.json file]].