=====Plugin API: info.json and Communication Settings===== The info.json file contains all the information necessary to load your script files, describe the basic communications you wish XTension to provide an interface to, defines the unit types that your plugin can create and defines the dynamic interfaces that can be displayed. This is a list of the keys into the info.json file and some description of their use. Please note that these key names are case sensitive. ====Plugin Description Keys==== These keys should be at the top level of the JSON object to describe the plugin to XTension and to setup the kind of connection interface that XTension will display. XTension has a default portion of the config window that can be configured to display a list of available serial ports, an address/port entry field if you need to connect to a network connected device or an interface to setting up an incoming networking server if your app is going to wait for incoming connections. It can also be setup to display just “none” or any combination of the above if your plugin does not require any of that information. ===script=== REQUIRED: (string) The type of the script being run. Currently supported values are “python2” to execute a python2 plugin script or “binary” if you are providing a xojo compiled command line app. The python2 value though might be used for other scripting languages as it simply runs the referenced file. The first line of a python file should be a link to the python interpreter like: #!/usr/bin/python and the script file needs it’s executable bit set. ===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 “Super 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” All single word tag names are reserved for use internally by XTension. ===isf=== REQUIRED: (string) The folder name that the plugin files live in. Plugin folder names should not contain spaces and should end in .isf they should also follow a bundle naming convention like “james_xtDimmer.isf” All single word folder names are reserved for use by XTension. ===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. This is the file that is going to actually be run. In the case of a binary plugin type use the binaryName tag below. This tag is not required if you have set your script type to binary. ===binaryName=== Optional: (string) required only if your script type is binary. This is the name of the executable in the plugin folder to execute when the plugin instance is enabled. ===APIVersion=== REQUIRED: (integer) the API version that is required to run your plugin. As of XTension version 9.4.8 the only API version that is supported is 2. ===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. ===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. ===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. ===allowNone=== OPTIONAL: (boolean) defaults to false. If one of the options for your plugin’s networking or port connection is “none” then including this key as true allows “none” to be selected from the popup menu of ports and networking options. You can also force the selection to be only None if no other networking or port selection is necessary using the next key “portSelectNone" ===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. This would make sense for USB devices or for networking systems that use a broadcast system or similar things where no other config is needed. Or where you have to provide a custom interface to whatever the options are in the plugin interface portion of the edit interface dialog. ===allowTCP=== OPTIONAL: (boolean) defaults to True. If true then the Outgoing TCP Connection option will be enabled in the port popup. There are some devices that might be connected via a serial port or via a serial to ethernet type adaptor. If selected by the user additional user interface will be inserted for them to enter a remote address and port. If your plugin only makes outgoing network connections then you should instead include the key “portSelectOutput” as below to force this to be the only selection. You can get the user entered address and port via the XTension.settings object in the plugin using the xtKeyRemoteAddress and xtKeyRemotePort constants like: myAddress = xtension.settings.get( xtKeyRemoteAddress) myPort = xtension.settings.get( xtKeyRemoteport) ===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. You can retrieve the selected serial port name from the XTension settings like: mySerialPortName = xtension.settings.get( xtKeyportName) ===Accepting Incoming Connections=== If your plugin needs to setup a server to listen for incoming connections there are several configuration options available for that option as well. The settings the user enters can be retrieved from the xtension.settings dictionary after your plugin starts up. ==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 UI section will be inserted into the window to set up the listening port and optionally the bonjour names. If your plugin can communicate only by incoming connections then you should specify the "portSelectIncoming" parameter below to force this selection. ==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. ==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. The actual work of creating the mDNS record is handled by XTension. Your plugin does not have to do anything other than specify that you’d like it to be an option and supply the default service type string. ==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.” ====An example of the initial portion of an info.json file==== This is not a complete info.json file but just a simple example of the first portion before defining any interfaces or unit types. { "name":"XTension 6 Channel Dimmer Kit", "vers":2, "readableVers":"2.0", "APIVersion":2, "checkVersionLink":"http://machomeautomation.com/plugins/xtDimmer4_version_info.json", "tag":”xt.Dimmer6", "isf":"xtension_PWM.isf", "desc":"XTension PWM Dimmer Kit", "wiki":"http:\/\/machomeautomation.com\/doku.php\/kits\/dimmer", "info":"Connects to the XTension PWM Dimmer kit", "script":"python2", "module":"xtDimmer.py", "portSelectOutgoing":true, "defaultPort”:10000 } PREVIOUS: [[plugins:01_files|]] NEXT: [[plugins:03_units|]]