Skip to content

Configuration

Jump to bottom Edit New page
Alan Tse edited this page Sep 27, 2020 · 53 revisions

Installation and Configuration

Enable Two Factor Authentication for your Amazon account

Unless you're willing to debug the login errors yourself, you should only use an account with 2FA enabled. No help will be provided for login errors if 2FA is not enabled.

Follow Amazon's instructions. We strongly recommend that you use an authenticator app so you can generate your own OTP codes without relying on Amazon sending them to you.

Update HA to 0.88.0 or above.

The latest build will only work on HA >= 0.88.0. We are targeting that release now. If you need something for older versions of HA, see the 0.x.y branch.

Get the files

Easy Mode

Use HACS. This will also inform you when there are new releases and you can update easily. If installed this way, you can proceed to configuration either using the Integrations Page or Configuration.yaml (legacy).

Manual Mode

Reproduce the directory structure of the master branch in your config/custom_components directory to create the folder alexa_media. Please ensure you are using raw mode from GitHub if you are saving files from the webpage. Alternatively, it may be easiest to just copy the custom_components directory from a release.

After copying all files from the alexa_media directory, your configuration should look like:

config
  custom_components
    alexa_media
      .translations
        *.json
      __init__.py
      alarm_control_panel.py
      manifest.json
      const.py
      helpers.py
      media_player.py
      notify.py
      sensor.py
      services.yaml

Once the files are downloaded, you’ll need to configure the component.

Configure HA

Integrations Page

This is the preferred method.

As of 2.2.0, the component can be configured via the Integrations page in HA.

  1. Goto the Configuration -> Integrations page.
  2. On the bottom right of the page, click on the Orange + sign to add an integration.
  3. Search for Alexa Media Player. (If you don't see it, try refreshing your browser page to reload the cache.)
  4. Enter the required information. (Account/Password)

You can also import your cookies if you have logged in manually through the web-browser. This is probably the easiest method and may become the preferred method.

  1. No reboot is required. You can relogin or change the password/settings by deleting and re-adding on this page.

NOTE: If you receive an invalid credentials error and you have confirmed your credentials, check to confirm amazon didn't email you a temporary password.

Cookie import

Requires >= 3.1.0

  1. Find a tool to export cookies from your browser in a cookies.txt. Chrome
  2. Login to your Alexa webapp domain. US.
  3. Export your cookies.txt. It will look like this:
# HTTP Cookie File for amazon.com by Genuinous @genuinous.
# To download cookies for this tab click here, or download all cookies.
# Usage Examples:
#   1) wget -x --load-cookies cookies.txt "https://alexa.amazon.com/spa/index.html#cards"
#   2) curl --cookie cookies.txt "https://alexa.amazon.com/spa/index.html#cards"
#   3) aria2c --load-cookies cookies.txt "https://alexa.amazon.com/spa/index.html#cards"
#
alexa.amazon.com	FALSE	/spa	FALSE	253402300799	DISPLAY_DEPRECATION_BANNER_STATUS	false
...
  1. Copy and paste the raw text from the cookies.txt into the Cookies.txt Data field.

Configuration.yaml

While this still works, it will be deprecated in the future. Please use Integrations. Once the files are downloaded, you’ll need to update your config to include the following under the alexa_media domain:

alexa_media:
  accounts:
    - email: !secret amazon_user
      password: !secret amazon_password
      url: amazon.com

Us kiwi (New Zealander) and our aussie mates

url: amazon.com.au

restart and it works

Multiple accounts can be added:

alexa_media:
  accounts:
    - email: your amazon email
      password: your amazon password
      url: amazon.com
    - email: your second email
      password: your amazon password
      url: amazon.com

Captcha challenge

Once you restart HA you may need to complete the Captcha challenge to log in. If so, you will be prompted with a notification alert on your dashboard (on the left side). Complete the Captcha (which may require multiple pop-ups, checking email or your phone for 2FA) and restart again. Once this is complete you should now see the notify.alexa_media service and media_players.

Alexapy Dependency

Hass.io

If using hassio, after following the instructions restart 2x. First time will load the alexapy dependency but output an error. Second time the dependency will be enabled and the component will work as expected. Otherwise consider a manual install.

Advanced Configuration

Configuring Inclusions or Exclusions (versions >= 0.9.6)

HA now has the ability to use the Entity Registry to disable items. That may be the preferred mechanism and we may deprecate this at any time.

Starting with version 0.9.6 you have the ability to only include or exclude devices (e.g., media_player, switch, alarm_control_panel) in Home Assistant.

Finding names

The filters require a case-sensitive name and quotes if including spaces. You can discover the name by looking at the developer-tools/state in Home Assistant and reviewing the friendly_name attribute. If you ever want to determine if a device is being filtered (e.g., you use include_devices and don't see a new entity), you can discover what is being excluded by enabling debug logging on alexa_media.helpers and searching for the Excluding device: line.

2019-09-04 02:08:11 DEBUG (MainThread) [custom_components.alexa_media.helpers] a******e@g*******m: Excluding device: <Entity Guest Room shuffle switch: off>

The entity being excluded is "Guest Room shuffle switch".

Media players

The configuration file needs the Amazon name and not the homeassistant entity_id. To find the Amazon name, check the Alexa app or get it from the raw json from here (update to your region url. Specifically, look for the “accountName” attribute in the json response.

{"devices":[{"accountName":"Kitchen"},  {"accountName":"Stairs"}]}
Other devices

The configuration file needs the HA friendly name. Alexa Guard includes the last 5 digits of the serial number and is admittedly difficult to find without using debug logs. The other switches should follow a standard naming convention, e.g. “Echo Bedroom do not disturb switch”, “Echo Bedroom repeat switch”, “Echo Bedroom shuffle switch”.

Integration Page

Enter your devices during setup without spaces, comma-separated, and case-sensitive. Quotations are not needed.

This Device,Alan's Alexa Apps,Stairs,Garage,Master Bedroom repeat switch

Configuration.yaml

Exclusions

To exclude devices, you will need to exclude them with the exclude_devices key. Please note it is case sensitive and you will need to use quotations for entries with spaces.

alexa_media:
  accounts:
  - email: your amazon email
    password: your amazon password
    url: amazon.com
    exclude_devices:
      - "This Device"
      - "Alan's Alexa Apps"
      - Stairs
      - Garage
      - "Master Bedroom repeat switch"
Inclusions

Alternatively, you can only include specific devices using the include_devices key. NOTE: include_devices only loads devices that have been listed and functions like a deny list. If you don't include the Alexa guard or the switches, then you will not see them.

Inclusions and Exclusions at the same time

If you have both include_devices and exclude_devices, the exclude will only remove devices already included. So in the example below, only "Master Bedroom" will be added.

alexa_media:
  accounts:
  - email: your amazon email
    password: your amazon password
    url: amazon.com
    include_devices:
      - "Master Bedroom"
      - Stairs
    exclude_devices:
      - Stairs
      - Garage

Scan interval (versions >= 1.0.0)

The default scan_interval has been increased from 30 seconds to 60 seconds and is now configurable. There is still a non-user configurable hard limiter at 15 seconds.

Please be careful as each additional Alexa device on your network will contact Amazon and excessive flooding may result in Amazon throttling your account. As of 1.0.0, we have implemented countermeasures so media players will stop polling when idle. Polling will resume automatically if controlled via voice or through HA.

alexa_media:
  accounts:
  - email: your amazon email
    password: your amazon password
    url: amazon.com
    scan_interval: 30

Queue Delay (versions >= 2.6.0)

This is accessible through the Integrations -> Options.

Queue delay controls how long each command will wait to queue up other commands. This will help reduce too many requests errors but will delay running the command. The default is 1.5 seconds. 0 seconds will result in no queuing behavior.

Uninstalling Integration

If you wish to uninstall this integration, you can click Uninstall on the component in HACS. You must also remove the integration from your Integrations page, under Configuration > Integrations and from your configuration.yaml. If you do not complete this last step, you will get an error message every time you restart Home Assistant that says 'error setting up alexa_media'.

Add a custom footer
Clone this wiki locally