MQTT 客户端组件

MQTT 客户端组件设置与你的代理服务器的 MQTT 连接。如果你要连接到 Home Assistant，你可能会更倾向于使用原生 API，在这种情况下则不需要此组件。

MQTT 在 ESP32、ESP8266、BK72xx、LN882H 和 RTL87xx 平台上受支持。

WARNING

如果你启用了 MQTT，但不使用 Api，则必须移除 api: 配置或设置 reboot_timeout: 0s，否则 ESP 将每 15 分钟重启一次，因为没有客户端连接到原生 API。

# 示例配置条目
mqtt:
  broker: 10.0.0.2
  username: livingroom
  password: !secret mqtt_password

NOTE

对 esp-idf 的支持仍是实验性的。如果你在使用 ESP-IDF 框架时遇到 MQTT 问题，请报告。

配置变量

broker (必选, string): 你的 MQTT 代理服务器的主机名。
enable_on_boot (可选, boolean): 启用后，MQTT 将在启动时启用。默认为 true。
port (可选, int): 要连接的端口。默认为 1883。
username (可选, string): 用于身份验证的用户名。空（默认值）表示不进行身份验证。
password (可选, string): 用于身份验证的密码。空（默认值）表示不进行身份验证。
clean_session (可选, boolean): 代理服务器在断开连接后是否清除 MQTT 会话。默认为 false。
client_id (可选, string): 打开连接时使用的客户端 ID。参见默认值了解更多信息。
discover_ip (可选, boolean): 是否启用 Home Assistant 自动设备发现。默认为 true。
discovery (可选, boolean): 是否启用 Home Assistant 自动实体发现。默认为 true。
discovery_retain (可选, boolean): 是否保留 MQTT 发现消息，以便在 Home Assistant 重启时自动添加实体。默认为 true。
discovery_prefix (可选, string): 用于 Home Assistant 的 MQTT 发现的前缀。不应包含尾随斜杠。默认为 homeassistant。
discovery_unique_id_generator (可选, string): 要使用的 unique_id 生成器。可以是 legacy 或 mac 之一。默认为 legacy，它生成格式为 ESP<组件类型><默认对象ID> 的 unique_id。 mac 生成器使用格式 <mac地址>-<组件类型>-<fnv1_hash(友好名称)>。
discovery_object_id_generator (可选, string): 要使用的 object_id 生成器。可以是 none 或 device_name 之一。默认为 none，即不生成 object_id。device_name 生成器使用格式 <设备名称>_<友好名称>。
use_abbreviations (可选, boolean): 是否在发现消息中使用缩写。默认为 true。
topic_prefix (可选, string): 用于所有 MQTT 消息的前缀。不应包含尾随斜杠。默认为 <APP_NAME>。使用 null 可禁用任何 MQTT 主题的发布或订阅，除非显式配置。
log_topic (可选, MQTTMessage): 发送 MQTT 日志消息的主题。如果你想禁用向 MQTT 发送日志，请使用 null。

log_topic 有一个额外的配置选项：
- level (可选, string): 用于 MQTT 日志的日志级别。参见日志级别了解选项。
birth_message (可选, MQTTMessage): 与代理服务器建立连接时发送的消息。参见遗嘱与上线消息了解更多信息。
will_message (可选, MQTTMessage): MQTT 连接断开时发送的消息。参见遗嘱与上线消息了解更多信息。
shutdown_message (可选, MQTTMessage): 节点关闭且连接被干净关闭时发送的消息。参见遗嘱与上线消息了解更多信息。
certificate_authority (可选, string): 仅在 ESP32 上。PEM 格式的 CA 证书。参见 TLS (ESP32) 了解更多信息。

TIP

有关包括 TLS 配置在内的 MQTT 安全建议，参见安全最佳实践指南。

client_certificate (可选, string): 仅在 esp32 上。PEM 格式的客户端证书。
client_certificate_key (可选, string): 仅在 esp32 上。PEM 格式的客户端私钥。
skip_cert_cn_check (可选, bool): 仅在 ESP32 上。不验证服务器证书中的通用名称是否与 broker 的值匹配。
idf_send_async (可选, bool): 仅在 ESP32 上。如果为 true，则在单独的 mqtt 任务中发布消息。客户端只将消息加入队列。默认为 false。异步发布的优点是它不会阻塞 esphome 主线程可能长达数十秒。缺点是为线程带来额外的内存占用。如果你需要确保 mqtt 不会阻塞主线程，尤其是在网络状况不佳的情况下，请将此选项设为 true。
reboot_timeout (可选, Time): 当不存在 MQTT 连接时重启前等待的时间。可通过将此值设为 0s 来禁用。默认为 15min。
keepalive (可选, Time): 保持 MQTT 套接字存活的时间；减小此值可以通过更多的 ping 增加 Wi-Fi 流量，因此可能有助于提高整体稳定性。默认为 15 秒。
on_connect (可选, Automation): 与代理服务器建立连接时执行的操作。
on_disconnect (可选, Automation): 与代理服务器的连接断开时执行的操作。
on_message (可选, Automation): 在特定 MQTT 主题上收到消息时执行的操作。参见 on_message 触发器。
on_json_message (可选, Automation): 在特定 MQTT 主题上收到 JSON 消息时执行的操作。参见 on_json_message 触发器。
id (可选, ID): 手动指定用于代码生成的 ID。
publish_nan_as_none (可选, bool): 发布 None 而不是 NaN 来处理 Home Assistant 中的 Unknown/Unavailable 传感器状态。默认为 false。
wait_for_connection (可选, bool): 阻塞其他组件启动，直到 MQTT 连接建立。默认为 false。

MQTTMessage

借助 MQTT 消息架构，你可以告诉 ESPHome 应如何发送特定的 MQTT 消息。它用于多种场合，如遗嘱与上线消息或 MQTT 日志选项。

# 简单：
some_option: topic/to/send/to

# 禁用：
some_option:

# 高级：
some_option:
  topic: topic/to/send/to
  payload: online
  qos: 0
  retain: true

配置选项：

topic (必选, string): 发布消息的 MQTT 主题。
payload (必选, string): 消息内容。某些选项（如 log_topic）会将其替换为实际的有效负载。
qos (可选, int): 主题的服务质量级别。默认为 0。
retain (可选, boolean): 发布的消息是否应带上 retain（保留）标志。默认为 true。

MQTT 设备发现

如果启用了 mqtt.discover_ip，ESPHome 设备将响应以下 MQTT 主题。

esphome/discover（所有 ESPHome 设备都会应答）
esphome/ping/<APP_NAME>

响应将被发送到 esphome/discover/<APP_NAME>，是一条 JSON 编码的消息。

MQTT 设备发现目前用于：

ESPHome 仪表盘（在线/离线状态）
ESPHome CLI（IP 发现；用于查看日志和执行 OTA 上传）
Home Assistant 设备发现

示例有效负载：

{
  "ip": "192.168.0.122",
  "name": "esp32-test",
  "friendly_name": "Test Device",
  "port": 6053,
  "version": "2024.4.1",
  "mac": "84fce6123456",
  "platform": "ESP32",
  "board": "esp32-c3-devkitm-1",
  "network": "wifi",
  "api_encryption": "Noise_NNpsk0_25519_ChaChaPoly_SHA256"
}

JSON 键：

ip (必选, ip): ESPHome 设备的 IP 地址。
name (必选, string): 设备的名称（esphome.name）。
mac (必选, string): 设备的 MAC 地址。
board (必选, string): 设备使用的开发板。
version (必选, string): ESPHome 版本。
port (可选, port): ESPHome API 的端口（如果启用）。
ipX (可选, ip): 其他 IP 地址（X 是从 1 开始的数字）。
friendly_name (可选, string): 设备的友好名称（esphome.friendly_name）。
platform (可选, string): 设备的平台（例如 ESP32 或 ESP8266）。
network (可选, string): 网络类型。
project_name (可选, string): esphome.project.name。
project_version (可选, string): esphome.project.version。
project_version (可选, string): dashboard_import.package_import_url。
api_encryption (可选, string): API 加密类型。

使用设备发现与 Home Assistant

MQTT 可用于在 Home Assistant 中自动发现 ESPHome 设备。这允许 Home Assistant 找到 ESPHome 设备并通过 ESPHome API 连接到它，从而可以使用比单独的 MQTT 实体发现更多的功能（例如蓝牙代理、语音助手）。

这可以通过在启用 mqtt.discover_ip 的同时启用 api 和 mqtt 来实现。禁用 mqtt.discovery 可能是有意义的，因为如果 Home Assistant 将连接到 ESPHome API，就不再需要使用 MQTT 实体发现。

示例配置：

api:
  encryption:
    key: "<secret>"

mqtt:
  broker: 10.0.0.2
  username: livingroom
  password: !secret mqtt_password
  discovery: False # 禁用实体发现
  discover_ip: True # 启用设备发现

与 Home Assistant MQTT 实体一起使用

将 ESPHome 与 Home Assistant 一起使用很容易，只需设置一个 MQTT 代理服务器（如 mosquitto），并将你的 Home Assistant 安装和 ESPHome 都指向该代理服务器。接下来，通过以下配置在 Home Assistant 中启用发现：

# 示例 Home Assistant configuration.yaml 条目
mqtt:
  broker: ...

这样就大功告成了 🎉 通过 ESPHome 定义的所有设备都应自动出现在 Home Assistant 的实体部分中。

当添加新实体时，你可能会遇到旧实体仍然出现在 Home Assistant 前端的问题。这是因为为了让 Home Assistant 在重启时”发现”你的设备，所有发现 MQTT 消息都必须被保留（retain）。因此，即使这些旧实体已不在 ESPHome 中，它们也会在每次 Home Assistant 重启时重新出现。

要解决此问题，ESPHome 提供了一个简单的辅助脚本来为你清除过期的保留消息：

esphome clean-mqtt configuration.yaml

使用 Docker：

docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome clean-mqtt configuration.yaml

这将删除主题为 <DISCOVERY_PREFIX>/+/NODE_NAME/# 的所有保留消息。如果你想清除另一个主题，只需在命令中添加 --topic <your_topic>。

Home Assistant 根据实体类型和实体名称为所有发现的设备生成实体名称（例如 sensor.uptime）。当多个设备为传感器使用相同名称时，实体名称会被附加数字后缀，这使得区分不同设备上类似的传感器变得更加困难。 Home Assistant 2021.12 允许 MQTT 设备通过指定 object_id 发现属性来改变此行为，该属性会替换生成的实体名称中的传感器名称部分。在 ESPHome MQTT 组件配置中设置 discovery_object_id_generator: device_name 将使 Home Assistant 在生成的实体名称中包含设备名称（例如 sensor.uptime 变为 sensor.<设备名称>_uptime），从而更容易在各种实体列表中区分实体。

默认值

默认情况下，ESPHome 会将所有消息加上你的节点名称或 topic_prefix（如果你手动指定了）作为前缀。客户端 ID 将通过使用你的节点名称并附加设备的 MAC 地址来自动生成。接下来，默认启用发现，并使用 Home Assistant 的默认前缀 homeassistant。

如果你想为所有 MQTT 消息使用不同的前缀，如 home/living_room，你可以在配置中指定自定义的 topic_prefix。这样，你就可以将现有的通配符如 home/+/# 与 ESPHome 一起使用。ESPHome 的所有其他功能（如可用性）仍应正常工作。

遗嘱与上线消息

ESPHome 使用 MQTT 的遗嘱(last will and testament) 和上线（birth）消息功能来实现 Home Assistant 的可用性报告。如果节点未连接到 MQTT，Home Assistant 将显示其所有实体为不可用（这是个很有用的功能 😉）。

默认情况下，ESPHome 会向 <TOPIC_PREFIX>/status 发送一条保留的 MQTT 消息，有效负载为 online，并会告诉代理服务器在连接断开时发送一条 <TOPIC_PREFIX>/status 有效负载为 offline 的消息。

你可以通过以下选项覆盖 birth_message 和 will_message 来更改这些消息。

mqtt:
  # ...
  birth_message:
    topic: myavailability/topic
    payload: online
  will_message:
    topic: myavailability/topic
    payload: offline

birth_message (可选, MQTTMessage)
will_message (可选, MQTTMessage)

如果上线消息和遗嘱消息的主题为空或彼此不同，可用性报告将被禁用。

TLS (ESP32)

在 ESP32 上，可以建立到 MQTT 代理服务器的 TLS 连接。需要服务器的 CA 证书来验证连接。

你必须下载 PEM 格式的服务器 CA 证书并将其添加到 certificate_authority。通常这些是 .crt 文件，你可以用任何文本编辑器打开它们。同时确保更改 MQTT 代理服务器的 port。大多数代理服务器使用端口 8883 进行 TLS 连接。

WARNING

MbedTLS，即 esp-idf 处理 TLS 的库，不验证通配符证书。

通用名称（CN）检查仅在证书中明确报告 CN 时有效。

*.example.com -> 失败
mqtt.example.com -> 成功

如果你的设备需要安全连接，你确实需要设置：

skip_cert_cn_check: false

mqtt:
  broker: test.mymqtt.local
  port: 8883
  discovery_prefix: ${mqtt_prefix}/homeassistant
  log_topic: ${mqtt_prefix}/logs
  # 仔细评估 skip_cert_cn_check
  skip_cert_cn_check: true
  idf_send_async: false
  certificate_authority: |
    -----BEGIN CERTIFICATE-----
    MIIEAzCCAuugAwIBAgIUBY1hlCGvdj4NhBXkZ/uLUZNILAwwDQYJKoZIhvcNAQEL
    BQAwgZAxCzAJBgNVBAYTAkdCMRcwFQYDVQQIDA5Vbml0ZWQgS2luZ2RvbTEOMAwG
    A1UEBwwFRGVyYnkxEjAQBgNVBAoMCU1vc3F1aXR0bzELMAkGA1UECwwCQ0ExFjAU
    BgNVBAMMDW1vc3F1aXR0by5vcmcxHzAdBgkqhkiG9w0BCQEWEHJvZ2VyQGF0Y2hv
    by5vcmcwHhcNMjAwNjA5MTEwNjM5WhcNMzAwNjA3MTEwNjM5WjCBkDELMAkGA1UE
    BhMCR0IxFzAVBgNVBAgMDlVuaXRlZCBLaW5nZG9tMQ4wDAYDVQQHDAVEZXJieTES
    MBAGA1UECgwJTW9zcXVpdHRvMQswCQYDVQQLDAJDQTEWMBQGA1UEAwwNbW9zcXVp
    dHRvLm9yZzEfMB0GCSqGSIb3DQEJARYQcm9nZXJAYXRjaG9vLm9yZzCCASIwDQYJ
    KoZIhvcNAQEBBQADggEPADCCAQoCggEBAME0HKmIzfTOwkKLT3THHe+ObdizamPg
    UZmD64Tf3zJdNeYGYn4CEXbyP6fy3tWc8S2boW6dzrH8SdFf9uo320GJA9B7U1FW
    Te3xda/Lm3JFfaHjkWw7jBwcauQZjpGINHapHRlpiCZsquAthOgxW9SgDgYlGzEA
    s06pkEFiMw+qDfLo/sxFKB6vQlFekMeCymjLCbNwPJyqyhFmPWwio/PDMruBTzPH
    3cioBnrJWKXc3OjXdLGFJOfj7pP0j/dr2LH72eSvv3PQQFl90CZPFhrCUcRHSSxo
    E6yjGOdnz7f6PveLIB574kQORwt8ePn0yidrTC1ictikED3nHYhMUOUCAwEAAaNT
    MFEwHQYDVR0OBBYEFPVV6xBUFPiGKDyo5V3+Hbh4N9YSMB8GA1UdIwQYMBaAFPVV
    6xBUFPiGKDyo5V3+Hbh4N9YSMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQEL
    BQADggEBAGa9kS21N70ThM6/Hj9D7mbVxKLBjVWe2TPsGfbl3rEDfZ+OKRZ2j6AC
    6r7jb4TZO3dzF2p6dgbrlU71Y/4K0TdzIjRj3cQ3KSm41JvUQ0hZ/c04iGDg/xWf
    +pp58nfPAYwuerruPNWmlStWAXf0UTqRtg4hQDWBuUFDJTuWuuBvEXudz74eh/wK
    sMwfu1HFvjy5Z0iMDU8PUDepjVolOCue9ashlS4EB5IECdSR2TItnAIiIwimx839
    LdUdRudafMu5T5Xma182OC0/u/xRlEm+tvKGGmfFcN0piqVl8OrSPBgIlb+1IKJE
    m/XriWr/Cq4h/JfB7NTsezVslgkBaoU=
    -----END CERTIFICATE-----

MQTT 组件基础配置

ESPHome 中所有通过 MQTT 进行某种通信的组件都可以对特定选项进行一些覆盖。

name: "Component Name"
# 可选变量：
qos: 1
retain: true
availability:
  topic: livingroom/status
  payload_available: online
  payload_not_available: offline
state_topic: livingroom/custom_state_topic
command_topic: livingroom/custom_command_topic
command_retain: false

配置变量

name (必选, string): 用于 MQTT 组件的名称。
qos (可选, int): 发布时的服务质量级别。默认为 0。
retain (可选, boolean): 是否应保留所有 MQTT 状态消息。默认为 true。
discovery (可选, boolean): 手动启用/禁用某个组件的发现。默认为全局默认值。
subscribe_qos (可选, int): 在发现中通告的用于订阅的服务质量级别（仅当启用发现时）。默认为 0。
availability (可选): 手动设置应向 Home Assistant 发送什么来显示实体可用性。默认派生自全局上线/遗嘱消息。
state_topic (可选, string, 可模板化): 发布状态更新的主题。默认为 <TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/state。

即使组件是内部的，ESPHome 也始终会发布手动配置的状态主题。使用 null（或在 lambda 中返回 ""）可禁用发布组件的状态。
command_topic (可选, string, 可模板化): 用于订阅来自远端的命令的主题。默认为 <TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/command。

即使组件是内部的，ESPHome 也始终会订阅手动配置的命令主题。使用 null（或在 lambda 中返回 ""）可禁用订阅组件的命令主题。
command_retain (可选, boolean): 发送到设备的 MQTT 命令消息是否应被保留。默认为 false。

WARNING

更改这些选项并且你正在使用 MQTT 发现时，需要重启 Home Assistant。这是因为 Home Assistant 在每次启动时只发现一次设备。

触发器

`on_connect` 触发器

当与 MQTT 代理服务器建立连接时，将激活此触发器。要检索会话是否存在，请使用 lambda 模板，它在该 lambda 中以 session_present 名称可用。 session_present 指示代理服务器是否有来自先前连接的此客户端的持久会话。当为 true 时，代理服务器保留了订阅并缓存了消息。当为 false 时，会话是新的。

mqtt:
  # ...
  on_connect:
    - switch.turn_on: switch1
    - lambda: |-
        ESP_LOGI("mqtt", "Session present: %s", session_present ? "true" : "false");
        if (!session_present) {
          // 如果会话不存在则执行某些操作
        }

`on_disconnect` 触发器

当与 MQTT 代理服务器的连接断开时，将激活此触发器。要检索断开原因，请使用 lambda 模板，该原因在该 lambda 中以 reason 名称可用。

mqtt:
  # ...
  on_disconnect:
    - switch.turn_off: switch1
    - lambda: |-
        // reason 为 MQTTClientDisconnectReason 类型
        // 可能的值：
        //   TCP_DISCONNECTED (0)
        //   MQTT_UNACCEPTABLE_PROTOCOL_VERSION (1)
        //   MQTT_IDENTIFIER_REJECTED (2)
        //   MQTT_SERVER_UNAVAILABLE (3)
        //   MQTT_MALFORMED_CREDENTIALS (4)
        //   MQTT_NOT_AUTHORIZED (5)
        //   ESP8266_NOT_ENOUGH_SPACE (6)
        //   TLS_BAD_FINGERPRINT (7)
        //   DNS_RESOLVE_ERROR (8)
        if (reason == mqtt::MQTTClientDisconnectReason::MQTT_NOT_AUTHORIZED) {
          ESP_LOGE("mqtt", "Not authorized!");
        }

`on_message` 触发器

借助此配置选项，你可以在特定主题上收到 MQTT 消息时编写复杂的自动化。要使用消息内容，请使用 lambda 模板，该消息的有效负载在该 lambda 中以 x 名称可用。

mqtt:
  # ...
  on_message:
    topic: my/custom/topic
    qos: 0
    then:
      - switch.turn_on: some_switch

配置变量

topic (必选, string): 要订阅并监听 MQTT 消息的 MQTT 主题。每次收到与此完全相同的主题的消息时，自动化都会触发。
qos (可选, int): 订阅该主题使用的 MQTT 服务质量。默认为 0。
payload (可选, string): 可选地设置要匹配的有效负载。只有当收到与你通过此选项指定的有效负载完全匹配的消息时，自动化才会执行。

NOTE

你甚至可以通过使用 YAML 列表来指定多个 on_message 触发器：

mqtt:
  on_message:
     - topic: some/topic
       then:
         - # ...
     - topic: some/other/topic
       then:
         - # ...

NOTE

此操作也可以在 lambdas 中使用：

mqtt:
  # 为 MQTT 组件指定一个 ID
  id: mqtt_client

id(mqtt_client).subscribe("the/topic", [=](const std::string &topic, const std::string &payload) {
    // 对有效负载执行某些操作
});

`on_json_message` 触发器

借助此配置选项，你可以在收到 JSON 编码的 MQTT 消息时编写复杂的自动化。要使用消息内容，请使用 lambda 模板，解码后的消息有效负载在该 lambda 中以 x 名称可用。

x 对象是 ArduinoJson 库中的 JsonObject 类型，你可以使用该库的所有方法来访问数据。

基本来说，你可以通过输入 x["THE_KEY"] 来访问元素并将其保存到局部变量中。请注意，最好先通过调用 containsKey 来检查键是否存在于 JSON 对象中，因为如果访问不存在的元素，ESP 会崩溃。

mqtt:
  # ...
  on_json_message:
    topic: the/topic
    then:
      - light.turn_on:
          id: living_room_lights

          transition_length: !lambda |-
            int length = 1000;
            if (x.containsKey("length"))
              length = x["length"];
            return length;

          brightness: !lambda "return x["bright"];"

          effect: !lambda |-
            const char *effect = "None";
            if (x.containsKey("effect"))
              effect = x["effect"];
            return effect;

配置变量

topic (必选, string): 要订阅并监听 MQTT 消息的 MQTT 主题。每次收到与此完全相同的主题的消息时，自动化都会触发。
qos (可选, int): 订阅该主题使用的 MQTT 服务质量。默认为 0。

NOTE

由于此触发器的内部工作方式，它与某些操作不兼容，并且会触发编译失败。例如与 delay 操作。

NOTE

此操作也可以在 lambdas 中使用：

mqtt:
  # 为 MQTT 组件指定一个 ID
  id: mqtt_client

id(mqtt_client).subscribe_json("the/topic", [=](const std::string &topic, JsonObject root) {
    // 对 JSON 解码值 root 执行某些操作
});

操作

`mqtt.publish` 操作

使用此操作在自动化中向某个主题发布 MQTT 消息。

on_...:
  then:
    - mqtt.publish:
        topic: some/topic
        payload: "Something happened!"

    # 模板化：
    - mqtt.publish:
        topic: !lambda |-
          if (id(reed_switch).state) return "topic1";
          else return "topic2";
        payload: !lambda |-
          return id(reed_switch).state ? "YES" : "NO";

配置变量

topic (必选, string, 可模板化): 发布消息的 MQTT 主题。
payload (必选, string, 可模板化): 消息内容。
qos (可选, int, 可模板化): 主题的服务质量级别。默认为 0。
retain (可选, boolean, 可模板化): 发布的消息是否应带上 retain（保留）标志。默认为 false。

NOTE

此操作也可以在 lambdas 中编写：

mqtt:
  # 为 MQTT 组件指定一个 ID
  id: mqtt_client

id(mqtt_client).publish("the/topic", "The Payload");

`mqtt.publish_json` 操作

使用此操作在自动化中向某个主题发布 JSON 格式的 MQTT 消息。

JSON 消息将使用 ArduinoJson 库构建。在 payload 选项中，你可以访问一个 root 对象，它代表 JSON 消息的基对象。你可以使用 root["KEY_NAME"] = VALUE; 语法为键赋值，如下所示。

on_...:
  then:
    - mqtt.publish_json:
        topic: the/topic
        payload: |-
          root["key"] = id(my_sensor).state;
          root["greeting"] = "Hello World";

        # 将产生：
        # {"key": 42.0, "greeting": "Hello World"}

配置变量

topic (必选, string, 可模板化): 发布消息的 MQTT 主题。
payload (必选, lambda): 消息内容。
qos (可选, int, 可模板化): 主题的服务质量级别。默认为 0。
retain (可选, boolean, 可模板化): 发布的消息是否应带上 retain（保留）标志。默认为 false。

NOTE

此操作也可以在 lambdas 中编写：

mqtt:
  # 为 MQTT 组件指定一个 ID
  id: mqtt_client

id(mqtt_client).publish_json("the/topic", [=](JsonObject root) {
  root["something"] = id(my_sensor).state;
});

`mqtt.disable` 操作

此操作按需关闭 MQTT 组件。

on_...:
  then:
    - mqtt.disable:

NOTE

如果你不希望 MQTT 在启动时启用，可以将配置选项 enable_on_boot 设为 false。

`mqtt.enable` 操作

此操作按需打开 MQTT 组件。

on_...:
  then:
    - mqtt.enable:

NOTE

如果你不希望 MQTT 在启动时启用，可以将配置选项 enable_on_boot 设为 false。 mqtt.enable 可用于自定义设置。例如，如果代理服务器的名称是动态协商的，并且保存在一个全局变量中。

mqtt:
  id: mqtt_id
  broker: ""
  enable_on_boot: False

globals:
  - id: broker_address
    type: std::string
    restore_value: yes
    max_restore_data_length: 24
    initial_value: '"192.168.1.2"'

on_...:
  then:
    - lambda: !lambda id(mqtt_id).set_broker_address(id(broker_address));
    - mqtt.enable:

条件

`mqtt.connected` 条件

此条件检查 MQTT 客户端当前是否已连接到 MQTT 代理服务器。

on_...:
  if:
    condition:
      mqtt.connected:
    then:
      - logger.log: MQTT is connected!

NOTE

此操作也可以在 lambdas 中编写：

mqtt:
  # 为 MQTT 组件指定一个 ID
  id: mqtt_client

if (id(mqtt_client)->is_connected()) {
  // 如果 MQTT 已连接则执行某些操作
}

另请参阅

API 参考：mqtt_client.h

MQTT 客户端组件

配置变量

MQTTMessage

MQTT 设备发现

使用设备发现与 Home Assistant

与 Home Assistant MQTT 实体一起使用

默认值

遗嘱与上线消息

TLS (ESP32)

MQTT 组件基础配置

配置变量

触发器

on_connect 触发器

on_disconnect 触发器

on_message 触发器

配置变量

on_json_message 触发器

配置变量

操作

mqtt.publish 操作

配置变量

mqtt.publish_json 操作

配置变量

mqtt.disable 操作

mqtt.enable 操作

条件

mqtt.connected 条件

另请参阅

`on_connect` 触发器

`on_disconnect` 触发器

`on_message` 触发器

`on_json_message` 触发器

`mqtt.publish` 操作

`mqtt.publish_json` 操作

`mqtt.disable` 操作

`mqtt.enable` 操作

`mqtt.connected` 条件