Integración domótica Xiaomi MIoT, gratuita y de código abierto
Purificadores, humidificadores, ventiladores, enchufes y lámparas Xiaomi en local (MIoT).
Publicado por guim31
- Dispositivos
- Versión 1.0.1
- Requiere Gladys >=5.1.0
- ★ 0
Controle sus dispositivos Wi-Fi Xiaomi, Mi Home y Mijia desde Gladys, en su red local: purificadores de aire, humidificadores, deshumidificadores, ventiladores, enchufes inteligentes, interruptores, lámparas, monitores de calidad del aire y los sensores que llevan integrados. La integración lee la especificación MIoT pública de cada modelo y traduce sus servicios estándar en funciones de Gladys: ningún modelo se programa a mano. Añade un widget del panel, un disparador de mantenimiento y una acción de escena.
La cuenta Xiaomi solo se usa una vez, para listar sus dispositivos con su dirección local y su token (la clave que necesita cada dispositivo). Después, todo queda en su red: Gladys habla directamente con cada dispositivo, como lo hace la aplicación Mi Home en su Wi-Fi.
Completa las otras integraciones del store: los robots aspiradores de la aplicación Mi Home los controla la integración Xiaomi Home, los robots Roborock y Dreame las suyas. Esta integración deja de lado los aspiradores.
Developed without the hardware: feedback welcome. Esta integración se ha construido y probado con especificaciones MIoT reales (publicadas por los proyectos homebridge-miot y hass-xiaomi-miot) y con dispositivos simulados, no con un purificador real ni con una cuenta Xiaomi real. Si algo no funciona como se describe, indíquelo en el foro de Gladys o en las issues.
Sin relación con Xiaomi. Xiaomi, Mi Home y Mijia son marcas de sus propietarios.
Lo que necesita
- Gladys Assistant 5.1.0 o posterior.
- Dispositivos Wi-Fi Xiaomi ya configurados en la aplicación Mi Home (Xiaomi Home), en la misma red que Gladys.
- O bien el correo electrónico (o el número de teléfono) y la contraseña de la cuenta Mi Home, y su región; o bien, para cada dispositivo, su dirección IP y su token (32 caracteres hexadecimales), obtenido con otra herramienta.
- Acceso a Internet para Gladys durante la configuración: la cuenta Xiaomi (una vez) y miot-spec.org (una vez por modelo, para descargar su especificación).
Configuración
Con la cuenta Xiaomi
- Instale la integración desde el catálogo de Gladys.
- Abra su Configuración e introduzca:
- Correo electrónico o teléfono y Contraseña de la cuenta Mi Home;
- Región de la cuenta: la región del servidor elegida en la aplicación Mi Home (Perfil → Ajustes → Región). Europa por defecto; un dispositivo emparejado en otra región no aparece;
- Intervalo de actualización: frecuencia de lectura de cada dispositivo, de 15 s a 2 min (30 s por defecto);
- Idioma de los nombres de las funciones: inglés, francés, alemán o español (francés por defecto). Los nombres de un dispositivo y de sus funciones se asignan al añadirlo.
- Guarde. La integración inicia sesión e importa los dispositivos enseguida; para repetirlo más tarde, haga clic en Importar los dispositivos de la cuenta Xiaomi: el mensaje bajo el botón lista lo importado y lo descartado.
- Verificación en dos pasos: si Xiaomi la pide, el mensaje da un enlace. Ábralo en un navegador, solicite allí el código (SMS o correo electrónico), pero no lo introduzca en esa página. De vuelta en Gladys, escriba el código en el campo Código de verificación y haga clic de nuevo en Importar los dispositivos de la cuenta Xiaomi, antes de 15 minutos.
- Abra la pestaña Descubrir: un dispositivo por cada dispositivo Xiaomi. Haga clic en Añadir, elija una habitación y guarde.
La contraseña queda en la configuración de la integración; los tokens se
guardan en su volumen privado (/data) y nunca se vuelven a mostrar. Puede
vaciar la contraseña una vez importados los dispositivos: siguen funcionando.
Con dirección IP y token
¿Sin cuenta, o un dispositivo que la cuenta no lista? En la configuración, haga clic en Añadir un dispositivo con dirección IP y token, con la dirección del dispositivo (su router la indica) y su token. La integración pide su modelo al dispositivo, lo que también comprueba el token. El dispositivo aparece en la pestaña Descubrir.
Otras acciones de la configuración
- Diagnosticar los dispositivos: para cada dispositivo, su modelo, su dirección, si responde, cuántas funciones se han traducido y qué servicios se han descartado; y los dispositivos miIO encontrados en la red que la integración no conoce.
- Olvidar un dispositivo y su token: retira un dispositivo de la integración (vendido, sustituido). Elimínelo también en Gladys.
Los dispositivos en Gladys
Cada dispositivo se convierte en un dispositivo de Gladys, con su nombre en Mi Home (o su tipo y el final de su identificador). Solo se publica lo que su especificación declara:
| Función | Qué es | Dispositivos |
|---|---|---|
| Encendido | Encendido / apagado | Purificadores, humidificadores, ventiladores, enchufes, interruptores |
| Luz | Encendida / apagada | Lámparas |
| Modo | La lista de modos del dispositivo (Auto, Noche, Favorito…) | Purificadores, humidificadores, ventiladores |
| Velocidad del ventilador | Una lista de niveles o un control deslizante | Purificadores, humidificadores, ventiladores |
| Oscilación horizontal | Oscilación sí / no | Ventiladores |
| Oscilación vertical | Oscilación sí / no | Ventiladores |
| Humedad objetivo | Una lista cada 5 % | Humidificadores, deshumidificadores |
| Nivel de agua | Agua restante en el depósito, en % | Humidificadores |
| Depósito vacío | Sí / no | Algunos humidificadores |
| Temperatura de consigna | La consigna, solo mostrada | Calefactores |
| Avería | Lo que indica el dispositivo, o Sin avería | La mayoría de los dispositivos |
| Temperatura | °C | Dispositivos con sensor |
| Humedad | % | Dispositivos con sensor |
| PM2,5 / PM10 | µg/m³ | Purificadores, monitores |
| CO2 | ppm | Monitores |
| Iluminancia | lux | Dispositivos con sensor de luz |
| Vida útil del filtro | % restante | Purificadores |
| Tiempo restante del filtro | Días u horas | Purificadores |
| Batería | % | Monitores con batería |
| Bloqueo infantil | Bloquea los botones del dispositivo | La mayoría de los dispositivos |
| Consumo | Vatios | Enchufes con medición |
| Brillo | % | Lámparas |
| Temperatura de color | Kelvin, dentro del rango del modelo | Lámparas |
| Color | El color de una lámpara de color | Lámparas de color |
- Un calefactor se muestra, nunca se controla: su encendido y su consigna son de solo lectura. Un calefactor controlado como una lámpara por una escena, un panel o un asistente de voz podría calentar una habitación vacía o encenderse junto a algo; use sus botones o la aplicación Mi Home.
- Lo que la traducción descarta (el pitido, la pantalla, el piloto, los ajustes propios del fabricante) lo lista Diagnosticar los dispositivos, y sigue accesible con la acción de escena Ajustar una propiedad MIoT.
- Cuando un dispositivo deja de responder, su distintivo lo indica como inaccesible; vuelve solo.
Widget del panel
Añada el widget Calidad del aire a un panel y elija un dispositivo en su configuración. Muestra hasta cuatro mosaicos en directo (PM2,5, CO2, temperatura, humedad, nivel de agua, vida útil del filtro como indicador, en este orden), el estado del dispositivo (encendido, apagado o no responde), su modo y su velocidad, una avería si la hay, y botones:
- Encender / Apagar, que conmuta el dispositivo sea cual sea el estado mostrado (no en un calefactor);
- los dos primeros modos del dispositivo (por ejemplo Auto y Noche); el que está en curso lleva una marca.
Escenas
Disparador
Dispositivo Xiaomi requiere atención: se dispara una vez cuando empieza un motivo, y de nuevo solo después de que haya terminado. Filtros:
- Dispositivo Xiaomi: un dispositivo, o cualquiera;
- Motivo: Filtro que cambiar (vida útil del filtro al 10 % o menos), Depósito vacío (la alarma del depósito, o un nivel de agua al 0 %), Avería (el dispositivo indica una avería); vacío para todos.
Las variables dan el nombre del dispositivo (device_name), el motivo
(filter, water o fault) y un detalle (la vida útil del filtro, la avería
indicada). Los motivos en curso se conservan tras un reinicio.
Acción
Ajustar una propiedad MIoT: escribe cualquier propiedad modificable de un
dispositivo por su número en miot-spec.org (siid.piid, por ejemplo 6.1
para el pitido de un Mi Air Purifier 4), con un valor como lo espera la
especificación (true / false, un número o un texto). La acción rechaza una
propiedad que no existe, de solo lectura, o un valor fuera de su rango; y
cualquier calefactor. Da el valor escrito a las acciones siguientes.
Para encontrar los números: abra https://home.miot-spec.com/spec/<modelo>
(por ejemplo zhimi.airp.mb5), o ejecute Diagnosticar los dispositivos,
que nombra los servicios descartados con su número.
Ideas de escenas
- Aviso de filtro: Dispositivo Xiaomi requiere atención, motivo Filtro que cambiar → enviar el mensaje «{{device_name}}: filtro al {{detail}}».
- Noches tranquilas: todos los días a las 22:00 → poner el Modo del
purificador en Noche, y después Ajustar una propiedad MIoT
6.1=falsepara silenciar su pitido. - Respirar mejor: cuando el PM2,5 del monitor supera 35 → encender el purificador, modo Auto.
- Rellenar el humidificador: Dispositivo Xiaomi requiere atención, motivo Depósito vacío → enviar un mensaje y apagar el humidificador.
Solución de problemas
- Ningún dispositivo importado: compruebe la región de la cuenta (una cuenta Xiaomi está ligada a una región) y el mensaje bajo el botón: los aspiradores y los dispositivos Bluetooth y Zigbee se descartan a propósito.
- «Xiaomi pide un captcha»: inicie sesión una vez en la aplicación Mi Home desde la misma red, espere unos minutos y vuelva a intentarlo; o añada los dispositivos a mano.
- Un dispositivo no responde: compruebe que está en la misma red que Gladys (una red de invitados o una VLAN aislada para objetos lo bloquea) y asígnele una dirección fija en su router. Un dispositivo que cambia de dirección se vuelve a encontrar en 15 minutos gracias a una difusión de descubrimiento que envía Gladys (puerto UDP 54321, de ahí este permiso en la instalación).
- «rechaza su token»: el dispositivo se ha restablecido o emparejado de nuevo en Mi Home, su token ha cambiado: haga clic de nuevo en Importar los dispositivos de la cuenta Xiaomi.
- «falta la especificación»: miot-spec.org no tiene nada para este modelo, o no era accesible; la integración lo vuelve a intentar cada 15 minutos. Los modelos antiguos solo miIO (anteriores a MIoT) no son compatibles.
- La integración registra lo que encuentra y lo que no responde (más con
LOG_LEVEL=debug): abra sus registros desde la interfaz de Gladys.
Límites
- Solo dispositivos Wi-Fi: los dispositivos Bluetooth y Zigbee que pasan por una pasarela Xiaomi no tienen dirección propia y se descartan.
- Los robots aspiradores se descartan (vea las integraciones Xiaomi Home, Roborock y Dreame).
- Aires acondicionados, termostatos, hervidores, cocinas y otros tipos aún no se traducen: solo aparecen si tienen uno de los servicios estándar de arriba (un enchufe, un sensor…).
- Sin notificación instantánea: cada dispositivo se lee cada 30 segundos por defecto, una petición agrupada por dispositivo; un cambio hecho en Mi Home aparece en la lectura siguiente.
- Los servidores de Xiaomi solo se llaman al importar los dispositivos (y cuando cambian los datos de la cuenta); miot-spec.org una vez por modelo. Ninguno de los dos hace falta después.
- Desarrollada sin el hardware: las diferencias propias de algunos modelos que las especificaciones no indican (una potencia en otra unidad) pueden necesitar ajustes; avísenos, por favor.
Parámetros de configuración
Estos son los parámetros que Xiaomi MIoT te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Cuenta Xiaomi | section | No | La cuenta solo se usa una vez, para listar sus dispositivos Wi-Fi con su dirección y su token; después todo queda en la red local. Guarde y ejecute «Importar los dispositivos de la cuenta Xiaomi» más abajo. ¿Sin cuenta? Añada un dispositivo con su dirección IP y su token. |
| Correo electrónico o teléfono | string | No | El usuario de su cuenta Mi Home (Xiaomi Home). |
| Contraseña | secret | No | |
| Región de la cuenta | select | No | La región del servidor elegida en la aplicación Mi Home (Perfil → Ajustes → Región). |
| Intervalo de actualización | select | No | Frecuencia de lectura de cada dispositivo en la red local. |
| Idioma de los nombres de las funciones | select | No | Nombres que reciben los dispositivos al añadirlos y textos de la integración. |
Cómo instalar Xiaomi MIoT en Gladys
- En Gladys, abre Integraciones: Xiaomi MIoT aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/guim31/gladys-xiaomi-miot:1.0.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/guim31/gladys-xiaomi-miot.
Xiaomi MIoT requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.
¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.
Sobre las integraciones externas
Xiaomi MIoT es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene guim31, no el equipo principal de Gladys.
- Explorar todas las integraciones externas
- Descubrir las integraciones nativas incluidas en Gladys
- Crear y publicar tu propia integración externa
- Código fuente en GitHub — fuente de esta documentación