> ## 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.

# Midea SmartHome (MSmartHome)

> Controle ar-condicionados Midea pela nuvem usando a conta do app oficial

# Midea SmartHome (MSmartHome)

Controla ar-condicionados Midea (e marcas OEM compatíveis — Comfee, Pelonis,
MDV, Master Kitchen, Arctic King) pela **nuvem MSmartHome**, usando a mesma
conta do app oficial. A integração **não precisa de edge local**: funciona
inteiramente pela internet.

Esta versão suporta **ar-condicionados de ambiente (device type `0xAC`)**:
splits, janela e portáteis que aparecem no app como "ar-condicionado". Outras
famílias Midea (desumidificadores, ventiladores, lava-roupas) chegam em versões
futuras.

> [!WARNING]
>
> A Midea **não possui um programa público de desenvolvedores**. Esta
> integração usa os mesmos endpoints do app oficial. Para proteger sua conta:
>
> * Use **a sua própria conta** — não compartilhe credenciais entre pessoas.
> * Se possível, cadastre uma conta separada **só para o Portal** e compartilhe
>   os aparelhos com ela pelo app Midea.
> * O Portal faz um máximo de **1 requisição por segundo por conta** para
>   evitar bloqueios.

## Pré-requisitos

* Uma conta no app **MSmartHome**, **NetHome Plus** ou **Midea Air** com os
  aparelhos já cadastrados e online.
* Senha da conta Midea.
* Os aparelhos precisam ter sido configurados no app oficial pelo menos uma
  vez (pareados ao Wi-Fi da casa).

## Configurar

**1. Adicione a integração**

Vá em **Configurações → Integrações → Adicionar → Midea SmartHome**.

**2. Escolha o app**

Selecione o app em que sua conta foi criada. Se não tem certeza, deixe em
**MSmartHome** — é o padrão global atual. Contas antigas podem precisar de
**NetHome Plus** ou **Midea Air**.

**3. Informe suas credenciais**

Digite o e-mail e a senha da conta Midea. O Portal valida o login contra
a nuvem antes de prosseguir.

**4. Selecione os aparelhos**

O Portal lista os ar-condicionados encontrados na conta. Marque quais você
quer importar — aparelhos offline aparecem marcados como `(offline)` e
podem ser selecionados para configurar antecipadamente.

Cada ar-condicionado importado vira uma entidade `climate` separada.

## Funcionalidades

* **Ligar/desligar** (`climate.turn_on` / `climate.turn_off`)
* **Modo HVAC** (`climate.set_hvac_mode`): `off`, `auto`, `cool`, `dry`,
  `heat`, `fan_only`
* **Temperatura alvo** (`climate.set_temperature`): 16 °C a 30 °C, passo de 0.5°
* **Velocidade do ventilador** (`climate.set_fan_mode`): `auto`, `silent`,
  `low`, `medium`, `high`, `full`
* **Swing** (`climate.set_swing_mode`): `off`, `vertical`, `horizontal`, `both`
* **Temperatura ambiente** — exibida quando o aparelho reporta o sensor interno.
* **Temperatura externa** — exibida no atributo `outdoor_temperature` quando a
  condensadora reporta.
* **Modos extras** — `eco_mode` e `turbo_mode` ficam disponíveis como atributos
  da entidade.
* **Código de erro** — exposto no atributo `error_code` quando o aparelho
  reporta uma falha.

O estado é atualizado por *polling* a cada **30 segundos**; comandos aplicam
uma atualização otimista imediata na interface.

> [!NOTE]
>
> O protocolo Midea 0xAC exige que todo comando reescreva o **estado completo**
> do aparelho. Antes de enviar uma alteração o Portal lê o estado atual e
> mescla apenas o campo alterado — assim mudar só a temperatura não zera o
> modo/ventilador.

## Como funciona

* O Portal se autentica com e-mail + senha contra `mp-prod.appsmb.com` (ou o
  endpoint equivalente para contas NetHome Plus / Midea Air).
* Para cada comando ou leitura, encapsula um pacote binário Midea e envia pelo
  endpoint "transparent send" da nuvem — o mesmo caminho que o app oficial usa.
* A sessão (access token) é mantida em memória pelo worker; se expirar, o
  Portal faz login de novo automaticamente usando as credenciais salvas.

## Solução de problemas

* **"Credenciais inválidas"**: verifique e-mail, senha e **qual app** você
  selecionou. Uma conta criada no NetHome Plus não loga no MSmartHome e
  vice-versa.
* **"Nenhum ar-condicionado foi encontrado"**: a conta foi autenticada mas
  não tem aparelho do tipo `0xAC` registrado. Confirme no app Midea que o
  aparelho aparece como "ar-condicionado".
* **O aparelho fica offline no Portal mas funciona no app**: a Midea às vezes
  bloqueia IPs com muitas requisições. O Portal já limita a 1 req/s por conta;
  se mesmo assim acontecer, aguarde algumas horas e reinicie a integração.
* **Mudanças feitas no controle remoto demoram a aparecer**: a nuvem Midea não
  tem push para o Portal — o estado é lido por *polling* a cada 30 s. Isso é
  esperado.

## Limitações atuais

* Apenas device type **`0xAC`** (ar-condicionados de ambiente). Desumidificador,
  ventilador e lava-roupas Midea entrarão em versões futuras.
* Sem descoberta/controle **LAN local** — toda comunicação passa pela nuvem.
* Sem suporte a *push* da Midea — toda atualização de estado é por *polling*.
* Autenticação **sem 2FA**: contas Midea que usam verificação em dois fatores
  precisam desativar 2FA ou usar uma conta secundária com os aparelhos
  compartilhados.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.