Installation and Configuration

Installation and Configuration

(Versions >= 1.0.0)

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.

Download python files

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
      const.py
      media_player.py
      notify.py

Configure HA

Once there 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 has been 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

WARNING: When you update to 1.0.0 from 0.x.y, you may have your entities added as entity_id_2. Rename those entities in Home Assistant and restart to get your old entity names again. This way you don’t have to change your automations.

Please note that for version 1.0.0 and greater, all other instructions should use the alexa_media domain and not the media_player domain.

Enable Notify Component (Versions > 1.2.0)

To use notification features, enable it.

(Versions < 1.0.0)

WARNING: This version is for historical reference only. This will only work for HA < 0.89.0 and is unsupported.

First thing is to download the media_player alexa.py file from the 0.x.y branch. This file will be placed in your config directory under a folder named custom_components/media_player. If these folders do not exist you need to add them.

Once there you’ll need to update your config to include the following:

media_player:
  - platform: alexa
    email: your amazon email
    password: your amazon password
    url: amazon.com

Once set, restart home assistant and you should see all your Alexa devices in home assistant. Amazon may require additional steps like a Captcha or 2FA. In this case, home assistant will provide a configurator to guide you through final installation.

Configuring Inclusions or Exclusions (versions >= 0.9.6)

Starting with version 0.9.6 you have the ability to only include or exclude devices. 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"}]}

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

Alternatively, you can only include specific devices using the include_devices key. 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 picked up.

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

Last called device (versions >= 0.10.0)

Each device will report an attribute on whether it is the last_called device or not. This allows us to identify the device that was called according to the Alexa Activities API. This is updated based on the scan_interval.

Here is an example to create a sensor based off the attribute.

Creating sensor.last_alexa

- platform: template
  sensors:
    last_alexa:
      entity_id:
        - media_player.YOUR_ECHO_1
        - media_player.YOUR_ECHO_2
      value_template: >
        {{ states.media_player | selectattr('attributes.last_called','eq',True) | map(attribute='entity_id') | first }}

Setting the volume for the last called device at a certain level

This can be useful, if you want to set up different volume levels for different echos. For example the echo dot second gen is much quieter at volume 0.3 than a echo dot third gen. So you probably want to set a higher volume for the second gen echo dot.

In script.yaml

alexa_set_volume:
  sequence:
    - service: media_player.volume_set
      data_template: 
        entity_id: '{{ states.sensor.last_alexa.state }}' 
        volume_level: >
          {% if is_state("sensor.last_alexa", "media_player.echo_dot_second_gen") %}
            0.5
          {% else %}
            0.3
          {% endif %} 

Send a tts to the last called alexa device:

Call this script in your automation. Turn on an input boolean or a dummy bulb with an alexa routine and use this as trigger for your automation.

Note: I am not sure if the delays are necessary.

In script.yaml:

alexa_tts:
  sequence:
    - service: script.turn_on
      entity_id: script.alexa_set_volume
    - delay: '00:00:01'      
    - service: media_player.alexa_tts
      data_template:
        entity_id: '{{ states.sensor.last_alexa.state }}' 
        message: "YOUR MESSAGE"

Here is an example how the automation could look like:

- alias: Alexa Routine TTS
  initial_state: 'on'
  trigger:
    platform: state
    entity_id: light.alexa_dummy_bulb
    to: 'on'
  condition:
    - condition: template
      value_template: '{{ states.light.alexa_dummy_bulb.attributes.brightness == (1 * 255)//100 }}' # Replace 1 by the percentage you set in the alexa app
  action:
    - delay:
        seconds: 0.5  
    - service: alexa_media.update_last_called 
    - delay:
        seconds: 0.5  
    - service: homeassistant.turn_on
      data_template: 
        entity_id: >
          {% if is_state("binary_sensor.some_state", "on") %}
            script.some_state_on_tts
          {% else %}
            script.some_state_off_tts
          {% endif %}  

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