MQTT를 통해 Faikin Faikout을 제어하고 모니터링하는 방법을 최초 설정부터 전체 토픽, 명령, 설정 레퍼런스까지 다루는 완전한 안내서입니다.

이 문서는 RevK의 펌웨어를 실행하는 WiFi Faikout 모듈을 대상으로 합니다(기기 브랜드명은 Faikout이며, 이전 명칭인 Faikin이 표시될 수도 있습니다). 펌웨어가 프로토콜을 자동으로 판별하므로 S21, X50A, CN_WIRED 기기 모두에 동일하게 적용됩니다. 본문 전체에서 예시 호스트명은 GuestAC, 예시 브로커 IP는 192.168.1.10입니다. 두 값 모두 사용자의 환경에 맞게 바꾸시기 바랍니다.

1. MQTT로 할 수 있는 일

모든 것이 로컬에서 처리됩니다. Faikout은 클라우드 계정이나 인터넷 의존성 없이 사용자의 자체 네트워크에서 MQTT로 통신합니다. MQTT를 통해 다음을 할 수 있습니다.

• 기기 제어: 전원, 운전 모드, 설정 온도, 팬 속도, 루버 스윙, powerful/econo.
• IR 리모컨에는 표시되지 않는 실시간 텔레메트리 읽기: 실내, 코일/냉매, 흡입구 및 외기 온도, 그리고 모델명과 운전 상태.
• Faikout Auto 계층 제어: 목표 대역, 스케줄, 외부 온도 기준값.
• Home Assistant(네이티브 자동 검색), openHAB, Node-RED, Domoticz, ioBroker 및 MQTT를 지원하는 그 밖의 모든 시스템과의 연동.

MQTT 제어는 내장 웹 인터페이스 및 IR 리모컨과 함께 동시에 작동합니다. 어느 한 곳에서 변경한 내용은 몇 초 안에 모든 곳에 반영됩니다.

2. 시작하기 전에

다음이 필요합니다.

• 이미 2.4GHz WiFi에 연결된 상태로 설치된 Faikout(설정 매뉴얼 참조). 브라우저에서 GuestAC.local 주소로 접속할 수 있습니다.
• 같은 네트워크에 있는 MQTT 브로커. 일반적으로 Home Assistant 내부의 Mosquitto 애드온을 쓰거나, Raspberry Pi, NAS 또는 서버에서 독립 실행형 Mosquitto를 사용합니다.
• 브로커의 IP 주소 또는 호스트명, 그리고 브로커가 인증을 요구하는 경우 사용자 이름과 비밀번호(Home Assistant의 브로커는 일반적으로 인증을 요구합니다).

브로커는 사용자가 통제하는 네트워크에 두십시오. Faikout의 MQTT는 일반 로컬 트래픽이며 인터넷에 노출하도록 설계되지 않았습니다.

3. 1단계: Faikout을 MQTT 브로커로 지정하기

1. GuestAC.local로 접속하여 WiFi settings를 엽니다(아직 WiFi에 연결되지 않은 경우, 기기의 설정 버튼을 누른 다음 기기의 Daikin/Faikout 액세스 포인트에 연결하십시오).
2. MQTT 섹션에서 Host(브로커 IP 또는 호스트명, 예: 192.168.1.10)를 입력하고, 브로커가 사용한다면 Username과 Password를 입력합니다.
3. Hostname을 기억하기 쉬운 이름으로 설정하십시오(예: GuestAC). 이 이름은 모든 MQTT 토픽의 일부가 되므로, 자동화를 구성하기 전에 미리 정해 두는 것이 좋습니다.
4. 저장합니다. Faikout이 재접속하여 발행을 시작합니다.

기반이 되는 연결 설정은 mqtthost(RevK 라이브러리 표준)입니다. 사용자 이름과 비밀번호는 같은 페이지에서 입력합니다. 연결된 후에는 MQTT 자체를 통해서도 이 값들을 나중에 변경할 수 있습니다(설정 레퍼런스 참조).

4. 2단계: 연결 확인하기

해당 기기의 모든 토픽을 구독하여 보존(retained)된 상태가 들어오는지 확인하십시오.

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

보존된 state/GuestAC 메시지가 보여야 합니다. 그 페이로드의 online 값이 true이면 에어컨이 모듈과 통신하고 있다는 뜻입니다. 접미사가 없는 state/GuestAC 토픽은 기기 자체의 존재(presence)를 나타내며, 페이로드가 false이면 Faikout 자체가 오프라인이라는 의미입니다(이것이 MQTT의 will/birth 메시지입니다).

아무것도 도착하지 않으면 문제 해결 항목으로 이동하십시오.

5. 토픽 구조

Faikout은 표준 RevK 라이브러리 토픽 레이아웃인 prefix/hostname/suffix를 사용합니다. 호스트명이 GuestAC인 경우:

대부분의 자동화에는 이 가운데 두 가지만 있으면 됩니다. command/GuestAC/control로 발행하고 state/GuestAC를 구독하십시오.

6. 명령 전송하기

command/GuestAC/<command>로 발행합니다. 단순한 명령은 페이로드가 필요 없으며, 일부 명령은 인수를 페이로드로 받습니다.

예시:

# 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. control 메시지 (핵심 메시지)

command/GuestAC/control은 JSON 페이로드를 받으며, 여러 항목을 한 번에 설정하는 가장 깔끔한 방법입니다. 동일한 필드 이름이 상태 JSON에도 나타나므로, 전송하는 내용이 읽는 내용과 그대로 일치합니다.

예시: 자동 팬, 수직 스윙 켜짐 상태로 24°C 냉방:

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

참고: powerful, econo, streamer 등의 부가 기능은 모델에 따라 다릅니다. S21은 역공학으로 분석된 것이며 기기마다 동일하지 않으므로, 사용 중인 기기에 없는 스위치는 그냥 무시됩니다. 상태 JSON을 보면 사용 중인 기기가 실제로 노출하는 제어 항목이 무엇인지 알 수 있습니다.

8. 상태 읽기

Faikout은 세 가지 계열의 토픽으로 상태를 발행합니다.

• state/GuestAC는 사람/자동화용 상태로, reporting초마다(기본값 60초) 그리고 중요한 변경이 있을 때 발행됩니다. livestatus를 켜면 모든 변경마다 실시간으로도 발행됩니다.
• Faikout/...은 약 1분에 한 번 발행되며, faikoutlog 도구가 그래프 작성을 위해 MySQL/MariaDB 데이터베이스에 저장하도록 만들어진 것입니다.
• <MAC>/...는 Home Assistant 자동 검색 피드로, HA 지원이 활성화되었을 때 발행됩니다(9절 참조).

state JSON에는 위의 control 표에 있는 모든 항목이 포함되며(따라서 power, mode, temp, fan 등을 다시 읽어 올 수 있습니다), 여기에 더해 다음의 읽기 전용 필드가 들어갑니다.

데이터베이스 로깅 형식: Faikout/ 피드에서는 각 값이 해당 기간에 대해 요약됩니다. 값이 변하지 않았으면 단일 값으로 보고되며, 변했으면 숫자 값은 [min, average, max] 배열이 되고 boolean 값은 해당 기간 중 true였던 비율을 나타내는 0.0~1.0의 분수가 됩니다. fixstatus를 켜면 변화 여부와 관계없이 항상 배열/분수 형식을 사용합니다.

9. MQTT를 통한 Home Assistant 연동

Faikout은 네이티브 Home Assistant 자동 검색을 지원하며 기본으로 켜져 있습니다(설정 haenable, 기본값 켜짐). 모듈이 Home Assistant와 같은 브로커에 연결되면 climate 엔티티가 자동으로 나타납니다.

설정 방법:

1. Home Assistant가 사용하는 MQTT 브로커를 실행합니다. 가장 쉬운 방법은 Home Assistant OS의 Mosquitto broker 애드온을 사용하고 MQTT 연동(integration)을 추가하는 것입니다.
2. Home Assistant에서 기기를 위한 MQTT 사용자를 생성합니다(Mosquitto 애드온에서는 일반 HA 사용자도 사용할 수 있습니다).
3. Faikout 설정 페이지에서 MQTT host를 Home Assistant의 IP로 설정하고, 해당 사용자 이름과 비밀번호를 입력합니다.
4. 1분 이내에 Home Assistant가 기기를 검색하여(<MAC>/... 토픽으로 발행됨) climate 카드를 추가합니다. YAML은 필요 없습니다.

유용한 HA 관련 설정(MQTT 또는 Advanced 웹 페이지를 통해 설정):

대시보드 및 엔티티 카드 YAML

엔티티를 생성하는 데에는 YAML이 필요 없습니다. 자동 검색이 climate 엔티티와 온도 센서를 자동으로 만들어 줍니다. 아래 YAML은 이를 Lovelace 대시보드에 배치하기 위한 것입니다.

엔티티 ID는 호스트명에서 파생되므로, GuestAC라는 이름의 기기는 climate.guestac와 sensor.guestac_temperature 같은 센서를 생성합니다. 정확한 슬러그는 펌웨어 버전과 HA 명명 설정에 따라 달라지므로, Settings → Devices & Services → MQTT → (사용 중인 기기) 또는 Developer Tools → States에서 확인하고 아래 ID를 그에 맞게 조정하십시오.

엔티티 카드. Add card → Manual로 아무 대시보드에나 카드를 추가하고 다음을 붙여 넣으십시오.

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

전체 대시보드 보기. 대시보드를 열고 Edit → (점 세 개) → Raw configuration editor로 이동하여, 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

단일 카드를 시각적으로 구성하고 싶다면, Mushroom의 "Climate" 카드와 내장 Thermostat 카드 모두 climate.guestac에 직접 바인딩됩니다.

더 간단한, MQTT를 쓰지 않는 대안. Faikout은 Daikin 자체의 로컬 API도 에뮬레이션하며 BRP 호환 UDP 검색에 응답합니다(설정 udpdiscovery). MQTT 브로커를 운영하고 싶지 않다면, 대신 Home Assistant의 내장 Daikin 연동을 추가하고 Faikout의 IP 주소를 지정하면 됩니다. 비전문 사용자에게는 이것이 HA로 들어가는 가장 번거롭지 않은 경로입니다. MQTT 경로는 Daikin 연동이 노출하지 않는 기능이 필요하거나 HA가 아닌 다른 것과 연동할 때를 위해 남겨 두십시오.

Apple Home / Alexa / Google. 이들은 MQTT를 직접 지원하지 않지만, 브리지가 그 간극을 메워 줍니다. Home Assistant는 세 가지 모두를 브리징합니다. HA가 없는 Apple 전용 가정의 경우, MQTT 플러그인(예: EasyMQTT)을 갖춘 Homebridge가 Faikout을 iOS 네이티브 Home 앱과 Siri로 가져옵니다. 널리 검증된 방식이지만 직접 호스팅하는 서버를 구축해야 하므로 어느 정도의 설정 작업을 예상하시기 바랍니다.

10. 기타 플랫폼

동일한 두 토픽(쓰기용 command/GuestAC/control, 읽기용 state/GuestAC)이 어디서나 작동합니다.

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

• 제어하려면: 토픽 command/GuestAC/control을 가진 mqtt out 노드를 사용합니다. JSON 객체인 msg.payload를 공급하십시오(template 또는 function 노드를 쓰거나, 페이로드를 JSON 값으로 설정하는 change 노드를 사용합니다).
• 모니터링하려면: state/GuestAC에 대한 mqtt in 노드를 두고, 이어서 json 노드로 파싱하여 라우팅에 사용할 수 있는 객체로 만듭니다(예: payload.home, payload.power).

openHAB

일반 MQTT 바인딩을 사용하십시오. 브로커용 MQTT Thing을 생성한 다음, 예를 들어 다음과 같은 채널을 만듭니다.

• commandTopic = command/GuestAC/control인 Switch 채널을 만들고 값을 {"power":%s} 형식으로 지정합니다.
• stateTopic = state/GuestAC인 Number 채널을 만들고 $.home 같은 JSONPATH 변환을 적용하여 실내 온도를 읽습니다.

동일한 패턴(command/.../control에 JSON 발행, state/...에서 JSON 파싱)이 Domoticz, ioBroker, Jeedom, FHEM, Homey, Hubitat, Gladys에도 적용됩니다.

11. MQTT를 통한 Faikout Auto

Faikout Auto는 기기를 난방/냉방/끄기 사이에서 조정하여 목표 대역을 유지하는 추가 제어 계층으로, 선택적으로 에어컨 자체 센서 대신 외부 온도 센서를 사용할 수 있습니다. 웹 UI, BLE 센서, MQTT의 세 가지 방법으로 구동할 수 있습니다. MQTT 경로는 아래와 같습니다.

A. 자체 자동화에서 측정값 푸시하기

env(그리고 선택적으로 target)를 담은 control 메시지를 보냅니다. 그러면 기기는 자신을 원격 제어 하에 있는 것으로 간주합니다.

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

• env는 사용자의 센서에서 측정한 현재 실내 온도입니다. 모든 control 메시지마다 그리고 최소한 tcontrol초(기본값 600)마다 다시 보내야 합니다. 시간이 초과되면 기기는 원격/자동 모드에서 벗어납니다.
• [min,max] 배열로 된 target(또는 margin과 함께 단일 숫자)을 보내면 Faikout Auto 모드가 강제되며 쾌적 대역이 정의됩니다.

B. Faikout을 센서 토픽에 구독시키기

값을 푸시하는 대신, Faikout이 기존 MQTT 토픽을 따르도록 지정할 수 있습니다.

중요: autotopic의 페이로드는 지정된 필드를 포함하는 JSON이어야 합니다. 단순한 숫자만 발행하는 토픽(예: 일반 ESPHome 상태 토픽)은 파싱되지 않으므로, JSON으로 감싸거나 경로 A를 사용하십시오.

C. 외부 센서를 추적하되 켜기/끄기는 수동으로 유지하기

흔한 요청 한 가지: 정확한 외부 측정값에 맞춰 제어하되, 기기가 스스로 전원을 켜거나 끄지 않게 하는 것입니다. 문제는 env를 보내면 기기가 "원격" 상태가 되고, 원격 상태에서는 autoptemp가 0이 아니면(기본값 0.5) 자동 전원이 적용된다는 점입니다. 따라서:

• autop을 끄고 autoptemp를 0으로 설정합니다(자동 전원 켜기/끄기를 중지함).
• tempadjust를 켜진 상태로 유지합니다(이것이 실제로 기기를 사용자의 기준값에 맞추는 기능으로, reference - measured만큼 설정 온도를 조정합니다).
• target 배열을 보내지 마십시오(배열은 전체 Auto 대역/전원 동작을 강제합니다). {"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}'

control 메시지로도 보낼 수 있는 자동 모드 제어 항목

이 항목들은 설정을 그대로 반영하며, 원격 제어 하에 있지 않을 때 상태에서 다시 보고됩니다.

12. 설정 레퍼런스

설정은 MQTT를 통해 두 가지 형태로 읽고 씁니다.

• 한 번에 전체 / 다시 읽기: setting/GuestAC에 JSON을 발행합니다(예: {"reporting":30,"livestatus":true}). 빈 페이로드를 보내면 기기가 현재 설정을 발행합니다.
• 한 번에 하나씩: setting/GuestAC/<name>에 값 그 자체를 발행합니다(예: 토픽 setting/GuestAC/livestatus, 페이로드 true).

아래 이름은 MQTT 이름입니다(Advanced 웹 페이지에서는 이들을 그룹으로 묶지만, MQTT에서는 한 단어로 작성합니다). 이는 작동하는 일부 목록일 뿐이며, 사용 중인 펌웨어에 대한 권위 있는 목록은 기기 자체의 설정 덤프(setting/GuestAC에 빈 페이로드 전송)입니다.

연결 및 보고

Home Assistant

9절 참조: haenable, haswitches, ha1c, hafanrpm, hacomprpm, hadomain, udpdiscovery, nohvacaction, nohomepreset.

Faikout Auto

예측 및 대역 동작의 미세 조정(pushtemp, switchtemp, coolover, coolback, heatover, heatback, tpredicts, tpredictt, tsample, tcoolmin, theatmax, frosttemp, minoutside)은 Advanced 매뉴얼에 문서화되어 있으며, 변경할 일은 거의 없습니다.

기능 재정의

펌웨어가 기기에 실제로 없는 제어를 제공하거나 그 반대인 경우, no... 설정으로 무엇을 숨길지 지정합니다. 예: nopowerful, noecono, nostreamer, noswingv, noswingh, noquiet, nodemand, nofaikoutauto. 프로토콜 강제 설정인 nos21, nox50a, nocnwired는 자동 감지가 잘못된 프로토콜을 선택한 경우 해당 프로토콜 시도를 중단시킵니다.

디버그

13. 문제 해결

MQTT에 아무것도 나타나지 않음 / 기기가 오프라인으로 표시됨. 접미사가 없는 state/GuestAC 토픽을 확인하십시오. false이면 Faikout 자체가 브로커에 연결되어 있지 않다는 뜻입니다. 그다음 설정의 브로커 IP/호스트명에 도달할 수 있는지, MQTT 사용자 이름과 비밀번호가 올바른지, 브로커가 수신 대기 중인지(보통 LAN의 1883 포트), 모듈이 2.4GHz WiFi에 연결되어 있는지(5GHz는 사용하지 않습니다) 확인하십시오. 브라우저에서 GuestAC.local이 열리는지 확인하여 WiFi가 정상임을 입증한다면, 문제는 MQTT 자격 증명 또는 브로커 도달 가능성에 있는 것입니다.

기기가 자꾸 스스로 켜짐. control 메시지로 env를 보내면 기기가 원격 제어 하에 놓이며, 원격 상태에서는 autoptemp가 0이 아니면(기본값 0.5) 자동 전원이 적용됩니다. 켜기/끄기를 수동으로 유지하려면 autop을 끄고 autoptemp를 0으로 설정한 뒤, tempadjust는 켠 상태로 두고 target 배열 없이 {"env": ...}만 보내십시오. 11C절을 참조하십시오.

Faikout이 얼마 후 Auto 모드에서 빠짐. env/control 메시지는 tcontrol초(기본값 600) 후에 타임아웃됩니다. 모든 control 메시지마다 그리고 타임아웃보다 짧은 주기로 env를 다시 보내십시오.

autotopic이 아무 동작도 하지 않음. 구독한 토픽은 autopayload에 지정된 필드를 가진 JSON을 담고 있어야 합니다. 단순한 숫자 페이로드는 파싱되지 않습니다. JSON을 발행하거나, env control 메시지로 값을 직접 푸시하십시오(11A절).

Home Assistant에 기기가 표시되지 않음. haenable이 켜져 있어야 하고(기본으로 켜져 있음), HA MQTT 연동이 검색 활성화 상태로 설치되어 있어야 하며, 기기가 HA와 같은 브로커에 있어야 합니다. <MAC>/#(모듈의 MAC 주소)을 구독하여 검색 메시지가 도착하는지 확인하십시오. MQTT를 전혀 사용하고 싶지 않다면, 대신 Faikout의 IP로 네이티브 Daikin 연동을 사용하십시오.

상태가 오래된 것처럼 보임. state/ 메시지는 보존되므로, 클라이언트는 재시작 후에도 마지막 값을 표시할 수 있습니다. 정말로 오래된 데이터가 보이면 해당 토픽의 보존 메시지를 지우고, 변경 시 즉시 갱신되도록 livestatus를 켜십시오.

일부 제어가 아무 동작도 하지 않음. S21은 역공학으로 분석되어 모델마다 다릅니다. powerful, econo, demand 등은 사용 중인 기기에 존재하지 않을 수 있으며 그런 경우 그냥 무시됩니다. 상태 JSON을 보면 사용 중인 기기가 실제로 노출하는 제어가 무엇인지 알 수 있습니다.

14. 빠른 참조 치트시트

GuestAC는 사용자의 호스트명으로, 192.168.1.10은 사용자의 브로커로 바꾸십시오.

읽기 (구독)

명령 (command/GuestAC/...로 발행)

control 페이로드

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

설정 (setting/GuestAC...로 발행)

외부 센서, 켜기/끄기는 수동 유지

출처: RevK ESP32-Faikout 펌웨어 및 매뉴얼(README, Setup, Controls, Advanced)과 Codeberg의 ESP/main/settings.def(codeberg.org/RevK/ESP32-Faikout). 설명된 동작은 2026년 6월 기준 펌웨어와 일치합니다. 설치된 버전에 대해서는 기기 자체의 설정 덤프가 권위 있는 기준입니다.