Mac Home Automation

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.

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.

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”

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“

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

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”

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.

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.

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

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

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.

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.

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.

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.

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:

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.

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.

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.

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.

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

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.

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.

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”

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

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.

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.

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

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

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.

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.

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.

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: Plugin API: File Structure NEXT: Plugin API: info.json Defining Unit Types