Manual de MQTT

Una guía completa para controlar y supervisar un Faikin Faikout a través de MQTT, desde la primera configuración hasta la referencia completa de topics, comandos y ajustes.

Esto cubre el módulo WiFi Faikout que ejecuta el firmware de RevK (el dispositivo se comercializa como Faikout; todavía puede ver el nombre antiguo Faikin). Se aplica por igual a las unidades S21, X50A y CN_WIRED, ya que el firmware deduce el protocolo de forma automática. A lo largo del documento, el nombre de host de ejemplo es GuestAC y la IP del broker de ejemplo es 192.168.1.10. Sustituya ambos por los suyos.

1. Qué le ofrece MQTT

Todo es local. Faikout habla MQTT en su propia red, sin cuenta en la nube ni dependencia de internet. A través de MQTT puede:

• Controlar la unidad: encendido, modo, consigna, velocidad del ventilador, oscilación de las lamas, powerful/econo.
• Leer la telemetría en vivo que oculta el mando IR: temperaturas de la sala, del serpentín/líquido, de admisión y exterior, además del modelo y el estado de funcionamiento.
• Gobernar la capa Faikout Auto: banda objetivo, programaciones y una referencia de temperatura externa.
• Integrarse con Home Assistant (autodescubrimiento nativo), openHAB, Node-RED, Domoticz, ioBroker y cualquier otra cosa que hable MQTT.

El control por MQTT funciona junto a la interfaz web integrada y al mando IR. Un cambio desde cualquier origen aparece en todas partes en unos pocos segundos.

2. Antes de empezar

Necesita:

• Un Faikout instalado y ya conectado a su WiFi de 2,4 GHz (consulte el manual de configuración). Puede acceder a él en GuestAC.local en un navegador.
• Un broker MQTT en la misma red. Las opciones habituales son el complemento Mosquitto dentro de Home Assistant, o un Mosquitto independiente en una Raspberry Pi, un NAS o un servidor.
• La dirección IP o el nombre de host del broker, y un nombre de usuario y una contraseña si el broker requiere autenticación (el broker de Home Assistant normalmente lo hace).

Mantenga el broker en una red que usted controle. El MQTT de Faikout es tráfico local sin cifrar y no está pensado para exponerse a internet.

3. Paso 1: Dirigir Faikout a su broker MQTT

1. Acceda a GuestAC.local y abra los ajustes de WiFi (o mantenga pulsado el botón de configuración del dispositivo y, a continuación, conéctese a su punto de acceso Daikin/Faikout si todavía no está en su WiFi).
2. En la sección MQTT, introduzca el Host (IP o nombre de host del broker, p. ej. 192.168.1.10) y, si su broker los usa, el Nombre de usuario y la Contraseña.
3. Asegúrese de que el Nombre de host esté establecido en algo fácil de recordar, p. ej. GuestAC. Este nombre pasa a formar parte de cada topic MQTT, así que elíjalo antes de crear automatizaciones.
4. Guarde. Faikout se vuelve a conectar y comienza a publicar.

El ajuste de conexión subyacente es mqtthost (estándar de la biblioteca de RevK). El nombre de usuario y la contraseña se introducen en la misma página. También puede cambiarlos más adelante por el propio MQTT una vez conectado (consulte la referencia de ajustes).

4. Paso 2: Confirmar que está conectado

No necesita un terminal para esto. Dos sitios se lo indican de inmediato.

En la propia página del Faikout

Vaya a GuestAC.local. En la parte superior de la página, junto al nombre del dispositivo, el Faikout muestra el estado del bróker. MQTT connected significa que el módulo ha llegado a su bróker y está publicando.

La indicación aparece junto al nombre del dispositivo, en la parte superior de la página. El host, el usuario y la contraseña de MQTT están más abajo en esa misma página.

Si falta esa indicación, el host, el nombre de usuario o la contraseña son incorrectos, o el bróker no es accesible desde la red en la que está el módulo. Vuelva a comprobar la sección MQTT en la página de ajustes y después consulte la Resolución de problemas.

En Home Assistant

No hay nada que añadir a mano. El Faikout publica los mensajes de descubrimiento MQTT de Home Assistant, así que en cuanto llega al bróker, Home Assistant lo encuentra solo. Basta con que la integración MQTT ya esté configurada y apunte al mismo bróker:

1. Vaya a Ajustes > Dispositivos y servicios > MQTT y abra la lista de dispositivos.
2. GuestAC aparece en unos segundos, indicado como fabricado por RevK, con su versión de firmware.
3. Ábralo y el dispositivo completo ya está ahí: una entidad de climatización (MQTT HVAC) con la temperatura actual y la de destino, el modo y los interruptores de funciones en Controls (Auto, Comfort, Econo, Power, Powerful, Quiet outdoor, Sensor, Streamer, Restart) y, en Sensors, las temperaturas ambiente y de destino, las velocidades del compresor y del ventilador, la humedad, las temperaturas de la batería y exterior, el consumo eléctrico y la energía acumulada.

Una página de dispositivo del Faikout en Home Assistant. Nada de esto se añadió a mano: la entidad de climatización, los controles y los sensores llegan todos por descubrimiento MQTT.

Si no aparece, confirme que Home Assistant usa el mismo bróker que el módulo y después consulte la Resolución de problemas. Nunca debería tener que escribir a mano una entidad de climatización en YAML para un Faikout: si acaba haciéndolo, algo falla más arriba.

Si prefiere comprobarlo desde un terminal

Opcional, y solo merece la pena si ya tiene instaladas las herramientas cliente de mosquitto:

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

Debería ver un mensaje retenido state/GuestAC. Su carga útil informa de online true cuando el aire acondicionado se está comunicando con el módulo. El topic simple state/GuestAC es la propia presencia del dispositivo: una carga útil de false significa que el propio Faikout está sin conexión (este es su mensaje will/birth de MQTT).

Si no llega nada, vaya a Resolución de problemas.

5. La estructura de topics

Faikout utiliza la disposición de topics estándar de la biblioteca de RevK: prefix/hostname/suffix. Con el nombre de host GuestAC:

Para la mayoría de las automatizaciones solo necesita dos de estos: publicar en command/GuestAC/control y suscribirse a state/GuestAC.

6. Enviar comandos

Publique en command/GuestAC/<command>. Los comandos sencillos no llevan carga útil; unos pocos toman un argumento como carga útil.

Ejemplos:

# 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. El mensaje control (el principal)

command/GuestAC/control toma una carga útil JSON y es la forma más limpia de fijar varias cosas a la vez. Los mismos nombres de campo aparecen en el JSON de estado, de modo que lo que envía refleja lo que lee.

Ejemplo: enfriar a 24 °C con ventilador automático y oscilación vertical activada:

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 y otros extras similares dependen del modelo. S21 está sometido a ingeniería inversa y no es idéntico en todas las unidades, de modo que un conmutador del que carezca su unidad simplemente se ignora. El JSON de estado le indica qué controles expone realmente su unidad.

8. Leer el estado

Faikout publica el estado en tres familias de topics:

• state/GuestAC es el estado para personas/automatización, publicado cada reporting segundos (60 por defecto) y ante cambios significativos. Active livestatus para publicar también ante cada cambio en tiempo real.
• Faikout/... se publica aproximadamente una vez por minuto y está pensado para que la herramienta faikoutlog lo almacene en una base de datos MySQL/MariaDB para su representación gráfica.
• <MAC>/... es el feed de autodescubrimiento de Home Assistant, publicado cuando la compatibilidad con HA está habilitada (consulte la sección 9).

El JSON de state incluye todo lo de la tabla control anterior (de modo que puede releer power, mode, temp, fan, etc.) más estos campos de solo lectura:

Formato del registro en base de datos: en el feed Faikout/, cada valor se resume a lo largo del periodo. Si no cambió, se informa como un único valor; si cambió, un valor numérico se convierte en un array [min, average, max] y un booleano en una fracción 0.0–1.0 que indica durante cuánto del periodo fue verdadero. Active fixstatus para usar siempre el formato de array/fracción, independientemente de ello.

9. Home Assistant a través de MQTT

Faikout dispone de autodescubrimiento nativo para Home Assistant y está activado de forma predeterminada (ajuste haenable, activado por defecto). Una vez que el módulo se comunica con el mismo broker que Home Assistant, aparece por sí sola una entidad climate.

Configuración:

1. Ejecute un broker MQTT que utilice Home Assistant. Lo más sencillo es el complemento Mosquitto broker en Home Assistant OS, con la integración MQTT añadida.
2. Cree un usuario MQTT en Home Assistant para el dispositivo (un usuario normal de HA funciona con el complemento Mosquitto).
3. En la página de configuración de Faikout, establezca el host MQTT en la IP de Home Assistant e introduzca ese nombre de usuario y contraseña.
4. En un minuto, Home Assistant descubre el dispositivo (publicado bajo los topics <MAC>/...) y añade una tarjeta climate. No se requiere YAML.

Ajustes útiles relacionados con HA (configurados por MQTT o por la página web avanzada):

YAML del panel y de la tarjeta de entidades

No necesita YAML para crear las entidades. El autodescubrimiento crea por sí solo una entidad climate más sensores de temperatura. El YAML siguiente sirve para distribuirlas en un panel Lovelace.

Los ID de entidad se derivan del nombre de host, de modo que un dispositivo llamado GuestAC da climate.guestac y sensores como sensor.guestac_temperature. Los slugs exactos varían según la versión del firmware y sus ajustes de nomenclatura de HA, así que confírmelos en Ajustes → Dispositivos y servicios → MQTT → (su dispositivo) o en Herramientas para desarrolladores → Estados, y ajuste los ID de abajo para que coincidan.

Tarjeta de entidades. Añada una tarjeta a cualquier panel con Añadir tarjeta → Manual y pegue:

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 de panel completa. Abra un panel, Editar → (tres puntos) → Editor de configuración en bruto, y añada esto como una vista nueva bajo 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 prefiere construir una sola tarjeta de forma visual, tanto la tarjeta «Climate» de Mushroom como la tarjeta Thermostat integrada se vinculan directamente a climate.guestac.

Alternativa más sencilla sin MQTT. Faikout también emula la propia API local de Daikin y responde al descubrimiento UDP compatible con BRP (ajuste udpdiscovery). Si no desea ejecutar un broker MQTT, puede añadir en su lugar la integración Daikin integrada de Home Assistant y apuntarla a la dirección IP del Faikout. Para usuarios no técnicos, esta es la vía menos engorrosa hacia HA. Reserve la vía MQTT para cuando desee funciones que la integración de Daikin no expone, o cuando vaya a integrarse con algo que no sea HA.

Apple Home / Alexa / Google. Estos no hablan MQTT directamente, pero un puente salva la distancia. Home Assistant hace de puente con los tres. Para un hogar exclusivamente Apple sin HA, Homebridge con un complemento MQTT (por ejemplo EasyMQTT) lleva Faikout a la app Home nativa de iOS y a Siri. Es una vía bien probada, pero es un servidor autoalojado que hay que configurar, así que cuente con algo de configuración.

10. Otras plataformas

Los mismos dos topics (command/GuestAC/control para escribir, state/GuestAC para leer) funcionan en todas partes.

Línea de comandos de 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: un nodo mqtt out con el topic command/GuestAC/control. Aliméntelo con un msg.payload que sea un objeto JSON (utilice un nodo template o function, o un nodo change que establezca la carga útil en un valor JSON).
• Para supervisar: un nodo mqtt in en state/GuestAC y, a continuación, un nodo json para analizarlo en un objeto sobre el que pueda enrutar (p. ej. payload.home, payload.power).

openHAB

Utilice el binding MQTT genérico. Cree un Thing MQTT para el broker y, a continuación, canales como:

• un canal Switch con commandTopic = command/GuestAC/control, dando formato al valor como {"power":%s};
• un canal Number con stateTopic = state/GuestAC y una transformación JSONPATH como $.home para leer la temperatura de la sala.

El mismo patrón (publicar JSON en command/.../control, analizar JSON desde state/...) se aplica a Domoticz, ioBroker, Jeedom, FHEM, Homey, Hubitat y Gladys.

11. Faikout Auto a través de MQTT

Faikout Auto es una capa de control adicional que mantiene una banda objetivo ajustando la unidad entre calor/frío/apagado, utilizando opcionalmente un sensor de temperatura externo en lugar del propio del aire acondicionado. Puede gobernarla de tres maneras: desde la interfaz web, desde un sensor BLE o por MQTT. Las vías MQTT se indican a continuación.

A. Enviar una lectura desde su propia automatización

Envíe un mensaje control que contenga env (y, opcionalmente, target). La unidad se considera entonces bajo control remoto:

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

• env es la temperatura ambiente actual de su sensor. Debe reenviarse en cada mensaje control y al menos cada tcontrol segundos (600 por defecto). Si se agota el tiempo, la unidad sale del modo remoto/automático.
• target como array [min,max] (o un solo número con margin) fuerza el modo Faikout Auto y define la banda de confort.

B. Suscribir Faikout a un topic de sensor

En lugar de enviar, indique a Faikout que siga un topic MQTT existente:

Importante: la carga útil en autotopic debe ser JSON que contenga el campo indicado. Un topic que publica un número simple (por ejemplo, un topic de estado normal de ESPHome) no se podrá analizar; envuélvalo en JSON o utilice la vía A.

C. Seguir un sensor externo pero mantener el encendido/apagado manual

Una petición habitual: regular según una lectura externa precisa, pero sin dejar nunca que la unidad se encienda o se apague sola. El problema es que enviar env pone la unidad en modo «remoto», y en remoto se asume el encendido automático si autoptemp no es cero (0.5 por defecto). Por tanto:

• Ponga autop en desactivado y autoptemp en 0 (detiene el encendido/apagado automático).
• Mantenga tempadjust activado (esto es lo que realmente orienta la unidad hacia su referencia: ajusta la consigna en reference - measured).
• No envíe un array target (un array fuerza el comportamiento completo de banda/encendido de Auto). Envíe 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}'

Controles del modo auto que también puede enviar en un mensaje control

Estos reflejan los ajustes y se informan de vuelta en el estado cuando no se está bajo control remoto:

12. Referencia de ajustes

Los ajustes se leen y se escriben por MQTT de dos formas:

• Todos a la vez / relectura: publique JSON en setting/GuestAC, p. ej. {"reporting":30,"livestatus":true}. Una carga útil vacía hace que el dispositivo publique sus ajustes actuales.
• De uno en uno: publique el valor simple en setting/GuestAC/<name>, p. ej. el topic setting/GuestAC/livestatus con carga útil true.

Los nombres de abajo son los nombres MQTT (la página web avanzada los agrupa, pero por MQTT se escriben como una sola palabra). Este es un subconjunto práctico; el propio volcado de ajustes del dispositivo (carga útil vacía en setting/GuestAC) es la lista autorizada para su firmware.

Conexión e informes

Home Assistant

Consulte la sección 9: haenable, haswitches, ha1c, hafanrpm, hacomprpm, hadomain, udpdiscovery, nohvacaction, nohomepreset.

Faikout Auto

El ajuste fino de la predicción y del comportamiento de la banda (pushtemp, switchtemp, coolover, coolback, heatover, heatback, tpredicts, tpredictt, tsample, tcoolmin, theatmax, frosttemp, minoutside) está documentado en el manual avanzado y rara vez necesita cambiarse.

Anulaciones de capacidades

Si el firmware ofrece un control que su unidad en realidad no tiene (o viceversa), los ajustes no... le indican qué ocultar: por ejemplo nopowerful, noecono, nostreamer, noswingv, noswingh, noquiet, nodemand, nofaikoutauto. Los ajustes de forzado de protocolo nos21, nox50a, nocnwired evitan que intente un protocolo dado si la detección automática elige el incorrecto.

Depuración

13. Resolución de problemas

No aparece nada en MQTT / el dispositivo aparece sin conexión. Compruebe el topic simple state/GuestAC: false significa que el propio Faikout no está conectado al broker. A continuación, verifique que la IP/el nombre de host del broker en los ajustes sea alcanzable, que el nombre de usuario y la contraseña de MQTT sean correctos, que el broker esté a la escucha (normalmente el puerto 1883 en la LAN) y que el módulo esté en su WiFi de 2,4 GHz (no usa 5 GHz). Confirme que GuestAC.local carga en un navegador para comprobar que el WiFi está bien; entonces se trata de un problema de credenciales de MQTT o de alcanzabilidad del broker.

La unidad se enciende sola una y otra vez. Enviar env en un mensaje control pone la unidad bajo control remoto, y en remoto se asume el encendido automático si autoptemp no es cero (0.5 por defecto). Para mantener el encendido/apagado manual, ponga autop en desactivado y autoptemp en 0, mantenga tempadjust activado y envíe solo {"env": ...} sin array target. Consulte la sección 11C.

Faikout abandona el modo Auto al cabo de un rato. Los mensajes env/control caducan tras tcontrol segundos (600 por defecto). Reenvíe env en cada mensaje control y según una programación más corta que el tiempo de espera.

autotopic no hace nada. El topic suscrito debe llevar JSON con el campo indicado en autopayload. Una carga útil con un número simple no se podrá analizar. Publique JSON o envíe el valor usted mismo con un mensaje control env (sección 11A).

Home Assistant no muestra el dispositivo. haenable debe estar activado (lo está por defecto), la integración MQTT de HA debe estar instalada con el descubrimiento habilitado y el dispositivo debe estar en el mismo broker que HA. Confirme que llegan los mensajes de descubrimiento suscribiéndose a <MAC>/# (la dirección MAC del módulo). Si prefiere no usar MQTT en absoluto, utilice la integración Daikin nativa con la IP del Faikout.

El estado parece obsoleto. Los mensajes state/ son retenidos, de modo que un cliente puede mostrar el último valor tras un reinicio. Si ve datos genuinamente antiguos, borre el mensaje retenido en ese topic y active livestatus para obtener actualizaciones instantáneas ante los cambios.

Algunos controles de S21 no hacen nada. S21 está sometido a ingeniería inversa y varía según el modelo; powerful, econo, demand y similares pueden no existir en su unidad y simplemente se ignoran. El JSON de estado muestra qué controles expone realmente su unidad.

14. Hoja de referencia rápida

Sustituya GuestAC por su nombre de host y 192.168.1.10 por su broker.

Leer (suscribirse)

Comandos (publicar en command/GuestAC/...)

La carga útil control

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

Ajustes (publicar en setting/GuestAC...)

Sensor externo, mantener el encendido/apagado manual

Fuentes: firmware y manuales de RevK ESP32-Faikout (README, Setup, Controls, Advanced) y ESP/main/settings.def en Codeberg (codeberg.org/RevK/ESP32-Faikout). El comportamiento descrito coincide con el firmware a fecha de junio de 2026; el propio volcado de ajustes del dispositivo es el autorizado para su versión instalada.