├── .gitignore ├── INSTALL-QUICKSTART.md ├── INSTALL.md ├── LICENSE ├── README.md ├── config_default.js ├── helper.js ├── index.js ├── lib ├── openhab.js └── wolfram.js ├── package.json └── samples ├── sample-intents.json ├── sample-slots.txt └── sample-utterances.txt /.gitignore: -------------------------------------------------------------------------------- 1 | /nbproject/ 2 | /node_modules/ 3 | .config.js 4 | -------------------------------------------------------------------------------- /INSTALL-QUICKSTART.md: -------------------------------------------------------------------------------- 1 | # Alexa-HA QUICKSTART with Ubuntu 14.04 LTS Server 2 | The purpose of this document is to provide a minimalistic set of instructions on how to setup Alexa-HA, a customizable Skill for your Amazon Echo. For this, we are taking the Semi-direct approach (Echo -> AWS ASK -> NodeJS/Express -> HA) for routing the Echo requests to your Home Automation controller. 3 | 4 | NOTE: We recommend proxying Node.js/Express.js behind a proper webserver such as Apache/Nginx (i.e. Echo -> AWS ASK -> Apache/Nginx -> NodeJS -> HA), which decouples your application logic from the public facing server and provides an extra layer of security. This is more complicated to configure however, and Alexa-App-Server is capable of doing everything we need here without this extra 'hop'. 5 | 6 | #### Before you begin 7 | You will need the following to complete these quick start instructions! 8 | - Ubuntu Server VM, already provisioned; preferably dedicated to Alexa-HA for improved security. This can be done on the same server as OpenHAB, but we suggest not exposing your OpenHAB server to the public internet... 9 | - An available public static IP or Dynamic DNS provider 10 | - Public port 443 available (i.e. not already in use by another service, however if it is already in use by Apache2/Nginx/etc you can still 'proxy' the communication to your Node.js server!) 11 | - Some knowledge of firewall/router setups and DNS configuration as we must expose the Node.js/Express.js service to the outside 12 | - Ideally a trusted SSL certificate, however self-signed SSL certificates may be used (setup is detailed below). 13 | 14 | #### Install Git 15 | This is optional, you could just grab a ZIP from GitHub via HTTPS and decompress the archive instead! 16 | ``` 17 | sudo apt-get install git 18 | ```` 19 | #### Install Node.js 20 | ``` 21 | curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash - 22 | sudo apt-get install -y nodejs 23 | ``` 24 | 25 | #### Create an unprivileged user to run Alexa-App-Server & Alexa-HA 26 | ``` 27 | sudo adduser alexa 28 | sudo su alexa 29 | cd ~ 30 | ``` 31 | 32 | #### Install necessary node packages and dependencies under the 'alexa' user 33 | ``` 34 | npm install alexa-app alexa-app-server request 35 | ``` 36 | 37 | #### Patch alexa-utterances module (a temporary fix for ASK custom slot support!) 38 | ``` 39 | cd ~/node_modules/alexa-app/node_modules/alexa-utterances/ 40 | wget https://github.com/unityfire/alexa-ha/files/155821/alexa-utterances_custom_slot_support.patch.txt 41 | patch -p1 < alexa-utterances_custom_slot_support.patch.txt 42 | ``` 43 | 44 | #### Copy Alexa-App-Server's examples directory to a new 'stub' server 45 | ``` 46 | cp -R ~/node_modules/alexa-app-server/examples/ ~/node_modules/alexa-app-server/api/ 47 | cd ~/node_modules/alexa-app-server/api/ 48 | ``` 49 | 50 | #### Remove existing demo apps, clone Alexa HA from GIT, and configure 51 | Be sure to select which branch you want in the command below! Use 'develop' for the latest and greatest or 'master' for the stable release of Alexa-HA. 52 | ``` 53 | rm -rf ~/node_modules/alexa-app-server/api/apps/* 54 | cd ~/node_modules/alexa-app-server/api/apps/ 55 | git clone -b master https://github.com/unityfire/alexa-ha.git 56 | cd alexa-ha 57 | cp config_default.js config.js 58 | nano config.js 59 | ``` 60 | - Set the various AWS ASK related settings as needed - applicationId is available from Amazon Developer Portal 61 | - userId can be found later in the install process after setting up external endpoint access, and issuing the first Alexa-HA command - the logs will show the device/skill current userId, which changes every time you re-install the Skill (even on the same device!) 62 | - If you want to use Wolfram Alpha with Alexa-HA (i.e. to have it 'research' anything for you via voice, which is optional!), register and enter your API key 63 | - Open up your various OpenHAB configuration files (i.e. items/sitemaps/rules) for reference in another window; use these to setup the rest of config.js as desired. The most important part of configuring this is that beyond the General Configuration section, the mappings setup in the HA* & config.item/mode/metric sections in Alexa-HA's config.js are correctly pointed to the items/modes/devices in OpenHAB! Alexa-HA uses this to determine which items in your home do what, and where... 64 | - Save config.js and exit 65 | - Create a few new items in your OpenHAB configuration/items/* file to be used by Alexa-HA. These are used only as a fallback for custom/arbitrary voice commands (optional, which can trigger custom rules on the OpenHAB server): 66 | 67 | ``` 68 | String ECHO_VoiceCMD "ECHO VoiceCMD: [%s]" 69 | String ECHO_Answer "ECHO Answer: [%s]" 70 | Switch ECHO_Processed "ECHO Proc [%s]" 71 | Switch ECHO_Switch "ECHO Switch [%s]" 72 | ``` 73 | 74 | #### Setup a self signed SSL cert (optional, if you do not have a trusted SSL cert available!) 75 | ``` 76 | cd ~/node_modules/alexa-app-server/api 77 | mkdir sslcert 78 | cd sslcert 79 | openssl genrsa -out private-key.pem 1024 80 | openssl req -new -x509 -key private-key.pem -out cert.cer -days 365 81 | ``` 82 | Remember to upload the contents of your ```~/node_modules/alexa-app-server/api/sslcert/cert.cer``` to AWS ASK Skill > SSL Certificate > 'I will upload a self-signed certificate in X.509 format' during the later steps of setting up the Skill via the AWS Developer Portal! 83 | 84 | #### Modify server.js to suit your needs 85 | ``` 86 | cd ~/node_modules/alexa-app-server/api 87 | nano server.js 88 | ``` 89 | Here is mine for example (note the non-standard app_root & ports, and HTTPS is enabled as its required for an AWS ASK): 90 | ``` 91 | var AlexaAppServer = require("../index.js"); 92 | AlexaAppServer.start( { 93 | app_dir:"apps", 94 | app_root:"/api/", 95 | port : 30001, 96 | httpsEnabled : true, 97 | httpsPort : 30000, 98 | privateKey:'private-key.pem', 99 | certificate:'cert.cer', 100 | preRequest: function(json,req,res) { 101 | // Include password value from URL parameter, so Alexa-HA can validate it... 102 | json.password = req.param('password').toString(); 103 | 104 | // Extract the IP address of the client (handles IPv4 and IPv6) 105 | var IPFromRequest = req.headers['x-forwarded-for'] || req.connection.remoteAddress; 106 | var indexOfColon = IPFromRequest.lastIndexOf(':'); 107 | var address = IPFromRequest.substring(indexOfColon+1,IPFromRequest.length); 108 | json.remoteAddress = address; 109 | 110 | }, 111 | postRequest: function(json,req,res) { 112 | } 113 | } ); 114 | 115 | ``` 116 | 117 | #### Redirect port 443 (external, currently required for AWS ASK's) to 30000 (internal) 118 | This uses iptables to work around restricted port limitations for non-root level users (i.e. our newly created 'alexa' account). Adjust port numbers as needed (external port 443 is required for ASK's!) 119 | ``` 120 | sudo iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT --to-port 30000 121 | ``` 122 | Next, make the iptables rules permanent (applied at boot time): 123 | ``` 124 | sudo apt-get install iptables-persistent 125 | ``` 126 | 127 | #### Start the service in the foreground 128 | ``` 129 | node server.js 130 | ``` 131 | 132 | #### Visit the Alexa-HA test page endpoint in your browser: 133 | https://LOCAL_IP/api/alexa-ha 134 | 135 | #### Setup perimeter router/firewall to port forward to the host IP 136 | (depends, out of scope) 137 | 138 | #### Setup internal and external DNS to map to the correct hostname/IP 139 | (depends, out of scope) 140 | 141 | #### Test URL from the outside 142 | Now that everything should be setup, test it by loading the HTTPS endpoint URL in your browser by IP (``` https://PUBLIC_IP/api/alexa-ha/ ```) and by Fully Qualified Domain Name (``` https://FQDN/api/alexa-ha/ ```). You should be able to reach the 'Alexa Tester' page! 143 | 144 | ### Daemonize Alexa-HA with PM2 145 | Consider using the Node.js PM2 module for daemonizing Alexa-HA. PM2 also handles logging to the file system. To have Alexa-HA automatically start at boot, do the following: 146 | 147 | - Stop node if currently running in the foreground (Control-C) 148 | - Run the following command as a privileged user to install PM2 globally (note you may need to change the username 'alexa' for your environment. This should be an unprivileged user!) 149 | ``` 150 | sudo npm install pm2 -g 151 | sudo env PATH=$PATH:/usr/local/bin pm2 startup -u alexa 152 | ``` 153 | - You may need to change the home path to your alexa user by editing the start script: 154 | ``` 155 | sudo nano /etc/init.d/pm2-init.sh 156 | ``` 157 | - Find the PM2_HOME export and set it to use our 'alexa' users directory, like so: 158 | ``` 159 | export PM2_HOME="/home/alexa/.pm2" 160 | ``` 161 | - Start Alexa-HA with PM2: 162 | ``` 163 | sudo su alexa 164 | cd ~/node_modules/alexa-app-server/api/ 165 | pm2 start server.js 166 | pm2 status 167 | ``` 168 | - Check the status of the service with: 169 | ``` 170 | pm2 show server 171 | ``` 172 | - The service will gracefully start and stop as needed. To manually restart it, run (as the 'alexa' user): 173 | ``` 174 | pm2 restart server 175 | ``` 176 | - Reboot the server to ensure everything comes up automatically: 177 | ``` 178 | sudo reboot 179 | ``` 180 | - Confirm the endpoint is still accessible by visiting the URL in your browser: ``` https://FQDN/api/alexa-ha/ ``` 181 | 182 | #### Additional considerations 183 | Look at the 'Additional considerations' in INSTALL.md for additional steps you should carry out for improved security. 184 | 185 | #### Congrats! 186 | If you made it this far, the next steps are relatively easy to finish your setup and get to using Alexa-HA with your Echo(s)! Continue to the second section named 'Setup Amazon Skills Kit' in [INSTALL.md]... 187 | 188 | [//]: # 189 | 190 | [INSTALL.md]: 191 | -------------------------------------------------------------------------------- /INSTALL.md: -------------------------------------------------------------------------------- 1 | # Setup Your HA Controller to work with Alexa-HA 2 | Currently only [OpenHAB] is supported - others HA solutions to follow. These installation steps can carried out directly on your HA server or better yet a seperate server on the same network. Depending on your environment, it is best to create a restricted user that runs Alexa-HA and its dependencies rather than simply using a global root/administrator for everything. That is outside of the scope of the current installation documentation... 3 | 4 | NOTE: These installation instructions are a bit rough, complex and UNDER CONSTRUCTION at the moment but should get the job done! It is assumed you are familiar with service/webserver configurations, SSL certificates, and firewall/router setup. This process will be greatly simplified in the future... 5 | 6 | To begin: 7 | - Ideally provision a new machine/VM as a dedicated server to host Alexa-HA for enhanced security, but these services are lightweight and can be installed on existing servers as well (i.e. on the OpenHAB server) 8 | - Install [node.js] 9 | - Install [npm] 10 | - Install [alexa-app] 11 | - Install [alexa-app-server] 12 | - Install [request] 13 | - Install [pm2] (optional, but very useful for setting Alexa-HA as a background service) 14 | - Apply a temporary [patch] to alexa-utterances (which was installed as a dependency for alexa-app), required to support the CUSTOM SLOT types - should not be necessary after the next release of alexa-app! 15 | 16 | You now have all the dependencies met and can continue with configuring and starting the Alexa-HA Skill. 17 | 18 | - Checkout the code or just download the ZIP from [Alexa-HA]'s github page to the Alexa-App-Server's /example/app/ directory (i.e. example/app/Alexa-HA) 19 | - Copy config_default.js to config.js 20 | - Edit config.js 21 | - Set the various AWS ASK related settings as needed - applicationId/userId values and more available from [Amazon Developer Portal] 22 | - If you want to use [Wolfram Alpha] with Alexa-HA (i.e. to have it 'research' stuff for you via voice, optional!), register and enter your API key 23 | - Open up your various OpenHAB configuration files (i.e. items/sitemaps/rules) for reference in another window; use these to setup the rest of config.js as desired. The most important part of configuring this is that beyond the General Configuration section, the mappings setup in the HA* & config.item/mode/metric sections in Alexa-HA's config.js are correctly pointed to the items/modes/devices in OpenHAB! Alexa-HA uses this to determine which items in your home do what, and where... 24 | - Create a few new items in your OpenHAB configuration/items/* file to be used by Alexa-HA. These are used only as a fallback for custom/arbitrary voice commands (which can trigger custom rules on the OpenHAB server): 25 | ``` 26 | String ECHO_VoiceCMD "ECHO CMD: [%s]" 27 | String ECHO_Answer "ECHO Answer: [%s]" 28 | Switch ECHO_Processed "ECHO Proc [%s]" 29 | ``` 30 | - You may also need to create new groups on the HA server (especially for lighting) so Alexa-HA can control many items (i.e. in the same room) at a time. 31 | - The rest of the config.js file can be revisited/improved later (i.e. units/colors/utterances/etc sections may be further customized). 32 | - Save & Exit 33 | - Consider editing Alexa-App-Server 'example/server.js' and changing the service to use a non-standard port number 34 | - You can now start the Alexa-App-Server and Alexa-HA app in the foreground with 'node server.js' or keep it running in the background with 'pm2 start server.js' ('pm2 status' displays additional useful info) 35 | - Visit http://INTERNAL_IP:PORT/api/Alexa-HA/ - which should show the Alexa Tester page. This confirms that the service is up and listening. 36 | - You now have the option of exposing your internal Node.js/Express service directly to the public, or setting it up behind a webserver such as Apache or Nginx. In all cases an SSL certificate (trusted, or alternatively a self signed cert can be uploaded via [Amazon Developer Portal]) must be used for HTTPS. For example, assuming you already have a SSL-enabled Apache webserver, edit Apache's 'sites-available/default-ssl' config file and add the following inside of the VirtualHost configuration (proxied address/ports depend entirely on your network setup!): 37 | ``` 38 | 39 | ProxyPass http://localhost:10000 40 | ProxyPassReverse http://localhost:10000 41 | 42 | ``` 43 | - Setup a port forwarding rule to route external public requests to the new Node.js/Express internal service. If you have an public static IP address (from your ISP), use it. If not, consider a dynamic DNS service which will route a static FQDN to your dynamic IP. In both cases, we recommend selecting a 'high port' of 30000+ to use for the communication from the public to Alexa-HA. For example, a public static IP:Port of '123.123.123.123:30000' is forwarded (by the firewally/router) to an internal private IP:port of '192.168.1.50:10000'. 44 | - Restart all services (Alexa-App-Server & webserver) for the changes to take effect. 45 | - You should now be able to access 'https://MY_FQDN/api/Alexa-HA' and see the 'Alexa Tester' page from the ouside (which is required for the next steps work)! If not, you have a service or firewall config issue that needs to be addressed before continuing. 46 | 47 | # Setup Amazon Skills Kit 48 | 49 | In order to continue setting up your Alexa-HA skill, you will need to define the 'Interaction Model' which encompasses the Amazon Skill Kits 'Intent Schema', 'Custom Slots' and 'Utterances' via the [Amazon Developer Portal]. Fortunately Alexa-HA takes care of generating most this for you automatically after properation configuration. For this, you must fully configure Alexa-HA via config.js and install Alexa-App-Server along with its dependencies. 50 | 51 | Complete the INSTALL steps for your HA controller first. Then continue with the ASK setup below. For quick reference, see steps 3-4 in this [tutorial] which includes additional details and screenshots. 52 | 53 | - Sign in or create an account on the [Amazon Developer Portal] 54 | - Once you’ve signed in, navigate to Apps & Services > Alexa > Alexa Skills Kit 55 | - Click 'Get Started' under Alexa Skills Kit 56 | - Click 'Add a new Skill' 57 | - Give your skill a name - simply 'Alexa-HA' will do 58 | - Set your desired Invocation Name - for example 'OpenHAB' or 'Jarvis' - which you can then use to invoke the custom Skill on your Echo. 59 | - Set your endpoint - this is a URL to your publicly accessible Alexa-App-Server's skill endpoint. For example: 'https://MY_FQDN/api/alexa-ha?password=CONFIG_PASSWORD' or 'https://MY_PUBLIC_IP/api/alexa-ha?password=CONFIG_PASSWORD'. Lambda ARN's have not been tested yet... 60 | - Save and continue to the next step - 'Interaction Model' 61 | - At this point, once you have configured and started the Alexa-App-Server, you should be able to visit the endpoints URL to get a full 'dump' of the Interaction Model. These values ('intent schema' and 'utterances') should be copied into the AWS ASK Interaction Model page. 62 | - Define your 'custom slots'. These should match what you've within Alexa-HA's config.js file. For example, a custom slot of 'COLOR_TYPE' with values like: 63 | ``` 64 | white 65 | red 66 | orange 67 | yellow 68 | green 69 | aqua 70 | blue 71 | purple 72 | magenta 73 | pink 74 | black 75 | ``` 76 | - A second custom slot for 'LOCATION_TYPE' should contain a list of rooms throughout your house. ASK uses these lists to automatically expand the utterances and build the interaction models on the ASK servers. For example: 77 | ``` 78 | all 79 | house 80 | living room 81 | great room 82 | kitchen 83 | bedroom 84 | bathroom 85 | data center 86 | garage 87 | office 88 | foyer 89 | utility 90 | outside 91 | 92 | ``` 93 | - IMPORTANT! Save these changes, but you do not need to continue on to fully publishing the app! Your new custom Service & Skill is now setup to control ONLY YOUR HOME! Do not make it public. 94 | - Say 'Alexa, open Jarvis' (or whatever your 'Invocation Name' is) and get started! 95 | 96 | NOTE: If you change the Alexa-HA files, including config.js, you need to restart the service(s) and re-upload the Interaction Model to the [Amazon Developer Portal] before all changes will take effect! 97 | 98 | # Additional considerations: 99 | - Avoid running everything on a single box! We do not recommend exposing your Home Automation controller directly to the Internet! 100 | - Lock down your webserver as much as possible, only allow the AWS ASK IP's to access Alexa-HA (which may vary) 101 | - Setup UFW to allow the Alexa-HA server to communicate ONLY with the gateway and the HA controller 102 | - Enable production server flags to hide version numbers for all services 103 | - Setup fail2ban, to pro-actively block clients by IP which make too many requests to the service in a short period of time 104 | 105 | [//]: # 106 | 107 | [Alexa-HA]: 108 | 109 | [node.js]: 110 | [npm]: 111 | [alexa-app]: 112 | [alexa-app-server]: 113 | [request]: 114 | [pm2]: 115 | 116 | [patch]: 117 | 118 | [OpenHAB]: 119 | [Wolfram Alpha]: 120 | 121 | [Amazon Developer Portal]: 122 | [AWS Lambda]: 123 | [tutorial]: 124 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Eclipse Public License - v 1.0 2 | 3 | THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC 4 | LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM 5 | CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. 6 | 7 | 1. DEFINITIONS 8 | 9 | "Contribution" means: 10 | 11 | a) in the case of the initial Contributor, the initial code and documentation 12 | distributed under this Agreement, and 13 | b) in the case of each subsequent Contributor: 14 | i) changes to the Program, and 15 | ii) additions to the Program; 16 | 17 | where such changes and/or additions to the Program originate from and are 18 | distributed by that particular Contributor. A Contribution 'originates' 19 | from a Contributor if it was added to the Program by such Contributor 20 | itself or anyone acting on such Contributor's behalf. Contributions do not 21 | include additions to the Program which: (i) are separate modules of 22 | software distributed in conjunction with the Program under their own 23 | license agreement, and (ii) are not derivative works of the Program. 24 | 25 | "Contributor" means any person or entity that distributes the Program. 26 | 27 | "Licensed Patents" mean patent claims licensable by a Contributor which are 28 | necessarily infringed by the use or sale of its Contribution alone or when 29 | combined with the Program. 30 | 31 | "Program" means the Contributions distributed in accordance with this 32 | Agreement. 33 | 34 | "Recipient" means anyone who receives the Program under this Agreement, 35 | including all Contributors. 36 | 37 | 2. GRANT OF RIGHTS 38 | a) Subject to the terms of this Agreement, each Contributor hereby grants 39 | Recipient a non-exclusive, worldwide, royalty-free copyright license to 40 | reproduce, prepare derivative works of, publicly display, publicly 41 | perform, distribute and sublicense the Contribution of such Contributor, 42 | if any, and such derivative works, in source code and object code form. 43 | b) Subject to the terms of this Agreement, each Contributor hereby grants 44 | Recipient a non-exclusive, worldwide, royalty-free patent license under 45 | Licensed Patents to make, use, sell, offer to sell, import and otherwise 46 | transfer the Contribution of such Contributor, if any, in source code and 47 | object code form. This patent license shall apply to the combination of 48 | the Contribution and the Program if, at the time the Contribution is 49 | added by the Contributor, such addition of the Contribution causes such 50 | combination to be covered by the Licensed Patents. The patent license 51 | shall not apply to any other combinations which include the Contribution. 52 | No hardware per se is licensed hereunder. 53 | c) Recipient understands that although each Contributor grants the licenses 54 | to its Contributions set forth herein, no assurances are provided by any 55 | Contributor that the Program does not infringe the patent or other 56 | intellectual property rights of any other entity. Each Contributor 57 | disclaims any liability to Recipient for claims brought by any other 58 | entity based on infringement of intellectual property rights or 59 | otherwise. As a condition to exercising the rights and licenses granted 60 | hereunder, each Recipient hereby assumes sole responsibility to secure 61 | any other intellectual property rights needed, if any. For example, if a 62 | third party patent license is required to allow Recipient to distribute 63 | the Program, it is Recipient's responsibility to acquire that license 64 | before distributing the Program. 65 | d) Each Contributor represents that to its knowledge it has sufficient 66 | copyright rights in its Contribution, if any, to grant the copyright 67 | license set forth in this Agreement. 68 | 69 | 3. REQUIREMENTS 70 | 71 | A Contributor may choose to distribute the Program in object code form under 72 | its own license agreement, provided that: 73 | 74 | a) it complies with the terms and conditions of this Agreement; and 75 | b) its license agreement: 76 | i) effectively disclaims on behalf of all Contributors all warranties 77 | and conditions, express and implied, including warranties or 78 | conditions of title and non-infringement, and implied warranties or 79 | conditions of merchantability and fitness for a particular purpose; 80 | ii) effectively excludes on behalf of all Contributors all liability for 81 | damages, including direct, indirect, special, incidental and 82 | consequential damages, such as lost profits; 83 | iii) states that any provisions which differ from this Agreement are 84 | offered by that Contributor alone and not by any other party; and 85 | iv) states that source code for the Program is available from such 86 | Contributor, and informs licensees how to obtain it in a reasonable 87 | manner on or through a medium customarily used for software exchange. 88 | 89 | When the Program is made available in source code form: 90 | 91 | a) it must be made available under this Agreement; and 92 | b) a copy of this Agreement must be included with each copy of the Program. 93 | Contributors may not remove or alter any copyright notices contained 94 | within the Program. 95 | 96 | Each Contributor must identify itself as the originator of its Contribution, 97 | if 98 | any, in a manner that reasonably allows subsequent Recipients to identify the 99 | originator of the Contribution. 100 | 101 | 4. COMMERCIAL DISTRIBUTION 102 | 103 | Commercial distributors of software may accept certain responsibilities with 104 | respect to end users, business partners and the like. While this license is 105 | intended to facilitate the commercial use of the Program, the Contributor who 106 | includes the Program in a commercial product offering should do so in a manner 107 | which does not create potential liability for other Contributors. Therefore, 108 | if a Contributor includes the Program in a commercial product offering, such 109 | Contributor ("Commercial Contributor") hereby agrees to defend and indemnify 110 | every other Contributor ("Indemnified Contributor") against any losses, 111 | damages and costs (collectively "Losses") arising from claims, lawsuits and 112 | other legal actions brought by a third party against the Indemnified 113 | Contributor to the extent caused by the acts or omissions of such Commercial 114 | Contributor in connection with its distribution of the Program in a commercial 115 | product offering. The obligations in this section do not apply to any claims 116 | or Losses relating to any actual or alleged intellectual property 117 | infringement. In order to qualify, an Indemnified Contributor must: 118 | a) promptly notify the Commercial Contributor in writing of such claim, and 119 | b) allow the Commercial Contributor to control, and cooperate with the 120 | Commercial Contributor in, the defense and any related settlement 121 | negotiations. The Indemnified Contributor may participate in any such claim at 122 | its own expense. 123 | 124 | For example, a Contributor might include the Program in a commercial product 125 | offering, Product X. That Contributor is then a Commercial Contributor. If 126 | that Commercial Contributor then makes performance claims, or offers 127 | warranties related to Product X, those performance claims and warranties are 128 | such Commercial Contributor's responsibility alone. Under this section, the 129 | Commercial Contributor would have to defend claims against the other 130 | Contributors related to those performance claims and warranties, and if a 131 | court requires any other Contributor to pay any damages as a result, the 132 | Commercial Contributor must pay those damages. 133 | 134 | 5. NO WARRANTY 135 | 136 | EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN 137 | "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR 138 | IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, 139 | NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each 140 | Recipient is solely responsible for determining the appropriateness of using 141 | and distributing the Program and assumes all risks associated with its 142 | exercise of rights under this Agreement , including but not limited to the 143 | risks and costs of program errors, compliance with applicable laws, damage to 144 | or loss of data, programs or equipment, and unavailability or interruption of 145 | operations. 146 | 147 | 6. DISCLAIMER OF LIABILITY 148 | 149 | EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY 150 | CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, 151 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION 152 | LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 153 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 154 | ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE 155 | EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY 156 | OF SUCH DAMAGES. 157 | 158 | 7. GENERAL 159 | 160 | If any provision of this Agreement is invalid or unenforceable under 161 | applicable law, it shall not affect the validity or enforceability of the 162 | remainder of the terms of this Agreement, and without further action by the 163 | parties hereto, such provision shall be reformed to the minimum extent 164 | necessary to make such provision valid and enforceable. 165 | 166 | If Recipient institutes patent litigation against any entity (including a 167 | cross-claim or counterclaim in a lawsuit) alleging that the Program itself 168 | (excluding combinations of the Program with other software or hardware) 169 | infringes such Recipient's patent(s), then such Recipient's rights granted 170 | under Section 2(b) shall terminate as of the date such litigation is filed. 171 | 172 | All Recipient's rights under this Agreement shall terminate if it fails to 173 | comply with any of the material terms or conditions of this Agreement and does 174 | not cure such failure in a reasonable period of time after becoming aware of 175 | such noncompliance. If all Recipient's rights under this Agreement terminate, 176 | Recipient agrees to cease use and distribution of the Program as soon as 177 | reasonably practicable. However, Recipient's obligations under this Agreement 178 | and any licenses granted by Recipient relating to the Program shall continue 179 | and survive. 180 | 181 | Everyone is permitted to copy and distribute copies of this Agreement, but in 182 | order to avoid inconsistency the Agreement is copyrighted and may only be 183 | modified in the following manner. The Agreement Steward reserves the right to 184 | publish new versions (including revisions) of this Agreement from time to 185 | time. No one other than the Agreement Steward has the right to modify this 186 | Agreement. The Eclipse Foundation is the initial Agreement Steward. The 187 | Eclipse Foundation may assign the responsibility to serve as the Agreement 188 | Steward to a suitable separate entity. Each new version of the Agreement will 189 | be given a distinguishing version number. The Program (including 190 | Contributions) may always be distributed subject to the version of the 191 | Agreement under which it was received. In addition, after a new version of the 192 | Agreement is published, Contributor may elect to distribute the Program 193 | (including its Contributions) under the new version. Except as expressly 194 | stated in Sections 2(a) and 2(b) above, Recipient receives no rights or 195 | licenses to the intellectual property of any Contributor under this Agreement, 196 | whether expressly, by implication, estoppel or otherwise. All rights in the 197 | Program not expressly granted under this Agreement are reserved. 198 | 199 | This Agreement is governed by the laws of the State of New York and the 200 | intellectual property laws of the United States of America. No party to this 201 | Agreement will bring a legal action under this Agreement more than one year 202 | after the cause of action arose. Each party waives its rights to a jury trial in 203 | any resulting litigation. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # DEPRECATED 2 | This project is no longer being maintained; in favor of OpenHAB's official Alexa Skill: 3 | 4 | https://www.openhab.org/docs/ecosystem/alexa/ 5 | 6 | # ALEXA HOME AUTOMATION 7 | Alexa HA provides tight integration between [Amazon Echo] and your Home Automation. This free and open source Skill for has been developed using the [Alexa Skills Kit]. Amazon Echo combined with the Alexa-HA Skill and a supported Home Automation solution delivers voice control and verbal feedback for practically anything in your home and beyond! The key feature highlights include: 8 | 9 | - Switch any controllable device - appliances/lights/fans/locks/shutters/etc 10 | - Set light colors individually; by room or group 11 | - Control light dimmer levels individually; by room or group 12 | - Set thermostat(s) target temperature 13 | - Get device states (i.e. temperature/humidity/luminance/power consumption, etc) 14 | - Set scenes/modes (i.e. home/lighting/security/etc) 15 | - Get scene modes (i.e. 'check current house mode', could be home/away/relax/gaming/party/sleep, etc) 16 | - Trigger custom server side rules and return a response which is spoken by the Echo (i.e. say 'watch a movie' automatically sets up your Home Theater by powering on the Projector/AV Receiver/HTPC, lowering the Projector Screen, dimming the lights, etc.) 17 | - Research virtually anything via voice through [Wolfram Alpha] API 18 | - Display useful 'cards' in the Alexa App 19 | - Automatically generates the Skill '[utterances]' based on configured devices/rooms, which trains Echo voice model for boosted accuracy 20 | - Crude support for Text-To-Speech 'announcements' by pairing the Echo with your HA server over Bluetooth 21 | 22 | The current version is focused on perfecting support for [OpenHAB]; other HA solutions may be added in the future. OpenHAB v1.x is currently well tested and supported, OpenHAB v2.x support is coming in due time. 23 | 24 | ### TECHNOLOGY STACK 25 | Alexa HA's technology stack is primarily comprised of the following key open source projects: 26 | 27 | * [node.js] - evented I/O for the backend 28 | * [alexa-app] - A Node.js module to simplify creation of Alexa (Amazon Echo) apps (Skills) using Node.js 29 | * [request] - A Node.js module for making HTTP(S) requests 30 | 31 | Your HA Controller does the heavy lifting of integrating with various downstream technologies/protocols, and Amazon Echo combined with the Alexa HA Skill translates your voice commands into HA actions. 32 | 33 | ### INSTALLATION & DEPLOYMENT 34 | Alexa HA uses the Alexa Skills Kit to communicate with your internal HA server. The Skill can be deployed in numerous ways, including: 35 | 36 | * Semi-direct (i.e. Echo -> AWS ASK -> NodeJS/Express -> HA) 37 | * Proxied through a webserver (i.e. Echo -> AWS ASK -> Apache/Nginx -> NodeJS -> HA) 38 | * In-cloud via [AWS Lambda] micro services (i.e. Echo -> AWS ASK -> AWS Lambda -> HA) 39 | 40 | To get started ASAP, see [INSTALL-QUICKSTART.md] to for setting up the Semi-direct approach. We generally prefer the second option of self-hosting a webserver and NodeJS application on the same network as your HA server/appliance, which proxies most of the communication internally behind a web server for improved security and control. In all cases external SSL encryption is required through proper trusted CA's or self signed certificates. Between the SSL transport encryption, custom application checks that confirm the requestors AWS ASK applicationId and userId match the configuration, as well as tracking all requestIds for audit trails, strong security is enforced. This ensures you and only your Echo(s) can issue commands to your HA controller. 41 | 42 | Note that due to the Amazon Echo/Alexa architecture it is NOT possible to keep everything on your local network - the voice processing must be conducted in the cloud, and you are currently required to setup port forwarding on your firewall to allow AWS access to an internally hosted application. The AWS ASK service then issues commands to your HA controller through your public facing endpoint. 43 | 44 | Currently you cannot simply install Alexa HA through the Alexa App's Skills page, rather its currently required to setup your own Skill through the [Amazon Developer Portal]. We are publishing this as an official Alexa App in due time. In some ways self-hosting is advantageous as you can better customize the skill to your homes layout, desired scenes and controllable devices. You can also personalize the skill 'Invocation Name'. To get started with configuring your own Alexa HA skill, see: 45 | * [Getting started with Alexa Skills Kit] 46 | * [INSTALL-QUICKSTART.md] 47 | * [INSTALL.md] 48 | 49 | ### VERSION HISTORY 50 | * 0.1.8 (09/29/2016) - Updated documentation 51 | * 0.1.7 (04/01/2016) - Added support for volume controls, minor bug fixes, documentation fixes & refinements 52 | * 0.1.6 (03/09/2016) - Log audit trails, added 'password' as an endpoint URL parameter, stub settings for controlling locks & roller shutters, stub settings for checking outdoor Temp/Humidity 53 | * 0.1.5 (03/07/2016) - Interaction Model expansion, validation/error handling improvements, documentation refinements, and new ability to 'GetMode' 54 | * 0.1.0 (02/29/2016) - Initial public release! 55 | 56 | ### LICENSE 57 | ---- 58 | 59 | [Eclipse Public License v1.0] 60 | 61 | [//]: # 62 | 63 | [node.js]: 64 | [alexa-app]: 65 | [alexa-app-server]: 66 | [express.js]: 67 | [request]: 68 | 69 | [Amazon Echo]: 70 | [OpenHAB]: 71 | [Wolfram Alpha]: 72 | 73 | [Alexa Skills Kit]: 74 | [AWS Lambda]: 75 | 76 | [EchoSim]: 77 | [Getting started with Alexa Skills Kit]: 78 | [Amazon Developer Portal]: 79 | [INSTALL.md]: 80 | [INSTALL-QUICKSTART.md]: 81 | 82 | [utterances]: 83 | 84 | [PayPal]: 85 | 86 | [Eclipse Public License v1.0]: 87 | -------------------------------------------------------------------------------- /config_default.js: -------------------------------------------------------------------------------- 1 | /* Default Alexa HA configuration file. Copy this to 'config.js' and adapt as needed! */ 2 | var config = {}; 3 | 4 | /******************************** GENERAL CONFIGURATION *****************************************/ 5 | // Name of the application/skill, which does not need to match the skills 'Invocation Name', 6 | // Defines both the Alexa-App-Server endpoint and the skills own name used in cards. 7 | config.applicationName = 'Alexa-HA'; 8 | 9 | // AWS ASK applicationId, resembles 'amzn1.echo-sdk-ams.app.[your-unique-value-here]' 10 | config.applicationId = 'amzn1.echo-sdk-ams.app.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; 11 | 12 | // AWS ASK userID, resembles 'amzn1.echo-sdk-account.[your-unique-value-here]' 13 | config.userId = 'amzn1.echo-sdk-account.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; 14 | 15 | // AWS ASK password, randomly generated password to be included in the Skill's endpoint URL (i.e. '?password=XXXXXXXXXXXX') 16 | config.password = 'XXXXXXXXXXXX'; 17 | 18 | // Greeting, when saying 'Alexa, open...' 19 | config.greeting = "OpenHAB, at your service"; 20 | 21 | // URL of an MP3 to play when opening the skill (optional; must be MPEG v2 codec / 48kbps bit rate / 16000 sample rate) 22 | //config.chime = "\