plugins:02_infojson
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
plugins:02_infojson [2018/08/19 14:29] – [portSelectOutgoing] James Sentman | plugins:02_infojson [Unknown date] (current) – removed - external edit (Unknown date) 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | =====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/ | ||
- | |||
- | |||
- | ===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: # | ||
- | |||
- | ===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=== | ||
- | 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) | ||
- | |||
- | ===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=== | ||
- | OPTIONAL: (string) Optional but should always be included. A 2 or 3 line long description of the plugin | ||
- | |||
- | ===wiki=== | ||
- | OPTIONAL: (url) if your plugin has a page on the MacHomeAutomation.com wiki you should | ||
- | |||
- | ===link=== | ||
- | OPTIONAL: (url) if your plugin has a web page elsewhere, or can link to a device | ||
- | |||
- | |||
- | ===checkVersLink=== | ||
- | OPTIONAL: (url) a link to a JSON file on your server that contains the current and | ||
- | |||
- | ===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 | ||
- | |||
- | ===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 " | ||
- | |||
- | ==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 | ||
- | < | ||
- | 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 " | ||
- | |||
- | ==portSelectIncoming== | ||
- | OPTIONAL: (boolean) if present and True the communications popup will be forced to | ||
- | |||
- | ==defaultPort== | ||
- | OPTIONAL: (integer) if present this will be filled in to the port field for the incoming | ||
- | |||
- | ==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 | ||
- | |||
- | |||
- | ====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: |