Scripts en Python para Home Assistant: Guía Definitiva de Pyscript y AppDaemon

Si has seguido nuestra trayectoria, ya has aprendido a organizar tu YAML en Packages y a crear flujos visuales en Node-RED. Tu casa es inteligente, sin duda.

Pero llega un momento en la vida de todo entusiasta de la domótica en el que te chocas contra un muro. Quieres hacer un cálculo matemático complejo, conectarte a una API rara de tu banco, o crear una lógica de calefacción que aprende de tus hábitos usando inteligencia artificial básica.

Ahí es donde la interfaz gráfica y el YAML fallan. Ahí es donde necesitas la artillería pesada: Python. En esta guía, vamos a ver cómo quitarle las rueditas a la bicicleta y empezar a pilotar un caza de combate usando Pyscript y AppDaemon.

¿Por qué abandonar la interfaz gráfica de Home Assistant?

La interfaz visual de Home Assistant ha mejorado enormemente, y para el 90% de los usuarios es suficiente. Pero tú no estás aquí para ser el 90%. Estás aquí porque quieres control absoluto.

La interfaz gráfica es una «Jaula de Oro». Es bonita, segura y fácil de usar, pero te impide salirte de los límites que los desarrolladores han decidido por ti. Escribir scripts en Python es abrir la puerta de esa jaula.

Las limitaciones de las automatizaciones YAML y el editor visual

Incluso si eres un maestro de Jinja2, te habrás encontrado con situaciones desesperantes:

• El infierno de los anidados: Intentar hacer un if/else complejo en YAML acaba en una pirámide de indentación ilegible.
• Falta de bucles reales: Aunque YAML tiene repeat, intentar procesar listas de datos complejas es doloroso y lento.
• Sin librerías externas: En YAML no puedes hacer import numpy para cálculos estadísticos o import requests para consultar una web compleja. Estás aislado.

Cuándo dar el salto: Señales de que necesitas Python

¿No estás seguro de si esto es para ti? Si te identificas con alguna de estas situaciones, es hora de instalar Pyscript:

1. Tu automatización YAML tiene más de 100 líneas y te da miedo tocarla.
2. Estás usando 5 input_boolean auxiliares solo para guardar estados temporales de una lógica.
3. Necesitas persistencia de datos compleja (guardar diccionarios o listas entre reinicios) que va más allá de un simple número.
4. Quieres integrar un algoritmo matemático o estadístico (ej: predicción de carga solar).

Ventajas de usar Scripts en Python frente a Node-RED

Esta es la gran pregunta. Si Node-RED ya permite usar funciones JavaScript, ¿por qué Python?

Característica	Node-RED	Python (Pyscript/AppDaemon)
Lógica Simple	✅ Excelente (Visual)	❌ Excesivo
Conectividad	✅ Brutal (Nodos para todo)	✅ Buena (Librerías Python)
Algoritmos Complejos	❌ «Spaghetti Visual» (Cables por todos lados)	✅ Limpio y legible
Control de Versiones	❌ Difícil (Son JSON gigantes)	✅ Perfecto (Archivos .py en Git)
Depuración	🟡 Visual pero a veces confuso	✅ Logs detallados y estándar

En resumen: Node-RED es excelente para conectar cosas (Si pasa A, activa B). Python es excelente para procesar datos (Si pasa A, calcula la integral de B, cruza datos con la API de C y decide el mejor curso de acción para D).

Los contendientes: Pyscript vs. AppDaemon

Decidir usar Python es el primer paso. El segundo es elegir dónde ejecutar ese Python. En el ecosistema de Home Assistant, hay dos grandes reyes, y aunque ambos hablan el mismo idioma, viven en mundos muy diferentes.

¿Qué es AppDaemon? Arquitectura y filosofía

AppDaemon es el veterano. La clave para entenderlo es que es un sistema independiente. No vive dentro de Home Assistant; vive al lado.

Imagina que Home Assistant es tu casa. AppDaemon es un mayordomo que vive en la caseta del jardín. Se comunica con la casa a través de un walkie-talkie (la API). Si la casa se incendia (HA se reinicia), el mayordomo sigue vivo en su caseta, esperando órdenes.

• Ventaja clave: Estabilidad y aislamiento. Un error en tu script no tirará abajo Home Assistant.
• Desventaja clave: Latencia y complejidad. Tienes que configurar un contenedor extra (Docker o Add-on) y la comunicación no es instantánea (aunque casi).
• Sintaxis: Orientada a objetos. Usas self.turn_on("light.salon").

¿Qué es Pyscript? Integración nativa y simplicidad

Pyscript es el aspirante moderno. Es una Integración Personalizada (HACS) que corre dentro del núcleo de Home Assistant.

Siguiendo la analogía, Pyscript es un implante cerebral conectado directamente al sistema nervioso de la casa. Ve lo que la casa ve, al instante.

• Ventaja clave: Magia sintáctica y velocidad. Puedes escribir light.salon.turn_on() directamente. Accede a las variables globales y al bus de eventos sin intermediarios.
• Desventaja clave: Riesgo. Si escribes un bucle infinito sin cuidado, puedes congelar todo Home Assistant, ya que comparten recursos.

Tabla comparativa: ¿Cuál elegir según tu nivel y necesidades?

No hay uno mejor que otro, pero sí uno más adecuado para ti.

Característica	AppDaemon 🐢	Pyscript ⚡
Instalación	Compleja (Requiere Add-on/Docker y YAML)	Muy Fácil (Instalar desde HACS y listo)
Sintaxis	Python Puro (Clásico)	Python «Mágico» (Simplificado para HA)
Rendimiento	Alto, pero externo	Nativo (Instantáneo)
Reinicio	Independiente de HA (No para scripts al reiniciar HA)	Se reinicia con HA
Librerías	Cualquier librería pip estándar	Cualquiera (pero requiere configuración extra)
Curva de aprendizaje	Alta (Para programadores)	Media (Para usuarios avanzados)
Veredicto	Úsalo si tienes 50 scripts complejos y buscas estabilidad empresarial.	Úsalo si vienes de YAML y quieres potencia rápida. (Recomendado hoy día).

Primeros pasos con Pyscript (Nivel Básico)

Olvídate de compilar o de crear entornos virtuales complejos. La belleza de Pyscript es que trae la simplicidad de Python al entorno «plug-and-play» de Home Assistant.

Instalación y configuración desde HACS

Como elegimos Pyscript por su facilidad, la instalación te llevará dos minutos:

1. Ve a HACS > Integraciones > Explorar y descargar.
2. Busca «Pyscript» y descárgalo.
3. Reinicia Home Assistant.
4. Ve a Ajustes > Dispositivos y Servicios > Añadir Integración y busca «Pyscript» para activarla.

⚠️ Diferencia Crítica: Al instalarse, se creará una carpeta nueva llamada /config/pyscript.

NO la confundas con la carpeta /config/python_scripts que viene por defecto en Home Assistant. Esa es una versión antigua y muy limitada. Nosotros trabajaremos exclusivamente dentro de la carpeta pyscript.

Entendiendo la sintaxis mágica de Pyscript

Python estándar no sabe lo que es una bombilla inteligente. Para que tu código entienda tu casa, Pyscript hace una «magia» llamada exposición de variables globales. Esto significa que cualquier entidad de tu casa se convierte automáticamente en un objeto de Python.

En lugar de llamar a una API complicada, simplemente escribes:

light.salon_techo.turn_on(brightness=255)

Así de simple. Sin importar librerías, sin autenticación.

Decoradores básicos: @service y @state_trigger

Para decirle a Home Assistant cuándo ejecutar tu código, usamos Decoradores (el símbolo @ antes de una función).

• @service: Convierte tu función de Python en un Servicio de Home Assistant. Esto te permite llamarlo desde un botón en el Dashboard o desde una automatización antigua en YAML.
• @state_trigger: Es el «oído» del script. Ejecuta la función automáticamente cuando una entidad cambia de estado (ej: se abre una puerta).

Tu primer script: «Hola Mundo» en el log de Home Assistant

Vamos a crear tu primer archivo. Crea /config/pyscript/hola_mundo.py y escribe esto:

@service
def saludar_al_log(nombre="Usuario"):
    """Este servicio saluda en el log."""
    log.info(f"Hola {nombre}, ¡Pyscript está funcionando!")

Guarda el archivo. Ahora ve a Herramientas para desarrolladores > Servicios y busca pyscript.saludar_al_log. Ejecútalo y mira el registro de Home Assistant. ¡Felicidades, eres programador!

Interactuando con entidades: Leer y modificar estados

La potencia real llega cuando leemos el estado de la casa.

• Leer: Simplemente usa el nombre de la entidad. binary_sensor.puerta.state te dará «on» o «off».
• Atributos: Accede a ellos como propiedades. light.salon.brightness.

Ejemplo práctico: Encender luces con condiciones simples

Vamos a replicar una automatización básica de sensores de movimiento, pero en Python.

Crea un archivo luces_inteligentes.py:

@state_trigger("binary_sensor.movimiento_pasillo == 'on'")
def encender_luz_pasillo():
    # Leemos si ya hay mucha luz (luxes)
    luxes = sensor.sensor_luz_pasillo.illuminance
    
    # Solo encendemos si está oscuro (menos de 50 lux)
    if int(luxes) < 50:
        log.info(f"Movimiento detectado con {luxes} lux. Encendiendo.")
        light.pasillo.turn_on(brightness_pct=100)
    else:
        log.info("Hay suficiente luz natural, no se enciende nada.")

Fíjate en lo limpio que es. Un if normal, una comparación < normal. Sin YAML anidado, sin nodos complejos. Python puro y duro.

Primeros pasos con AppDaemon (Nivel Básico)

Si Pyscript es la «magia», AppDaemon es la «ingeniería». Aquí no hay atajos sintácticos; hay estructura, orden y Orientación a Objetos. Si vienes del mundo de Java o C++, te sentirás como en casa.

Instalación del Add-on y estructura de carpetas

A diferencia de Pyscript, AppDaemon corre en su propio contenedor aislado. Para instalarlo:

1. Ve a Ajustes > Complementos (Add-ons) > Tienda.
2. Busca e instala AppDaemon.
3. Inícialo y marca «Vigilancia» (Watchdog) para que se reinicie si falla.

Al arrancar, creará una carpeta llamada /config/appdaemon. Dentro verás una subcarpeta crucial: apps. Aquí es donde vivirán tus creaciones.

Anatomía de una aplicación AppDaemon (Clases y herencia)

Aquí es donde los novatos se asustan, pero no deberían. En AppDaemon, cada automatización es una Clase de Python.

Para que tu script pueda hablar con Home Assistant, debe «heredar» los superpoderes de la clase madre hass.Hass. Tu código siempre empezará así:

import hassapi as hass

class MiPrimeraApp(hass.Hass):
    # Todo tu código va indentado aquí dentro

El método initialize(): Donde todo comienza

En lugar de ejecutarse de arriba a abajo como un script normal, AppDaemon busca una función específica llamada initialize(). Es el equivalente al «arranque» del motor.

Aquí NO pones la lógica (ej: «encender luz»), sino que registras los «oídos» (listeners) que esperarán a que pasen cosas.

Configuración a través de apps.yaml

AppDaemon separa el código de la configuración. Esto es brillante para reutilizar código.

• El Código (.py): Escribes la lógica genérica («Si hay movimiento, enciende ESTA luz»).
• La Configuración (apps.yaml): Defines qué es «ESTA luz».

Archivo: /config/appdaemon/apps/apps.yaml

luces_pasillo:
  module: mis_luces  # Nombre del archivo .py
  class: LucesAutomaticas # Nombre de la Clase dentro del archivo
  sensor: binary_sensor.movimiento_pasillo
  luz: light.techo_pasillo

Escuchando eventos y cambios de estado (listen_state)

Para replicar el ejemplo de Pyscript, usaremos el método listen_state. Le decimos a AppDaemon: «Vigila este sensor, y si cambia, ejecuta esta función».

Archivo: /config/appdaemon/apps/mis_luces.py

import hassapi as hass

class LucesAutomaticas(hass.Hass):

    def initialize(self):
        # Leemos la entidad desde apps.yaml (self.args)
        sensor_movimiento = self.args["sensor"]
        
        # Escuchamos cambios. Cuando cambie, llamamos a 'movimiento_detectado'
        self.listen_state(self.movimiento_detectado, sensor_movimiento, new="on")

    def movimiento_detectado(self, entity, attribute, old, new, kwargs):
        # Leemos la luz objetivo desde apps.yaml
        luz = self.args["luz"]
        
        # Usamos 'self' para enviar la orden
        self.turn_on(luz)
        self.log(f"Movimiento en {entity}, encendiendo {luz}")

Fíjate que usamos self.turn_on en lugar de light.turn_on. Esa es la sintaxis orientada a objetos.

Casos de uso avanzados: Cuando la lógica se complica (Nivel Intermedio)

Hasta ahora hemos encendido luces. Eso es fácil. Pero Python brilla cuando necesitas procesar datos, realizar cálculos matemáticos o conectarte con el mundo exterior de forma dinámica.

Bucles complejos y lógica matemática

YAML no sabe hacer raíces cuadradas ni interpolaciones lineales fácilmente. Python sí. Un caso de uso clásico es la iluminación biodinámica.

Ejemplo: Cálculo dinámico de temperatura de color (Ciclo Circadiano)

Queremos que la luz cambie gradualmente cada minuto basándose en la hora del día, simulando el sol. En Node-RED esto sería una maraña de cables. En Pyscript es una función matemática.

Usaremos el decorador @time_trigger para ejecutar esto cada 5 minutos.

@time_trigger("cron(*/5 * * * *)")
def ciclo_circadiano_simple():
    hora = datetime.now().hour
    
    # Lógica matemática simple (mapa lineal)
    # Mañana (06-12h): De 2000K a 5500K
    # Tarde (12-20h): De 5500K a 2700K
    # Noche (20-06h): Fijo a 2000K
    
    kelvin = 2000 # Valor por defecto (Noche)
    
    if 6 <= hora < 12:
        progreso = (hora - 6) / 6
        kelvin = 2000 + (3500 * progreso)
    elif 12 <= hora < 20:
        progreso = (hora - 12) / 8
        kelvin = 5500 - (2800 * progreso)
        
    # Aplicamos a todas las luces del salón si están encendidas
    if light.salon.state == "on":
        light.salon.turn_on(kelvin=int(kelvin), transition=30)
        log.info(f"Ciclo Circadiano: Ajustando salón a {int(kelvin)}K")

Consultas a APIs externas sin sensores REST

A veces necesitas enviar datos a una API (ej: registrar datos en Google Sheets) o consultar una web que requiere una lógica de autenticación compleja que los sensores REST de YAML no soportan.

Importando librerías estándar de Python (requests, datetime)

⚠️ Advertencia de Experto: Pyscript corre en el bucle principal de Home Assistant. Si usas requests.get() y la web tarda 10 segundos en responder, congelarás todo tu Home Assistant durante 10 segundos. Nadie podrá encender una luz.

Para evitarlo, debemos usar task.executor, que envía esa tarea pesada a un hilo secundario.

import requests

@service
def obtener_precio_bitcoin():
    # Definimos la función que bloquea
    def fetch_url():
        r = requests.get("https://api.coindesk.com/v1/bpi/currentprice.json")
        return r.json()

    # La ejecutamos de forma segura en otro hilo
    data = await task.executor(fetch_url)
    
    precio = data["bpi"]["USD"]["rate_float"]
    
    # Guardamos el dato en un sensor de HA
    state.set("sensor.bitcoin_pyscript", value=precio, unit_of_measurement="USD")
    log.info(f"Bitcoin actualizado: ${precio}")

Persistencia de datos entre reinicios

Una variable normal en Python (mi_contador = 0) se borra si reinicias Home Assistant o recargas el script. Para guardar datos a largo plazo, Pyscript nos permite interactuar directamente con la máquina de estados de HA.

No uses variables globales de Python para cosas importantes. Usa entidades.

• Mala práctica: global contador (Se pierde al reiniciar).
• Buena práctica: Escribir en un input_number auxiliar o crear un sensor virtual persistente con state.persist.

# Guardar un dato para que sobreviva a un reinicio
state.set("sensor.ultima_visita_suegra", value="2023-10-27", attributes={"persist": True})

Al añadir persist=True, Pyscript le dice a Home Assistant que restaure ese valor la próxima vez que arranque.

Territorio Experto: Optimización y Lógica Profesional

Cualquiera puede escribir un script que encienda una luz. Pero escribir un script que se ejecute miles de veces al día sin consumir toda la CPU de tu Raspberry Pi requiere entender cómo funciona Home Assistant por dentro.

Gestión de asincronía (async/await) en Home Assistant

Home Assistant funciona sobre un Bucle de Eventos (Event Loop) principal. Imagina una autopista de un solo carril por donde pasan todas las órdenes (encender luz, leer temperatura, notificar). Todo va muy rápido, pero es un solo carril.

Evitando bloquear el «Main Loop» de Home Assistant

Si escribes un código que tarda 10 segundos en ejecutarse (por ejemplo, descargar un archivo grande o esperar con time.sleep(10)), estás poniendo un camión cruzado en la autopista. Durante esos 10 segundos, nada más funciona en tu casa. Ni interruptores, ni sensores.

La Regla de Oro en Pyscript:

• Bloqueante (MAL): time.sleep(10). Detiene el mundo.
• Asíncrono (BIEN): task.sleep(10). Se aparta al arcén, deja pasar el tráfico, y vuelve a entrar a los 10 segundos.

Pyscript maneja mucha magia async/await por ti, pero cuando interactúes con el exterior, recuerda usar siempre funciones asíncronas.

Creación de Blueprints y Servicios personalizados

Has creado un script increíble. Ahora quieres que tu pareja pueda usarlo desde el móvil sin ver código. Pyscript permite convertir tus funciones en servicios nativos de la interfaz visual (UI).

Exponer funciones de Python como servicios llamables desde el Dashboard

El truco está en los Docstrings (comentarios de documentación). Pyscript lee tu código y genera la interfaz gráfica automáticamente.

@service
def modo_cine_avanzado(brillo=20, color="rojo", persianas=True):
    """
    Activa el modo cine con opciones personalizadas.
    
    :param brillo: Porcentaje de luz (0-100).
    :param color: Color ambiental (rojo, azul).
    :param persianas: ¿Bajar persianas? (True/False).
    """
    # Tu lógica aquí...
    log.info(f"Cine activado: {color} al {brillo}%")

Al guardar esto, si vas a Herramientas para desarrolladores > Servicios, verás que aparecen casillas y desplegables para rellenar «brillo», «color» y un interruptor para «persianas». ¡Has creado tu propia integración!

Depuración (Debugging) y manejo de errores

El código nunca funciona a la primera. La diferencia entre un novato y un experto es cómo encuentran el error.

Uso de Jupyter Notebooks con Pyscript Kernel

Esta es la «joya de la corona» de Pyscript. Puedes conectar un entorno Jupyter Notebook directamente a tu Home Assistant.

Esto te permite ejecutar código línea por línea en vivo contra tu casa real. Escribes light.salon.turn_on(), pulsas Enter, y la luz se enciende al instante. Es la herramienta definitiva para prototipar lógica compleja sin tener que guardar archivo -> reiniciar -> mirar logs.

Para configurarlo, necesitarás seguir la documentación del Kernel de Pyscript.

Logs avanzados y notificaciones de error al móvil

No dejes que tu script muera en silencio. Usa bloques try/except para capturar errores y avisarte.

@service
def tarea_arriesgada():
    try:
        # Código que puede fallar (ej: conexión a API)
        resultado = 10 / 0
    except Exception as e:
        # Si falla, no rompas nada. Avísame.
        log.error(f"Error crítico en tarea: {e}")
        notify.mobile_app_mi_movil(message=f"🔥 El script falló: {e}")

Mantenimiento y Buenas Prácticas de Desarrollo

Hay un dicho famoso en programación: «Escribe código como si la persona que fuera a mantenerlo en el futuro fuera un psicópata violento que sabe dónde vives». Esa persona, probablemente, serás tú mismo dentro de seis meses.

A medida que tu colección de scripts crece, el desorden puede matar tu sistema. Vamos a aplicar reglas de ingeniería de software a tu servidor doméstico.

Organización del código y modularidad

No metas todo en un solo archivo mis_scripts.py de 2000 líneas. Pyscript permite importar módulos, igual que Python normal.

La estrategia de «Librerías Compartidas»:
Si tienes una función que calcula el coste de la electricidad o formatea una fecha, no la copies en cada script. Crea una librería.

1. Crea una carpeta /config/pyscript/modules.
2. Dentro, crea un archivo utilidades.py.
3. Escribe tus funciones auxiliares ahí (sin decoradores de HA).

# /config/pyscript/modules/utilidades.py
def calcular_iva(precio):
    return precio * 1.21

# /config/pyscript/luces.py
from modules.utilidades import calcular_iva  # Importamos la función

@service
def coste_luz_actual():
    precio_base = float(sensor.precio_luz.state)
    precio_final = calcular_iva(precio_base)
    log.info(f"Precio con IVA: {precio_final}")

Control de versiones: Integrando tus scripts con GitHub

¿Alguna vez has borrado una línea de código, guardado el archivo, y te has dado cuenta de que acabas de romper toda la casa… y no recuerdas qué había escrito antes?

Necesitas Git. Es el sistema de «puntos de guardado» para programadores.

Cómo implementarlo en Home Assistant:

1. Instala el complemento «Studio Code Server» (VS Code en el navegador).
2. Este editor trae integración nativa con Git.
3. Crea una cuenta en GitHub (es gratis y privado).
4. Inicializa el repositorio en tu carpeta /config.

Ahora, cada vez que hagas un cambio importante en tus scripts Python:

• Haces un Commit (Guardar cambios con un mensaje: «Añadida lógica de calefacción»).
• Haces un Push (Subir a la nube).

Si algo se rompe, puedes «viajar en el tiempo» y restaurar el archivo tal y como estaba ayer, hace una semana o hace un año. Además, te sirve de copia de seguridad externa automática.

Conclusión: El poder ilimitado (y su responsabilidad)

Felicidades. Has cruzado una línea invisible. Hasta ayer, eras un usuario de Home Assistant que configuraba dispositivos. Hoy, eres un desarrollador que crea sus propias reglas.

Usar Python (vía Pyscript) elimina todas las barreras. Ya no importa si el desarrollador de una integración olvidó poner una función específica; ahora puedes programarla tú mismo. Has aprendido a:

1. Instalar y configurar Pyscript.
2. Escribir lógica que reacciona a eventos en milisegundos.
3. Conectarte con el mundo exterior mediante APIs.
4. Gestionar errores y versiones como un profesional.

El único límite ahora es tu imaginación (y la memoria RAM de tu servidor). Úsalo con sabiduría.

---

Preguntas Frecuentes (FAQ)

¿Por qué no funciona «print()» en mis scripts?

Es el error número 1. La función print() envía texto a la consola del sistema, la cual no puedes ver fácilmente en Home Assistant. Debes usar siempre log.info(), log.warning() o log.error() para que los mensajes aparezcan en el registro oficial de HA.

¿Puedo instalar cualquier librería de Python (pip)?

En Pyscript, sí, pero con un paso extra. Debes crear un archivo requirements.txt en tu carpeta /config/pyscript y listar allí las librerías (ej: pandas, numpy). Al reiniciar, Pyscript las instalará automáticamente por ti.

¿Esto sustituye totalmente a Node-RED?

No necesariamente. Muchos usuarios usan un enfoque híbrido: Node-RED para automatizaciones visuales sencillas (luces con movimiento) y Python para la lógica de «backend» compleja (algoritmos de clima, gestión de energía). Usa la mejor herramienta para cada tarea.

¿Qué pasa si mi script entra en un bucle infinito?

Si no usas funciones asíncronas (await), bloquearás Home Assistant y tendrás que reiniciar el hardware físicamente (quitar cable). Si usas Pyscript correctamente, Home Assistant intentará matar el proceso si detecta que tarda demasiado, pero no te confíes. ¡Programa con cuidado!

¿Te ha sido útil? ¡Compártelo con otros!

WhatsApp Facebook X (Twitter) Telegram

Únete a la Comunidad

Síguenos en nuestras redes para ver tutoriales en vídeo, ideas de decoración y trucos rápidos para tu hogar inteligente.