> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt
> Use this file to discover all available pages before exploring further.
# Xiaomi MIoT
> Conecte robôs aspiradores Xiaomi (e ecossistema Mi Home) ao Portal via Mi Cloud
# Xiaomi MIoT
Integração baseada no protocolo **MIoT (Mi IoT)** — o mesmo usado pelo app Mi Home e pela integração
[hass-xiaomi-miot](https://github.com/al-one/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
Vá em **Configurações → Integrações → Adicionar → Xiaomi MIoT**.
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).
Use o mesmo e-mail (ou Mi ID) e senha do app Mi Home.
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.
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
| Categoria | Modelos | Funcionalidades |
| ------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **Robô aspirador** | `roborock.vacuum.*`, `dreame.vacuum.*`, `viomi.vacuum.*`, `mijia.vacuum.*`, `mi.robot.*` | Iniciar, pausar, parar, voltar à base, localizar, ajustar sucção |
A detecção usa o padrão de model MIoT (`.vacuum.`). 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`](https://github.com/) 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
| Serviço | Descrição |
| ---------------------- | ----------------------------------------------------------------------- |
| `vacuum.start` | Inicia limpeza |
| `vacuum.stop` | Para o robô |
| `vacuum.pause` | Pausa a limpeza em andamento |
| `vacuum.return_home` | Envia o robô de volta à base |
| `vacuum.locate` | Faz o robô emitir um som para localização |
| `vacuum.set_fan_speed` | Define a velocidade da sucção (`silent`, `standard`, `medium`, `turbo`) |
## 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.`.
## 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.