MQTT 客户端组件

MQTT 客户端组件用于设置与您的代理的 MQTT 连接。如果您要连接到 Home Assistant，可能更希望使用原生 API，这种情况下不需要此组件。

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 (Required, string): MQTT 代理的主机地址。
enable_on_boot (Optional, boolean): 如果启用，MQTT 将在启动时启用。默认为 true。
port (Optional, int): 要连接的端口。默认为 1883。
username (Optional, string): 用于认证的用户名。空值（默认）表示不进行认证。
password (Optional, string): 用于认证的密码。空值（默认）表示不进行认证。
clean_session (Optional, boolean): 代理是否在断开连接后清理 MQTT 会话。默认为 false。
client_id (Optional, string): 用于打开连接的客户端 ID。有关更多信息，请参阅默认值。
discover_ip (Optional, boolean): 是否启用 Home Assistant 自动设备发现。默认为 true。
discovery (Optional, boolean): 是否启用 Home Assistant 自动实体发现。默认为 true。
discovery_retain (Optional, boolean): 是否保留 MQTT 发现消息，以便在 Home Assistant 重启时自动添加实体。默认为 true。
discovery_prefix (Optional, string): 用于 Home Assistant MQTT 发现的前缀。不应包含尾部斜杠。默认为 homeassistant。
discovery_unique_id_generator (Optional, string): 要使用的 unique_id 生成器。可以是 legacy 或 mac 之一。默认为 legacy，它以 ESP<component_type><default_object_id> 格式生成 unique_id。 mac 生成器使用格式 <mac_address>-<component_type>-<fnv1_hash(friendly_name)>。
discovery_object_id_generator (Optional, string): 要使用的 object_id 生成器。可以是 none 或 device_name 之一。默认为 none，不生成 object_id。device_name 生成器使用格式 <device_name>_<friendly_name>。
use_abbreviations (Optional, boolean): 是否在发现消息中使用缩写。默认为 true。
topic_prefix (Optional, string): 用于所有 MQTT 消息的前缀。不应包含尾部斜杠。默认为 <APP_NAME>。使用 null 禁用发布或订阅任何 MQTT 主题，除非明确配置。
log_topic (Optional, MQTTMessage): 发送 MQTT 日志消息的主题。如果要禁用向 MQTT 发送日志，请使用 null。

log_topic 有一个额外的配置选项：
- level (Optional, string): MQTT 日志使用的日志级别。请参阅日志级别了解选项。
birth_message (Optional, MQTTMessage): 当与代理建立连接时要发送的消息。有关更多信息，请参阅遗嘱和诞生消息。
will_message (Optional, MQTTMessage): 当 MQTT 连接断开时要发送的消息。有关更多信息，请参阅遗嘱和诞生消息。
shutdown_message (Optional, MQTTMessage): 当节点关闭且连接正常关闭时要发送的消息。有关更多信息，请参阅遗嘱和诞生消息。
ssl_fingerprints (Optional, list): 仅适用于 ESP8266。用于验证 SSL 连接的 SHA1 哈希列表。请参阅 SSL 指纹。了解更多信息。
certificate_authority (Optional, string): 仅适用于 ESP32。PEM 格式的 CA 证书。请参阅 TLS (ESP32) 了解更多信息。

TIP

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

client_certificate (Optional, string): 仅适用于 esp32。PEM 格式的客户端证书。
client_certificate_key (Optional, string): 仅适用于 esp32。PEM 格式的客户端私钥。
skip_cert_cn_check (Optional, bool): 仅适用于 ESP32。不验证服务器证书中的通用名称是否与 broker 的值匹配。
idf_send_async (Optional, bool): 仅适用于 ESP32。如果为 true，消息发布从单独的 mqtt 任务进行。客户端只是将消息排队。默认为 false。异步发布的优点是它不会阻塞 esphome 主线程可能长达数十秒。缺点是线程的额外内存使用。如果您需要确保 mqtt 不阻塞主线程，特别是在网络条件不佳的情况下，请将其设置为 true。
reboot_timeout (Optional, Time): 当没有 MQTT 连接时等待重启的时间。可以通过设置为 0s 来禁用。默认为 15min。
keepalive (Optional, Time): 保持 MQTT 套接字活动的时间，减少此值可以通过更多的 ping 流量帮助提高整体稳定性。默认为 15 秒。
on_connect (Optional, Automation): 当与代理建立连接时要执行的动作。
on_disconnect (Optional, Automation): 当与代理的连接断开时要执行的动作。
on_message (Optional, Automation): 当收到特定 MQTT 主题上的消息时要执行的动作。请参阅 on_message 触发器。
on_json_message (Optional, Automation): 当收到特定 MQTT 主题上的 JSON 消息时要执行的动作。请参阅 on_json_message 触发器。
id (Optional, ID): 手动指定用于代码生成的 ID。
publish_nan_as_none (Optional, bool): 发布 None 而不是 NaN 以处理 Home Assistant 中的未知/不可用传感器状态。默认为 false。
wait_for_connection (Optional, 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 (Required, string): 发布消息的 MQTT 主题。
payload (Required, string): 消息内容。某些选项（如 log_topic）会由实际负载填充。
qos (Optional, int): 主题的服务质量级别。默认为 0。
retain (Optional, boolean): 发布的消息是否应带有保留标志。默认为 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": "测试设备",
  "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 (Required, ip): ESPHome 设备的 IP 地址。
name (Required, string): 设备名称（esphome.name）。
mac (Required, string): 设备的 MAC 地址。
board (Required, string): 设备使用的开发板。
version (Required, string): ESPHome 版本。
port (Optional, port): ESPHome API 端口（如果已启用）。
ipX (Optional, ip): 额外的 IP 地址（X 是从 1 开始的数字）。
friendly_name (Optional, string): 设备的友好名称（esphome.friendly_name）。
platform (Optional, string): 设备平台（例如 ESP32 或 ESP8266）。
network (Optional, string): 网络类型。
project_name (Optional, string): esphome.project.name。
project_version (Optional, string): esphome.project.version。
project_version (Optional, string): dashboard_import.package_import_url。
api_encryption (Optional, string): API 加密类型。

在 Home Assistant 中使用设备发现

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

这可以通过启用 api 和 mqtt 并启用 mqtt.discover_ip 来实现。如果 Home Assistant 将连接到 ESPHome API，禁用 mqtt.discovery 可能是有意义的，因为不再需要使用 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 实体一起使用

在 Home Assistant 中使用 ESPHome 很简单，只需设置一个 MQTT 代理（如 mosquitto），并将您的 Home Assistant 安装和 ESPHome 都指向该代理。接下来，在您的 Home Assistant 配置中启用发现，如下所示：

# 示例 Home Assistant configuration.yaml 配置项
mqtt:
  broker: ...

就是这样 🎉 所有通过 ESPHome 定义的设备应该自动显示在 Home Assistant 的实体部分。

添加新实体时，您可能会遇到旧实体仍然出现在 Home Assistant 前端的问题。这是因为为了让 Home Assistant 在重启时”发现”您的设备，所有发现 MQTT 消息都需要保留。因此，即使 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.<device name>_uptime），从而更容易在各种实体列表中区分实体。

默认值

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

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

遗嘱和诞生消息

ESPHome 使用 MQTT 的遗嘱和诞生消息功能来实现 Home Assistant 的可用性报告。如果节点未连接到 MQTT，Home Assistant 将显示其所有实体为不可用（一个功能 😉）。

默认情况下，ESPHome 将向 <TOPIC_PREFIX>/status 发送负载为 online 的保留 MQTT 消息，并告诉代理在连接断开时发送负载为 offline 的消息到 <TOPIC_PREFIX>/status。

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

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

birth_message (Optional, MQTTMessage)
will_message (Optional, MQTTMessage)

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

SSL 指纹

在 ESP8266 上，您可以选择为 MQTT 使用 SSL 连接。此功能将在基础库 AsyncTCP 支持后扩展到 ESP32。请注意，SSL 功能只检查 SSL 证书的 SHA1 哈希来验证连接的完整性，所以每次证书更改时，您必须更新指纹变量。此外，SHA1 已知部分不安全，使用一些计算能力可以伪造指纹。

要获取此指纹，首先在配置中放入代理和端口选项，然后运行 ESPHome 的 mqtt-fingerprint 脚本获取证书：

esphome mqtt-fingerprint livingroom.yaml
> SHA1 Fingerprint: a502ff13999f8b398ef1834f1123650b3236fc07
> Copy above string into mqtt.ssl_fingerprints section of livingroom.yaml

mqtt:
  # ...
  ssl_fingerprints:
    - a502ff13999f8b398ef1834f1123650b3236fc07

TLS (ESP32)

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

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

WARNING

MbedTLS（为 esp-idf 处理 TLS 的库）不验证通配符证书。

通用名称检查仅在证书中明确报告 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: "组件名称"
# 可选变量：
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 (Required, string): 用于 MQTT 组件的名称。
qos (Optional, int): 发布的服务质量级别。默认为 0。
retain (Optional, boolean): 是否保留所有 MQTT 状态消息。默认为 true。
discovery (Optional, boolean): 手动启用/禁用组件的发现。默认为全局默认值。
subscribe_qos (Optional, int): 在发现中通告的用于订阅的服务质量级别（仅在启用发现时）。默认为 0。
availability (Optional): 手动设置应发送给 Home Assistant 的内容以显示实体可用性。默认值派生自全局诞生/遗嘱消息。
state_topic (Optional, string, templatable): 发布状态更新的主题。默认为 <TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/state。

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

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

WARNING

更改这些选项并且您正在使用 MQTT 发现时，您需要重启 Home Assistant。这是因为 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", "未授权！");
        }

`on_message` 触发器

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

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

配置变量

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

NOTE

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

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

NOTE

此动作也可以在 lambda 中使用：

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 (Required, string): 要订阅并监听 MQTT 消息的 MQTT 主题。每次收到与此主题完全相同的消息时，自动化将触发。
qos (Optional, int): 订阅主题的 MQTT 服务质量级别。默认为 0。

NOTE

由于此触发器内部的工作方式，它与某些动作不兼容，将导致编译失败。例如与 delay 动作。

NOTE

此动作也可以在 lambda 中使用：

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: "发生了某些事情！"

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

配置变量

topic (Required, string, templatable): 发布消息的 MQTT 主题。
payload (Required, string, templatable): 消息内容。
qos (Optional, int, templatable): 主题的服务质量级别。默认为 0。
retain (Optional, boolean, templatable): 发布的消息是否应带有保留标志。默认为 false。

NOTE

此动作也可以在 lambda 中编写：

mqtt:
  # 给 MQTT 组件一个 ID
  id: mqtt_client

id(mqtt_client).publish("the/topic", "负载内容");

`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 (Required, string, templatable): 发布消息的 MQTT 主题。
payload (Required, lambda): 消息内容。
qos (Optional, int): 主题的服务质量级别。默认为 0。
retain (Optional, boolean): 发布的消息是否应带有保留标志。默认为 false。

NOTE

此动作也可以在 lambda 中编写：

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 已连接！

NOTE

此动作也可以在 lambda 中编写：

mqtt:
  # 给 MQTT 组件一个 ID
  id: mqtt_client

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

另见

API Reference: mqtt_client.h

MQTT 客户端组件

配置变量

MQTTMessage

MQTT 设备发现

在 Home Assistant 中使用设备发现

与 Home Assistant MQTT 实体一起使用

默认值

遗嘱和诞生消息

SSL 指纹

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` 条件