Mac Home Automation

There are several more keys you can add to the info.json file for other options or inteface options which are optional or only required in certain cases.

cameraapi Boolean - Set to true if this plugin is implementing a video camera API. The plugin will be treated very differently. Instead of being run as a separate instance it will instead be imported into one of the video plugins and added to the popup list of available camera plugins in the edit interface window for the video plugins. This is a very large topic and will be documented separately. Have a look at the existing camera api plugins for more info in the meantime.

“cameraapi”:true,

checkVersLink String/http link - This is currently unimplemented. Eventually this will expect a small json file describing the current version of your plugin and will add it to a list of plugins available for update either by the system automatically or by directing the user to the plugin home page. At the moment this will be ignored.

“checkVersLink”:”https:\/\/weatherslam.worlddomination.com\/xtpluginvers.json”,

dontvalidatehandlers Boolean - (note all lower case) When you register for a script handler it also is added to a list of valid extra scripting commands in XTension. If the user tries to call a script handler that you have not registered it will result in a script error just like trying to call a regular script command that does not exist. By setting this to true the scripting engines will ignore this and pass any request to run a custom script handler to the plugin even if it does not know about it. This lets you expand the scripting without knowing what the handler names might be ahead of time but will result in no error being generated by the script if the plugin has no handler for this making it harder to catch typos or other mistakes in scripting in XTension. In order to handle unregistered script handlers in the plugin you must instead create a callback for the xtCommandScriptHandler command and check the name of the handler requested yourself.

“dontvalidatehandlers”:true,

link String/http link - If supplied then the “more info” link in the Edit Interface window will be enabled and if clicked will take the user to this address in their browser. In general this is used to take the user to the web page of the maker or device that the plugin will connect to. If there is no device then it might be used to take the user to the github page with more info, or anywhere that makes sense to get more info about the plugin or the device or service it connects to. For more specific online instructions for the use of the plugin please see the wiki key below which should link to the documentation of the plugin itself.

“link”:”https:\/\/weatherslam.gov\/xtensionplugindocs”,

forcex86 Boolean - Set to true to force the plugin to run in emulation on an M1 mac rather than use the python arm code. When ever possible a plugin should include a fat binary of any libraries that are loaded natively by python. The python interpreter included in XTension includes both the x86 and ARM versions of the binary and all included plugins and libraries. If it is not possible to provide an ARM capable version of any libraries then you can use this to force the python instance running this plugin to run under emulation. This will allow it to load and use an x86 only library. This should not be used unless absolutely necessary as it will incurr extra CPU and memory usage on the server and at some point in the hopefully distant future Apple may stop supporting this emulation layer. This defaults to false, use only if needed.

“forcex86”:true,

menuHandlers JSON List of lists - If included allows you to insert items into the contextual menu of the Plugin instance in the Interface List window. Each item in the list should be another list with 2 elements in it. The first being the display name you wish placed into the menu, the second being the script handler name that should be called in the plugin if the user selects this from the menu. Any number of menu items may be added but dont get too excited or the user may not bother to scroll through them all. You must register the handler names with XTension and then you will get a callback to that when the user selects this. This can also be added to Unit device type declarations in the info.json file to add items to the individual units contextual menus. In the following example 2 menu items would be added when control clicking on an instance of the interface. They would be “Reboot Device” which would send an execute script command to the plugin for a handler named “reboot_device”. The second would have a menu with the text “Flash The Indicator” and execute a script handler named “flashindicator”.

“menuHandlers”:[[“Reboot Device”, “reboot_device”], [“Flash The Indicator”, “flashindicator”]...]

info String - If included this text will be displayed below the plugin popup in the Edit Interface dialog. The size of the field is auto-resized to accomidate a longer or shorter message. This is in addition to the description key that will be added to the popup menu itself. This should be used for things like “Special configuration required, please read the wiki article for more info” or that sort of thing.

 “info”:”In order to function you must allow a remote connection via the devices configuration pages. Click the wiki link for more info”,

remoteExecution Boolean - If you wish the plugin to be running on some separate machine, like a raspberry pi, then setting this will insert an extra bit of interface asking for a 4 digit remote execution key. Then upon enabling it will start listening with that key for a connection from the remote process but not start the process itself. The 4 digit key should be in the configuration for the remote plugin instance so that it can send it during the connection process. the keys must match, but are not a substitute for security or only running across the local network. The XTension inter communications port should never be exposed to the internet as a whole. If you need to tunnel a connection to a remote location you can setup an SSH tunnel or other means to safely connect from the remote location to yoyur local XTension. Note that the plugins are not generally setup for remote execution and no simple default way to do this is included as part of the package. Contact me for more info until there is a documentation page for this. This can be a very useful debugging tool for binary plugins as you can create the remote interface in XTension but run them in the debugger and have them connect as if they were running inside XTension itself. I routinely use this for testing of the binary plugins or when developing more of them.
You can use this temporarily on any plugin without adding it to the info.json file by holding down the option key while right clickng on the label “Device” before the plugin selection popup. It will offer to turn on remote execution for this plugin instance temporarily for debugging purposes. To clear the temporary action erase the pin number and save with the field empty.

“remoteExecution”:true,

applescriptTemplate String/File Name
javascriptTemplate String/File Name
pythonTemplate String/File Name
luaTemplate String/File Name
At this moment only the applescriptTemplace key is implemented but at least the python template will be enabled at the time that adding python scripting support to XTension is complete. The others were added on a whim and may never be supported but they could be. This is a file name that should be the name of a file included in the root level of your plugin folder. It should contain the plain text of the template script most useful for your plugin. When the user clicks the Edit button for the Interface Script associated with this plugin instance a template script with the various standard plugin interface script handlers is added to the otherwise empty new script window by default. Things like error handlers and others are added automatically with long winded comments to explain what they do. If you add one of these files it should describe any plugin specific callbacks that are implemented by your plugin that the user may want to use without having to reference the documentation. If this is present then the contents of that file will be added to a new empty script before the default handlers that apply to all interfaces.

“applescriptTemplate”:”applescript_template.txt”,

showDefault Boolean - defaults to false. This is a hold over from a much earlier and more innocent age when there was only an X10 interface. You remember, like back in the 70’s or during XTension’s earliest life time in the 90’s. There were many scripting verbs that by default sent specific commands to the interface. Then when I added the ability to have multiple interfaces or plugin instances those verbs no longer specified which interface they should run on. I added extra fields to the verbs so that you could specify the name of the plugin instance to apply them to, but many people at that point had lots of scripts using these commands and did not take kindly to being told to edit them all. So instead I added the ability to set an interface instance as the default for all those commands. Then without a specific interface name it would apply to that interface. These verbs are no longer used for anything other than legacy support of the X10 and X10 wireless devices. Please do not use this key without a very good reason It will enable the controls at the bottom of the edit interface window for the user to select this plugin instance to be used as either the default powerline interface or the default wireless interface. There is very little chance this will be useful to any other plugins.

“showDefault”:true,

sudo Boolean - Defaults to false. It is rarely advisable but sometimes necessary to run a plugin as the root user. The most obvious reason being if it needs to listen on a port lower than 1024 or something similar. If your plugin must do this then you set this key to true. This will add the sudo command to the beginning of the command string when launching the app. There is no attempt to send a password to the sudo command from XTension. The User must have added the command to their “sudoers” file manually so that the plugin command may be run as sudo without asking for a password. Once saved if you instruct the user to control click on the new instance in the Interface List window they will find a new contextual menu option there to “Copy Sudoers File Configuration Line To The Clipboard” this will copy the line that needs to be added to the suders file to the clipboard for easy cutting and pasting into the sudoers file. There is currently only one default included plugin that uses this and that is the Amazon Alexa Bridge run as Sudo plugin. There are more detailed instructions on that page for editing the sudoers file. It cannot be edited with any text editor but you must use the “sudo visudo” command and use a slightly altered version of the vi editor to do it. And it is not unlikely that future updates to the OS or security updates will reset that to the original without your added command. So after updates you should instruct the user to verify that the plugin is still running properly.

“sudo”:true,

wiki String/http link - If included this should be a link to either the machomeautomation wiki page that documents the plugin, or whatever page you have elsewhere that documents your plugin. If present the “wiki” link next to the selected plugin popup will enable and if clicked will open this link in the users browser.

“wiki”:”https:\/\/wiki.weatherslam.gov\/xtension_plugin_docs\/“,

Next:Info.json: Unit Definition