Manual MQTT

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

Isto 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 às 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 do broker de exemplo é 192.168.1.10. Substitua ambos pelos seus próprios.

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, velocidade da ventoinha, oscilação das lâminas, powerful/econo.
• Ler telemetria em tempo real que o comando IR oculta: temperaturas do ambiente, da serpentina/líquido, da entrada e do exterior, bem como o modelo e o 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), o openHAB, o Node-RED, o Domoticz, o ioBroker e tudo o mais que comunique por MQTT.

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

2. Antes de começar

Necessita de:

• Um Faikout instalado e já ligado à sua rede WiFi de 2,4GHz (consulte o manual de configuração). Pode aceder-lhe em GuestAC.local num navegador.
• Um broker MQTT na mesma rede. Escolhas comuns 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 é simples tráfego local 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 WiFi (ou mantenha premida a configuração do dispositivo e, em seguida, ligue-se ao respetivo ponto de acesso Daikin/Faikout caso ainda não esteja na sua rede WiFi).
2. Na secção MQTT, introduza o Host (IP ou nome de anfitrião do broker, p. ex. 192.168.1.10) e, se o seu broker os utilizar, o Username e a Password.
3. Certifique-se de que o Hostname está definido como algo memorável, p. ex. GuestAC. Este nome passa a fazer parte de cada tópico 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 os pode alterar mais tarde através do próprio MQTT depois de ligado (consulte a Referência de definições).

4. Passo 2: Confirmar que está ligado

Não precisa de um terminal para isto. Há dois locais que o mostram de imediato.

Na própria página do Faikout

Aceda a GuestAC.local. No topo da página, ao lado do nome do dispositivo, o Faikout mostra o estado do broker. MQTT connected significa que o módulo chegou ao seu broker e está a publicar.

O distintivo fica ao lado do nome do dispositivo, no topo da página. O host, o utilizador e a palavra-passe do MQTT estão mais abaixo na mesma página.

Se esse distintivo não aparecer, ou o host, o nome de utilizador ou a palavra-passe estão errados, ou o broker não está acessível a partir da rede em que o módulo se encontra. Verifique novamente a secção MQTT na página de definições e depois consulte a Resolução de problemas.

No Home Assistant

Não há nada a acrescentar manualmente. O Faikout publica as mensagens de deteção MQTT do Home Assistant, por isso, assim que chegar ao broker, o Home Assistant encontra-o sozinho. Basta que a integração MQTT já esteja configurada e apontada para o mesmo broker:

1. Vá a Settings > Devices & services > MQTT e abra a lista de dispositivos.
2. GuestAC aparece em poucos segundos, listado como fabricado pela RevK, com a versão do firmware.
3. Abra-o e o dispositivo completo já lá está: uma entidade climate (MQTT HVAC) a mostrar a temperatura atual e a pretendida, os comandos de modo e de funcionalidades em Controls (Auto, Comfort, Econo, Power, Powerful, Quiet outdoor, Sensor, Streamer, Restart) e, em Sensors, as temperaturas do ambiente e pretendida, as velocidades do compressor e da ventoinha, a humidade, as temperaturas da serpentina e exterior, o consumo de energia e a energia acumulada.

Uma página de dispositivo Faikout no Home Assistant. Nada aqui foi acrescentado manualmente: a entidade climate, os comandos e os sensores chegam todos pela deteção MQTT.

Se não aparecer, confirme que o Home Assistant está a usar o mesmo broker do módulo e depois consulte a Resolução de problemas. Nunca deverá ser necessário escrever manualmente uma entidade climate em YAML para um Faikout: se estiver a fazê-lo, algo está errado a montante.

Se preferir verificar a partir de um terminal

Opcional, e só vale a pena se já tiver as ferramentas de cliente mosquitto instaladas:

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

Deverá ver uma mensagem retida state/GuestAC. O seu payload indica online como true quando o ar condicionado está a comunicar com o módulo. O tópico state/GuestAC isolado é 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 recebem 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 automática 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 em todas as unidades, pelo que um interruptor que a sua unidade não tenha é simplesmente ignorado. O JSON de estado indica que controlos a sua unidade realmente expõe.

8. Ler o estado

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

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

O JSON state inclui tudo o que consta na tabela control acima (pelo que pode reler power, mode, temp, fan, etc.) além destes campos só de leitura:

Formato de registo em base de dados: no fluxo Faikout/, cada valor é resumido ao longo do período. Se não tiver mudado, é comunicado como um único valor; se mudou, um valor numérico passa a ser uma matriz [min, average, max] e um valor booleano passa a ser uma fração 0.0–1.0 correspondente à parte do período em que esteve true. Ative fixstatus para utilizar sempre o formato de matriz/fração, independentemente disso.

9. Home Assistant através de MQTT

O Faikout tem deteção automática nativa do Home Assistant e está 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 MQTT host para o IP do Home Assistant e introduza esse nome de utilizador e palavra-passe.
4. No espaço 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 via 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 cria sozinha uma entidade climate e sensores de temperatura. O YAML abaixo destina-se a dispô-los num painel Lovelace.

Os IDs de entidade derivam do nome de anfitrião, pelo que um dispositivo com o nome GuestAC dá climate.guestac e sensores como sensor.guestac_temperature. Os slugs exatos variam consoante a versão do firmware e as suas definições de nomenclatura do HA, por isso confirme-os em Definições → Dispositivos e Serviços → MQTT → (o seu dispositivo) ou Ferramentas de Programador → Estados e ajuste os IDs abaixo em conformidade.

Cartão de entidade. Adicione um cartão a qualquer painel com Adicionar cartão → 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 completa do painel. Abra um painel, Editar → (três pontos) → Editor de configuração em bruto 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 Mushroom "Climate" como o cartão Thermostat integrado se associam diretamente a climate.guestac.

Alternativa mais simples, sem MQTT. O Faikout também emula a própria API local da Daikin e responde à deteção UDP compatível com BRP (definição udpdiscovery). Se não quiser executar um broker MQTT, pode antes 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, esta é a via menos complicada para o HA. Reserve o caminho MQTT para quando pretender funcionalidades que a integração Daikin não expõe, ou quando estiver a integrar com algo diferente do HA.

Apple Home / Alexa / Google. Estes não comunicam diretamente por MQTT, mas uma ponte preenche essa lacuna. O Home Assistant faz de ponte para os três. Para um agregado familiar exclusivamente Apple sem HA, o Homebridge com um plugin MQTT (por exemplo, o EasyMQTT) integra o Faikout na aplicação nativa iOS Home e na Siri. É uma via bem estabelecida, mas implica um servidor autoalojado a configurar, 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. Forneça-lhe um msg.payload que seja um objeto JSON (utilize 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 (p. ex. payload.home, payload.power).

openHAB

Utilize 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 ambiente.

O mesmo padrão (publicar JSON em command/.../control, analisar 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 ao alternar a unidade entre aquecimento/arrefecimento/desligado, utilizando opcionalmente um sensor de temperatura externo em vez do do próprio 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 são apresentadas abaixo.

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

Envie uma mensagem control que contenha 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 ambiente atual a partir do seu sensor. Tem de ser reenviada em cada mensagem control e, pelo menos, a cada tcontrol segundos (predefinição 600). Se expirar, a unidade sai do modo remoto/automático.
• target como uma matriz [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 que siga um tópico MQTT existente:

Importante: o payload em autotopic tem de ser JSON que contenha o campo indicado. Um tópico que publique um número simples (por exemplo, um tópico de estado ESPHome comum) não será analisado; envolva-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 rigorosa, mas nunca deixar a unidade ligar-se ou desligar-se sozinha. O senão é que enviar env torna a unidade "remota" e, em modo remoto, assume-se a alimentação automática se autoptemp não for zero (predefinição 0.5). Por isso:

• Defina autop como desligado e autoptemp como 0 (impede o ligar/desligar automático).
• Mantenha tempadjust ligado (é isto que efetivamente direciona a unidade para a sua referência: ajusta o ponto de regulação em reference - measured).
• Não envie uma matriz target (uma matriz força o comportamento completo de banda/alimentação 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 Auto que também pode enviar numa mensagem control

Estes espelham as definições e são comunicados no estado quando não 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 / releitura: publique JSON em setting/GuestAC, p. 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 simples em setting/GuestAC/<name>, p. 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 única palavra). Este é um subconjunto prático; o despejo de definições do próprio dispositivo (payload vazio em setting/GuestAC) é a lista oficial para o seu firmware.

Ligação e comunicação de dados

Home Assistant

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

Faikout Auto

O ajuste fino do comportamento de previsão e de banda (pushtemp, switchtemp, coolover, coolback, heatover, heatback, tpredicts, tpredictt, tsample, tcoolmin, theatmax, frosttemp, minoutside) está documentado no manual Advanced e raramente necessita 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 imposição de protocolo nos21, nox50a, nocnwired impedem-no de tentar um determinado 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 mostra-se 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 é acessível, que o nome de utilizador e a palavra-passe MQTT estão corretos, que o broker está à escuta (normalmente a porta 1883 na LAN) e que o módulo está na sua rede WiFi de 2,4GHz (não utiliza 5GHz). Confirme que GuestAC.local carrega num navegador para comprovar 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, em modo remoto, assume-se a alimentação automática se autoptemp não for zero (predefinição 0.5). Para manter o ligar/desligar manual, defina autop como desligado e autoptemp como 0, mantenha tempadjust ligado e envie apenas {"env": ...} sem matriz target. Consulte a secção 11C.

O Faikout sai do modo Auto ao fim de algum tempo. As mensagens env/control expiram após tcontrol segundos (predefinição 600). Reenvie env em cada mensagem control e com um intervalo 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 apenas um número não será analisado. Ou publica JSON, ou envia você próprio o valor 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 HA MQTT 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 realmente antigos, limpe a mensagem retida nesse tópico e ative livestatus para obter 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 e são simplesmente ignorados. O JSON de estado mostra que controlos a sua unidade realmente expõe.

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 despejo de definições do próprio dispositivo é a referência oficial para a versão que tem instalada.