Installation and Configuration

Installation and Configuration

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.

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. After copying all files from the alexa_media directory, your configuration should look like:

config
  custom_components
    alexa_media
      __init__.py
      alarm_control_panel.py
      manifest.json
      const.py
      media_player.py
      notify.py
      services.yaml

Configure HA

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

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 have restart HA you need to complete the Captcha challenge to log in. You will be prompted with a notification alert on your dashboard. 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)

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”.

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 black 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