plugins:02_infojson
Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
|
plugins:02_infojson [2017/07/14 13:21] 127.0.0.1 external edit |
plugins:02_infojson [2018/08/24 15:14] (current) James Sentman [allowBonjour] added info that XTension will take care of it |
||
|---|---|---|---|
| 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, 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. | + | 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. |
| - | ==script== | + | ====Plugin Description Keys==== |
| - | 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. | + | 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. |
| - | ==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== | + | ===script=== |
| - | 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 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. |
| - | ==isf== | + | ===name=== |
| - | REQUIRED: (string) The folder name that the plugin files live in. | + | 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" |
| - | ==module== | + | ===tag=== |
| - | 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" | + | 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. | ||
| - | ==desc== | + | ===module=== |
| - | 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. | + | 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. |
| - | ==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) 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. | 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== | + | ===wiki=== |
| 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 page on the MacHomeAutomation.com wiki you should place a link to it in this field. | ||
| - | ==link== | + | ===link=== |
| OPTIONAL: (url) if your plugin has a web page elsewhere, or can link to a device manufacturer that url should be included here. | 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== | + | ===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. | 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== | + | ===allowNone=== |
| - | 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. | + | 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" |
| - | ===Connection Control=== | + | ===portSelectNone=== |
| - | 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) 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. |
| - | ==allowNone== | + | ===allowTCP=== |
| - | 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) 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. |
| - | ==portSelectNone== | + | You can get the user entered address and port via the XTension.settings object in the plugin using the xtKeyRemoteAddress and xtKeyRemotePort constants like: |
| - | 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. | + | <code> |
| + | myAddress = xtension.settings.get( xtKeyRemoteAddress) | ||
| + | myPort = xtension.settings.get( xtKeyRemoteport) | ||
| + | </code> | ||
| - | ==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 "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. | 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. | ||
| 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 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. | + | 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: |
| + | <code> | ||
| + | mySerialPortName = xtension.settings.get( xtKeyportName) | ||
| + | </code> | ||
| - | ==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=== | ===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 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) 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== | ==portSelectIncoming== | ||
| Line 82: | Line 90: | ||
| ==defaultPort== | ==defaultPort== | ||
| OPTIONAL: (integer) if present this will be filled in to the port field for the incoming communication field. | 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== | ==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. | + | 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 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." | + | 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|]] | ||
| + | ====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. | ||
| + | |||
| + | <code> | ||
| + | { | ||
| + | "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 | ||
| + | } | ||
| + | </code> | ||
| + | PREVIOUS: [[plugins:01_files|]] NEXT: [[plugins:03_units|]] | ||
plugins/02_infojson.1500038490.txt.gz · Last modified: 2017/07/14 13:21 by 127.0.0.1
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
