Um guia completo para controlar e monitorizar um Faikin Faikout através de MQTT, desde a configuração inicial até à referência completa de tópicos, comandos e definições.

Abrange o módulo WiFi Faikout com o firmware da RevK (o dispositivo tem a marca Faikout; poderá ainda ver o nome mais antigo Faikin). Aplica-se igualmente a unidades S21, X50A e CN_WIRED, uma vez que o firmware determina o protocolo automaticamente. Ao longo do documento, o nome de anfitrião de exemplo é GuestAC e o IP de exemplo do broker é 192.168.1.10. Substitua ambos pelos seus.

1. O que o MQTT lhe oferece

Tudo é local. O Faikout comunica por MQTT na sua própria rede, sem conta na nuvem e sem dependência da internet. Através de MQTT pode:

• Controlar a unidade: ligar/desligar, modo, ponto de regulação (setpoint), velocidade da ventoinha, oscilação das lâminas, powerful/econo.
• Ler telemetria em tempo real que o comando por infravermelhos não mostra: temperaturas da divisão, da serpentina/líquido, da admissão e do exterior, além do modelo e do estado de funcionamento.
• Comandar a camada Faikout Auto: banda alvo, agendamentos e uma referência de temperatura externa.
• Integrar com o Home Assistant (deteção automática nativa), openHAB, Node-RED, Domoticz, ioBroker e qualquer outro sistema que comunique por MQTT.

O controlo por MQTT funciona em paralelo com a interface web integrada e o comando por infravermelhos. Uma alteração feita a partir de qualquer origem aparece em todo o lado em poucos segundos.

2. Antes de começar

Precisa de:

• Um Faikout instalado e já ligado à sua rede WiFi de 2,4 GHz (consulte o manual de configuração). Pode aceder-lhe em GuestAC.local através de um navegador.
• Um broker MQTT na mesma rede. As opções habituais são o add-on Mosquitto dentro do Home Assistant, ou um Mosquitto autónomo num Raspberry Pi, NAS ou servidor.
• O endereço IP ou nome de anfitrião do broker e um nome de utilizador e palavra-passe se o broker exigir autenticação (o broker do Home Assistant normalmente exige).

Mantenha o broker numa rede que controle. O MQTT do Faikout é tráfego local simples e não se destina a ser exposto à internet.

3. Passo 1: apontar o Faikout para o seu broker MQTT

1. Aceda a GuestAC.local e abra as definições de WiFi (ou mantenha premido o botão de configuração do dispositivo e ligue-se ao seu ponto de acesso Daikin/ Faikout se ainda não estiver na sua rede WiFi).
2. Na secção MQTT, introduza o Host (IP ou nome de anfitrião do broker, por ex. 192.168.1.10) e, se o seu broker os utilizar, o nome de utilizador e a palavra-passe.
3. Certifique-se de que o nome de anfitrião está definido com algo fácil de memorizar, por ex. GuestAC. Este nome passa a fazer parte de todos os tópicos MQTT, por isso escolha-o antes de criar automações.
4. Guarde. O Faikout volta a ligar-se e começa a publicar.

A definição de ligação subjacente é mqtthost (padrão da biblioteca RevK). O nome de utilizador e a palavra-passe são introduzidos na mesma página. Também pode alterá-los mais tarde através do próprio MQTT, depois de estabelecida a ligação (consulte a referência de definições).

4. Passo 2: confirmar que está ligado

Subscreva tudo o que diz respeito a esse dispositivo e observe o estado retido:

      mosquitto_sub -h 192.168.1.10 -u USER -P PASS -t 'state/GuestAC/#' -v
    

Deverá ver uma mensagem retida em state/GuestAC. O seu payload indica online true quando o ar condicionado está a comunicar com o módulo. O tópico state/GuestAC isolado representa a presença do próprio dispositivo: um payload de false significa que o próprio Faikout está offline (esta é a sua mensagem MQTT will/birth).

Se nada chegar, avance para a Resolução de problemas.

5. A estrutura de tópicos

O Faikout utiliza a disposição de tópicos padrão da biblioteca RevK: prefix/hostname/suffix . Com o nome de anfitrião GuestAC:

Para a maioria das automações só precisa de dois destes: publicar em command/GuestAC/control e subscrever state/GuestAC.

6. Enviar comandos

Publique em command/GuestAC/<command>. Os comandos simples não levam payload; alguns recebem um argumento como payload.

Exemplos:

      # Power on
mosquitto_pub -h 192.168.1.10 -t 'command/GuestAC/on' -n

# Switch to cooling
mosquitto_pub -h 192.168.1.10 -t 'command/GuestAC/cool' -n

# Set target to 21 C
mosquitto_pub -h 192.168.1.10 -t 'command/GuestAC/temp' -m '21'
    

7. A mensagem control (a principal)

command/GuestAC/control recebe um payload JSON e é a forma mais limpa de definir várias coisas de uma só vez. Os mesmos nomes de campo aparecem no JSON de estado, pelo que o que envia espelha o que lê.

Exemplo: arrefecer até 24 °C com ventoinha em auto e oscilação vertical ativada:

      mosquitto_pub -h 192.168.1.10 -t 'command/GuestAC/control' \
  -m '{"power":true,"mode":"C","temp":24,"fan":"A","swingv":true}'
    

Nota: powerful, econo, streamer e extras semelhantes dependem do modelo. O S21 foi obtido por engenharia inversa e não é idêntico entre unidades, pelo que um interruptor que a sua unidade não tenha é simplesmente ignorado. O JSON de estado indica quais os controlos que a sua unidade realmente disponibiliza.

8. Ler o estado

O Faikout publica o estado em três famílias de tópicos:

• state/GuestAC é o estado para pessoas/automações, publicado a cada reporting segundos (predefinição 60) e em alterações significativas. Ative livestatus para publicar também a cada alteração em tempo real.
• Faikout/... é publicado cerca de uma vez por minuto e destina-se à ferramenta faikoutlog para armazenamento numa base de dados MySQL/MariaDB com vista à criação de gráficos.
• <MAC>/... é o feed de deteção automática do Home Assistant, publicado quando o suporte de HA está ativado (consulte a secção 9).

O JSON de state inclui tudo o que consta da tabela control acima (pode assim voltar a ler power, mode, temp, fan, etc.) mais estes campos só de leitura:

Formato de registo em base de dados: no feed Faikout/, cada valor é resumido ao longo do período. Se não se alterou, é reportado como um único valor; se se alterou, um valor numérico passa a um array [min, average, max] e um boolean passa a uma fração 0.0– 1.0 indicando durante que parte do período esteve verdadeiro. Ative fixstatus para usar sempre o formato de array/fração, independentemente disso.

9. Home Assistant através de MQTT

O Faikout tem deteção automática nativa do Home Assistant, ativada por predefinição (definição haenable, predefinição ativada). Assim que o módulo estiver a comunicar com o mesmo broker que o Home Assistant, surge automaticamente uma entidade climate.

Configuração:

1. Execute um broker MQTT que o Home Assistant utilize. O mais fácil é o add-on Mosquitto broker no Home Assistant OS, com a integração MQTT adicionada.
2. Crie um utilizador MQTT no Home Assistant para o dispositivo (um utilizador HA normal funciona com o add-on Mosquitto).
3. Na página de configuração do Faikout, defina o host MQTT para o IP do Home Assistant e introduza esse nome de utilizador e palavra-passe.
4. Em menos de um minuto o Home Assistant deteta o dispositivo (publicado nos tópicos <MAC>/...) e adiciona um cartão climate. Não é necessário YAML.

Definições úteis relacionadas com o HA (definidas por MQTT ou na página web Advanced):

YAML do painel e do cartão de entidade

Não precisa de YAML para criar as entidades. A deteção automática gera, por si só, uma entidade climate mais sensores de temperatura. O YAML abaixo serve para os dispor num painel Lovelace.

Os IDs de entidade derivam do nome de anfitrião, pelo que um dispositivo chamado GuestAC origina climate.guestac e sensores como sensor.guestac_temperature. Os slugs exatos variam com a versão do firmware e as suas definições de nomenclatura do HA, por isso confirme-os em Settings → Devices & Services → MQTT → (o seu dispositivo) ou Developer Tools → States, e ajuste os IDs abaixo em conformidade.

Cartão de entidade. Adicione um cartão a qualquer painel com Add card → Manual e cole:

      type: entities
title: Guest AC
show_header_toggle: false
entities:
  - entity: climate.guestac          # adjust IDs to match your install
    name: Air conditioner
  - type: section
    label: Live temperatures
  - entity: sensor.guestac_temperature
    name: Room
  - entity: sensor.guestac_outside_temperature
    name: Outside
  - entity: sensor.guestac_inlet_temperature
    name: Inlet
  - entity: sensor.guestac_liquid_temperature
    name: Liquid / coil
    

Vista de painel completa. Abra um painel, Edit → (três pontos) → Raw configuration editor, e adicione isto como uma nova vista em views::

      title: Climate
path: climate
icon: mdi:air-conditioner
cards:
  - type: thermostat
    entity: climate.guestac          # adjust IDs to match your install

  - type: entities
    title: Guest AC
    entities:
      - entity: climate.guestac
        name: Controls
      - type: section
        label: Live temperatures
      - entity: sensor.guestac_temperature
        name: Room
      - entity: sensor.guestac_outside_temperature
        name: Outside
      - entity: sensor.guestac_inlet_temperature
        name: Inlet
      - entity: sensor.guestac_liquid_temperature
        name: Liquid / coil

  - type: history-graph
    title: Temperatures (24 h)
    hours_to_show: 24
    entities:
      - sensor.guestac_temperature
      - sensor.guestac_outside_temperature
    

Se preferir construir um único cartão visualmente, tanto o cartão "Climate" do Mushroom como o cartão Thermostat integrado se associam diretamente a climate.guestac.

Alternativa mais simples, sem MQTT. O Faikout também emula a API local da própria Daikin e responde à deteção UDP compatível com BRP (definição udpdiscovery). Se não quiser executar um broker MQTT, pode em alternativa adicionar a integração Daikin integrada do Home Assistant e apontá-la para o endereço IP do Faikout. Para utilizadores não técnicos, este é o caminho menos complicado para chegar ao HA. Reserve a via MQTT para quando quiser funcionalidades que a integração Daikin não disponibiliza, ou quando estiver a integrar com algo que não seja o HA.

Apple Home / Alexa / Google. Estes não comunicam diretamente por MQTT, mas uma ponte resolve a diferença. O Home Assistant faz a ponte com os três. Para um agregado exclusivamente Apple sem HA, o Homebridge com um plugin MQTT (por exemplo o EasyMQTT) integra o Faikout na app Casa nativa do iOS e na Siri. É um caminho bem conhecido, mas implica configurar um servidor próprio (self-hosted), pelo que deve contar com alguma configuração.

10. Outras plataformas

Os mesmos dois tópicos ( command/GuestAC/control para escrever, state/GuestAC para ler) funcionam em todo o lado.

Linha de comandos do mosquitto

      # Watch everything for this device
mosquitto_sub -h 192.168.1.10 -u USER -P PASS -t 'state/GuestAC/#' -v

# Ask the device to report its current settings (empty payload)
mosquitto_pub -h 192.168.1.10 -t 'setting/GuestAC' -n

# Change one setting
mosquitto_pub -h 192.168.1.10 -t 'setting/GuestAC/reporting' -m '30'

# Full control
mosquitto_pub -h 192.168.1.10 -t 'command/GuestAC/control' \
  -m '{"power":true,"mode":"H","temp":21,"fan":2}'
    

Node-RED

• Para controlar: um nó mqtt out com o tópico command/GuestAC/control. Alimente-o com um msg.payload que seja um objeto JSON (use um nó template ou function, ou um nó change que defina o payload como um valor JSON).
• Para monitorizar: um nó mqtt in em state/GuestAC e, em seguida, um nó json para o converter num objeto sobre o qual pode encaminhar (por ex. payload.home, payload.power).

openHAB

Use o binding MQTT genérico. Crie um MQTT Thing para o broker e, depois, canais como:

• um canal Switch com commandTopic = command/GuestAC/control, formatando o valor como {"power":%s};
• um canal Number com stateTopic = state/GuestAC e uma transformação JSONPATH como $.home para ler a temperatura da divisão.

O mesmo padrão (publicar JSON em command/.../control, interpretar JSON de state/...) aplica-se ao Domoticz, ioBroker, Jeedom, FHEM, Homey, Hubitat e Gladys.

11. Faikout Auto através de MQTT

O Faikout Auto é uma camada de controlo adicional que mantém uma banda alvo ajustando a unidade entre aquecimento/arrefecimento/desligado, opcionalmente usando um sensor de temperatura externo em vez do próprio do ar condicionado. Pode comandá-lo de três formas: a partir da interface web, a partir de um sensor BLE, ou através de MQTT. As vias MQTT estão abaixo.

A. Enviar uma leitura a partir da sua própria automação

Envie uma mensagem control contendo env (e opcionalmente target). A unidade passa então a considerar-se sob controlo remoto:

      mosquitto_pub -h 192.168.1.10 -t 'command/GuestAC/control' \
  -m '{"env":22.4,"target":[20,22]}'
    

• env é a temperatura atual da divisão a partir do seu sensor. Deve ser reenviada em cada mensagem control e, no mínimo, a cada tcontrol segundos (predefinição 600). Se exceder o tempo limite, a unidade sai do modo remoto/auto.
• target como array [min,max] (ou um único número com margin) força o modo Faikout Auto e define a banda de conforto.

B. Subscrever o Faikout a um tópico de sensor

Em vez de enviar, indique ao Faikout para seguir um tópico MQTT já existente:

Importante: o payload em autotopic tem de ser JSON contendo o campo indicado. Um tópico que publique um número isolado (por exemplo um tópico de estado ESPHome simples) não será interpretado; encapsule-o em JSON, ou utilize a via A.

C. Seguir um sensor externo mas manter o ligar/desligar manual

Um pedido comum: controlar com base numa leitura externa precisa, mas nunca deixar a unidade ligar-se ou desligar-se sozinha. O senão é que enviar env torna a unidade "remota" e, quando remota, assume-se o controlo automático de energia se autoptemp não for zero (predefinição 0.5). Então:

• Defina autop off e autoptemp 0 (impede o ligar/desligar automático).
• Mantenha tempadjust on (é isto que efetivamente orienta a unidade para a sua referência: ajusta o ponto de regulação (setpoint) por reference - measured).
• Não envie um array target (um array força o comportamento completo de banda/energia do Auto). Envie apenas {"env": 22.4}.

      mosquitto_pub -h 192.168.1.10 -t 'setting/GuestAC' -m '{"autop":false,"autoptemp":0}'
mosquitto_pub -h 192.168.1.10 -t 'command/GuestAC/control' -m '{"env":22.4}'
    

Controlos do modo automático que também pode enviar numa mensagem control

Estes espelham as definições e são reportados no estado quando não se está sob controlo remoto:

12. Referência de definições

As definições são lidas e escritas por MQTT de duas formas:

• Todas de uma vez / leitura de retorno: publique JSON em setting/GuestAC, por ex. {"reporting":30,"livestatus":true}. Um payload vazio faz com que o dispositivo publique as suas definições atuais.
• Uma de cada vez: publique o valor isolado em setting/GuestAC/<name>, por ex. tópico setting/GuestAC/livestatus com payload true.

Os nomes abaixo são os nomes MQTT (a página web Advanced agrupa-os, mas por MQTT são escritos como uma só palavra). Este é um subconjunto funcional; o dump de definições do próprio dispositivo (payload vazio para setting/GuestAC) é a lista autoritativa para o seu firmware.

Ligação e reporte

Home Assistant

Consulte a secção 9: haenable, haswitches, ha1c, hafanrpm, hacomprpm, hadomain, udpdiscovery, nohvacaction, nohomepreset.

Faikout Auto

O ajuste fino da previsão e do comportamento da banda ( pushtemp, switchtemp, coolover, coolback, heatover, heatback, tpredicts, tpredictt, tsample, tcoolmin, theatmax, frosttemp, minoutside) está documentado no manual Advanced e raramente precisa de ser alterado.

Substituições de capacidades

Se o firmware oferecer um controlo que a sua unidade na verdade não tem (ou vice-versa), as definições no... indicam-lhe o que ocultar: por exemplo nopowerful, noecono, nostreamer, noswingv, noswingh, noquiet, nodemand, nofaikoutauto. As definições de forçar protocolo nos21, nox50a, nocnwired impedem-no de tentar um dado protocolo se a deteção automática escolher o errado.

Depuração

13. Resolução de problemas

Não aparece nada no MQTT / o dispositivo surge como offline. Verifique o tópico state/GuestAC isolado: false significa que o próprio Faikout não está ligado ao broker. Em seguida, confirme que o IP/nome de anfitrião do broker nas definições está acessível, que o nome de utilizador e a palavra-passe MQTT estão corretos, que o broker está à escuta (normalmente na porta 1883 da LAN) e que o módulo está na sua rede WiFi de 2,4 GHz (não usa 5 GHz). Confirme que GuestAC.local carrega num navegador para provar que o WiFi está bem; nesse caso, trata-se de um problema de credenciais MQTT ou de acessibilidade do broker.

A unidade continua a ligar-se sozinha. Enviar env numa mensagem control coloca a unidade sob controlo remoto e, quando remota, assume-se o controlo automático de energia se autoptemp não for zero (predefinição 0.5). Para manter o ligar/desligar manual, defina autop off e autoptemp 0, mantenha tempadjust on, e envie apenas {"env": ...} sem array target. Consulte a secção 11C.

O Faikout sai do modo Auto ao fim de algum tempo. As mensagens env/ control expiram ao fim de tcontrol segundos (predefinição 600). Reenvie env em cada mensagem control e numa periodicidade inferior ao tempo limite.

autotopic não faz nada. O tópico subscrito tem de transportar JSON com o campo indicado em autopayload. Um payload com um número isolado não será interpretado. Publique JSON, ou envie o valor por si próprio com uma mensagem control env (secção 11A).

O Home Assistant não mostra o dispositivo. haenable tem de estar ativado (está por predefinição), a integração MQTT do HA tem de estar instalada com a deteção ativada, e o dispositivo tem de estar no mesmo broker que o HA. Confirme que as mensagens de deteção estão a chegar subscrevendo <MAC>/# (o endereço MAC do módulo). Se preferir não usar MQTT de todo, utilize antes a integração Daikin nativa com o IP do Faikout.

O estado parece desatualizado. As mensagens state/ são retidas, pelo que um cliente pode mostrar o último valor após um reinício. Se vir dados genuinamente antigos, limpe a mensagem retida nesse tópico e ative livestatus para atualizações instantâneas a cada alteração.

Alguns controlos não fazem nada. O S21 foi obtido por engenharia inversa e varia consoante o modelo; powerful, econo, demand e semelhantes podem não existir na sua unidade, sendo simplesmente ignorados. O JSON de estado mostra quais os controlos que a sua unidade realmente disponibiliza.

14. Guia de referência rápida

Substitua GuestAC pelo seu nome de anfitrião e 192.168.1.10 pelo seu broker.

Ler (subscrever)

Comandos (publicar em command/GuestAC/...)

O payload control

      {"power":true,"mode":"C","temp":24,"fan":"A","swingv":true}
    

Definições (publicar em setting/GuestAC...)

Sensor externo, manter o ligar/desligar manual

Fontes: firmware e manuais RevK ESP32-Faikout (README, Setup, Controls, Advanced) e ESP/main/settings.def no Codeberg (codeberg.org/RevK/ESP32-Faikout). O comportamento descrito corresponde ao firmware de junho de 2026; o dump de definições do próprio dispositivo é autoritativo para a versão que tem instalada.