plugins:02_infojson
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revisionLast revisionBoth sides next revision | ||
plugins:02_infojson [2017/07/14 13:21] – external edit 127.0.0.1 | plugins:02_infojson [2018/08/24 15:14] – [allowBonjour] added info that XTension will take care of it James Sentman | ||
---|---|---|---|
Line 1: | Line 1: | ||
=====Plugin API: info.json and Communication Settings===== | =====Plugin API: info.json and Communication Settings===== | ||
- | The info.json file contains all the information necessary to load your script files, | + | The info.json file contains all the information necessary to load your script files, |
- | ==script== | + | ====Plugin Description Keys==== |
- | REQUIRED: (string) The scripting language that the plugin is written in. As of plugin | + | These keys should be at the top level of the JSON object to describe the plugin |
- | ==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: " | ||
- | ==tag== | + | ===script=== |
- | REQUIRED: (string) The tag is a short string used by the program | + | REQUIRED: (string) The type of the script being run. Currently supported values are “python2” |
- | ==isf== | + | ===name=== |
- | REQUIRED: (string) The folder | + | REQUIRED: (string) The name of the plugin |
- | ==module== | + | ===tag=== |
- | REQUIRED: (string) The name of the script file to load from inside the isf folder. In the case of the python plugin | + | REQUIRED: (string) The tag is a short string used by the program to identify items belonging |
+ | ===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. | ||
- | ==desc== | + | ===module=== |
- | OPTIONAL: (string) | + | REQUIRED: (string) |
- | ==info== | + | ===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) | ||
+ | |||
+ | ===readableVers=== | ||
+ | OPTIONAL: (string) a more human readable version string like 6.5.4 or 4.5.6.334.234 | ||
+ | |||
+ | |||
+ | ===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 | ||
+ | |||
+ | ===info=== | ||
OPTIONAL: (string) Optional but should always be included. A 2 or 3 line long description of the plugin | OPTIONAL: (string) Optional but should always be included. A 2 or 3 line long description of the plugin | ||
- | ==wiki== | + | ===wiki=== |
OPTIONAL: (url) if your plugin has a page on the MacHomeAutomation.com wiki you should | OPTIONAL: (url) if your plugin has a page on the MacHomeAutomation.com wiki you should | ||
- | ==link== | + | ===link=== |
OPTIONAL: (url) if your plugin has a web page elsewhere, or can link to a device | OPTIONAL: (url) if your plugin has a web page elsewhere, or can link to a device | ||
- | ==vers== | ||
- | REQUIRED: (integer) | ||
- | |||
- | ==readableVers== | ||
- | OPTIONAL: (string) a more human readable version string like 6.5.4 or 4.5.6.334.234 | ||
- | ==checkVersLink== | + | ===checkVersLink=== |
OPTIONAL: (url) a link to a JSON file on your server that contains the current and | OPTIONAL: (url) a link to a JSON file on your server that contains the current and | ||
- | ==APIVersion== | + | ===allowNone=== |
- | REQUIRED: (integer) the API version that is required | + | OPTIONAL: (boolean) defaults |
- | ===Connection Control=== | + | ===portSelectNone=== |
- | The plugin host can handle simple | + | OPTIONAL: (boolean) if present and set to true the communications |
- | ==allowNone== | + | ===allowTCP=== |
- | OPTIONAL: (boolean) defaults to false. If your plugin does not require normal | + | OPTIONAL: (boolean) defaults to True. If true then the Outgoing TCP Connection option will be enabled in the port popup. |
- | ==portSelectNone== | + | You can get the user entered address |
- | OPTIONAL: (boolean) if present | + | < |
+ | myAddress = xtension.settings.get( xtKeyRemoteAddress) | ||
+ | myPort = xtension.settings.get( xtKeyRemoteport) | ||
+ | </ | ||
- | ==allowTCP== | + | ===portSelectOutgoing=== |
- | 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 " | + | |
- | + | ||
- | ==portSelectOutgoing== | + | |
OPTIONAL: (boolean) if present and True the communications selection popup will be forced to select " | OPTIONAL: (boolean) if present and True the communications selection popup will be forced to select " | ||
Line 60: | Line 71: | ||
OPTIONAL: (integer) if included then this will be offered as the pre-filled in value in the TCP connection Port field. | OPTIONAL: (integer) if included then this will be offered as the pre-filled in value in the TCP connection Port field. | ||
- | ==allowSerial== | + | ===allowSerial=== |
- | OPTIONAL: (boolean) defaults to True. Allows the selection of available serial | + | OPTIONAL: (boolean) defaults to True. Allows the selection of available serial |
+ | < | ||
+ | mySerialPortName = xtension.settings.get( xtKeyportName) | ||
+ | </ | ||
- | ==baud== | ||
- | REQUIRED if AllowSerial: | ||
- | \\ | ||
- | 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 | ||
===Accepting Incoming Connections=== | ===Accepting Incoming Connections=== | ||
- | Incoming connection support is not enabled in XTension 9.3.1 but will appear in a not too distant future release. | + | 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== | ==TCPListen== | ||
- | OPTIONAL: (boolean) defaults to false. If present and true the user will have the | + | OPTIONAL: (boolean) defaults to false. If present and true the user will have the option of selecting " |
==portSelectIncoming== | ==portSelectIncoming== | ||
Line 82: | Line 90: | ||
==defaultPort== | ==defaultPort== | ||
OPTIONAL: (integer) if present this will be filled in to the port field for the incoming | OPTIONAL: (integer) if present this will be filled in to the port field for the incoming | ||
- | |||
- | ==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 | ||
==allowBonjour== | ==allowBonjour== | ||
- | OPTIONAL: (boolean) defaults to True. Allows for you to register a bonjour, zero-conf or | + | 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== | ==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. | 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== | ==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 | + | 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 |
- | PREVIOUS: [[plugins: | ||
+ | ====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. | ||
+ | |||
+ | < | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | </ | ||
+ | PREVIOUS: [[plugins: |