Hướng dẫn đầy đủ về việc điều khiển và giám sát Faikin Faikout qua MQTT, từ bước thiết lập ban đầu cho đến tài liệu tham khảo đầy đủ về topic, lệnh và cài đặt.

Tài liệu này áp dụng cho mô-đun WiFi Faikout chạy phần mềm của RevK (thiết bị mang nhãn hiệu Faikout; bạn vẫn có thể thấy tên cũ là Faikin). Nó áp dụng như nhau cho các thiết bị S21, X50A và CN_WIRED, vì phần mềm tự động xác định giao thức. Trong toàn bộ tài liệu, tên máy chủ ví dụ là GuestAC và địa chỉ IP của broker ví dụ là 192.168.1.10. Hãy thay cả hai bằng giá trị của riêng bạn.

1. MQTT mang lại điều gì

Mọi thứ đều diễn ra cục bộ. Faikout giao tiếp MQTT trên mạng của riêng bạn, không cần tài khoản đám mây và không phụ thuộc vào internet. Qua MQTT, bạn có thể:

• Điều khiển thiết bị: nguồn, chế độ, điểm đặt nhiệt độ, tốc độ quạt, đảo hướng cánh gió, powerful/econo.
• Đọc dữ liệu đo trực tiếp mà điều khiển hồng ngoại không hiển thị: nhiệt độ phòng, dàn lạnh/môi chất, gió hồi và nhiệt độ ngoài trời, cùng với tên model và trạng thái vận hành.
• Điều khiển lớp Faikout Auto: dải nhiệt độ mục tiêu, lịch trình, và một nguồn tham chiếu nhiệt độ bên ngoài.
• Tích hợp với Home Assistant (tự động phát hiện gốc), openHAB, Node-RED, Domoticz, ioBroker và bất kỳ thứ gì khác hỗ trợ MQTT.

Điều khiển qua MQTT hoạt động song song với giao diện web tích hợp sẵn và điều khiển hồng ngoại. Một thay đổi từ bất kỳ nguồn nào sẽ hiển thị ở mọi nơi trong vòng vài giây.

2. Trước khi bắt đầu

Bạn cần:

• Một thiết bị Faikout đã được lắp đặt và đã kết nối với mạng WiFi 2.4GHz của bạn (xem hướng dẫn Thiết lập). Bạn có thể truy cập thiết bị tại GuestAC.local trên trình duyệt.
• Một broker MQTT trên cùng mạng. Các lựa chọn phổ biến là tiện ích bổ sung Mosquitto bên trong Home Assistant, hoặc một Mosquitto độc lập trên Raspberry Pi, NAS hoặc máy chủ.
• Địa chỉ IP hoặc tên máy chủ của broker, và một tên người dùng và mật khẩu nếu broker yêu cầu xác thực (broker của Home Assistant thường yêu cầu).

Hãy giữ broker trên một mạng mà bạn kiểm soát. MQTT của Faikout là lưu lượng cục bộ thuần túy và không nhằm để công khai ra internet.

3. Bước 1: Trỏ Faikout đến broker MQTT của bạn

1. Truy cập GuestAC.local và mở Cài đặt WiFi (hoặc nhấn giữ nút thiết lập của thiết bị, rồi kết nối với điểm truy cập Daikin/Faikout của nó nếu thiết bị chưa kết nối WiFi của bạn).
2. Trong phần MQTT, nhập Host (IP hoặc tên máy chủ của broker, ví dụ 192.168.1.10) và, nếu broker của bạn dùng, nhập Tên người dùng và Mật khẩu.
3. Hãy đảm bảo Tên máy chủ được đặt thành một tên dễ nhớ, ví dụ GuestAC. Tên này trở thành một phần của mọi topic MQTT, vì vậy hãy chọn nó trước khi bạn xây dựng các quy trình tự động hóa.
4. Lưu lại. Faikout kết nối lại và bắt đầu phát thông điệp.

Cài đặt kết nối cơ bản là mqtthost (chuẩn thư viện RevK). Tên người dùng và mật khẩu được nhập trên cùng trang. Bạn cũng có thể thay đổi những thông số này sau qua chính MQTT khi đã kết nối (xem Tài liệu tham khảo cài đặt).

4. Bước 2: Xác nhận thiết bị đã kết nối

Hãy đăng ký nhận mọi thứ của thiết bị đó và theo dõi trạng thái được giữ lại:

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

Bạn sẽ thấy một thông điệp state/GuestAC được giữ lại. Payload của nó báo cáo online là true khi máy điều hòa đang giao tiếp với mô-đun. Topic state/GuestAC trống cho biết sự hiện diện của chính thiết bị: payload là false nghĩa là chính Faikout đang ngoại tuyến (đây là thông điệp will/birth MQTT của nó).

Nếu không có gì xuất hiện, hãy chuyển đến phần Khắc phục sự cố.

5. Cấu trúc topic

Faikout sử dụng bố cục topic chuẩn của thư viện RevK: prefix/hostname/suffix. Với tên máy chủ GuestAC:

Đối với phần lớn việc tự động hóa, bạn chỉ cần hai topic trong số này: phát đến command/GuestAC/control và đăng ký nhận state/GuestAC.

6. Gửi lệnh

Hãy phát đến command/GuestAC/<command>. Các lệnh đơn giản không cần payload; một số ít lệnh nhận một đối số làm payload.

Ví dụ:

# 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. Thông điệp control (thông điệp chính)

command/GuestAC/control nhận một payload JSON và là cách gọn gàng nhất để đặt nhiều thứ cùng một lúc. Các tên trường tương tự cũng xuất hiện trong JSON trạng thái, vì vậy những gì bạn gửi phản chiếu những gì bạn đọc.

Ví dụ: làm mát đến 24°C với quạt tự động, bật đảo gió dọc:

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

Lưu ý: powerful, econo, streamer và các tính năng bổ sung tương tự phụ thuộc vào model. S21 được dịch ngược và không giống nhau hoàn toàn giữa các thiết bị, vì vậy một công tắc mà thiết bị của bạn không có thì đơn giản sẽ bị bỏ qua. JSON trạng thái cho bạn biết những điều khiển nào mà thiết bị của bạn thực sự cung cấp.

8. Đọc trạng thái

Faikout phát trạng thái tới ba nhóm topic:

• state/GuestAC là trạng thái dành cho con người/tự động hóa, được phát mỗi reporting giây (mặc định 60) và khi có thay đổi đáng kể. Bật livestatus để đồng thời phát theo thời gian thực mỗi khi có bất kỳ thay đổi.
• Faikout/... được phát khoảng mỗi phút một lần và dành cho công cụ faikoutlog để lưu vào cơ sở dữ liệu MySQL/MariaDB nhằm vẽ biểu đồ.
• <MAC>/... là luồng tự động phát hiện của Home Assistant, được phát khi bật hỗ trợ HA (xem mục 9).

JSON state bao gồm mọi thứ từ bảng control ở trên (do đó bạn có thể đọc lại power, mode, temp, fan, v.v.) cùng với các trường chỉ đọc sau:

Định dạng ghi nhật ký cơ sở dữ liệu: trong luồng Faikout/, mỗi giá trị được tóm tắt trong khoảng thời gian. Nếu giá trị không thay đổi, nó được báo cáo dưới dạng một giá trị đơn; nếu có thay đổi, một giá trị số trở thành mảng [min, average, max] và một giá trị boolean trở thành một phân số 0.0–1.0 thể hiện thời gian nó đúng trong khoảng đó. Bật fixstatus để luôn dùng định dạng mảng/phân số bất kể trường hợp nào.

9. Home Assistant qua MQTT

Faikout có tính năng tự động phát hiện Home Assistant gốc và tính năng này bật theo mặc định (cài đặt haenable, mặc định bật). Khi mô-đun giao tiếp với cùng broker với Home Assistant, một thực thể climate sẽ tự động xuất hiện.

Thiết lập:

1. Chạy một broker MQTT mà Home Assistant sử dụng. Cách dễ nhất là tiện ích bổ sung Mosquitto broker trong Home Assistant OS, với tích hợp MQTT đã được thêm.
2. Tạo một người dùng MQTT trong Home Assistant cho thiết bị (một người dùng HA thông thường hoạt động được với tiện ích bổ sung Mosquitto).
3. Trên trang thiết lập Faikout, đặt MQTT host thành IP của Home Assistant và nhập tên người dùng và mật khẩu đó.
4. Trong vòng một phút, Home Assistant phát hiện thiết bị (được phát dưới các topic <MAC>/...) và thêm một thẻ climate. Không cần YAML.

Các cài đặt hữu ích liên quan đến HA (đặt qua MQTT hoặc trang web Nâng cao):

YAML cho bảng điều khiển và thẻ thực thể

Bạn không cần YAML để tạo các thực thể. Tính năng tự động phát hiện sẽ tự tạo một thực thể climate cùng với các cảm biến nhiệt độ. YAML bên dưới là để sắp xếp chúng trên bảng điều khiển Lovelace.

ID thực thể được suy ra từ tên máy chủ, vì vậy một thiết bị tên GuestAC sẽ cho ra climate.guestac và các cảm biến như sensor.guestac_temperature. Các slug chính xác thay đổi tùy theo phiên bản phần mềm và cài đặt đặt tên HA của bạn, vì vậy hãy xác nhận chúng tại Settings → Devices & Services → MQTT → (thiết bị của bạn) hoặc Developer Tools → States, và điều chỉnh các ID bên dưới cho khớp.

Thẻ thực thể. Thêm một thẻ vào bất kỳ bảng điều khiển nào bằng Add card → Manual và dán:

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

Chế độ xem bảng điều khiển đầy đủ. Mở một bảng điều khiển, Edit → (ba chấm) → Raw configuration editor, và thêm phần này thành một view mới dưới 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

Nếu bạn muốn dựng một thẻ duy nhất một cách trực quan, thẻ "Climate" của Mushroom và thẻ Thermostat tích hợp sẵn đều liên kết trực tiếp với climate.guestac.

Lựa chọn thay thế đơn giản hơn, không dùng MQTT. Faikout cũng mô phỏng API cục bộ của riêng Daikin và đáp ứng khám phá UDP tương thích BRP (cài đặt udpdiscovery). Nếu bạn không muốn chạy một broker MQTT, bạn có thể thay vào đó thêm tích hợp Daikin tích hợp sẵn của Home Assistant và trỏ nó đến địa chỉ IP của Faikout. Đối với người dùng không chuyên kỹ thuật, đây là cách ít rắc rối nhất để vào HA. Hãy dành đường dẫn MQTT cho khi bạn muốn các tính năng mà tích hợp Daikin không cung cấp, hoặc khi bạn tích hợp với thứ gì đó khác ngoài HA.

Apple Home / Alexa / Google. Những thứ này không giao tiếp MQTT trực tiếp, nhưng một cầu nối sẽ thu hẹp khoảng cách. Home Assistant làm cầu nối cho cả ba. Đối với một gia đình chỉ dùng Apple mà không có HA, Homebridge cùng một plugin MQTT (ví dụ EasyMQTT) đưa Faikout vào ứng dụng Home gốc trên iOS và Siri. Đây là cách đã được nhiều người sử dụng nhưng là một máy chủ tự lưu trữ cần thiết lập, vì vậy hãy chuẩn bị cho một số bước cấu hình.

10. Các nền tảng khác

Hai topic tương tự (command/GuestAC/control để ghi, state/GuestAC để đọc) hoạt động ở mọi nơi.

Dòng lệnh 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

• Để điều khiển: một node mqtt out với topic command/GuestAC/control. Cấp cho nó một msg.payload là một đối tượng JSON (dùng node template hoособ function, hoặc một node change đặt payload thành một giá trị JSON).
• Để giám sát: một node mqtt in trên state/GuestAC, rồi một node json để phân tích nó thành một đối tượng mà bạn có thể định tuyến (ví dụ payload.home, payload.power).

openHAB

Dùng MQTT binding tổng quát. Tạo một MQTT Thing cho broker, rồi các channel như:

• một channel Switch với commandTopic = command/GuestAC/control, định dạng giá trị thành {"power":%s};
• một channel Number với stateTopic = state/GuestAC và một phép biến đổi JSONPATH như $.home để đọc nhiệt độ phòng.

Cùng một mẫu (phát JSON tới command/.../control, phân tích JSON từ state/...) áp dụng cho Domoticz, ioBroker, Jeedom, FHEM, Homey, Hubitat và Gladys.

11. Faikout Auto qua MQTT

Faikout Auto là một lớp điều khiển bổ sung giữ một dải nhiệt độ mục tiêu bằng cách điều chỉnh thiết bị giữa sưởi/làm mát/tắt, tùy chọn sử dụng một cảm biến nhiệt độ bên ngoài thay cho cảm biến của chính máy điều hòa. Bạn có thể điều khiển nó theo ba cách: từ giao diện web, từ một cảm biến BLE, hoặc qua MQTT. Các đường dẫn MQTT được trình bày bên dưới.

A. Đẩy một giá trị đọc từ quy trình tự động hóa của riêng bạn

Gửi một thông điệp control chứa env (và tùy chọn target). Thiết bị khi đó sẽ coi mình đang chịu điều khiển từ xa:

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

• env là nhiệt độ phòng hiện tại từ cảm biến của bạn. Nó phải được gửi lại trong mỗi thông điệp control và ít nhất mỗi tcontrol giây (mặc định 600). Nếu hết thời gian chờ, thiết bị sẽ thoát khỏi chế độ điều khiển từ xa/tự động.
• target dưới dạng một mảng [min,max] (hoặc một con số đơn với margin) buộc kích hoạt chế độ Faikout Auto và xác định dải nhiệt độ thoải mái.

B. Đăng ký Faikout vào một topic cảm biến

Thay vì đẩy, hãy bảo Faikout theo dõi một topic MQTT có sẵn:

Quan trọng: payload trên autotopic phải là JSON chứa trường được đặt tên. Một topic phát ra một con số thuần (ví dụ một topic trạng thái ESPHome thông thường) sẽ không phân tích được; hãy bọc nó trong JSON, hoặc dùng đường dẫn A.

C. Theo dõi một cảm biến bên ngoài nhưng giữ bật/tắt thủ công

Một yêu cầu phổ biến: điều khiển theo một giá trị đọc bên ngoài chính xác, nhưng không bao giờ để thiết bị tự bật hoặc tắt nguồn. Vấn đề là việc gửi env khiến thiết bị trở nên "remote", và khi ở chế độ remote, nguồn tự động được giả định nếu autoptemp không bằng không (mặc định 0.5). Vì vậy:

• Đặt autop tắt và autoptemp 0 (ngừng tự động bật/tắt nguồn).
• Giữ tempadjust bật (đây mới là thứ thực sự hướng thiết bị theo giá trị tham chiếu của bạn: nó điều chỉnh điểm đặt theo reference - measured).
• Không gửi một mảng target (một mảng buộc kích hoạt hành vi dải/nguồn Auto đầy đủ). Chỉ gửi {"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}'

Các điều khiển chế độ Auto mà bạn cũng có thể gửi trong một thông điệp control

Những điều khiển này phản chiếu các cài đặt và được báo cáo lại trong trạng thái khi không chịu điều khiển từ xa:

12. Tài liệu tham khảo cài đặt

Các cài đặt được đọc và ghi qua MQTT theo hai dạng:

• Tất cả cùng lúc / đọc lại: phát JSON tới setting/GuestAC, ví dụ {"reporting":30,"livestatus":true}. Một payload trống khiến thiết bị phát lại các cài đặt hiện tại của nó.
• Từng cài đặt một: phát giá trị thuần tới setting/GuestAC/<name>, ví dụ topic setting/GuestAC/livestatus payload true.

Các tên bên dưới là tên MQTT (trang web Nâng cao nhóm chúng lại, nhưng qua MQTT chúng được viết liền thành một từ). Đây là một tập hợp con hữu dụng; bản kết xuất cài đặt của chính thiết bị (payload trống tới setting/GuestAC) là danh sách chính thức cho phần mềm của bạn.

Kết nối và báo cáo

Home Assistant

Xem mục 9: haenable, haswitches, ha1c, hafanrpm, hacomprpm, hadomain, udpdiscovery, nohvacaction, nohomepreset.

Faikout Auto

Việc tinh chỉnh hành vi dự đoán và dải (pushtemp, switchtemp, coolover, coolback, heatover, heatback, tpredicts, tpredictt, tsample, tcoolmin, theatmax, frosttemp, minoutside) được mô tả trong hướng dẫn Nâng cao và hiếm khi cần thay đổi.

Ghi đè khả năng

Nếu phần mềm cung cấp một điều khiển mà thiết bị của bạn thực ra không có (hoặc ngược lại), các cài đặt no... sẽ cho nó biết cần ẩn gì: ví dụ nopowerful, noecono, nostreamer, noswingv, noswingh, noquiet, nodemand, nofaikoutauto. Các cài đặt buộc giao thức nos21, nox50a, nocnwired sẽ ngăn nó thử một giao thức nhất định nếu việc tự động phát hiện chọn sai.

Gỡ lỗi

13. Khắc phục sự cố

Không có gì xuất hiện trên MQTT / thiết bị hiển thị ngoại tuyến. Kiểm tra topic state/GuestAC trống: false nghĩa là chính Faikout không kết nối được với broker. Sau đó xác minh rằng IP/tên máy chủ của broker trong cài đặt có thể truy cập, tên người dùng và mật khẩu MQTT đúng, broker đang lắng nghe (thường là cổng 1883 trên mạng LAN), và mô-đun đang ở trên WiFi 2.4GHz của bạn (nó không dùng 5GHz). Hãy xác nhận GuestAC.local tải được trên trình duyệt để chứng minh WiFi ổn, khi đó vấn đề là ở thông tin xác thực MQTT hoặc khả năng truy cập broker.

Thiết bị cứ tự bật. Việc gửi env trong một thông điệp control đưa thiết bị vào chế độ điều khiển từ xa, và khi ở chế độ remote, nguồn tự động được giả định nếu autoptemp không bằng không (mặc định 0.5). Để giữ bật/tắt thủ công, hãy đặt autop tắt và autoptemp 0, giữ tempadjust bật, và chỉ gửi {"env": ...} mà không có mảng target. Xem mục 11C.

Faikout thoát khỏi chế độ Auto sau một lúc. Các thông điệp env/control hết thời gian chờ sau tcontrol giây (mặc định 600). Hãy gửi lại env trong mỗi thông điệp control và theo một lịch ngắn hơn thời gian chờ.

autotopic không có tác dụng gì. Topic đã đăng ký phải mang JSON với trường được đặt tên trong autopayload. Một payload là con số thuần sẽ không phân tích được. Hãy hoặc phát JSON, hoặc tự đẩy giá trị bằng một thông điệp control env (mục 11A).

Home Assistant không hiển thị thiết bị. haenable phải được bật (theo mặc định là vậy), tích hợp MQTT của HA phải được cài đặt với tính năng phát hiện được bật, và thiết bị phải ở trên cùng broker với HA. Hãy xác nhận các thông điệp phát hiện đang đến bằng cách đăng ký nhận <MAC>/# (địa chỉ MAC của mô-đun). Nếu bạn không muốn dùng MQTT chút nào, hãy dùng tích hợp Daikin gốc với IP của Faikout.

Trạng thái trông cũ. Các thông điệp state/ được giữ lại, vì vậy một client có thể hiển thị giá trị cuối cùng sau khi khởi động lại. Nếu bạn thấy dữ liệu thực sự cũ, hãy xóa thông điệp được giữ lại trên topic đó, và bật livestatus để cập nhật tức thì khi có thay đổi.

Một số điều khiển không có tác dụng gì. S21 được dịch ngược và khác nhau tùy model; powerful, econo, demand và những thứ tương tự có thể không tồn tại trên thiết bị của bạn và đơn giản sẽ bị bỏ qua. JSON trạng thái cho biết những điều khiển nào mà thiết bị của bạn thực sự cung cấp.

14. Bảng tra cứu nhanh

Thay GuestAC bằng tên máy chủ của bạn và 192.168.1.10 bằng broker của bạn.

Đọc (đăng ký)

Lệnh (phát tới command/GuestAC/...)

Payload control

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

Cài đặt (phát tới setting/GuestAC...)

Cảm biến bên ngoài, giữ bật/tắt thủ công

Nguồn: phần mềm và tài liệu RevK ESP32-Faikout (README, Setup, Controls, Advanced) và ESP/main/settings.def trên Codeberg (codeberg.org/RevK/ESP32-Faikout). Hành vi được mô tả khớp với phần mềm tính đến tháng 6 năm 2026; bản kết xuất cài đặt của chính thiết bị là tài liệu chính thức cho phiên bản bạn đã cài đặt.