This is an old revision of the document!
NOTE: this plugin now requires Python3. This is not installed by default on MacOSX. Please visit the Python.org Download Page and install the latest version of python3 before running this plugin.
The non-cloud based solutions for letting Home Automation systems be controlled from Amazon’s Alexa devices have always relied on emulating another device that Amazon supports directly. Yes it requires a working internet connection to do the voice recognition, but to then do yet another trip up to the cloud, run a huge amount of code, and then send a result back to control a device that is sitting literally 2 feet from your XTension server has always driven me insane as to the stupidity of that plan.
The device with the best direct, non-cloud support and options has been the original Phillips Hue Hub. XTension’s emulator like almost everyone elses made use of this. In October of 2019 Amazon pushed out a software update that broke the phillips hue emulation support for every Home Automation platform that had implemented something like this. There was much complaining and chatter and enough bug reports made to Amazon to prove that they don’t actually read any of those at all. As of Feb 2020 there is still no fix from Amazon and as far as I’ve been able to discover they have no intention of putting back the original functionality.
Some explanation of how it all works follows: When you send out a UPNP packet claiming to be a Hue Hub you send out a URL to a built in web server that allows for the control of the devices you are sharing. This is a standard URL and so you could include a higher port number along with it allowing you to run the plugin emulator on a port other than the default web port of 80. Unfortunately the new Amazon software no longer honors the port you include in this link. It will only ever connect on port 80 and thus was every hue emulator plugin for every home automation software platform broken beyond repair.
On the Mac it is very difficult to run a program that listens on port 80 as the system reserves ports below 1024 for processes and servers running as root. The solution is to run the plugin process as root, but not the entirety of XTension. This requires that you’re not running anything else on port 80. If you require a web server on port 80 on your server please have a look at the upcoming raspberry pi code that you can run separately from XTension and will perform the same work as this plugin but running on a separate device leaving port 80 available on your Mac for Apache or whatever other server you might need to run. Another reason you might opt for the raspberry pi solution is if you have security concerns about running the Alexa plugin as root on your house server Mac. The plugin code is available in plaintext inside the XTension executable and if you believe that there are attacks which might allow a person to run code as root please review the code and suggest changes or additions I can make to make this less likely. Since the install is not exposed to the internet only your internal network it is much less likely to be subject to random attacks. One might argue that if you have something compromised on your internal network so badly that it can run attacks against other members of your private network that you have bigger problems than a potentially compromised Alexa plugin but those are decisions only you can make for yourself and what you are comfortable with.
Since all plugin instances in XTension run as separate processes it is possible to run this one as root without affecting any other XTension functions or running the entire app as root. The following instructions show you how to add this single command to your “sudoers” file so that it can be run as root without asking for your root password. Saving your machines root password in the XTension preferences would be a potential security risk and this avoids that necessity.
If you haven’t already, please read through the main Alexa Plugin Documentation as everything remains the same except for the extra configuration needed due to Amazon’s software choices.
If you already have an Alexa interface that stopped working when your Alexa device updated itself you can simply change the plugin type popup from the old Alexa plugin to the “Alexa Plugin With Sudo.” Make sure to change the port number to 80 and save it. If you’re creating a new interface select the new Sudo Alexa plugin from the start and then follow the original Alexa plugin setup instructions as linked to above. The default for a new interface should be port 80 as well but verify as that is the only number that will work.
Save the interface before continuing, but do not yet try to enable the interface.
On every single one of my testing machines and my development machine there was an instance of Apache running on the standard web port of 80. Even though I have never used that and I’m not sure in every case where it came from it was there. Since only one server can be running on a specific port and we absolutely need port 80 in order to make this work we have to disable any other server software. There are several ways this might have been installed that I will talk about below. There are a truly uncountable number of ways you might have installed things yourself either through Brew or other methods and if you did that then disabling that server is up to you. You must turn off anything that will want to listen on port 80 and not just in this session but so that it will not try to restart after the next reboot. If you need that server please see the forthcoming raspberry pi solution.
You can try any or all of these, just because one errored does not mean that the next one will. These are the commands that I used to test and finally succeeded in getting it shutdown on my testing machines. This includes machines that were loaded with standard MacOSX as well as those that had server installed. If you have a version of OSX Server that still included the web server then just use the Server app to shut it down or change it’s port to something other than 80. In my case that no longer shows up as Apple is no longer maintaining their server configuration utility but it was still running anyway.
Use your browser to visit the machine in question and see if you get anything. The standard Apache install and OSX Server install will return a simple page that just says “it works!”. You might see that if you open safari on your XTension server and visit “http://localhost/“
the way that Safari caches pages means that even after you successfully stop the server it will continue to show that page until you FORCE a reload and clear the cache. You can do that with the various developer menu items to clear the cache or just hold the shift key as you click reload. Once you get an error message about the server not responding rather than the “IT WORKS!” message you’ve succeeded in at least temporarily disabling the server.
There are so many ways to install Apache that not all these will work for anyone, but the combination will work for most people. Try one after another or all of them, there is no harm in generating an error with these if you’re still showing something running on port 80.
sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist sudo apachectl -k stop sudo /usr/sbin/httpd -k stop
if you’ve done all that and you still show the “It Works!” page when shift reloading then you have an even more interesting install of apache than I did here and you’ll have to figure out how to stop it separately or switch to the forthcoming raspberry pi solution.
Once that has stopped and you have gotten the proper error message when shift-reloading the page you need to make sure the fix sticks after restarting. Restart your server mac, log in again and try again. If the error message continues then you’ve successfully stopped your standard web server!
This is the part of the process that requires some mucking about with the command line. We need to enable the user that your XTension app is running as to be able to run just this one plugin app as root without affecting anything else. You can do this by editing the sudoers file as described below. This does not require any changes to the system as a whole or turning off system integrity protection or anything like that.
Once you’ve saved the interface above, but not yet tried to enable it, find the new interface in the list of plugins on the Interface List window. Control or right click on the new interface and you’ll see a new contextual menu item “Copy Sudoers Configuration Line To The Clipboard” select this and you now have on the clipboard the line you need to add to this system file in order to allow the plugin to run as root and therefore access port 80.
DO NOT use any other editor for this file than the one that is built into the system. It will make sure that you do not put something into the file that will break any sudo commands and leave you unable to execute any command as root which you need for the normal proper operating of your system! This is very important!
The command to edit the sudoers file is:
Open a terminal window and enter that. It will open a special version of the “vi” editor editor and open the current sudoers file. Hold the down arrow key or use your trackpad or mouse to scroll to the very bottom. VI is a really “old school” and high powered editor that nobody shares the secrets of it’s use with people on the internet in such tutorials. They generally ask you to use simpler, more word processing like app, but in this case we have no choice or you could lose the ability to use sudo at all and you need that!
When you get to the bottom of the file we need to add the line that is now copied to your clipboard.
Press the shift key and the “A” key. This means “Append” and the shift key means that it will jump to the end of the current line. Press Enter to add a new line and then do a standard Paste either from the edit menu or pressing command-V just like any other app.
The line that appears should start with the user name, and end with the path to the plugin file. With “ALL= NOPASSWD:” in between them. This allows this user to run this single program with sudo as root without having to enter their password. They still can’t do anything else, only this one program can be run without the password.
If the line you see instead contains an error message or other text that doesn’t look something like:
gonzosk8er12 ALL= NOPASSWD: /Users/gonzosk8er12/Automation\ Apps/XTension/XTension.app/contents/resources/plugins/alexasudo.isf/alexasudo.py
Then do NOT continue. Press the escape key to exit edit mode. type a colon and then “q!” to make the editor quit without saving any changes.
If your output looks something like the above with your correct user name and the correct path to where you have installed XTension then you can save it. Press the esc key to leave insert mode. Type a colon and then “w” to write the file back out, and then “:q” to exit the editor.
Once you have done that if all else has worked properly XTension should now be able to run this plugin and listen on port 80 without your having to save your root password into XTension’s preferences anywhere.
At this point you can return to XTension and enable the interface. If nothing that looks like an error is written to the log file you can continue.
Getting the new instance of Alexa seen by the Alexa servers can be either instant, easy and just work, or might require some futzing around. If you converted an existing Alexa instance then it SHOULD just work. If you’re creating a new one or are debugging one that is causing problems you may need to delete and re-add your devices.
If everything comes back to life and you can control devices now then you’re done!
If not please visit “alexa.amazon.com” in your browser and select the “Smart Home” item from the list on the left. Click the “Devices” entry and finally the “Forget All” button. Once they are all cleared you can attempt to rediscover them all. You can use the “Discover” button at the bottom of this page or just ask your alexa device to “discover new devices”
Once your devices are back you can re-setup any special phrases or other groups and scenes and such that you had working previously.
The sudo capable Alexa plugin was first included in XTension 9.4.28 released towards the end of February 2020.