Manuale MQTT

Una guida completa per controllare e monitorare un Faikin Faikout tramite MQTT, dalla prima configurazione fino al riferimento completo di topic, comandi e impostazioni.

Questo riguarda il modulo WiFi Faikout con il firmware di RevK (il dispositivo è commercializzato come Faikout; potrebbe ancora comparire il vecchio nome Faikin). Si applica indistintamente alle unità S21, X50A e CN_WIRED, poiché il firmware determina il protocollo automaticamente. In tutto il documento, il nome host di esempio è GuestAC e l'IP del broker di esempio è 192.168.1.10. Sostituisca entrambi con i propri.

1. Cosa offre MQTT

Tutto è locale. Faikout parla MQTT sulla propria rete, senza account cloud e senza dipendenza da internet. Tramite MQTT è possibile:

• controllare l'unità: accensione, modalità, set-point, velocità del ventilatore, oscillazione delle alette, powerful/econo.
• leggere la telemetria in tempo reale che il telecomando IR nasconde: temperature dell'ambiente, della batteria/del liquido, di aspirazione ed esterna, oltre al modello e allo stato di funzionamento.
• gestire il livello Faikout Auto: banda obiettivo, programmazioni e un riferimento di temperatura esterno.
• integrarsi con Home Assistant (rilevamento automatico nativo), openHAB, Node-RED, Domoticz, ioBroker e qualsiasi altra cosa che parli MQTT.

Il controllo MQTT funziona in parallelo all'interfaccia web integrata e al telecomando IR. Una modifica da qualsiasi origine compare ovunque entro pochi secondi.

2. Prima di iniziare

Occorre:

• un Faikout installato e già connesso al proprio WiFi a 2,4 GHz (vedere il manuale di configurazione). È raggiungibile all'indirizzo GuestAC.local da un browser.
• un broker MQTT sulla stessa rete. Le scelte comuni sono l'add-on Mosquitto all'interno di Home Assistant, oppure un Mosquitto autonomo su un Raspberry Pi, un NAS o un server.
• l'indirizzo IP o il nome host del broker e un nome utente e una password se il broker richiede l'autenticazione (il broker di Home Assistant normalmente la richiede).

Mantenga il broker su una rete che lei controlla. L'MQTT di Faikout è traffico locale in chiaro e non è pensato per essere esposto a internet.

3. Passo 1: puntare Faikout al proprio broker MQTT

1. Acceda a GuestAC.local e apra le impostazioni WiFi (oppure tenga premuto il pulsante di configurazione del dispositivo, quindi si connetta al suo punto di accesso Daikin/Faikout se non è ancora sul suo WiFi).
2. Nella sezione MQTT, inserisca l'Host (IP o nome host del broker, ad es. 192.168.1.10) e, se il broker li usa, il Nome utente e la Password.
3. Si assicuri che il Nome host sia impostato su qualcosa di facile da ricordare, ad es. GuestAC. Questo nome diventa parte di ogni topic MQTT, quindi lo scelga prima di creare automazioni.
4. Salvi. Faikout si riconnette e inizia a pubblicare.

L'impostazione di connessione sottostante è mqtthost (standard della libreria RevK). Il nome utente e la password si inseriscono nella stessa pagina. È possibile modificarli anche in seguito tramite lo stesso MQTT una volta connesso (vedere il riferimento delle impostazioni).

4. Passo 2: confermare la connessione

Non serve un terminale. Due punti glielo dicono subito.

Sulla pagina del Faikout stesso

Vada su GuestAC.local. In alto nella pagina, accanto al nome del dispositivo, il Faikout mostra lo stato del broker. MQTT connected significa che il modulo ha raggiunto il broker e sta pubblicando.

La dicitura si trova accanto al nome del dispositivo, in alto nella pagina. Host, utente e password MQTT si trovano più in basso nella stessa pagina.

Se la dicitura non c'è, l'host, il nome utente o la password sono errati, oppure il broker non è raggiungibile dalla rete su cui si trova il modulo. Ricontrolli la sezione MQTT nella pagina delle impostazioni, poi veda la Risoluzione dei problemi.

In Home Assistant

Non c'è nulla da aggiungere a mano. Il Faikout pubblica i messaggi di discovery MQTT di Home Assistant, quindi appena raggiunge il broker Home Assistant lo trova da solo. È sufficiente che l'integrazione MQTT sia già configurata e punti allo stesso broker:

1. Vada in Impostazioni > Dispositivi e servizi > MQTT, poi apra l'elenco dei dispositivi.
2. GuestAC compare in pochi secondi, indicato come prodotto da RevK, con la sua versione del firmware.
3. Lo apra e troverà già l'intero dispositivo: un'entità clima (MQTT HVAC) con temperatura attuale e impostata, la modalità e gli interruttori delle funzioni sotto Controls (Auto, Comfort, Econo, Power, Powerful, Quiet outdoor, Sensor, Streamer, Restart) e, sotto Sensors, le temperature ambiente e impostata, le velocità di compressore e ventola, l'umidità, le temperature della batteria e esterna, il consumo elettrico e l'energia totale.

Una pagina dispositivo del Faikout in Home Assistant. Qui non è stato aggiunto nulla a mano: entità clima, controlli e sensori arrivano tutti tramite discovery MQTT.

Se non compare, verifichi che Home Assistant usi lo stesso broker del modulo, poi veda la Risoluzione dei problemi. Per un Faikout non dovrebbe mai essere necessario scrivere a mano un'entità clima in YAML: se si ritrova a farlo, qualcosa a monte non va.

Se preferisce verificare da un terminale

Facoltativo, e conviene solo se ha già installato gli strumenti client mosquitto:

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

Dovrebbe vedere un messaggio state/GuestAC trattenuto. Il suo payload riporta online true quando il climatizzatore sta comunicando con il modulo. Il topic semplice state/GuestAC è la presenza stessa del dispositivo: un payload pari a false significa che il Faikout stesso è offline (è il suo messaggio will/birth MQTT).

Se non arriva nulla, passi alla Risoluzione dei problemi.

5. La struttura dei topic

Faikout utilizza la disposizione di topic standard della libreria RevK: prefix/hostname/suffix. Con il nome host GuestAC:

Per la maggior parte delle automazioni ne servono solo due: pubblicare su command/GuestAC/control e iscriversi a state/GuestAC.

6. Inviare comandi

Pubblichi su command/GuestAC/<command>. I comandi semplici non prendono payload; alcuni prendono un argomento come payload.

Esempi:

# 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. Il messaggio control (il principale)

command/GuestAC/control prende un payload JSON ed è il modo più pulito per impostare più cose in una sola volta. Gli stessi nomi di campo compaiono nel JSON di stato, quindi ciò che invia rispecchia ciò che legge.

Esempio: raffreddare a 24 °C con ventilatore automatico, oscillazione verticale attiva:

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 simili extra dipendono dal modello. S21 è frutto di reverse engineering e non è identico su tutte le unità, quindi un interruttore che la sua unità non possiede viene semplicemente ignorato. Il JSON di stato le indica quali controlli la sua unità espone effettivamente.

8. Leggere lo stato

Faikout pubblica lo stato su tre famiglie di topic:

• state/GuestAC è lo stato destinato alle persone/all'automazione, pubblicato ogni reporting secondi (60 di default) e in caso di modifiche significative. Attivi livestatus per pubblicare anche a ogni modifica, in tempo reale.
• Faikout/... viene pubblicato circa una volta al minuto ed è destinato a essere memorizzato dallo strumento faikoutlog in un database MySQL/MariaDB per la rappresentazione grafica.
• <MAC>/... è il feed di rilevamento automatico di Home Assistant, pubblicato quando il supporto HA è abilitato (vedere la sezione 9).

Il JSON state include tutto ciò che è presente nella tabella control precedente (così è possibile rileggere power, mode, temp, fan, ecc.) più questi campi di sola lettura:

Formato di registrazione su database: nel feed Faikout/, ogni valore viene riepilogato sul periodo. Se non è cambiato, viene riportato come valore singolo; se è cambiato, un valore numerico diventa un array [min, average, max] e un booleano diventa una frazione 0.0–1.0 che indica per quanta parte del periodo è stato vero. Attivi fixstatus per usare sempre il formato array/frazione, a prescindere.

9. Home Assistant tramite MQTT

Faikout dispone del rilevamento automatico nativo per Home Assistant ed è attivo per impostazione predefinita (impostazione haenable, attiva di default). Una volta che il modulo comunica con lo stesso broker di Home Assistant, compare da sé un'entità climate.

Configurazione:

1. Esegua un broker MQTT utilizzato da Home Assistant. Il più semplice è l'add-on Mosquitto broker in Home Assistant OS, con l'integrazione MQTT aggiunta.
2. Crei un utente MQTT in Home Assistant per il dispositivo (un normale utente HA funziona con l'add-on Mosquitto).
3. Nella pagina di configurazione di Faikout, imposti l'host MQTT sull'IP di Home Assistant e inserisca quel nome utente e password.
4. Entro un minuto Home Assistant rileva il dispositivo (pubblicato sotto i topic <MAC>/...) e aggiunge una scheda climate. Nessun YAML richiesto.

Impostazioni utili relative a HA (impostate tramite MQTT o la pagina web avanzata):

YAML della dashboard e della scheda entità

Non serve YAML per creare le entità. Il rilevamento automatico crea da sé un'entità climate più i sensori di temperatura. Lo YAML seguente serve a disporle su una dashboard Lovelace.

Gli ID delle entità derivano dal nome host, quindi un dispositivo chiamato GuestAC dà climate.guestac e sensori come sensor.guestac_temperature. Gli slug esatti variano in base alla versione del firmware e alle sue impostazioni di denominazione di HA, quindi li confermi in Impostazioni → Dispositivi e servizi → MQTT → (il suo dispositivo) oppure in Strumenti per sviluppatori → Stati, e adatti di conseguenza gli ID qui sotto.

Scheda entità. Aggiunga una scheda a una qualsiasi dashboard con Aggiungi scheda → Manuale e incolli:

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 dashboard completa. Apra una dashboard, Modifica → (tre puntini) → Editor della configurazione non elaborata, e aggiunga questo come nuova vista sotto 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 preferisce costruire una singola scheda in modo visuale, sia la scheda «Climate» di Mushroom sia la scheda Thermostat integrata si collegano direttamente a climate.guestac.

Alternativa più semplice, senza MQTT. Faikout emula anche l'API locale propria di Daikin e risponde al rilevamento UDP compatibile con BRP (impostazione udpdiscovery). Se non desidera eseguire un broker MQTT, può aggiungere invece l'integrazione Daikin integrata di Home Assistant e puntarla all'indirizzo IP del Faikout. Per gli utenti non tecnici questa è la via meno macchinosa verso HA. Riservi la via MQTT a quando desidera funzioni che l'integrazione Daikin non espone, oppure quando integra qualcosa di diverso da HA.

Apple Home / Alexa / Google. Questi non parlano MQTT direttamente, ma un bridge colma la lacuna. Home Assistant fa da ponte per tutti e tre. Per una casa esclusivamente Apple senza HA, Homebridge con un plugin MQTT (ad esempio EasyMQTT) porta Faikout nell'app Home nativa di iOS e in Siri. È una via ben collaudata, ma è un server self-hosted da configurare, quindi metta in conto un po' di configurazione.

10. Altre piattaforme

Gli stessi due topic (command/GuestAC/control per scrivere, state/GuestAC per leggere) funzionano ovunque.

Riga di comando 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

• Per controllare: un nodo mqtt out con il topic command/GuestAC/control. Lo alimenti con un msg.payload che sia un oggetto JSON (usi un nodo template o function, oppure un nodo change che imposta il payload su un valore JSON).
• Per monitorare: un nodo mqtt in su state/GuestAC, quindi un nodo json per analizzarlo in un oggetto su cui instradare (ad es. payload.home, payload.power).

openHAB

Usi il binding MQTT generico. Crei un Thing MQTT per il broker, quindi canali come:

• un canale Switch con commandTopic = command/GuestAC/control, formattando il valore come {"power":%s};
• un canale Number con stateTopic = state/GuestAC e una trasformazione JSONPATH come $.home per leggere la temperatura dell'ambiente.

Lo stesso schema (pubblicare JSON su command/.../control, analizzare JSON da state/...) si applica a Domoticz, ioBroker, Jeedom, FHEM, Homey, Hubitat e Gladys.

11. Faikout Auto tramite MQTT

Faikout Auto è un livello di controllo aggiuntivo che mantiene una banda obiettivo regolando l'unità tra riscaldamento/raffreddamento/spento, usando facoltativamente un sensore di temperatura esterno anziché quello del climatizzatore. È possibile gestirlo in tre modi: dall'interfaccia web, da un sensore BLE o tramite MQTT. Le vie MQTT sono indicate di seguito.

A. Inviare una lettura dalla propria automazione

Invii un messaggio control contenente env (e facoltativamente target). L'unità si considera quindi sotto controllo remoto:

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

• env è la temperatura ambiente attuale del suo sensore. Deve essere reinviata in ogni messaggio control e almeno ogni tcontrol secondi (600 di default). In caso di timeout, l'unità esce dalla modalità remota/auto.
• target come array [min,max] (o un singolo numero con margin) forza la modalità Faikout Auto e definisce la banda di comfort.

B. Iscrivere Faikout a un topic di un sensore

Invece di inviare, indichi a Faikout di seguire un topic MQTT esistente:

Importante: il payload su autotopic deve essere JSON contenente il campo indicato. Un topic che pubblica un numero nudo (ad esempio un normale topic di stato ESPHome) non potrà essere analizzato; lo racchiuda in JSON, oppure usi la via A.

C. Seguire un sensore esterno mantenendo manuale l'accensione/spegnimento

Una richiesta frequente: regolare in base a una lettura esterna precisa, ma senza mai lasciare che l'unità si accenda o si spenga da sola. Il problema è che inviare env rende l'unità «remota», e in modalità remota l'accensione automatica viene presupposta se autoptemp non è zero (0.5 di default). Pertanto:

• Imposti autop su disattivo e autoptemp su 0 (interrompe l'accensione/spegnimento automatici).
• Mantenga tempadjust attivo (è ciò che effettivamente orienta l'unità verso il suo riferimento: regola il set-point di reference - measured).
• Non invii un array target (un array forza il comportamento completo di banda/potenza Auto). Invii solo {"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}'

Controlli della modalità auto che può inviare anche in un messaggio control

Questi rispecchiano le impostazioni e vengono riportati nello stato quando non si è sotto controllo remoto:

12. Riferimento delle impostazioni

Le impostazioni si leggono e si scrivono tramite MQTT in due forme:

• Tutte in una volta / rilettura: pubblichi JSON su setting/GuestAC, ad es. {"reporting":30,"livestatus":true}. Un payload vuoto fa sì che il dispositivo pubblichi le sue impostazioni attuali.
• Una alla volta: pubblichi il valore nudo su setting/GuestAC/<name>, ad es. topic setting/GuestAC/livestatus con payload true.

I nomi qui sotto sono i nomi MQTT (la pagina web avanzata li raggruppa, ma tramite MQTT vengono scritti come un'unica parola). Questo è un sottoinsieme pratico; il dump delle impostazioni del dispositivo stesso (payload vuoto su setting/GuestAC) è l'elenco autorevole per il suo firmware.

Connessione e segnalazione

Home Assistant

Vedere la sezione 9: haenable, haswitches, ha1c, hafanrpm, hacomprpm, hadomain, udpdiscovery, nohvacaction, nohomepreset.

Faikout Auto

La messa a punto fine della previsione e del comportamento della banda (pushtemp, switchtemp, coolover, coolback, heatover, heatback, tpredicts, tpredictt, tsample, tcoolmin, theatmax, frosttemp, minoutside) è documentata nel manuale avanzato e raramente necessita di modifiche.

Override delle funzionalità

Se il firmware offre un controllo che la sua unità in realtà non ha (o viceversa), le impostazioni no... gli indicano cosa nascondere: ad esempio nopowerful, noecono, nostreamer, noswingv, noswingh, noquiet, nodemand, nofaikoutauto. Le impostazioni di forzatura del protocollo nos21, nox50a, nocnwired gli impediscono di provare un dato protocollo se il rilevamento automatico ne sceglie uno errato.

Debug

13. Risoluzione dei problemi

Non compare nulla su MQTT / il dispositivo risulta offline. Controlli il topic semplice state/GuestAC: false significa che il Faikout stesso non è connesso al broker. Verifichi quindi che l'IP/il nome host del broker nelle impostazioni sia raggiungibile, che il nome utente e la password MQTT siano corretti, che il broker sia in ascolto (di solito la porta 1883 sulla LAN) e che il modulo sia sul suo WiFi a 2,4 GHz (non usa il 5 GHz). Confermi che GuestAC.local si carichi in un browser per dimostrare che il WiFi funziona; a quel punto si tratta di un problema di credenziali MQTT o di raggiungibilità del broker.

L'unità continua ad accendersi da sola. Inviare env in un messaggio control mette l'unità sotto controllo remoto, e in modalità remota l'accensione automatica viene presupposta se autoptemp non è zero (0.5 di default). Per mantenere manuale l'accensione/spegnimento, imposti autop su disattivo e autoptemp su 0, mantenga tempadjust attivo e invii solo {"env": ...} senza array target. Vedere la sezione 11C.

Faikout esce dalla modalità Auto dopo un po'. I messaggi env/control scadono dopo tcontrol secondi (600 di default). Reinvii env in ogni messaggio control e con una cadenza più breve del timeout.

autotopic non fa nulla. Il topic a cui è iscritto deve veicolare JSON con il campo indicato in autopayload. Un payload costituito da un numero nudo non potrà essere analizzato. Pubblichi JSON, oppure invii il valore lei stesso con un messaggio control env (sezione 11A).

Home Assistant non mostra il dispositivo. haenable deve essere attivo (lo è per impostazione predefinita), l'integrazione MQTT di HA deve essere installata con il rilevamento abilitato e il dispositivo deve essere sullo stesso broker di HA. Confermi l'arrivo dei messaggi di rilevamento iscrivendosi a <MAC>/# (l'indirizzo MAC del modulo). Se preferisce non usare affatto MQTT, usi l'integrazione Daikin nativa con l'IP del Faikout.

Lo stato sembra obsoleto. I messaggi state/ sono trattenuti, quindi un client può mostrare l'ultimo valore dopo un riavvio. Se vede dati realmente vecchi, cancelli il messaggio trattenuto su quel topic e attivi livestatus per aggiornamenti istantanei a ogni modifica.

Alcuni controlli S21 non fanno nulla. S21 è frutto di reverse engineering e varia in base al modello; powerful, econo, demand e simili potrebbero non esistere sulla sua unità e vengono semplicemente ignorati. Il JSON di stato mostra quali controlli la sua unità espone realmente.

14. Scheda di riferimento rapido

Sostituisca GuestAC con il suo nome host e 192.168.1.10 con il suo broker.

Leggere (iscriversi)

Comandi (pubblicare su command/GuestAC/...)

Il payload control

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

Impostazioni (pubblicare su setting/GuestAC...)

Sensore esterno, mantenere manuale l'accensione/spegnimento

Fonti: firmware e manuali RevK ESP32-Faikout (README, Setup, Controls, Advanced) e ESP/main/settings.def su Codeberg (codeberg.org/RevK/ESP32-Faikout). Il comportamento descritto corrisponde al firmware aggiornato a giugno 2026; il dump delle impostazioni del dispositivo stesso è autorevole per la versione installata.