Faikin Ninja P1P2 — Manual MQTT

Um guia completo para controlar e monitorizar um Faikin Ninja P1P2 por MQTT, desde a primeira configuração até à referência completa de tópicos, comandos e sensores.

Abrange o módulo Faikin Ninja instalado num barramento de controlo Daikin P1/P2: VRV e VRF, Sky Air, comerciais da série F e sistemas de conduta com Airbase ou controlador de zonas. Ao longo da página, o tópico base de exemplo é ac/livingroom e o IP do broker de exemplo é 192.168.1.10. Substitua ambos pelos seus.

Esta não é a mesma interface MQTT do Faikin Faikout. O Ninja usa firmware diferente, com uma disposição de tópicos diferente, pelo que as automatizações escritas para um Faikout não se aplicam. Se tiver um Faikout, consulte antes o manual MQTT do Faikin Faikout. A secção 5 tem uma comparação lado a lado.

1. O que o MQTT lhe dá

A página web integrada do Ninja chega para o uso diário. O MQTT é o que precisa quando o ar condicionado tem de fazer parte de algo maior.

• Automatização. Acione a unidade a partir de qualquer coisa: presença, um horário, um feed de preços da eletricidade, um sensor de porta, a temperatura de outra divisão.
• Instrumentação a sério. O barramento P1/P2 transporta muito mais do que ligado, desligado e temperatura. O Ninja publica os termístores interiores e exteriores, as pressões do refrigerante, a posição da válvula de expansão, o estado do compressor e do ventilador, as horas de funcionamento e os próprios códigos de avaria da unidade. Quase nada disto é visível no comando de parede.
• Zonas em sistemas de conduta. Se tiver um controlador de zonas Daikin, cada registo passa a ser um interruptor controlável individualmente.
• Um único sítio para tudo. Home Assistant, Node-RED, openHAB e tudo o mais que fale MQTT podem ver o mesmo dispositivo ao mesmo tempo.
• Fica local. O MQTT corre no seu próprio broker, na sua própria rede. Nada sai de casa e não há conta nenhuma para criar.

2. Antes de começar

Precisa de três coisas.

1. O Ninja na sua rede WiFi, acessível na respetiva página web. Se não estiver, faça primeiro o guia de instalação.
2. Um broker MQTT na sua rede. Se usa Home Assistant, instale o add-on Mosquitto broker; demora poucos minutos e dá-lhe um broker mais um nome de utilizador e uma palavra-passe. Caso contrário, serve qualquer broker Mosquitto ou compatível numa máquina que fique sempre ligada.
3. O endereço IP, o nome de utilizador e a palavra-passe do broker.

Não precisa de Home Assistant para usar MQTT, nem precisa de MQTT para usar Home Assistant. São escolhas separadas que por acaso funcionam bem juntas.

3. Passo 1: apontar o Ninja ao seu broker MQTT

Abra a página web do Ninja e vá às MQTT settings.

Estes dois últimos contam mais do que parece. O Ninja constrói todos os seus tópicos a partir deles:

tópico base = <Topic> / <Friendly Name>

Assim, Topic = ac e Friendly Name = livingroom dá um tópico base ac/livingroom, e o tópico de estado passa a ser ac/livingroom/state.

Escolha ambos antes de construir qualquer automatização. Alterá-los depois renomeia todos os tópicos e parte em silêncio tudo o que se refira aos antigos. Uma convenção útil é um prefixo comum para todas as unidades (ac) mais um nome de divisão que não vá mudar (livingroom, masterbed, office).

Guarde, e o módulo volta a ligar-se e começa a publicar.

4. Passo 2: confirmar que está ligado

Não precisa de um terminal para isto. Dois sítios dizem-lho de imediato.

Na própria página do Ninja

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

Se faltar, então o anfitrião, a porta, o nome de utilizador ou a palavra-passe estão errados, ou o broker não está acessível a partir da rede onde o módulo se encontra. Reveja as definições MQTT e depois consulte a Resolução de problemas.

No Home Assistant

Não há nada a acrescentar à mão. O Ninja publica as mensagens de discovery MQTT do Home Assistant, por isso, assim que chega ao broker, o Home Assistant encontra-o sozinho. Desde que a integração MQTT já esteja configurada e apontada ao mesmo broker:

1. Vá a Settings > Devices & services > MQTT e abra a lista de dispositivos.
2. O seu dispositivo aparece em poucos segundos, com o nome do Friendly Name que definiu.
3. Abra-o e está lá tudo: uma entidade climate com modo, temperatura alvo, velocidade do ventilador e deflector; uma longa lista de sensores de diagnóstico; e, se tiver um controlador de zonas, um interruptor por cada zona de registo.

Nunca deverá ter de escrever à mão uma entidade climate em YAML para um Ninja. Se der por si a fazê-lo, algo está mal a montante.

Se preferir verificar a partir de um terminal

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

mosquitto_sub -h 192.168.1.10 -u USER -P PASS -t 'ac/livingroom/#' -v

Deverá ver ac/livingroom/availability a indicar online, e um payload JSON completo em ac/livingroom/state.

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

5. A estrutura de tópicos

Tudo assenta no tópico base que construiu na secção 3. Com o tópico base ac/livingroom:

Climatização e controlo

Sistema e gestão

Para a maioria das automatizações só precisa de três: publicar nos tópicos .../set e subscrever state e availability.

Se também tiver um Faikout

Os dois produtos seguem abordagens opostas, por isso vale a pena vê-los lado a lado.

6. Enviar comandos

Publique uma cadeia de texto simples no tópico .../set correspondente. Não há invólucro JSON: o payload é o valor puro.

power/set

mode/set

temp/set

A temperatura alvo como número, p. ex. 24. Intervalo 16 a 32 °C, em passos de 1.0 °C. Pode estreitar esse intervalo com system/set_min_temp e system/set_max_temp (secção 11).

fan/set

As velocidades disponíveis dependem da unidade interior. O módulo indica as que a sua unidade suporta de facto; enviar uma que não exista é ignorado.

Os agrupamentos habituais são:

• 3 velocidades com auto: low, medium, high, auto
• 2 velocidades: low, high
• 4 velocidades zonas/Airbase: low, medium, low_auto, medium_auto
• 6 velocidades zonas/Airbase: low, medium, high, low_auto, medium_auto, high_auto

vane/set

Exemplos

# On, cooling, 24 C, auto fan, swinging
mosquitto_pub -h 192.168.1.10 -t 'ac/livingroom/power/set' -m 'ON'
mosquitto_pub -h 192.168.1.10 -t 'ac/livingroom/mode/set'  -m 'cool'
mosquitto_pub -h 192.168.1.10 -t 'ac/livingroom/temp/set'  -m '24'
mosquitto_pub -h 192.168.1.10 -t 'ac/livingroom/fan/set'   -m 'auto'
mosquitto_pub -h 192.168.1.10 -t 'ac/livingroom/vane/set'  -m 'swing'

Como cada controlo tem o seu próprio tópico, a ordem não importa e pode enviar apenas os que lhe interessam.

7. Zonas em sistemas de conduta

Se houver um controlador de zonas Daikin no barramento P1/P2, o Ninja consegue abrir e fechar cada registo.

Publique ON ou OFF em ac/livingroom/zone/<n>/set, em que <n> é 1 a 8:

# Open zone 1, close zone 3
mosquitto_pub -h 192.168.1.10 -t 'ac/livingroom/zone/1/set' -m 'ON'
mosquitto_pub -h 192.168.1.10 -t 'ac/livingroom/zone/3/set' -m 'OFF'

O payload de estado devolve:

No Home Assistant, cada zona ativa é descoberta automaticamente como interruptor próprio, pelo que não é preciso configurar nada.

Duas notas práticas. As zonas só aparecem se existir um controlador de zonas, por isso num split simples não haverá quaisquer chaves de zona. E fechar todas as zonas ao mesmo tempo é uma boa forma de maltratar um sistema de conduta: deixe pelo menos uma aberta, ou desligue antes a unidade.

8. Ler o estado

O módulo publica um objeto JSON completo em <base>/state sempre que algo muda.

Só aparecem os sensores que a sua unidade comunica de facto. O Ninja deteta o que as unidades interior e exterior ligadas publicam e esconde o resto, pelo que o seu payload será mais curto do que o exemplo abaixo e dois Daikin diferentes produzem chaves diferentes. É normal. Escreva as automatizações com base nas chaves que consegue ver na sua unidade.

{
  "power": "on",
  "mode": "cool",
  "action": "cooling",
  "temperature": 24,
  "fan": "auto",
  "vane": "swing",
  "room_temperature": 25.5,
  "outside_temperature": 32.0,
  "f_intake_temp": 25.0,
  "f_indoor_th1": 18.2,
  "f_indoor_th2": 24.8,
  "f_outdoor_th1": 32.0,
  "f_outdoor_th3": 75.4,
  "f_pe_pressure": 0.83,
  "f_pc_pressure": 2.40,
  "f_drain_pump": false,
  "f_electric_heater": false,
  "f_comp_operating": true,
  "operating": true,
  "f_fan_step": 3,
  "f_ev_pulses": 240,
  "f_id_op_hours": 1250,
  "f_error_present": false,
  "f_error_code": "",
  "f_indoor_model": "FBA100BVMA",
  "f_outdoor_model": "RZA100DV1",
  "zone_count": 4,
  "zone_1": true,
  "zone_2": true,
  "zone_3": false,
  "zone_4": false
}

As chaves a conhecer primeiro:

Uma unidade pode estar "power": "on" com "action": "idle" e isso é perfeitamente normal: chegou à temperatura. Se quiser saber se está mesmo a trabalhar, veja action, operating ou f_comp_operating.

Subscreva também <base>/availability. offline aí significa que o módulo caiu, o que é diferente de o ar condicionado estar desligado.

9. Home Assistant por MQTT

Adicione a integração MQTT e aponte-a ao mesmo broker. É toda a configuração: o Ninja anuncia-se e o Home Assistant constrói o resto.

O que obtém:

• Uma entidade climate com os modos heat, cool, dry, fan_only e off, os modos de ventilação da sua unidade, posições de oscilação 1 a 5 e swing, e um passo de 1.0 °C.
• Sensores e sensores binários para cada termístor, pressão, atuador, contador de horas, código de avaria e cadeia de modelo que a sua unidade comunica. A maioria fica em Diagnóstico.
• Interruptores para cada zona de registo ativa.

Os entity ID seguem o Friendly Name, por isso com livingroom vai obter climate.livingroom, sensor.livingroom_outside_temperature, switch.livingroom_zone_1 e assim por diante. Confirme os nomes exatos em Developer tools > States antes de escrever YAML.

Um cartão de dashboard

type: vertical-stack
cards:
  - type: thermostat
    entity: climate.livingroom

  - type: entities
    title: Zones
    entities:
      - entity: switch.livingroom_zone_1
        name: Living
      - entity: switch.livingroom_zone_2
        name: Master bed
      - entity: switch.livingroom_zone_3
        name: Study
      - entity: switch.livingroom_zone_4
        name: Kids

  - type: glance
    title: Right now
    columns: 3
    entities:
      - entity: sensor.livingroom_room_temperature
        name: Room
      - entity: sensor.livingroom_outside_temperature
        name: Outside
      - entity: binary_sensor.livingroom_compressor_operating
        name: Compressor

  - type: history-graph
    hours_to_show: 24
    entities:
      - sensor.livingroom_room_temperature
      - sensor.livingroom_outside_temperature
      - sensor.livingroom_od_pc_pressure

Uma automatização

Desligar a unidade quando a casa estiver confortável, usando action em vez de power para não disparar enquanto a unidade ainda está a trabalhar:

alias: Living room off when settled
triggers:
  - trigger: state
    entity_id: climate.livingroom
    attribute: hvac_action
    to: idle
    for: "00:20:00"
conditions:
  - condition: numeric_state
    entity_id: sensor.livingroom_room_temperature
    below: 25
actions:
  - action: climate.turn_off
    target:
      entity_id: climate.livingroom
mode: single

Vigiar avarias

alias: Air conditioner fault
triggers:
  - trigger: state
    entity_id: binary_sensor.livingroom_ac_error_present
    to: "on"
actions:
  - action: notify.mobile_app_phone
    data:
      title: Air conditioner fault
      message: >-
        Error {{ states('sensor.livingroom_ac_error_code') }} on
        {{ state_attr('climate.livingroom','friendly_name') }}.
mode: single

Essa vale a pena montar. O código de avaria é o mesmo que um técnico leria no comando de parede, e sabê-lo antes de telefonar poupa uma deslocação.

10. Outras plataformas

Os mesmos tópicos funcionam em todo o lado. Publique cadeias de texto em <base>/…/set, subscreva <base>/state.

linha de comandos mosquitto

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

# Turn on and cool to 23
mosquitto_pub -h 192.168.1.10 -t 'ac/livingroom/power/set' -m 'ON'
mosquitto_pub -h 192.168.1.10 -t 'ac/livingroom/mode/set'  -m 'cool'
mosquitto_pub -h 192.168.1.10 -t 'ac/livingroom/temp/set'  -m '23'

# Open zone 1
mosquitto_pub -h 192.168.1.10 -t 'ac/livingroom/zone/1/set' -m 'ON'

Node-RED

Use um nó MQTT in em ac/livingroom/state com a saída definida como objeto JSON já analisado e leia depois msg.payload.power, msg.payload.room_temperature e assim por diante.

Para enviar, use MQTT out com o tópico e o payload em branco, para virem da mensagem. Os payloads têm de ser cadeias de texto, por isso converta primeiro os números.

Definir a unidade toda de uma vez:

const base = "ac/livingroom";
return [
    { topic: base + "/power/set", payload: "ON" },
    { topic: base + "/mode/set",  payload: "cool" },
    { topic: base + "/temp/set",  payload: "24" },
    { topic: base + "/fan/set",   payload: "auto" }
];

Um cursor de dashboard a comandar a temperatura alvo:

msg.topic = "ac/livingroom/temp/set";
msg.payload = String(msg.payload);
return msg;

Ligar apenas se estiver desligada:

const p = typeof msg.payload === 'string'
    ? JSON.parse(msg.payload)
    : msg.payload;
if (p.power !== "on") {
    return [{ topic: "ac/livingroom/power/set", payload: "ON" }];
}
return null;

Subscrever ac/livingroom/availability é uma forma barata de esbater o seu dashboard quando o módulo cai.

openHAB

Adicione um Thing de broker MQTT e depois um Generic MQTT Thing com canais apontados aos tópicos. Um canal switch em ac/livingroom/power/set com ON/OFF, um canal number em ac/livingroom/temp/set, e canais de estado a ler ac/livingroom/state com uma transformação JSONPATH como $.room_temperature.

11. Gestão do sistema e opções

Estas ficam sob <base>/system/. A maioria reinicia o módulo, por isso não as ligue a nada que dispare com frequência.

system/set

factory apaga também as suas definições de WiFi e MQTT, pelo que o módulo volta na sua própria rede de configuração e tem de ser reconfigurado de raiz. Trate-o como último recurso.

Limites de temperatura

Útil num arrendamento ou num escritório: limite o intervalo e ninguém põe 16 °C em julho.

Safe Mode

system/set_safemode com on ou off. Reinicia.

Modbus RTU ID

system/set_modbus_rtu_id com um número de 1 a 254, para instalações de gestão técnica de edifícios que usem a versão RS485. Reinicia.

Opções por MQTT

system/opt/rqt aceita um objeto JSON e permite alterar várias definições ao mesmo tempo sem a página web:

{
  "options": {
    "homekit": "On",
    "mode": "All",
    "safemode": "Off",
    "webpanel": "On"
  }
}

O que for aceite é devolvido em system/opt/rps, por isso subscreva aí para confirmar em vez de assumir.

Desligar webpanel retira-lhe a forma de voltar a entrar. Só o faça se tiver a certeza de que o MQTT está a funcionar.

system/info

Publicado periodicamente:

{
  "connection_state": "online",
  "safe_mode": "Off",
  "reset_reason": "Software reset via ESP_RESTART",
  "web_panel": "On",
  "free_heap": "68.45",
  "rssi": "-62",
  "bssid": "AA:BB:CC:DD:EE:FF",
  "up_time": 172800,
  "min_temp": 16,
  "max_temp": 32,
  "protocol_ver": "P1P2"
}

rssi é o valor a vigiar. Abaixo de cerca de -80 dBm, tire o módulo da caixa metálica antes de culpar seja o que for.

12. Referência de sensores

Tudo o que se segue é detetado automaticamente. Se a sua unidade não o comunicar, a chave não consta do payload de estado e não é criada qualquer entidade no Home Assistant. Uma lista curta não é uma avaria.

As principais

Termístores interiores

Termístores e pressões exteriores

A temperatura de descarga e as duas pressões, em conjunto, são o mais próximo que tem de um exame de saúde ao vivo da unidade exterior. Represente-as num gráfico ao longo de uma estação e um valor anómalo salta à vista muito antes de algo disparar.

Atuadores e estado de funcionamento

Horas e avarias

Onde a unidade guarda histórico de avarias, cada evento registado traz um número de linha, o código, a data e o número da unidade:

[
  {"row": 1, "code": "A9-01", "date": "17/01/24", "unit": 0},
  {"row": 2, "code": "E7-57", "date": "10/11/23", "unit": 0},
  {"row": 3, "code": "C2-04", "date": "05/08/23", "unit": 0}
]

Telemetria do módulo

13. Resolução de problemas

Sem o distintivo MQTT connected na página web. Verifique o anfitrião e a porta, depois o nome de utilizador e a palavra-passe. Se o broker estiver numa VLAN ou sub-rede diferente da do módulo, é normalmente esse o verdadeiro problema.

O distintivo diz ligado, mas não aparece nada no Home Assistant. Confirme que a integração MQTT do Home Assistant aponta para o mesmo broker. Dois brokers na mesma rede é um erro comum e confuso. Depois verifique se o discovery está ativado nas definições do módulo.

Faltam alguns sensores. É esperado. Só é publicado o que as unidades ligadas comunicam, e um split pequeno mostra bastante menos do que um VRV. Não é avaria.

Sem interruptores de zona. As zonas precisam de um controlador de zonas Daikin no barramento P1/P2. Sem ele não há nada para controlar.

Os comandos são ignorados. Os payloads são cadeias de texto simples e são sensíveis a maiúsculas e minúsculas, conforme documentado: ON e OFF em maiúsculas para ligar/desligar e zonas, nomes de modo em minúsculas. Enviar um número em vez de uma cadeia de texto para a temperatura falha em alguns clientes, incluindo o Node-RED.

A temperatura não vai para onde quer. Verifique min_temp e max_temp em system/info. Alguém pode ter estreitado o intervalo.

Está sempre a cair. Veja rssi em system/info. Perto de -80 dBm ou pior é marginal. Tire o módulo da caixa metálica.

A unidade está ligada mas não acontece nada. Veja action e f_comp_operating. Se action for idle, chegou à temperatura. Se o compressor nunca arranca e f_error_present for verdadeiro, leia f_error_code e comunique-o ao seu instalador.

Parou tudo depois de uma alteração de definições. Renomear o Topic ou o Friendly Name renomeia todos os tópicos. As suas automatizações continuam a apontar para os antigos.

14. Guia rápido de referência

Tópico base ac/livingroom. Substitua pelo seu.

Ler (subscrever)

Controlar (publicar)

Sistema (publicar)

Chaves a vigiar

Fontes: a documentação do protocolo MQTT do Faikin Ninja P1P2. O comportamento descrito corresponde ao firmware de agosto de 2026; a página web do seu módulo e os system/info publicados são a referência para a versão que tem instalada. A disponibilidade de sensores varia consoante as unidades interior e exterior.