INFRAESTRUCTURA/docs/home-assistant-setup-alexa.md

Home Assistant + Alexa: Guía completa de configuración

Resumen

Home Assistant instalado en el VPS Contabo para controlar luces de Alexa ("barras" y "cuartillo") de forma gratuita e ilimitada, reemplazando VoiceMonkey.

---

1. Instalación (YA HECHA)

Home Assistant corre en el VPS en modo network_mode: host:

# /opt/homeassistant/docker-compose.yml
services:
  homeassistant:
    container_name: homeassistant
    image: homeassistant/home-assistant:2025.1
    restart: unless-stopped
    network_mode: host
    environment:
      - TZ=Europe/Madrid
    volumes:
      - ./config:/config

URL de acceso: http://185.187.169.109:8123

---

2. Configuración inicial (WIZARD)

Al acceder por primera vez a http://185.187.169.109:8123:

1. Crear cuenta admin:

   • Nombre: admin (o el que quieras)
   • Usuario: admin
   • Contraseña: (guardarla en Engram)

2. Configuración básica:

   • Nombre de la casa: Casa Juanjo (o el que quieras)
   • Ubicación: Madrid, España
   • Zona horaria: Europe/Madrid (ya configurada)
   • Unidades: Métricas

3. Saltar la detección automática de dispositivos (lo haremos manualmente)

---

3. Instalar HACS (Home Assistant Community Store)

HACS es necesario para instalar Alexa Media Player.

Método 1: Script automático (RECOMENDADO)

# Desde el VPS
docker exec -it homeassistant bash
wget -O - https://get.hacs.xyz | bash -
exit
docker restart homeassistant

Método 2: Manual

1. Acceder a http://185.187.169.109:8123
2. Settings → Devices & Services → Add Integration
3. Buscar "HACS"
4. Seguir el wizard (pide vincular con GitHub)

Reiniciar Home Assistant después de instalar HACS.

---

4. Instalar Alexa Media Player

1. Abrir HACS:

   • Settings → Devices & Services → HACS

2. Buscar "Alexa Media Player":

   • HACS → Integrations → Explore & Download Repositories
   • Buscar: Alexa Media Player
   • Download

3. Reiniciar Home Assistant:

   • Settings → System → Restart

4. Añadir la integración:

   • Settings → Devices & Services → Add Integration
   • Buscar: Alexa Media Player
   • Introducir credenciales de Amazon (usuario/contraseña)
   • Si pide 2FA: introducir el código que llegue al móvil/email

5. Verificar dispositivos detectados:

   • Settings → Devices & Services → Alexa Media Player
   • Debería aparecer el Echo Dot y las luces "barras" y "cuartillo"

---

5. Generar API Token (Long-Lived Access Token)

1. Ir al perfil de usuario:

   • Click en tu nombre (esquina inferior izquierda)
   • Scroll hasta "Long-Lived Access Tokens"

2. Crear token:

   • Click en "Create Token"
   • Nombre: Protocolo Apagado PC
   • Copiar el token (aparece una sola vez)

3. Guardar el token en .env:

   HOMEASSISTANT_URL=http://185.187.169.109:8123
   HOMEASSISTANT_TOKEN=<token-copiado>
   

---

6. Probar el control de luces (desde el PC)

Script de prueba Python:

import requests
import os
from dotenv import load_dotenv

load_dotenv()

url = os.getenv("HOMEASSISTANT_URL")
token = os.getenv("HOMEASSISTANT_TOKEN")

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Apagar "barras"
response = requests.post(
    f"{url}/api/services/light/turn_off",
    headers=headers,
    json={"entity_id": "light.barras"}
)
print(f"Barras: {response.status_code}")

# Apagar "cuartillo"
response = requests.post(
    f"{url}/api/services/light/turn_off",
    headers=headers,
    json={"entity_id": "light.cuartillo"}
)
print(f"Cuartillo: {response.status_code}")

Ejecutar:

python C:\Users\juanm\Documents\Github\INFRAESTRUCTURA\scripts\test_homeassistant.py

Resultado esperado:

Barras: 200
Cuartillo: 200

---

7. Actualizar el protocolo de apagado

Una vez verificado que funciona, actualizar protocolo_apagado.py y protocolo_apagado_test.py para usar Home Assistant en lugar de VoiceMonkey.

El script final está en INFRAESTRUCTURA/scripts/protocolo_apagado_homeassistant.py.

---

8. Troubleshooting

Problema: Alexa Media Player no detecta las luces

Solución:

1. Verificar que las luces estén configuradas en la app Alexa
2. Ir a Settings → Devices & Services → Alexa Media Player → Options
3. Marcar "Include devices" (por defecto solo incluye Echos)
4. Reload integration

Problema: Entity IDs incorrectos

Las luces pueden tener IDs diferentes. Para verificar:

import requests
url = "http://185.187.169.109:8123/api/states"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
lights = [e for e in response.json() if e["entity_id"].startswith("light.")]
for light in lights:
    print(light["entity_id"], light["attributes"].get("friendly_name"))

Problema: 401 Unauthorized

• Token incorrecto o expirado
• Regenerar el token en Home Assistant

Problema: Alexa pide re-autenticación

• Login caducado (cada ~2 semanas)
• Re-login en Settings → Devices & Services → Alexa Media Player → Configure

---

Referencias

• Home Assistant: https://www.home-assistant.io/
• Alexa Media Player: https://github.com/custom-components/alexa_media_player
• HACS: https://hacs.xyz/
• API REST: https://developers.home-assistant.io/docs/api/rest/