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: info.json and Communication Settings=====
The info.json file contains all the information necessary to load your script files, provide the basic communications, defines the unit types that your plugin can create and defines the dynamic interfaces that can be displayed. There are many keys into this JSON structure but there is no ability in the JSON definition to include comments along with the data so the various keys and an explanation of their use is included here along with an example configuration file.

==script==
REQUIRED: (string) The scripting language that the plugin is written in. As of plugin API version 1 the only supported value for this key is “python2” Since Python 2.7 is by default included with MacOS this version was chosen as it doesn’t require the user to do an install of python 3 separately. If Apple ever includes the newer versions we will update the API to support that as well. I will also consider other options for other scripting languages. Currently on my list for future consideration are Javascript and Lua. If those are things you’d like to see please let me know.

==name==
REQUIRED: (string) The name of the plugin that will be displayed in the popup of available interface types. This should be a short name ie: "XTension Dimmer Kit" or "Some Temp Sensor"

==tag==
REQUIRED: (string) The tag is a short string used by the program to identify items belonging to this  plugin. It should be a short unique string. It must be unique so you should consider  using standard bundle naming conventions. ie: “com.sentman.xtDimmerKit"

==isf==
REQUIRED: (string) The folder name that the plugin files live in.

==module==
REQUIRED: (string) The name of the script file to load from inside the isf folder. In the case of the python plugin this should be the name of the myPlugin.py file that is the main entry point for your plugin but without the file extension. So if your file name was  myPlugin.py you would enter just “myPlugin"


==desc==
OPTIONAL: (string) A short description of the plugin or the device it supports. This is shown  in parans next to the name of the plugin in the popup to give the user a quick  idea of just what your plugin does. This needs to fit in a reasonable space after the   name in the popupmenu so should not be long winded. Use the "info" key for a longer  description.

==info==
OPTIONAL: (string) Optional but should always be included. A 2 or 3 line long description of the plugin  that is displayed in the edit interface dialog when the plugin is actually selected  from the popup.

==wiki==
OPTIONAL: (url) if your plugin has a page on the MacHomeAutomation.com wiki you should  place a link to it in this field.

==link==
OPTIONAL: (url) if your plugin has a web page elsewhere, or can link to a device  manufacturer that url should be included here.

==vers==
REQUIRED: (integer)  the internal version or build number of your plugin. This should  be an integer. You may also include a user readable one with more dots (ie: 7.6.54.332)  in the next key. This is used to compare against the current available version to  determine if an offer to upgrade should be made.

==readableVers==
OPTIONAL: (string) a more human readable version string like 6.5.4 or 4.5.6.334.234  or whatever you would like to present to the user.

==checkVersLink==
OPTIONAL: (url) a link to a JSON file on your server that contains the current and   previous version information. XTension will access this on startup and once a week if that option is selected to see if there is an update for your plugin and offer  to download and install it. NOTE that this is unimplemented as of XTension 9.3.1 but will be implemented in a future version. A description of that JSON file contents will be available before that feature is released.

==APIVersion==
REQUIRED: (integer) the API version that is required to run your plugin. We are currently at API version 1. XTension may be able to support older API versions if called for by a plugin, but plugins that require a newer version will refuse to load and log an error.

===Connection Control===
The plugin host can handle simple communications via an outgoing TCP port or serial  port for you and even simple parsing of some messages. If you can connect to your   device in this way then no networking code needs to be written in the script at all  simplifying the process of creating the connection. To the plugin host there is no   difference between a serial port or a TCP connection so ethernet/serial adaptors   can be swapped in transparently with no changes to your code for remotely accessing  relocated devices. The following keys describe the interface and communications settings:

==allowNone==
OPTIONAL: (boolean) defaults to false. If your plugin does not require normal  networking setup, or can function without it you can allow the selection of   "None" from the communications popup. You can also force this to be selected and   the only selection available by specifying the portSelectNone key below.

==portSelectNone==
OPTIONAL: (boolean) if present and set to true the communications popup will be  forced to select None and then disabled so that no other communications options  can be selected.

==allowTCP==
OPTIONAL: (boolean) defaults to True. Allows for the opening of an outgoing TCP  connection. If absent or present and True this will allow the selection of   "Remote IP Address" as a connection type. If present and false then the option of   selecting this will be greyed out. When this option is selected an extra interface  element will be added allowing for the entry of a DNS name or IP address  and a port number.  If your device can only be connected to over TCP you may   specify the "portSelectOutgoing" option below.

==portSelectOutgoing==
OPTIONAL: (boolean) if present and True the communications selection popup will be  forced to select "remote tcp connection" and then disabled so that no other comm  type can be selected by the user.

==defaultPort==
OPTIONAL: (integer) if included then this will be offered as the pre-filled in   value in the TCP connection Port field. 

==allowSerial==
OPTIONAL: (boolean) defaults to True. Allows the selection of available serial  ports found on the machine for your connection. If included and False the serial  port portion of the port popup will be greyed out. If you include the ability to  open a serial port you must include the baud rate setting below so that the port  can be properly opened.

==baud==
REQUIRED if AllowSerial: (integer) defaults to 9600. If you allow the selection of  a serial port then you must provide the baud rate at which you want the port to be  opened for you. Like TCP connections the port management can be handled in the plugin  host and no low level serial work has to be done in the plugin code if you don't  wish to.  recognized values are: 300, 600, 1200, 1800, 2400, 3600, 4800, 7200, 9600,  14400, 19200, 28800, 38400, 57600, 115200, 230400. If a value is found that is not  known then the default of 9600 will be used. Just because we have asked the port  to open at that baud rate doesn't mean that the usb/serial adaptor will support it.\\
\\
There are other serial port settings such as parity and flow control and enabling of the dtr line that can be added to a future version. If your device needs this please let me know.

==packetBoundry==
OPTIONAL: (formatted string, see below) If the device you're talking to uses a simple  protocol with a known packet boundary then the plugin host can handle managing the buffer.  It will send already parsed packets to the scripts dataAvailable event. If this is   omitted then the dataAvailable event will be called with each read of data from the  low level port, be it TCP or Serial and any buffering and parsing will be up to you  in your own code. The packet boundary string is a space separated list of string  segments or numerical entries to denote non-printable characters. Decimal numbers can  be entered as they are, hex numbers should be prefixed with "&h" for example, if  your packet boundary is the word END with a new line and then carriage return  you would enter: "END 10 13" or "END &h0A &h0D" if the packet delineator was just a  carriage return you could enter just "13"

===Accepting Incoming Connections===
Incoming connection support is not enabled in XTension 9.3.1 but will appear in a not too distant future release.

==TCPListen==
OPTIONAL: (boolean) defaults to false. If present and true the user will have the   option of selecting "Listen for incoming TCP Connections" from the communications  popup. Once selected an additional interface to set up an incoming networking  system will be displayed. If your plugin can communicate only by incoming connections  then you should specify the "portSelectIncoming" parameter below.

==portSelectIncoming==
OPTIONAL: (boolean) if present and True the communications popup will be forced to   select "Listen for incoming TCP connections" and then disabled so that the user cannot  select any other method of communications.

==defaultPort==
OPTIONAL: (integer) if present this will be filled in to the port field for the incoming  communication field.

==allowTCP==
OPTIONAL: (boolean) defaults to True. If your interface needs to accept incoming TCP  communications this should be left out or set to true.

==allowUDP==
OPTIONAL: (boolean) defaults to False. If your inteface needs to accept UDP packets on the  specified port you should include this parameter as True. Each packet received will be   a single call to dataAvailable. You will be responsible for any protocol management or   packet fragmentation that might occur. 

==allowBonjour==
OPTIONAL: (boolean) defaults to True. Allows for you to register a bonjour, zero-conf or   mDNS name on the local network making it easier to find. 

==defaultBonjourName==
OPTIONAL: (string) if present this will be offered as the default Bonjour name for the  service you are registering. This is the DNS name that other devices will use to find  your server.

==defaultBonjourService==
OPTIONAL: (string) though optional you should definitely include this. This is the  default service name for the bonjour so that anyone searching for a specific type of   service can find you and the port you're operating on. This must be what the clients   expect or your service will not be found, don't leave it up to the user entirely.  ie: "_http._tcp."

PREVIOUS: [[plugins:01_files|]] NEXT: [[plugins:03_units|]]
Mac Home Automation

User Tools

Site Tools

Page Tools
