Skip to content

Configuration

Jump to bottom Edit New page
Daniel edited this page Nov 16, 2024 · 53 revisions

Table of contents generated with markdown-toc

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.

Built-in 2FA App

Requires >= 3.3.0

WARNING: By using this, your configuration files in Home Assistant will have all information to log into your Amazon account since it will have your password and the key to generate 2FA codes. Anyone who gets a copy of your core.config_entries file will be able to log in as you.

Instead of using a separate 2FA code, you can also register a 2FA app with Alexa Media Player.

  1. Go to Amazon.com's 2FA page and Add new App. You should save this key so you can reuse it if you reinstall.
  2. Instead of scanning the QR code, select Can't scan the barcode.
  3. Select the bolded value under Enter your Key (e.g., 35T5 LQSY I5IO 3EFQ LGAJ I6YB JWBY JJPR PYT7 XPPW IDAK SQBJ CVXA)(Remove spaces)
  4. Enter the value from Step 3 in the Built-in 2FA App Key when adding the integration. 2FA should be automatically generated from now on and can be left blank.
  5. (Optional) All these steps only add another authentication method but do not activate 2FA. In case you haven’t enabled 2FA yet, follow Amazon's instructions.

NOTE: If you are using a public URL, such as one through duckdns.org, but get an error, try using your local url (e.g., "http://192.168.0.123:8123/").

Update HA to 0.88.0 or above.

The latest build will only work on HA >= 0.88.0. 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

Copy the custom_components/alexa_media directory from the latest release to your custom_components directory.

Alternatively, you can 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. Please also ensure the translations directories are copied and you hard refresh your browser to avoid blanks on the form.

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

config
  custom_components
    alexa_media
      .translations
        *.json
      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 installed, 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/2FA)
    1. As of 3.5.0, the default login mode is by using the login proxy method which will allow a login through Amazon's UI. Disable if you prefer the legacy method.
    2. As of 3.5.0, you can also use the non oauth-token login method by disabling the option. This is the default method from 3.4.1 and below which imitated the webapp but also reported reauth problems. Oauth token is how the mobile apps login and in theory will not have that problem.
  5. No reboot is required. You can relogin or change the password/settings by deleting and re-adding on this page without impacting any automations/scripts.

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

Warning: Cookie method will not allow an oauth token which could result in frequent reauths.

  1. Find a tool to export cookies from your browser in a cookies.txt.
  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 (i.e. not the commented out lines) from the cookies.txt into the Cookies.txt Data field during Integration setup.

Alternatively, you can copy the cookies.txt to /config/.storage/alexa_media.{account}.txt before adding the component.

Configuration.yaml

<<< To be deprecated as of v4.14.0 >>>

While this currently still works, it is completely unsupported and any issues encountered will NOT be fixed. Please use Integrations to add Alexa Media Player.

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. If the CAPTCHA does not appear, enter anything (e.g. 123456) in the CAPTCHA field and submit. That should cause the CAPTCHA to appear. Then, you may need to enter the password, CAPTCHA, and 2FA and click submit multiple times before it is accepted. 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

Requires >= 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

<<< "yaml" config will be deprecated as of v4.14.0 >>>

Exclusions

<<< "yaml" config will be deprecated as of v4.14.0 >>>

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.

<<< "yaml" config will be deprecated as of v4.14.0 >>>

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

Requires >= 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

Requires >= 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