Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/joeyhage/homebridge-alexa-smarthome

Connect Alexa devices to HomeKit
https://github.com/joeyhage/homebridge-alexa-smarthome

alexa echo homebridge homebridge-plugin homekit smarthome

Last synced: 6 days ago
JSON representation

Connect Alexa devices to HomeKit

Awesome Lists containing this project

README 

        


  homebridge-logo






  

    License

  

    Build, lint, and test





  

    npm version

  

    npm downloads





  

    verified-by-homebridge

  

    Discord




# Homebridge Alexa Smart Home



This plugin enables smart home device integration between HomeKit and Alexa which allows HomeKit/Siri to control smart home devices that are connected via Amazon Alexa.



This plugin **does not** allow Alexa to control devices in HomeKit. For that, please see the [Homebridge Alexa](https://github.com/NorthernMan54/homebridge-alexa) plugin.



## Table of Contents



- [Compatibility](#compatibility)

- [Currently supported devices](#currently-supported-devices)

- [Features](#features)

  - [Air quality monitors](#air-quality-monitors)

- [Initial configuration](#initial-configuration)

- [Common issues](#common-issues)

- [Support](#support)

- [Contributing](#contributing)

- [Long-term support](#long-term-support)

- [Thanks](#thanks)

- [Disclaimer](#disclaimer)



## Compatibility



Compatibility is not guaranteed with HOOBS and I am unable to provide support for HOOBS users since I do not use HOOBS.



Node.js versions supported: 16.x, 18.x, 20.x



## Currently supported devices



- Lightbulbs

- Switches

  - HomeKit switches do not support brightness so any switches you have that support brightness will appear in HomeKit as Lightbulbs.

- Fans

- Outlets + smart plugs

- Thermostats

- Locks

- Air Quality Monitors

  - Only confirmed to work with Amazon Air Quality Monitor. Please report an issue if it doesn't work with your air quality monitor.

- Device types not listed above that support on/off will be added as switches. For example:

  - Air fresheners

  - Vacuum cleaners

  - Game consoles

- [Request / vote](https://homebridge-alexa-smarthome.canny.io/feedback?selectedCategory=supported-device-types) on device types you would like to see supported.



## Features



- Devices already linked to your Alexa account can be integrated with HomeKit automatically.

- Only Amazon credentials needed to configure this plugin rather than credentials for all your devices.

- This plugin does not store your Amazon username or password. Instead, it uses session cookies that are valid for up to 14 days. This plugin will automatically refresh the session cookie before it expires.



### Air quality monitors



All of the following are supported depending on what your device measures:



- Air quality score (Excellent / Fair / Poor)

- Particulate matter density (PM2.5)

- VOC Density

- Carbon monoxide levels

- Relative humidity percent

- Temperature



When you first add an Air Quality Monitor to HomeKit, the above measurements may appear in the Default Room but can be assigned to any room you choose.



## Initial configuration



The first time this plugin starts, you will need to authenticate using your Amazon Alexa account. Please follow these steps in order - screenshots included.



1. Verify that your plugin configuration is correct. Specifically, the proxy `clientHost` and `port`. The `clientHost` should be the same host you use to access homebridge. For example, if you access homebridge via the url `http://my-homebridge-server.local:8581` then `clientHost` should be `my-homebridge-server.local`. The `port` should be a different value from homebridge (not 8581). Restart Homebridge if you made any changes to the settings.

   1. It is highly recommended to explicitly provide in the plugin settings the device names you wish to use with this plugin. The plugin performs much better this way.

   2. ![config screenshot](./docs/img/1-config.png)

2. Download the Alexa app onto a device of your choosing (smartphone, tablet, etc) and sign in using the Amazon account your devices are linked to. Confirm the `amazonDomain` plugin setting matches what you see in the Alexa app. Go to Settings -> About, scroll to the bottom, and look for Host Name. The Host Names you see should end with the `amazonDomain` you choose in the plugin settings, it will not match exactly.

   1. Alexa app settings

   2. Alexa app host

3. **This plugin may not work and support or help troubleshooting will not be provided** if you do not use multi-factor authentication / two-step verification or if you use SMS for the verification code. Again, SMS two step verification will **not** work. Please download an authenticator app such as AWS Virtual MFA, Google Authenticator, Microsoft Authenticator and follow the instructions to enable two step verification on Amazon's website.

4. Check the homebridge logs for an error that you must manually open the url to authenticate.

   1. ![failed to initialize screenshot](./docs/img/2-failed-to-initialize.png)

5. Visit the url in your browser to open a login screen. If you open the url from a mobile device the Alexa App is installed on, it may not work because Amazon might open the Alexa App. It is recommended to use a device, preferably a computer, the Alexa App is not installed on. When the page loads, it is a real login screen proxied so the plugin can capture the session cookie. The username/password are not stored by the plugin.

   1. ![login screenshot](./docs/img/3-alexa-login.png)

6. Enter your MFA code if you have MFA enabled on your Amazon Alexa account. Again, the plugin does not store this value.

   1. ![mfa screenshot](./docs/img/4-alexa-mfa.png)

7. If successful, you should see a message that the Amazon Alexa cookie was successfully retrieved. If you see a 404 page, return to step 3 and start over.

   1. ![login successful screenshot](./docs/img/5-login-success.png)

8. The homebridge logs will also show a message such as "Successfully authenticated Alexa account".

   1. ![authentication successful screenshot](./docs/img/6-homebridge-success.png)



## Common issues



  Alexa login errors or Failed to initialize connection to Alexa.`

  
    

        
  1. Please ensure you have the Alexa app installed on your device (iPhone, iPad, etc).
    2. 

        
  2. Please download an authenticator app such as AWS Virtual MFA, Google Authenticator, Microsoft Authenticator and follow the instructions to enable two step verification on Amazon's website. SMS two-step verification does not work with this plugin.
    3. 

        
  3. Try using a computer to access the proxy url
    4. 

        
  4. See Troubleshooting for the Alexa Remote project, which this plugin relies on.
    5. 

        
  5. Repeat initial configuration steps again.
    6. 

        
  6. Delete the persist/.homebridge-alexa-smarthome file in your homebridge installation directory and then restart Homebridge.
    7. 

        
  7. Try an incognito window with Javascript disabled. Detailed instructions

    8. 

      



  This plugin slows down Homebridge

  Please update the Performance section of the plugin settings. More information can be found on the plugin settings page.



  I can't find my device in HomeKit/Apple Home app.

  
    

        
  • Please check the Default Room for the device. Air quality, humidity, and temperature sensors appear as statuses at the top of the room, not as device tiles.
    • 

        
  • Double check the name of the device in the Alexa app matches the name specified in the plugin settings. Spaces, uppercase, and lowercase matter.
    • 

      



## Support



Please visit the [Canny feedback board](https://homebridge-alexa-smarthome.canny.io/feedback) first to see if your issue or request is currently being worked on. You can also suggest new features and vote on features requested by others.



If you run into issues or you need help please use the [issues template](https://github.com/joeyhage/homebridge-alexa-smarthome/issues/new/choose). Fill all the relevant sections and submit your issue. It is important that you use the templates because I will automatically be assigned to your issue and I will receive an email. If you use the blank template without assigning me, I will most likely miss the Github notification.



## Contributing



Please see [CONTRIBUTING.md](./CONTRIBUTING.md) and [PULL_REQUEST_TEMPLATE.md](./.github/PULL_REQUEST_TEMPLATE.md)



## Long-term support



Please consider supporting the development of this plugin by sponsoring me. Sponsorship will encourage me to continue improving this plugin, support more devices, adapt to changes in the Alexa API, and fuel my late-night coding sessions. :coffee:



## Thanks



A huge thanks is due to Apollon77 for maintaining alexa-remote2, alexa-cookie2, and ioBroker.alexa2. This plugin is made possible due to those projects.



## Disclaimer



- I am not affiliated with Amazon nor any of the device brands and this plugin is a personal project that I maintain in my free time

- Use this plugin entirely at your own risk

- Please see license for more information