La biblioteca python-miio se ha consolidado como la herramienta de referencia para desarrolladores y entusiastas de la domótica que buscan interactuar con dispositivos inteligentes de Xiaomi (ecosistema Mi Home). Basada en la implementación de los protocolos miIO y MIoT, esta librería permite gestionar una vasta gama de hardware, desde aspiradoras robotizadas hasta sensores ambientales, de forma programática y local.

Instalación y Configuración del Entorno

Para comenzar a trabajar con esta librería, es recomendable utilizar un entorno virtual de Python. La instalación se realiza de forma sencilla a través del gestor de paquetes pip:

# Instalación de la versión estable
pip install python-miio

# Instalación de la versión de desarrollo para soporte de hardware reciente
pip install git+https://github.com/rytilahti/python-miio.git

Gestión de Credenciales: Obtención del Token

El control de los dispositivos Xiaomi requiere un token de acceso único de 32 caracteres. La forma más eficiente de recuperar todos los tokens asociados a una cuenta de Mi Home es mediante la utilidad de nube integrada en la interfaz de línea de comandos (CLI):

# Autenticación con los servidores de Xiaomi
miiocli cloud --username usuario@email.com --password tu_contraseña

Este comando devolverá un listado con el nombre de cada dispositivo, su dirección IP local y su token correspondiente, información esencial para cualquier comunicación posterior.

Interacción mediante Interfaz de Línea de Comandos (CLI)

La herramienta miiocli permite ejecutar comandos rápidos sin necesidad de escribir scripts complejos. Para interactuar con dispositivos modernos que utilizan el protocolo MIoT, se utiliza el comando genericmiot.

Consulta de estado

# Obtener información detallada del hardware
miiocli genericmiot --ip 192.168.1.50 --token b4567890abcdef1234567890abcdef12 status

Ejecución de acciones

# Cambiar la intensidad de una luz o ventilador
miiocli genericmiot --ip 192.168.1.50 --token b4567890abcdef1234567890abcdef12 set light:brightness 75

Implementación con la API de Python

Para integraciones más profundas o desarrollo de software personalizado, la API de Python ofrece un control granular. El uso de DeviceFactory facilita la instanciación de objetos sin conocer de antemano el modelo exacto.

from miio import DeviceFactory

def gestionar_dispositivo(direccion_ip, access_token):
    # Detección automática del tipo de dispositivo
    nodo_iot = DeviceFactory.create(direccion_ip, access_token)
    
    detalles = nodo_iot.info()
    print(f"Conectado a: {detalles.model} - Versión FW: {detalles.firmware_version}")

    # Consultar sensores y estados actuales
    estado_actual = nodo_iot.status()
    return estado_actual

# Ejemplo de uso
mi_dispositivo = gestionar_dispositivo("192.168.1.55", "tu_token_aqui")

Categorías de Dispositivos Soportados

El ecosistema soportado por python-miio es extenso y se divide principalmente en:

• Limpieza: Series completas de Roborock (S5, S6, S7) y aspiradoras Xiaomi Mi Robot.
• Climatización: Purificadores de aire (Air Purifier 2, 3H, Pro), humidificadores y ventiladores inteligentes.
• Iluminación: Lámparas Yeelight, bombillas Philips Wi-Fi y paneles LED.
• Infraestructura: Enchufse inteligentes (Smart Power Strip), gateways multifunción y repetidores.

Diagnóstico y Depuración

En entornos donde la comunicación falla o el dispositivo no responde como se espera, es fundamental habilitar el registro detallado (debug) para inspeccionar los paquetes de red enviados y recibidos:

# Ejecución en modo depuración
miiocli --debug device --ip 192.168.1.50 --token tu_token info

Si un dispositivo no es reconocido automáticamente, se puede forzar el uso de un modelo específico para verificar compatibilidad parcial:

miiocli airpurifier --model zhimi.airpurifier.v7 --ip 192.168.1.60 --token tu_token status

Consideraciones Técnicas

Python-miIO es el núcleo que alimenta integraciones populares en plataformas como Home Assistant. Su arquitectura modular permite a los desarrolladores extender las funcionalidades existentes mediante la creación de nuevas clases de entegración en el directorio miio/integrations/ del código fuente. La capacidad de realizar una introspección de las propiedades de un dispositivo mediante device.settings() y device.actions() facilita enormemente el desarrollo de interfaces de control dinámicas.