Manuel MQTT

Un guide complet pour commander et surveiller un Faikin Faikout via MQTT, de la première configuration jusqu'à la référence complète des topics, commandes et réglages.

Ce manuel concerne le module WiFi Faikout exécutant le micrologiciel de RevK (l'appareil est commercialisé sous le nom Faikout ; vous pouvez encore voir l'ancien nom Faikin). Il s'applique indifféremment aux unités S21, X50A et CN_WIRED, car le micrologiciel détermine le protocole automatiquement. Tout au long du document, le nom d'hôte d'exemple est GuestAC et l'adresse IP du broker d'exemple est 192.168.1.10. Remplacez les deux par les vôtres.

1. Ce que MQTT vous apporte

Tout est local. Faikout parle MQTT sur votre propre réseau, sans compte cloud ni dépendance à internet. Via MQTT, vous pouvez :

• commander l'unité : marche/arrêt, mode, consigne, vitesse du ventilateur, oscillation des volets, powerful/econo.
• lire la télémétrie en direct que la télécommande IR masque : températures de la pièce, de la batterie/du liquide, d'admission et extérieure, ainsi que le modèle et l'état de fonctionnement.
• piloter la couche Faikout Auto : plage cible, programmations et une référence de température externe.
• vous intégrer à Home Assistant (découverte automatique native), openHAB, Node-RED, Domoticz, ioBroker et tout ce qui parle MQTT.

La commande MQTT fonctionne en parallèle de l'interface web intégrée et de la télécommande IR. Une modification provenant de n'importe quelle source apparaît partout en quelques secondes.

2. Avant de commencer

Il vous faut :

• un Faikout installé et déjà connecté à votre WiFi 2,4 GHz (voir le manuel de configuration). Vous pouvez y accéder via GuestAC.local dans un navigateur.
• un broker MQTT sur le même réseau. Les choix courants sont le module complémentaire Mosquitto au sein de Home Assistant, ou un Mosquitto autonome sur un Raspberry Pi, un NAS ou un serveur.
• l'adresse IP ou le nom d'hôte du broker, ainsi qu'un nom d'utilisateur et un mot de passe si le broker exige une authentification (le broker de Home Assistant l'exige normalement).

Gardez le broker sur un réseau que vous contrôlez. Le MQTT de Faikout est du trafic local en clair et n'est pas destiné à être exposé à internet.

3. Étape 1 : diriger Faikout vers votre broker MQTT

1. Accédez à GuestAC.local et ouvrez les réglages WiFi (ou maintenez le bouton de configuration de l'appareil, puis connectez-vous à son point d'accès Daikin/Faikout s'il n'est pas encore sur votre WiFi).
2. Dans la section MQTT, saisissez l'Hôte (IP ou nom d'hôte du broker, p. ex. 192.168.1.10) et, si votre broker les utilise, le Nom d'utilisateur et le Mot de passe.
3. Assurez-vous que le Nom d'hôte est défini sur quelque chose de mémorisable, p. ex. GuestAC. Ce nom fait partie de chaque topic MQTT, choisissez-le donc avant de créer des automatisations.
4. Enregistrez. Faikout se reconnecte et commence à publier.

Le réglage de connexion sous-jacent est mqtthost (standard de la bibliothèque RevK). Le nom d'utilisateur et le mot de passe se saisissent sur la même page. Vous pouvez également les modifier plus tard via MQTT lui-même une fois connecté (voir la référence des réglages).

4. Étape 2 : confirmer la connexion

Pas besoin de terminal pour cela. Deux endroits vous le disent immédiatement.

Sur la page du Faikout lui-même

Rendez-vous sur GuestAC.local. En haut de la page, à côté du nom de l'appareil, le Faikout affiche l'état de son broker. MQTT connected signifie que le module a atteint votre broker et qu'il publie.

La mention se trouve à côté du nom de l'appareil, en haut de la page. L'hôte, l'utilisateur et le mot de passe MQTT se trouvent plus bas sur la même page.

Si cette mention est absente, c'est que l'hôte, le nom d'utilisateur ou le mot de passe est incorrect, ou que le broker n'est pas joignable depuis le réseau sur lequel se trouve le module. Revérifiez la section MQTT de la page des réglages, puis consultez le Dépannage.

Dans Home Assistant

Rien à ajouter à la main. Le Faikout publie les messages de découverte MQTT de Home Assistant : dès qu'il atteint le broker, Home Assistant le trouve tout seul. Il suffit que l'intégration MQTT soit déjà configurée et qu'elle pointe vers le même broker :

1. Allez dans Paramètres > Appareils et services > MQTT, puis ouvrez la liste des appareils.
2. GuestAC apparaît en quelques secondes, indiqué comme fabriqué par RevK, avec sa version de firmware.
3. Ouvrez-le : tout l'appareil est déjà là, avec une entité de climatisation (MQTT HVAC) indiquant la température actuelle et la température de consigne, le mode et les interrupteurs de fonctions sous Controls (Auto, Comfort, Econo, Power, Powerful, Quiet outdoor, Sensor, Streamer, Restart) et, sous Sensors, les températures ambiante et de consigne, les vitesses du compresseur et du ventilateur, l'humidité, les températures de la batterie et extérieure, la consommation électrique et l'énergie cumulée.

Une page d'appareil Faikout dans Home Assistant. Rien n'a été ajouté à la main ici : l'entité de climatisation, les commandes et les capteurs arrivent tous par la découverte MQTT.

S'il n'apparaît pas, vérifiez que Home Assistant utilise le même broker que le module, puis consultez le Dépannage. Vous ne devriez jamais avoir à écrire une entité de climatisation à la main en YAML pour un Faikout : si vous en arrivez là, c'est qu'un problème existe en amont.

Si vous préférez vérifier depuis un terminal

Facultatif, et utile uniquement si vous avez déjà installé les outils client mosquitto :

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

Vous devriez voir un message state/GuestAC retenu. Sa charge utile indique online true lorsque le climatiseur communique avec le module. Le topic nu state/GuestAC correspond à la présence propre de l'appareil : une charge utile de false signifie que le Faikout lui-même est hors ligne (il s'agit de son message will/birth MQTT).

Si rien n'arrive, passez au Dépannage.

5. La structure des topics

Faikout utilise la disposition de topics standard de la bibliothèque RevK : prefix/hostname/suffix. Avec le nom d'hôte GuestAC :

Pour la plupart des automatisations, vous n'avez besoin que de deux d'entre eux : publier sur command/GuestAC/control et vous abonner à state/GuestAC.

6. Envoyer des commandes

Publiez sur command/GuestAC/<command>. Les commandes simples ne prennent pas de charge utile ; quelques-unes prennent un argument comme charge utile.

Exemples :

# 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. Le message control (le principal)

command/GuestAC/control prend une charge utile JSON et constitue la manière la plus propre de définir plusieurs choses à la fois. Les mêmes noms de champ apparaissent dans le JSON d'état, de sorte que ce que vous envoyez reflète ce que vous lisez.

Exemple : refroidir à 24 °C avec ventilateur auto, oscillation verticale activée :

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

Remarque : powerful, econo, streamer et les extras similaires dépendent du modèle. S21 est issu de la rétro-ingénierie et n'est pas identique d'une unité à l'autre, de sorte qu'un commutateur que votre unité ne possède pas est simplement ignoré. Le JSON d'état vous indique quelles commandes votre unité expose réellement.

8. Lire l'état

Faikout publie l'état sur trois familles de topics :

• state/GuestAC est l'état destiné aux personnes/à l'automatisation, publié toutes les reporting secondes (60 par défaut) et lors de changements importants. Activez livestatus pour publier aussi à chaque changement, en temps réel.
• Faikout/... est publié environ une fois par minute et est destiné à être stocké par l'outil faikoutlog dans une base de données MySQL/MariaDB à des fins de représentation graphique.
• <MAC>/... est le flux de découverte automatique de Home Assistant, publié lorsque la prise en charge de HA est activée (voir la section 9).

Le JSON state inclut tout ce qui figure dans le tableau control ci-dessus (vous pouvez donc relire power, mode, temp, fan, etc.) ainsi que ces champs en lecture seule :

Format de journalisation en base de données : dans le flux Faikout/, chaque valeur est résumée sur la période. Si elle n'a pas changé, elle est rapportée comme une valeur unique ; si elle a changé, une valeur numérique devient un tableau [min, average, max] et un booléen devient une fraction 0.0–1.0 indiquant pendant quelle proportion de la période il était vrai. Activez fixstatus pour toujours utiliser le format tableau/fraction, quoi qu'il arrive.

9. Home Assistant via MQTT

Faikout dispose d'une découverte automatique native pour Home Assistant, et elle est activée par défaut (réglage haenable, activé par défaut). Une fois que le module communique avec le même broker que Home Assistant, une entité climate apparaît d'elle-même.

Configuration :

1. Exécutez un broker MQTT utilisé par Home Assistant. Le plus simple est le module complémentaire Mosquitto broker dans Home Assistant OS, avec l'intégration MQTT ajoutée.
2. Créez un utilisateur MQTT dans Home Assistant pour l'appareil (un utilisateur HA normal fonctionne avec le module Mosquitto).
3. Sur la page de configuration de Faikout, définissez l'hôte MQTT sur l'IP de Home Assistant et saisissez ce nom d'utilisateur et ce mot de passe.
4. En une minute, Home Assistant découvre l'appareil (publié sous les topics <MAC>/...) et ajoute une carte climate. Aucun YAML requis.

Réglages utiles liés à HA (définis via MQTT ou la page web avancée) :

YAML du tableau de bord et de la carte d'entités

Vous n'avez pas besoin de YAML pour créer les entités. La découverte automatique crée d'elle-même une entité climate ainsi que des capteurs de température. Le YAML ci-dessous sert à les disposer sur un tableau de bord Lovelace.

Les ID d'entité sont dérivés du nom d'hôte ; un appareil nommé GuestAC donne donc climate.guestac et des capteurs comme sensor.guestac_temperature. Les slugs exacts varient selon la version du micrologiciel et vos réglages de nommage HA, confirmez-les donc sous Paramètres → Appareils et services → MQTT → (votre appareil) ou Outils de développement → États, et adaptez les ID ci-dessous en conséquence.

Carte d'entités. Ajoutez une carte à n'importe quel tableau de bord avec Ajouter une carte → Manuel et collez :

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

Vue de tableau de bord complète. Ouvrez un tableau de bord, Modifier → (trois points) → Éditeur de configuration brute, et ajoutez ceci comme nouvelle vue sous 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

Si vous préférez construire une carte unique de façon visuelle, la carte « Climate » de Mushroom et la carte Thermostat intégrée se lient toutes deux directement à climate.guestac.

Alternative plus simple, sans MQTT. Faikout émule également l'API locale propre à Daikin et répond à la découverte UDP compatible BRP (réglage udpdiscovery). Si vous ne souhaitez pas exécuter de broker MQTT, vous pouvez ajouter à la place l'intégration Daikin intégrée de Home Assistant et la diriger vers l'adresse IP du Faikout. Pour les utilisateurs non techniques, c'est la voie la moins compliquée vers HA. Réservez la voie MQTT aux cas où vous souhaitez des fonctions que l'intégration Daikin n'expose pas, ou lorsque vous intégrez autre chose que HA.

Apple Home / Alexa / Google. Ceux-ci ne parlent pas MQTT directement, mais une passerelle comble l'écart. Home Assistant fait le pont avec les trois. Pour un foyer exclusivement Apple sans HA, Homebridge avec un plugin MQTT (par exemple EasyMQTT) intègre Faikout à l'application Maison native d'iOS et à Siri. C'est une voie éprouvée, mais c'est un serveur auto-hébergé à mettre en place, prévoyez donc un peu de configuration.

10. Autres plateformes

Les deux mêmes topics (command/GuestAC/control pour écrire, state/GuestAC pour lire) fonctionnent partout.

Ligne de commande 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

• Pour commander : un nœud mqtt out avec le topic command/GuestAC/control. Alimentez-le avec un msg.payload qui est un objet JSON (utilisez un nœud template ou function, ou un nœud change qui définit la charge utile sur une valeur JSON).
• Pour surveiller : un nœud mqtt in sur state/GuestAC, puis un nœud json pour l'analyser en un objet sur lequel router (p. ex. payload.home, payload.power).

openHAB

Utilisez le binding MQTT générique. Créez un Thing MQTT pour le broker, puis des canaux tels que :

• un canal Switch avec commandTopic = command/GuestAC/control, en formatant la valeur sous la forme {"power":%s} ;
• un canal Number avec stateTopic = state/GuestAC et une transformation JSONPATH telle que $.home pour lire la température de la pièce.

Le même schéma (publier du JSON sur command/.../control, analyser du JSON depuis state/...) s'applique à Domoticz, ioBroker, Jeedom, FHEM, Homey, Hubitat et Gladys.

11. Faikout Auto via MQTT

Faikout Auto est une couche de commande supplémentaire qui maintient une plage cible en ajustant l'unité entre chauffage/refroidissement/arrêt, en utilisant éventuellement un capteur de température externe plutôt que celui du climatiseur. Vous pouvez la piloter de trois manières : depuis l'interface web, depuis un capteur BLE, ou via MQTT. Les voies MQTT sont indiquées ci-dessous.

A. Envoyer une mesure depuis votre propre automatisation

Envoyez un message control contenant env (et éventuellement target). L'unité se considère alors sous commande à distance :

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

• env est la température ambiante actuelle issue de votre capteur. Elle doit être renvoyée dans chaque message control et au moins toutes les tcontrol secondes (600 par défaut). En cas d'expiration, l'unité sort du mode distant/auto.
• target sous forme de tableau [min,max] (ou un nombre unique avec margin) force le mode Faikout Auto et définit la plage de confort.

B. Abonner Faikout à un topic de capteur

Plutôt que d'envoyer, indiquez à Faikout de suivre un topic MQTT existant :

Important : la charge utile sur autotopic doit être du JSON contenant le champ nommé. Un topic qui publie un nombre nu (par exemple un topic d'état ESPHome ordinaire) ne pourra pas être analysé ; encapsulez-le en JSON, ou utilisez la voie A.

C. Suivre un capteur externe tout en gardant la marche/l'arrêt manuels

Une demande fréquente : réguler selon une mesure externe précise, mais sans jamais laisser l'unité s'allumer ou s'éteindre toute seule. Le hic, c'est qu'envoyer env rend l'unité « distante », et en mode distant, la mise sous tension automatique est supposée si autoptemp n'est pas nul (0.5 par défaut). Donc :

• Mettez autop sur désactivé et autoptemp sur 0 (arrête la marche/l'arrêt automatiques).
• Gardez tempadjust activé (c'est ce qui oriente réellement l'unité vers votre référence : il ajuste la consigne de reference - measured).
• N'envoyez pas de tableau target (un tableau force le comportement complet de plage/puissance Auto). N'envoyez que {"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}'

Commandes du mode auto que vous pouvez aussi envoyer dans un message control

Celles-ci reflètent les réglages et sont retournées dans l'état lorsque l'on n'est pas sous commande à distance :

12. Référence des réglages

Les réglages se lisent et s'écrivent via MQTT sous deux formes :

• Tous en une fois / relecture : publiez du JSON sur setting/GuestAC, p. ex. {"reporting":30,"livestatus":true}. Une charge utile vide amène l'appareil à publier ses réglages actuels.
• Un par un : publiez la valeur nue sur setting/GuestAC/<name>, p. ex. topic setting/GuestAC/livestatus avec charge utile true.

Les noms ci-dessous sont les noms MQTT (la page web avancée les regroupe, mais via MQTT ils s'écrivent en un seul mot). Il s'agit d'un sous-ensemble pratique ; le vidage des réglages propre à l'appareil (charge utile vide vers setting/GuestAC) constitue la liste de référence pour votre micrologiciel.

Connexion et rapports

Home Assistant

Voir la section 9 : haenable, haswitches, ha1c, hafanrpm, hacomprpm, hadomain, udpdiscovery, nohvacaction, nohomepreset.

Faikout Auto

Le réglage fin de la prédiction et du comportement de la plage (pushtemp, switchtemp, coolover, coolback, heatover, heatback, tpredicts, tpredictt, tsample, tcoolmin, theatmax, frosttemp, minoutside) est documenté dans le manuel avancé et nécessite rarement d'être modifié.

Substitutions de capacités

Si le micrologiciel propose une commande que votre unité ne possède pas réellement (ou inversement), les réglages no... lui indiquent quoi masquer : par exemple nopowerful, noecono, nostreamer, noswingv, noswingh, noquiet, nodemand, nofaikoutauto. Les réglages de forçage de protocole nos21, nox50a, nocnwired l'empêchent d'essayer un protocole donné si la détection automatique choisit le mauvais.

Débogage

13. Dépannage

Rien n'apparaît sur MQTT / l'appareil est indiqué hors ligne. Vérifiez le topic nu state/GuestAC : false signifie que le Faikout lui-même n'est pas connecté au broker. Vérifiez ensuite que l'IP/le nom d'hôte du broker dans les réglages est joignable, que le nom d'utilisateur et le mot de passe MQTT sont corrects, que le broker est à l'écoute (généralement le port 1883 sur le LAN) et que le module est sur votre WiFi 2,4 GHz (il n'utilise pas le 5 GHz). Confirmez que GuestAC.local se charge dans un navigateur pour prouver que le WiFi fonctionne ; il s'agit alors d'un problème d'identifiants MQTT ou de joignabilité du broker.

L'unité se rallume sans cesse. Envoyer env dans un message control place l'unité sous commande à distance, et en mode distant, la mise sous tension automatique est supposée si autoptemp n'est pas nul (0.5 par défaut). Pour garder la marche/l'arrêt manuels, mettez autop sur désactivé et autoptemp sur 0, gardez tempadjust activé, et n'envoyez que {"env": ...} sans tableau target. Voir la section 11C.

Faikout quitte le mode Auto au bout d'un moment. Les messages env/control expirent après tcontrol secondes (600 par défaut). Renvoyez env dans chaque message control et selon une cadence plus courte que le délai d'expiration.

autotopic ne fait rien. Le topic abonné doit véhiculer du JSON avec le champ nommé dans autopayload. Une charge utile constituée d'un nombre nu ne pourra pas être analysée. Publiez du JSON, ou envoyez la valeur vous-même avec un message control env (section 11A).

Home Assistant n'affiche pas l'appareil. haenable doit être activé (il l'est par défaut), l'intégration MQTT de HA doit être installée avec la découverte activée, et l'appareil doit être sur le même broker que HA. Confirmez l'arrivée des messages de découverte en vous abonnant à <MAC>/# (l'adresse MAC du module). Si vous préférez ne pas utiliser MQTT du tout, utilisez l'intégration Daikin native avec l'IP du Faikout.

L'état semble obsolète. Les messages state/ sont retenus, de sorte qu'un client peut afficher la dernière valeur après un redémarrage. Si vous voyez des données réellement anciennes, effacez le message retenu sur ce topic et activez livestatus pour des mises à jour instantanées lors des changements.

Certaines commandes S21 ne font rien. S21 est issu de la rétro-ingénierie et varie selon le modèle ; powerful, econo, demand et similaires peuvent ne pas exister sur votre unité et sont simplement ignorés. Le JSON d'état montre quelles commandes votre unité expose réellement.

14. Aide-mémoire de référence rapide

Remplacez GuestAC par votre nom d'hôte et 192.168.1.10 par votre broker.

Lire (s'abonner)

Commandes (publier sur command/GuestAC/...)

La charge utile control

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

Réglages (publier sur setting/GuestAC...)

Capteur externe, garder la marche/l'arrêt manuels

Sources : micrologiciel et manuels RevK ESP32-Faikout (README, Setup, Controls, Advanced) et ESP/main/settings.def sur Codeberg (codeberg.org/RevK/ESP32-Faikout). Le comportement décrit correspond au micrologiciel en date de juin 2026 ; le vidage des réglages propre à l'appareil fait référence pour votre version installée.