MQTT 手册

这是一份完整指南，介绍如何通过 MQTT 控制和监控 Faikin Faikout，从初次设置到完整的主题、命令与设置参考。

本文适用于运行 RevK 固件的 WiFi Faikout 模块（设备品牌为 Faikout；您可能仍会看到旧名称 Faikin）。它同样适用于 S21、X50A 和 CN_WIRED 机型，因为固件会自动识别协议。本文通篇以示例主机名 GuestAC 和示例代理 IP 192.168.1.10 为例。请将两者替换为您自己的设置。

1. MQTT 能为您带来什么

一切都在本地完成。Faikout 在您自己的网络上使用 MQTT，无需云端账户，也不依赖互联网。通过 MQTT，您可以：

• 控制机组：电源、模式、设定温度、风速、导风板摆动、强力/节能。
• 读取红外遥控器隐藏的实时遥测数据：房间、盘管/冷媒、回风口和室外温度，以及型号和运行状态。
• 驱动 Faikout Auto 层：目标温度带、定时计划，以及外部温度参考。
• 与 Home Assistant（原生自动发现）、openHAB、Node-RED、Domoticz、ioBroker 以及任何支持 MQTT 的系统集成。

MQTT 控制与内置网页界面和红外遥控器并行运行。来自任一来源的更改都会在几秒钟内同步显示到各处。

2. 开始之前

您需要：

• 一台已安装并连接到您 2.4GHz WiFi 的 Faikout（参见设置手册）。您可以在浏览器中通过 GuestAC.local 访问它。
• 同一网络上的一个 MQTT 代理。常见选择是 Home Assistant 内的 Mosquitto 加载项，或在树莓派、NAS 或服务器上独立运行的 Mosquitto。
• 代理的 IP 地址或主机名，以及在代理要求身份验证时的 用户名和密码（Home Assistant 的代理通常需要）。

请将代理保留在您可控的网络中。Faikout 的 MQTT 是普通的本地流量，不应暴露到互联网。

3. 步骤 1：将 Faikout 指向您的 MQTT 代理

1. 访问 GuestAC.local 并打开 WiFi 设置（或长按设备的设置按钮，然后在它尚未接入您的 WiFi 时连接到它的 Daikin/Faikout 接入点）。
2. 在 MQTT 区域中，输入 主机（代理 IP 或主机名，例如 192.168.1.10），如果您的代理使用，还需输入 用户名 和 密码。
3. 确保 主机名 设置为一个便于记忆的名称，例如 GuestAC。该名称会成为每个 MQTT 主题的一部分，因此请在构建自动化之前先确定它。
4. 保存。Faikout 会重新连接并开始发布。

底层的连接设置是 mqtthost（RevK 库标准）。用户名和密码在同一页面输入。连接成功后，您也可以稍后通过 MQTT 本身更改这些设置（参见设置参考）。

4. 步骤 2：确认已连接

这一步不需要终端。有两个地方可以立即看到结果。

在 Faikout 自己的网页上

打开 GuestAC.local。在页面顶部、设备名称旁边，Faikout 会显示 broker 连接状态。显示 MQTT connected 即表示模块已连接到您的 broker 并正在发布数据。

该标识位于页面顶部设备名称旁边。MQTT 的主机、用户名和密码在同一页面的下方。

如果没有该标识，说明主机、用户名或密码有误，或者模块所在网络无法访问 broker。请重新检查设置页面上的 MQTT 部分，然后参见故障排除。

在 Home Assistant 中

无需手动添加任何内容。Faikout 会发布 Home Assistant 的 MQTT 自动发现消息，因此只要连接上 broker，Home Assistant 就会自动发现它。只要 MQTT 集成已设置好并指向同一个 broker：

1. 进入 Settings > Devices & services > MQTT，然后打开设备列表。
2. GuestAC 会在几秒内出现，制造商显示为 RevK，并带有固件版本。
3. 打开后整台设备已经就绪：一个 climate 实体（MQTT HVAC），显示当前温度和目标温度；Controls 下是模式与功能开关（Auto、Comfort、Econo、Power、Powerful、Quiet outdoor、Sensor、Streamer、Restart）；Sensors 下是室内温度与目标温度、压缩机与风扇转速、湿度、盘管温度与室外温度、功率消耗以及累计能耗。

Home Assistant 中的 Faikout 设备页面。这里没有任何内容是手动添加的：climate 实体、控件和传感器全部来自 MQTT 自动发现。

如果没有出现，请确认 Home Assistant 与模块使用的是同一个 broker，然后参见故障排除。对于 Faikout，您完全不需要手写 YAML 的 climate 实体：如果需要这样做，说明前面某个环节出了问题。

如果您想从终端检查

可选步骤，只有在您已安装 mosquitto 客户端工具时才值得一试：

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

您应当看到一条保留的 state/GuestAC 消息。当空调正在与模块通信时，其负载会报告 online 为 true。裸 state/GuestAC 主题是设备自身的在线状态：负载为 false 表示 Faikout 本身离线（这是它的 MQTT 遗嘱/上线消息）。

如果什么都没收到，请跳转到故障排除。

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/... 大约每分钟发布一次，供 faikoutlog 工具用于将数据存入 MySQL/MariaDB 数据库以便绘图。
• <MAC>/... 是 Home Assistant 自动发现源，在启用 HA 支持时发布（参见第 9 节）。

state JSON 包含上面 control 表中的所有内容（因此您可以读回 power、mode、temp、fan 等），外加以下只读字段：

数据库记录格式：在 Faikout/ 源中，每个值都会在该周期内汇总。如果未发生变化，则报告为单个值；如果发生了变化，数值会变为 [min, average, max] 数组，布尔值会变为表示该周期内为 true 的占比的分数 0.0–1.0。打开 fixstatus 可始终使用数组/分数格式，无论是否变化。

9. 通过 MQTT 接入 Home Assistant

Faikout 具备原生的 Home Assistant 自动发现，并且默认开启（设置 haenable，默认开）。一旦模块与 Home Assistant 使用同一个代理通信，气候实体便会自动出现。

设置：

1. 运行一个供 Home Assistant 使用的 MQTT 代理。最简单的是 Home Assistant OS 中的 Mosquitto broker 加载项，并添加 MQTT 集成。
2. 在 Home Assistant 中为该设备创建一个 MQTT 用户（普通 HA 用户即可配合 Mosquitto 加载项使用）。
3. 在 Faikout 设置页面上，将 MQTT 主机 设为 Home Assistant 的 IP，并输入相应的 用户名和密码。
4. 一分钟内 Home Assistant 会发现该设备（发布于 <MAC>/... 主题下）并添加一张气候卡片。无需 YAML。

实用的 HA 相关设置（通过 MQTT 或高级网页设置）：

仪表板和实体卡片 YAML

您无需 YAML 即可创建这些实体。自动发现会自行生成一个 climate 实体以及温度传感器。下面的 YAML 用于将它们布局到 Lovelace 仪表板上。

实体 ID 由主机名衍生而来，因此名为 GuestAC 的设备会得到 climate.guestac 以及诸如 sensor.guestac_temperature 的传感器。具体的标识符会随固件版本和您的 HA 命名设置而变化，因此请在 设置 → 设备与服务 → MQTT →（您的设备） 或 开发者工具 → 状态 中确认，并将下面的 ID 调整为相符。

实体卡片。通过 添加卡片 → 手动 向任意仪表板添加一张卡片并粘贴：

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

完整仪表板视图。打开一个仪表板，编辑 →（三个点）→ 原始配置编辑器，并将其作为新视图添加到 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 最省事的途径。当您需要 Daikin 集成未开放的功能，或要与 HA 以外的系统集成时，再使用 MQTT 路径。

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 binding。为代理创建一个 MQTT Thing，然后创建诸如以下的通道：

• 一个 Switch 通道，commandTopic = command/GuestAC/control，将值格式化为 {"power":%s}；
• 一个 Number 通道，stateTopic = state/GuestAC，并使用诸如 $.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）。如果超时，机组会退出远程/自动模式。
• target 作为 [min,max] 数组（或带 margin 的单个数字）会强制进入 Faikout Auto 模式并定义舒适温度带。

B. 让 Faikout 订阅一个传感器主题

除了推送之外，也可以让 Faikout 跟随一个现有的 MQTT 主题：

重要：autotopic 上的负载必须是包含所命名字段的 JSON。发布裸数字的主题（例如普通的 ESPHome 状态主题）无法解析；请将其包装为 JSON，或使用方式 A。

C. 跟踪外部传感器但保持手动开/关

一个常见需求：依据准确的外部读数进行控制，但绝不让机组自行开机或关机。难点在于，发送 env 会使机组变为 "远程"，而处于远程时，如果 autoptemp 不为零（默认 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 名称（高级网页将它们分组，但通过 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）记载于高级手册中，很少需要更改。

能力覆盖

如果固件提供了您机组实际并不具备的某项控制（或反之），no... 设置会告诉它需要隐藏什么：例如 nopowerful、noecono、nostreamer、noswingv、noswingh、noquiet、nodemand、nofaikoutauto。协议强制设置 nos21、nox50a、nocnwired 会在自动检测选错时阻止它尝试某一给定协议。

调试

13. 故障排除

MQTT 上什么都没出现 / 设备显示离线。 检查裸 state/GuestAC 主题：false 表示 Faikout 本身未连接到代理。然后确认设置中的代理 IP/主机名可达、MQTT 用户名和密码正确、代理正在监听（在局域网上通常为 1883 端口），以及模块连接在您的 2.4GHz WiFi 上（它不使用 5GHz）。确认 GuestAC.local 能在浏览器中加载以证明 WiFi 正常，那么问题就出在 MQTT 凭据或代理可达性上。

机组不断自行开机。 在 control 消息中发送 env 会使机组进入远程控制，而处于远程时，如果 autoptemp 不为零（默认 0.5），则会假定启用自动电源。要保持手动开/关，请将 autop 设为关、autoptemp 设为 0，保持 tempadjust 开，并只发送 {"env": ...} 而不带 target 数组。参见第 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，请改用原生 Daikin 集成并填入 Faikout 的 IP。

状态看起来是旧的。 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 月的固件一致；设备自身的设置导出才是您所安装版本的权威依据。