Skip to main content

​
Xiaomi MIoT

Integração baseada no protocolo MIoT (Mi IoT) — o mesmo usado pelo app Mi Home e pela integração hass-xiaomi-miot do Home Assistant. Autentica direto na Mi Cloud e expõe dispositivos ao Portal como entidades nativas. Nesta primeira versão a integração se concentra em robôs aspiradores (.vacuum.), cobrindo os comandos essenciais e a leitura de estado (status, bateria, velocidade do sucção).

​
Pré-requisitos

  • Conta Mi Cloud (a mesma do app Mi Home) com pelo menos um robô aspirador vinculado.
  • Escolha da região correta (China, EUA, Alemanha, Singapura, Rússia, Taiwan, Índia). A região aqui é a do servidor Mi Cloud, não a do local físico do robô.
  • Contas com verificação em duas etapas são suportadas: o Portal apresenta a URL de aprovação e refaz o login após você confirmar pelo app Mi Home.
A senha da conta Mi é armazenada no config entry para permitir renovação automática da sessão quando o serviceToken expira. Não use uma senha reutilizada em outros serviços — considere criar uma senha exclusiva para a conta Mi.

​
Configurar

1

Adicione a integração

Vá em Configurações → Integrações → Adicionar → Xiaomi MIoT.
2

Escolha a região

Selecione o mesmo servidor que sua conta usa no app Mi Home (China é o mais comum para contas asiáticas; EUA ou Alemanha para o resto do mundo).
3

Informe usuário e senha

Use o mesmo e-mail (ou Mi ID) e senha do app Mi Home.
4

Verificação em duas etapas (se solicitada)

Se a Mi Cloud pedir verificação (contas novas, novo device, IP diferente), o Portal mostra um segundo passo com uma URL da Xiaomi e um campo de código.Ordem importante:
  1. Abra a URL numa nova aba. A Xiaomi mostra uma tela com botões “Enviar SMS” e “Enviar e-mail”.
  2. Clique no método desejado — o código só é enviado nesse momento. Não basta o Portal chamar a API.
  3. Aguarde o SMS ou e-mail chegar (destinatários cadastrados na sua conta Mi).
  4. Volte ao Portal, digite o código no campo e clique em Confirmar.
O Portal valida o código na API /identity/auth/verifyPhone (ou verifyEmail), completa a sessão via serviceToken e persiste o deviceId — que fica confiável para renovações futuras.
5

Sincronização automática

O Portal faz login na Mi Cloud, lista todos os dispositivos e cria uma entidade vacuum para cada robô encontrado. Um card Vacuum já pode ser usado no dashboard.

​
Dispositivos suportados

A detecção usa o padrão de model MIoT (<fabricante>.vacuum.<serie>). Modelos que caiam no padrão são criados como entidades vacuum mesmo sem override específico — se algum comando não funcionar, o mapeamento das ações MIoT (SIID/AIID) pode precisar ser adicionado em packages/sdk/src/integrations/xiaomi_miot/const.ts na tabela XIAOMI_VACUUM_OVERRIDES.

​
Como funciona

A integração roda no cloud edge. Não é preciso ter um Portal home rodando na LAN — o worker se comunica direto com a Mi Cloud pelas APIs home/device_list e miotspec/prop/get|set|action.
  • Login: implementa o fluxo serviceLogin → serviceLoginAuth2 → location (redirect para obter o cookie serviceToken). O ssecurity retornado é usado para assinar cada requisição.
  • Polling: a cada 60 segundos o worker consulta status, bateria e velocidade de sucção usando miotspec/prop/get.
  • Comandos: enviados via miotspec/action (start, stop, pause, return_home, locate) ou miotspec/prop/set (set_fan_speed). Cada resposta 401/403 dispara um re-login automático com as credenciais armazenadas.

​
Serviços expostos

​
Card Vacuum

O Portal disponibiliza um card específico para entidades vacuum com:
  • Ícone, nome e status traduzido (Limpando, Na base, Voltando à base, Pausado, Erro, Parado).
  • Barra de bateria com semáforo de cor (verde/laranja/vermelho).
  • Seletor de velocidade de sucção baseado no fan_speed_list do robô.
  • Controles: Iniciar/Pausar (principal, no header), Parar, Voltar à base e Localizar.
Adicione o card pelo editor visual do dashboard (Adicionar card → Vacuum) e selecione uma entidade unicontrol.xiaomi_miot.vacuum.<did>.

​
Limitações conhecidas

  • Somente vacuum: outras categorias MIoT (luzes, purificadores, câmeras, sensores) não são criadas nesta versão.
  • Mapeamento genérico de SIID/PIID: modelos raros podem precisar de override em XIAOMI_VACUUM_OVERRIDES.
  • Renovação de sessão: o serviceToken da Mi Cloud costuma durar alguns dias. Quando expira, o worker faz re-login automático usando as credenciais e o deviceId armazenados — como o Xiaomi associa a confiança 2FA ao deviceId, refresh de sessão não pede verificação de novo.
  • Verificação repetida: em raros casos (IP muito diferente, longa inatividade) a Xiaomi pode pedir verificação novamente. Reabra a integração via Reconfigurar para regenerar a URL.