MQTT-handleiding

Een volledige handleiding voor het besturen en bewaken van een Faikin Faikout via MQTT, van de eerste configuratie tot de volledige naslag van topics, commando's en instellingen.

Dit betreft de WiFi-Faikout-module met de firmware van RevK (het apparaat draagt de merknaam Faikout; mogelijk ziet u nog de oudere naam Faikin). Het is van toepassing op S21-, X50A- en CN_WIRED-units, aangezien de firmware het protocol automatisch bepaalt. Overal in deze handleiding is de voorbeeldhostnaam GuestAC en het voorbeeld-broker-IP 192.168.1.10. Vervang beide door uw eigen waarden.

1. Wat MQTT u biedt

Alles is lokaal. Faikout spreekt MQTT op uw eigen netwerk, zonder cloudaccount en zonder afhankelijkheid van internet. Via MQTT kunt u:

• De unit besturen: aan/uit, modus, instelwaarde, ventilatorsnelheid, lamellenzwaai, powerful/econo.
• Live telemetrie uitlezen die de IR-afstandsbediening verbergt: kamer-, spoel-/vloeistof-, inlaat- en buitentemperatuur, plus model en bedrijfstoestand.
• De Faikout Auto-laag aansturen: doelbereik, schema's en een externe temperatuurreferentie.
• Integreren met Home Assistant (eigen automatische detectie), openHAB, Node-RED, Domoticz, ioBroker en al het andere dat MQTT spreekt.

MQTT-besturing werkt naast de ingebouwde webinterface en de IR-afstandsbediening. Een wijziging via welke bron dan ook verschijnt binnen enkele seconden overal.

2. Voordat u begint

U hebt nodig:

• Een Faikout die is geïnstalleerd en al verbonden is met uw 2,4GHz-WiFi (zie de installatiehandleiding). U bereikt deze via GuestAC.local in een browser.
• Een MQTT-broker op hetzelfde netwerk. Veelgebruikte keuzes zijn de Mosquitto-add-on binnen Home Assistant, of een losstaande Mosquitto op een Raspberry Pi, NAS of server.
• Het IP-adres of de hostnaam van de broker, en een gebruikersnaam en wachtwoord als de broker authenticatie vereist (de broker van Home Assistant doet dat doorgaans).

Houd de broker op een netwerk dat u beheert. De MQTT van Faikout is gewoon lokaal verkeer en is niet bedoeld om aan internet te worden blootgesteld.

3. Stap 1: Wijs Faikout naar uw MQTT-broker

1. Ga naar GuestAC.local en open WiFi-instellingen (of houd de setup van het apparaat ingedrukt en maak vervolgens verbinding met het Daikin/Faikout-toegangspunt als het nog niet op uw WiFi zit).
2. Voer in het gedeelte MQTT de Host in (IP of hostnaam van de broker, bijv. 192.168.1.10) en, als uw broker deze gebruikt, de Username en het Password.
3. Zorg dat de Hostname op iets gedenkwaardigs is ingesteld, bijv. GuestAC. Deze naam wordt onderdeel van elk MQTT-topic, dus kies hem voordat u automatiseringen bouwt.
4. Opslaan. Faikout maakt opnieuw verbinding en begint te publiceren.

De onderliggende verbindingsinstelling is mqtthost (standaard van de RevK-bibliotheek). De gebruikersnaam en het wachtwoord worden op dezelfde pagina ingevoerd. U kunt deze later ook via MQTT zelf wijzigen zodra er verbinding is (zie Naslag van instellingen).

4. Stap 2: Bevestig dat de verbinding tot stand is gekomen

Hiervoor hebt u geen terminal nodig. Twee plekken laten het u meteen zien.

Op de eigen pagina van de Faikout

Ga naar GuestAC.local. Boven aan de pagina, naast de apparaatnaam, toont de Faikout de status van de broker. MQTT connected betekent dat de module uw broker heeft bereikt en publiceert.

De melding staat boven aan de pagina naast de apparaatnaam. De MQTT-host, de gebruiker en het wachtwoord staan verderop op dezelfde pagina.

Ontbreekt die melding, dan klopt de host, de gebruikersnaam of het wachtwoord niet, of is de broker niet bereikbaar vanaf het netwerk waarop de module zit. Controleer het MQTT-gedeelte op de instellingenpagina opnieuw en raadpleeg daarna Problemen oplossen.

In Home Assistant

U hoeft niets met de hand toe te voegen. De Faikout publiceert de MQTT-discovery-berichten van Home Assistant, dus zodra hij de broker bereikt, vindt Home Assistant hem vanzelf. Voorwaarde is alleen dat de MQTT-integratie al is ingesteld en naar dezelfde broker wijst:

1. Ga naar Instellingen > Apparaten & diensten > MQTT en open daarna de apparatenlijst.
2. GuestAC verschijnt binnen enkele seconden, vermeld als gemaakt door RevK, met de firmwareversie.
3. Open hem en het hele apparaat staat er al: een klimaatentiteit (MQTT HVAC) met de huidige en de ingestelde temperatuur, de modus en de functieschakelaars onder Controls (Auto, Comfort, Econo, Power, Powerful, Quiet outdoor, Sensor, Streamer, Restart) en onder Sensors de kamer- en doeltemperatuur, de compressor- en ventilatorsnelheid, de luchtvochtigheid, de warmtewisselaar- en buitentemperatuur, het stroomverbruik en de totale energie.

Een apparaatpagina van de Faikout in Home Assistant. Niets hiervan is met de hand toegevoegd: de klimaatentiteit, de bedieningselementen en de sensoren komen allemaal via MQTT-discovery binnen.

Verschijnt hij niet, controleer dan of Home Assistant dezelfde broker gebruikt als de module en raadpleeg daarna Problemen oplossen. Voor een Faikout hoeft u nooit met de hand een klimaatentiteit in YAML te schrijven: doet u dat toch, dan zit er verderop iets fout.

Als u het liever vanaf een terminal controleert

Optioneel, en alleen de moeite waard als u de mosquitto-clienttools al hebt geïnstalleerd:

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

U zou een behouden state/GuestAC-bericht moeten zien. De payload meldt online als true wanneer de airco met de module communiceert. Het kale topic state/GuestAC is de eigen aanwezigheid van het apparaat: een payload van false betekent dat de Faikout zelf offline is (dit is zijn MQTT-will/birth-bericht).

Als er niets binnenkomt, ga dan naar Problemen oplossen.

5. De topicstructuur

Faikout gebruikt de standaard topicindeling van de RevK-bibliotheek: prefix/hostname/suffix. Met hostnaam GuestAC:

Voor de meeste automatisering hebt u er maar twee nodig: publiceer naar command/GuestAC/control en abonneer u op state/GuestAC.

6. Commando's verzenden

Publiceer naar command/GuestAC/<command>. Eenvoudige commando's nemen geen payload; enkele nemen een argument als payload.

Voorbeelden:

# 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. Het control-bericht (het belangrijkste)

command/GuestAC/control neemt een JSON-payload en is de overzichtelijkste manier om meerdere zaken tegelijk in te stellen. Dezelfde veldnamen verschijnen in de status-JSON, dus wat u verzendt komt overeen met wat u uitleest.

Voorbeeld: koelen tot 24°C met automatische ventilator, verticale zwaai aan:

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

Let op: powerful, econo, streamer en soortgelijke extra's zijn modelafhankelijk. S21 is via reverse-engineering verkregen en niet voor alle units identiek, dus een schakelaar die uw unit niet heeft, wordt simpelweg genegeerd. De status-JSON laat zien welke besturingen uw unit daadwerkelijk biedt.

8. Status uitlezen

Faikout publiceert status naar drie families van topics:

• state/GuestAC is de status voor mensen/automatisering, gepubliceerd elke reporting seconden (standaard 60) en bij significante wijzigingen. Zet livestatus aan om ook bij elke wijziging in realtime te publiceren.
• Faikout/... wordt ongeveer eens per minuut gepubliceerd en is bedoeld voor de faikoutlog-tool om op te slaan in een MySQL/MariaDB-database voor grafieken.
• <MAC>/... is de automatische-detectiefeed van Home Assistant, gepubliceerd wanneer HA-ondersteuning is ingeschakeld (zie sectie 9).

De state-JSON bevat alles uit de bovenstaande control-tabel (zodat u power, mode, temp, fan, enz. kunt teruglezen) plus deze alleen-lezen velden:

Formaat van databaselogging: in de Faikout/-feed wordt elke waarde over de periode samengevat. Als deze niet veranderde, wordt deze als één enkele waarde gemeld; deed deze dat wel, dan wordt een numerieke waarde een [min, average, max]-array en een booleaanse waarde een fractie 0.0–1.0 voor hoeveel van de periode deze true was. Zet fixstatus aan om altijd het array-/fractieformaat te gebruiken, ongeacht het voorgaande.

9. Home Assistant via MQTT

Faikout heeft eigen automatische detectie voor Home Assistant en deze staat standaard aan (instelling haenable, standaard aan). Zodra de module met dezelfde broker als Home Assistant communiceert, verschijnt er vanzelf een climate-entiteit.

Configuratie:

1. Draai een MQTT-broker die Home Assistant gebruikt. Het eenvoudigst is de Mosquitto broker-add-on in Home Assistant OS, met de toegevoegde MQTT-integratie.
2. Maak in Home Assistant een MQTT-gebruiker aan voor het apparaat (een normale HA-gebruiker werkt met de Mosquitto-add-on).
3. Stel op de configuratiepagina van Faikout de MQTT-host in op het IP van Home Assistant en voer die gebruikersnaam en dat wachtwoord in.
4. Binnen een minuut detecteert Home Assistant het apparaat (gepubliceerd onder de <MAC>/...-topics) en voegt het een climate-kaart toe. Geen YAML vereist.

Nuttige HA-gerelateerde instellingen (in te stellen via MQTT of de Advanced-webpagina):

YAML voor dashboard en entiteitenkaart

U hebt geen YAML nodig om de entiteiten te maken. Automatische detectie maakt vanzelf een climate-entiteit plus temperatuursensoren. De onderstaande YAML dient om ze op een Lovelace-dashboard te plaatsen.

Entiteit-ID's worden afgeleid van de hostnaam, dus een apparaat met de naam GuestAC geeft climate.guestac en sensoren zoals sensor.guestac_temperature. De exacte slugs variëren met de firmwareversie en uw HA-naamgevingsinstellingen, controleer ze dus onder Instellingen → Apparaten en services → MQTT → (uw apparaat) of Ontwikkelhulpmiddelen → Statussen en pas de onderstaande ID's daarop aan.

Entiteitenkaart. Voeg op een willekeurig dashboard een kaart toe via Kaart toevoegen → Handmatig en plak:

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

Volledige dashboardweergave. Open een dashboard, Bewerken → (drie puntjes) → Onbewerkte configuratie-editor, en voeg dit toe als een nieuwe weergave onder 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

Wilt u liever één enkele kaart visueel opbouwen, dan binden zowel de Mushroom-kaart "Climate" als de ingebouwde Thermostat-kaart rechtstreeks aan climate.guestac.

Eenvoudiger alternatief zonder MQTT. Faikout emuleert ook Daikins eigen lokale API en beantwoordt BRP-compatibele UDP-detectie (instelling udpdiscovery). Wilt u geen MQTT-broker draaien, dan kunt u in plaats daarvan de ingebouwde Daikin-integratie van Home Assistant toevoegen en deze op het IP-adres van de Faikout richten. Voor niet-technische gebruikers is dit de minst omslachtige route naar HA. Houd het MQTT-pad achter de hand voor wanneer u functies wilt die de Daikin-integratie niet biedt, of wanneer u met iets anders dan HA integreert.

Apple Home / Alexa / Google. Deze spreken niet rechtstreeks MQTT, maar een bridge overbrugt het gat. Home Assistant bridget alle drie. Voor een huishouden met uitsluitend Apple zonder HA brengt Homebridge met een MQTT-plug-in (bijvoorbeeld EasyMQTT) Faikout in de eigen iOS-Home-app en Siri. Het is een beproefde route, maar het is een zelf gehoste server om op te zetten, dus reken op enige configuratie.

10. Andere platforms

Dezelfde twee topics (command/GuestAC/control om te schrijven, state/GuestAC om te lezen) werken overal.

mosquitto-opdrachtregel

# 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

• Om te besturen: een mqtt out-node met topic command/GuestAC/control. Voed deze met een msg.payload die een JSON-object is (gebruik een template- of function-node, of een change-node die de payload op een JSON-waarde instelt).
• Om te bewaken: een mqtt in-node op state/GuestAC, daarna een json-node om het te parseren tot een object waarop u kunt routeren (bijv. payload.home, payload.power).

openHAB

Gebruik de generieke MQTT-binding. Maak een MQTT-Thing voor de broker en vervolgens kanalen zoals:

• een Switch-kanaal met commandTopic = command/GuestAC/control, dat de waarde opmaakt als {"power":%s};
• een Number-kanaal met stateTopic = state/GuestAC en een JSONPATH-transformatie zoals $.home om de kamertemperatuur uit te lezen.

Hetzelfde patroon (JSON publiceren naar command/.../control, JSON parseren uit state/...) is toepasbaar op Domoticz, ioBroker, Jeedom, FHEM, Homey, Hubitat en Gladys.

11. Faikout Auto via MQTT

Faikout Auto is een extra besturingslaag die een doelbereik aanhoudt door de unit tussen verwarmen/koelen/uit te sturen, waarbij optioneel een externe temperatuursensor wordt gebruikt in plaats van die van de airco zelf. U kunt het op drie manieren aansturen: vanuit de web-UI, vanaf een BLE-sensor, of via MQTT. De MQTT-routes staan hieronder.

A. Een meting pushen vanuit uw eigen automatisering

Verstuur een control-bericht met env (en optioneel target). De unit beschouwt zichzelf dan als onder afstandsbesturing:

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

• env is de huidige kamertemperatuur van uw sensor. Deze moet in elk control-bericht opnieuw worden verzonden en minstens elke tcontrol seconden (standaard 600). Bij een time-out valt de unit terug uit de afstands-/automodus.
• target als een [min,max]-array (of een enkel getal met margin) forceert de Faikout Auto-modus en bepaalt het comfortbereik.

B. Faikout abonneren op een sensortopic

In plaats van te pushen, laat u Faikout een bestaand MQTT-topic volgen:

Belangrijk: de payload op autotopic moet JSON zijn die het genoemde veld bevat. Een topic dat een kaal getal publiceert (bijvoorbeeld een gewoon ESPHome-statustopic) wordt niet geparseerd; verpak het in JSON, of gebruik route A.

C. Een externe sensor volgen maar aan/uit handmatig houden

Een veelgehoorde wens: besturen op een nauwkeurige externe meting, maar de unit zichzelf nooit laten in- of uitschakelen. De valkuil is dat het verzenden van env de unit "remote" maakt, en in remote-toestand wordt automatisch vermogen aangenomen als autoptemp niet nul is (standaard 0.5). Dus:

• Zet autop uit en autoptemp op 0 (stopt het automatisch in-/uitschakelen).
• Houd tempadjust aan (dit richt de unit daadwerkelijk op uw referentie: het past de instelwaarde aan met reference - measured).
• Verstuur geen target-array (een array forceert het volledige Auto-bereik-/vermogensgedrag). Verstuur alleen {"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}'

Auto-modusbesturingen die u ook in een control-bericht kunt verzenden

Deze weerspiegelen de instellingen en worden in de status teruggemeld wanneer er geen afstandsbesturing is:

12. Naslag van instellingen

Instellingen worden via MQTT in twee vormen gelezen en geschreven:

• Allemaal tegelijk / teruglezen: publiceer JSON naar setting/GuestAC, bijv. {"reporting":30,"livestatus":true}. Een lege payload laat het apparaat zijn huidige instellingen publiceren.
• Eén voor één: publiceer de kale waarde naar setting/GuestAC/<name>, bijv. topic setting/GuestAC/livestatus met payload true.

De onderstaande namen zijn de MQTT-namen (de Advanced-webpagina groepeert ze, maar via MQTT worden ze als één woord geschreven). Dit is een werkbare selectie; de eigen instellingen-dump van het apparaat (lege payload naar setting/GuestAC) is de gezaghebbende lijst voor uw firmware.

Verbinding en rapportage

Home Assistant

Zie sectie 9: haenable, haswitches, ha1c, hafanrpm, hacomprpm, hadomain, udpdiscovery, nohvacaction, nohomepreset.

Faikout Auto

Fijnafstemming van het voorspellings- en bereikgedrag (pushtemp, switchtemp, coolover, coolback, heatover, heatback, tpredicts, tpredictt, tsample, tcoolmin, theatmax, frosttemp, minoutside) is gedocumenteerd in de Advanced-handleiding en hoeft zelden te worden gewijzigd.

Overschrijvingen van mogelijkheden

Als de firmware een besturing biedt die uw unit feitelijk niet heeft (of omgekeerd), geven de no...-instellingen aan wat verborgen moet worden: bijvoorbeeld nopowerful, noecono, nostreamer, noswingv, noswingh, noquiet, nodemand, nofaikoutauto. De protocol-forcerende instellingen nos21, nox50a, nocnwired zorgen dat een bepaald protocol niet wordt geprobeerd als de automatische detectie het verkeerde kiest.

Debug

13. Problemen oplossen

Er verschijnt niets op MQTT / het apparaat toont offline. Controleer het kale topic state/GuestAC: false betekent dat de Faikout zelf niet met de broker is verbonden. Verifieer vervolgens dat het broker-IP/de hostnaam in de instellingen bereikbaar is, dat de MQTT-gebruikersnaam en het wachtwoord juist zijn, dat de broker luistert (meestal poort 1883 op het LAN), en dat de module op uw 2,4GHz-WiFi zit (5GHz wordt niet gebruikt). Bevestig dat GuestAC.local in een browser laadt om aan te tonen dat de WiFi in orde is; dan gaat het om een probleem met MQTT-inloggegevens of bereikbaarheid van de broker.

De unit blijft zichzelf inschakelen. Het verzenden van env in een control-bericht plaatst de unit onder afstandsbesturing, en in remote-toestand wordt automatisch vermogen aangenomen als autoptemp niet nul is (standaard 0.5). Om aan/uit handmatig te houden, zet u autop uit en autoptemp op 0, houdt u tempadjust aan, en verzendt u alleen {"env": ...} zonder target-array. Zie sectie 11C.

Faikout valt na een tijdje uit de Auto-modus. env-/control-berichten verlopen na tcontrol seconden (standaard 600). Verstuur env in elk control-bericht opnieuw en met een interval korter dan de time-out.

autotopic doet niets. Het geabonneerde topic moet JSON bevatten met het veld dat in autopayload wordt genoemd. Een payload met een kaal getal wordt niet geparseerd. Publiceer JSON, of push de waarde zelf met een env-control-bericht (sectie 11A).

Home Assistant toont het apparaat niet. haenable moet aan staan (dat is standaard zo), de HA MQTT-integratie moet geïnstalleerd zijn met detectie ingeschakeld, en het apparaat moet op dezelfde broker als HA zitten. Bevestig dat detectieberichten binnenkomen door u te abonneren op <MAC>/# (het MAC-adres van de module). Wilt u MQTT helemaal niet gebruiken, gebruik dan in plaats daarvan de eigen Daikin-integratie met het IP van de Faikout.

De status lijkt verouderd. state/-berichten worden behouden, zodat een client na een herstart de laatste waarde kan tonen. Ziet u werkelijk oude gegevens, wis dan het behouden bericht op dat topic en zet livestatus aan voor directe updates bij wijziging.

Sommige besturingen doen niets. S21 is via reverse-engineering verkregen en verschilt per model; powerful, econo, demand en dergelijke bestaan mogelijk niet op uw unit en worden simpelweg genegeerd. De status-JSON toont welke besturingen uw unit werkelijk biedt.

14. Beknopte naslag (spiekbriefje)

Vervang GuestAC door uw hostnaam en 192.168.1.10 door uw broker.

Lezen (abonneren)

Commando's (publiceer naar command/GuestAC/...)

De control-payload

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

Instellingen (publiceer naar setting/GuestAC...)

Externe sensor, aan/uit handmatig houden

Bronnen: RevK ESP32-Faikout-firmware en -handleidingen (README, Setup, Controls, Advanced) en ESP/main/settings.def op Codeberg (codeberg.org/RevK/ESP32-Faikout). Het beschreven gedrag komt overeen met de firmware van juni 2026; de eigen instellingen-dump van het apparaat is gezaghebbend voor uw geïnstalleerde versie.