2025.3.4
首页 ▸ Integrations ▸

MQTT

MQTT（即 MQ Telemetry Transport）是一种基于 TCP/IP 的机器对机器或“物联网”连接协议。它允许极轻量级的发布/订阅消息传输。

配置

要将 MQTT integration 添加到您的 Home Assistant 实例中，请使用此 My 按钮：

手动配置步骤

如果上述 My 按钮不起作用，您也可以手动执行以下步骤：

移除 MQTT 集成

可以通过以下步骤移除 MQTT 集成及其实体：

  1. 导航到 设置 > 设备与服务
  2. 找到 MQTT 集成并点击它
  3. 点击删除按钮以移除 MQTT 配置条目

注意：此操作不会移除 MQTT broker 或其数据。如果您想完全移除 MQTT：

  1. 检查您的 configuration.yaml 和其他 YAML 文件中的 MQTT 相关配置并将其移除
  2. 检查您的自动化和脚本是否有任何 MQTT 依赖
  3. 在进行这些更改之前，建议备份您的配置

通过 MQTT 发现配置 MQTT 组件

通过 YAML 配置 MQTT 组件

要让 MQTT 和 Home Assistant 一起工作，您的第一步是选择一个 broker。

最简单的选项是安装官方的 Mosquitto Broker 插件。您可以在设置 MQTT 集成时选择自动设置和配置此插件。Home Assistant 将自动生成并分配一个安全的用户名和密码，无需进一步操作。如果您已经提前设置了此插件，这种方式也适用。 您可以使用 Mosquitto 插件配置 为您的 MQTT 设备和服务设置额外的登录信息。

Important

当 MQTT 使用官方的 Mosquitto MQTT broker 插件设置时，broker 的凭据会被生成并保密。如果需要重新安装官方的 Mosquitto MQTT broker，请确保保存一份插件用户选项的副本，例如额外的登录信息。重新安装插件后，MQTT 集成会自动更新重新安装的 broker 的新密码，并自动重新连接。

或者，您可以使用其他与 Home Assistant 兼容的 MQTT broker，并自行配置。

设置 broker

虽然有公共的 MQTT broker 可用，但最简单且最私密的选项是运行您自己的 broker。

推荐的设置方法是使用 Mosquitto MQTT broker 插件。

Warning

ActiveMQ MQTT broker 和 RabbitMQ MQTT 插件不受支持，请使用像 Mosquitto 这样的已知可用的 broker。 ActiveMQ MQTT broker 至少存在 两个问题 导致 MQTT 消息保留功能失效。

Broker 配置

MQTT broker 设置在首次设置 MQTT 集成时进行配置，之后可以根据需要进行更改。

添加 MQTT 集成，然后提供您的 broker 的主机名（或 IP 地址）和端口，以及（如果需要）Home Assistant 应使用的用户名和密码。要稍后更改设置，请按照以下步骤操作：

  1. 转到 设置 > 设备与服务。
  2. 选择 MQTT 集成。
  3. 通过 设置 > 设备与服务 重新配置 MQTT broker 设置，点击 并选择 重新配置。

Important

如果您遇到类似 Failed to connect due to exception: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed 的错误消息，请打开 高级选项 并将 Broker 证书验证 设置为 自动。

高级 broker 配置

高级 broker 配置选项包括设置自定义客户端 ID、设置客户端证书和密钥进行身份验证，以及启用 TLS 验证 broker 的证书以进行安全连接。要访问高级设置，请打开 MQTT broker 设置，打开 高级选项 并点击 下一步。如果已经配置了高级设置，则默认会显示高级选项。

Tip

高级 broker 选项仅在启用高级模式（请参阅用户设置）时可访问，或者已经配置了高级 broker 设置时可访问。

替代客户端 ID

您可以设置自定义的 MQTT 客户端 ID，这在调试时很有帮助。请注意，客户端 ID 必须是唯一的。如果您希望 Home Assistant 生成唯一的 ID，请将此设置保留为默认值。

保持连接

此客户端发送保持连接消息的时间间隔（以秒为单位）。默认值为 60 秒。保持连接设置应至少为 15 秒。

Broker 证书验证

要启用与 broker 的安全连接，应验证 broker 证书。如果您的 broker 使用受信任的证书，请选择 自动。这将允许对证书 CA 捆绑证书进行验证。如果使用自签名证书，请选择 自定义。可以上传自定义的 PEM 编码 CA 证书。点击 下一步 显示上传 CA 证书的控件。 如果服务器证书与主机名不匹配，则验证将失败。要允许在不验证主机名的情况下进行连接，请打开 忽略 broker 证书验证 开关。

MQTT 协议

MQTT 协议设置默认为版本 3.1.1。如果您的 MQTT broker 支持 MQTT 版本 5，您可以将协议设置为 5。

保护连接

通过安全的 broker 连接，可以使用客户端证书进行身份验证。要设置客户端证书和私钥，请打开 使用客户端证书 选项并点击“下一步”以显示上传文件的控件。只能上传 PEM 编码的客户端证书和 PEM 编码的私钥。确保私钥没有设置密码。

使用 WebSockets 作为传输方式

如果您的 MQTT broker 支持，您可以选择 websockets 作为传输方式。当您选择 websockets 并点击 下一步 时，您将能够添加 WebSockets 路径（默认值为 /）和 WebSockets 头（可选）。目标 WebSockets URI: ws://{broker}:{port}{WebSockets path} 是使用 broker、port 和 ws_path（WebSocket 路径）设置构建的。 要配置 WebSocket 的头，请提供有效的 JSON 字典字符串。例如 { "Authorization": "token" , "x-header": "some header"}。默认的传输方式是 tcp。WebSockets 传输可以使用 TLS 进行保护，并可选地使用用户凭据或客户端证书。

Note

配置的客户端证书仅在启用 broker 证书验证时才会生效。

配置 MQTT 选项

要更改选项，请按照以下步骤操作：

  1. 转到 设置 > 设备与服务。
  2. 选择 MQTT 集成。
  3. 选择 配置，然后 重新配置 MQTT。
  4. 要打开 MQTT 选项页面，请选择 下一步。

更改 MQTT 发现选项

可以通过以下步骤更改 MQTT 发现选项：

  1. 转到 设置 > 设备与服务。
  2. 找到 MQTT 集成并选择它。
  3. 要打开 MQTT 发现选项页面，请选择 配置 MQTT 选项 按钮。

发现选项

默认情况下启用 MQTT 发现。可以关闭发现。也可以在此处更改发现主题的前缀（默认值为 homeassistant）。 另请参阅 MQTT 发现部分

出生和遗嘱消息

Home Assistant 的 MQTT 集成支持所谓的出生和遗嘱消息。前者用于在服务启动后发送消息，后者用于通知其他客户端断开连接的客户端。请注意，遗嘱消息将在干净（例如 Home Assistant 关闭）和不干净（例如 Home Assistant 崩溃或失去网络连接）断开连接的情况下发送。

如果禁用的实体在 30 秒后启用并添加，MQTT 集成将重新加载，并导致所有发现的 MQTT 实体被卸载。 当 MQTT 启动时，所有现有的 MQTT 设备、实体、标签和设备触发器将不可用，直到收到并处理发现消息。暴露 MQTT 发现的设备或服务应订阅出生消息，并将其用作发送 发现负载 的触发器。为了避免 MQTT broker 上的高 IO 负载，建议在发送发现负载时添加一些随机延迟。

替代方法：

  • 保留 发现负载：这将在 MQTT broker 上存储发现负载，并在 MQTT 集成订阅 MQTT 发现时提供给它。当有很多实体时，这可能会导致高 IO 负载。
  • 定期重新发送发现负载：这可能会导致一些延迟，或者如果有很多 MQTT 发现消息，则会导致大量 IO。

默认情况下，Home Assistant 发送 online 和 offline 到 homeassistant/status。

可以从 UI 自定义或禁用 MQTT 出生和遗嘱消息。为此，请在 UI 中的集成页面上点击“配置”，然后“重新配置 MQTT”，然后“下一步”。

测试您的设置

mosquitto broker 包含命令行工具（通常作为 *-clients 包）来发送和接收 MQTT 消息。要向运行在 localhost 上的 broker 发送测试消息，您可以使用 mosquitto_pub，请参阅下面的示例：

mosquitto_pub -h 127.0.0.1 -t homeassistant/switch/1/on -m "Switch is ON"

另一种手动发送 MQTT 消息的方法是使用前端的 MQTT 集成。选择左侧菜单中的“设置”，点击“设备与服务”，然后在“Mosquitto broker”磁贴中选择“配置”。在“发布数据包”下的“主题”字段中输入类似于下面示例的内容，然后按“发布”。

  1. 转到 设置 > 设备与服务。
  2. 选择 Mosquitto broker 集成，然后选择 配置。
  3. 在 发布数据包 下的 主题 字段中输入类似于下面示例的内容。选择 发布。
   homeassistant/switch/1/power

在有效负载字段中输入

   ON

在“监听主题”字段中，输入 # 以查看所有内容，或输入“homeassistant/switch/#”以仅关注已发布的主题，然后按“开始监听”。消息应类似于下面的文本：

Message 23 received on homeassistant/switch/1/power/stat/POWER at 12:16 PM:
ON
QoS: 0 - Retain: false
Message 22 received on homeassistant/switch/1/power/stat/RESULT at 12:16 PM:
{
    "POWER": "ON"
}
QoS: 0 - Retain: false

要读取发送到运行在 localhost 上的 broker 上的主题 homeassistant 的所有消息：

mosquitto_sub -h 127.0.0.1 -v -t "homeassistant/#"

设备配置共享

MQTT 实体可以共享设备配置，这意味着一个实体可以包含完整的设备配置，其他实体可以通过仅设置必填字段来链接到该设备。 以前，必填字段仅限于 connection 和 identifiers 中的至少一个，但现在已扩展为 connection 和 identifiers 中的至少一个以及 name。

MQTT 实体命名

对于每个配置的 MQTT 实体，Home Assistant 会自动分配一个唯一的 entity_id。如果配置了 unique_id 选项，您可以在创建后更改 entity_id，更改将存储在实体注册表中。entity_id 是在项目首次加载时生成的。

如果设置了 object_id 选项，则将使用它来生成 entity_id。 例如，如果我们配置了一个 sensor，并将 object_id 设置为 test，则 Home Assistant 将尝试分配 sensor.test 作为 entity_id，但如果此 entity_id 已存在，它将附加一个后缀以使其唯一，例如 sensor.test_2。

这意味着任何属于设备的 MQTT 实体将 自动将其 friendly_name 属性前缀为设备名称

未命名的 binary_sensor、button、number 和 sensor 实体现在将根据其设备类别命名，而不是命名为“MQTT binary sensor”等。 允许将 MQTT 实体的名称设置为 None（在 YAML 中使用 null），以将其标记为设备的主要功能。

请注意，在每个 MQTT 实体上，has_entity_name 属性将设置为 True。更多详细信息 可以在此处找到。

MQTT 发现

MQTT 设备的发现将使一个人能够以最小的配置工作量使用 MQTT 设备。配置在设备本身和设备使用的主题上完成。类似于 HTTP binary sensor 和 HTTP sensor。为了防止设备重新连接时出现多个相同的条目，需要一个唯一标识符。设备端需要两个部分：包含必要设备类型和唯一标识符的配置主题，以及不包含设备类型的剩余设备配置。

默认情况下启用 MQTT 发现，但可以禁用。可以更改发现主题的前缀（默认值为 homeassistant）。 请参阅 MQTT 选项部分

Note

支持 MQTT 发现的 MQTT 组件文档 可以在此处找到。

发现消息

发现主题

发现主题需要遵循特定格式：

<discovery_prefix>/<component>/[<node_id>/]<object_id>/config
  • <discovery_prefix>：发现前缀默认为 homeassistant，可以 更改。
  • <component>：支持的 MQTT 集成之一，例如 binary_sensor，或在设备发现的情况下为 device。
  • <node_id>：（可选）：提供主题的节点的 ID，这不由 Home Assistant 使用，但可以用于结构化 MQTT 主题。节点的 ID 只能由字符类 [a-zA-Z0-9_-]（字母数字、下划线和连字符）中的字符组成。
  • <object_id>：设备的 ID。这仅用于为每个设备提供单独的主题，而不用于 entity_id。设备的 ID 只能由字符类 [a-zA-Z0-9_-]（字母数字、下划线和连字符）中的字符组成。

<node_id> 级别可以由客户端使用，通过使用一个通配符主题如 <discovery_prefix>/+/<node_id>/+/set 仅订阅其自己的（命令）主题。

对于具有 unique_id 的实体，最佳实践是将 <object_id> 设置为 unique_id 并省略 <node_id>。

设备发现负载

设备可以发送发现负载以暴露设备的所有组件。 发现主题中的 <component> 部分必须设置为 device。

作为替代方案，也可以设备 可以为其要设置的每个组件发送发现负载。

JSON 消息的根级别必须包括：

  • device 映射（缩写为 dev）
  • origin 映射（缩写为 o）

这些映射是强制性的，不能在实体/组件级别覆盖。

支持的共享选项包括：

  • availability 选项。
  • origin（必需）选项
  • command_topic
  • state_topic
  • qos
  • encoding

组件特定的选项作为映射放置在 components 键（缩写为 cmp）下，如：

{
  "dev": {
    "ids": "ea334450945afc",
    "name": "Kitchen",
    "mf": "Bla electronics",
    "mdl": "xya",
    "sw": "1.0",
    "sn": "ea334450945afc",
    "hw": "1.0rev2"
  },
  "o": {
    "name":"bla2mqtt",
    "sw": "2.1",
    "url": "https://bla2mqtt.example.com/support"
  },
  "cmps": {
    "some_unique_component_id1": {
      "p": "sensor",
      "device_class":"temperature",
      "unit_of_measurement":"°C",
      "value_template":"{{ value_json.temperature}}",
      "unique_id":"temp01ae_t"
    },
    "some_unique_id2": {
      "p": "sensor",
      "device_class":"humidity",
      "unit_of_measurement":"%",
      "value_template":"{{ value_json.humidity}}",
      "unique_id":"temp01ae_h"
    }
  },
  "state_topic":"sensorBedroom/state",
  "qos": 2
}

components（cmp）键下的组件 ID 用作发现标识的一部分。每个添加的组件配置都需要一个 platform（p）配置选项来标识组件平台。实体组件还需要一个 unique_id。

要删除组件，请将空的（保留的）字符串负载发布到发现主题。这将删除组件并清除已发布的发现负载。如果没有进一步引用它，它还将删除设备条目。

可以发布空配置作为更新以从设备发现中删除单个组件。请注意，仍然需要添加 platform（p）选项。

{
  "dev": {
    "ids": "ea334450945afc",
    "name": "Kitchen",
    "mf": "Bla electronics",
    "mdl": "xya",
    "sw": "1.0",
    "sn": "ea334450945afc",
    "hw": "1.0rev2"
  },
  "o": {
    "name":"bla2mqtt",
    "sw": "2.1",
    "url": "https://bla2mqtt.example.com/support"
  },
  "cmps": {
    "some_unique_component_id1": {
      "p": "sensor",
      "device_class":"temperature",
      "unit_of_measurement":"°C",
      "value_template":"{{ value_json.temperature}}",
      "unique_id":"temp01ae_t"
    },
    "some_unique_id2": {
      "p": "sensor"
    }
  },
  "state_topic":"sensorBedroom/state",
  "qos": 2
}

这将显式删除湿度传感器及其条目。

删除组件后，您应发送另一个更新，其中省略已删除的组件配置。这确保 Home Assistant 拥有最新的设备配置。例如：

{
  "dev": {
    "ids": "ea334450945afc",
    "name": "Kitchen",
    "mf": "Bla electronics",
    "mdl": "xya",
    "sw": "1.0",
    "sn": "ea334450945afc",
    "hw": "1.0rev2"
  },
  "o": {
    "name":"bla2mqtt",
    "sw": "2.1",
    "url": "https://bla2mqtt.example.com/support"
  },
  "cmps": {
    "some_unique_component_id1": {
      "p": "sensor",
      "device_class":"temperature",
      "unit_of_measurement":"°C",
      "value_template":"{{ value_json.temperature}}",
      "unique_id":"temp01ae_t"
    }
  },
  "state_topic":"sensorBedroom/state",
  "qos": 2
}

设备发现负载中的组件配置部分必须设置 platform（p）选项，并且还必须至少有一个组件特定的配置选项。实体组件必须设置 unique_id 选项并具有 device 上下文。

从单个组件迁移到基于设备的发现

为了允许从单个组件发现平滑迁移到基于设备的发现：

  1. 确保所有实体都有 unique_id 和 device 上下文。
  2. 如果可用，将 object_id 移动到发现负载内部，或使用唯一 ID 或组件。
  3. 考虑使用以前的 node_id 作为新设备发现主题的 object_id。
  4. 确保 unique_id 匹配，并且 device 上下文具有正确的标识符。
  5. 将以下负载发送到所有现有的单个组件发现主题：{"migrate_discovery": true }。这将卸载已发现的项目，但其设置将保留。
  6. 将发现主题切换到基于设备的发现主题，并包括所有组件配置。
  7. 通过发布空负载清理单个组件发现消息。

在迁移步骤期间，将记录 INFO 消息以通知您迁移的进展。

Important

在将迁移过程应用于生产环境之前，请考虑在非生产环境中测试迁移过程。

具有设备自动化和传感器的发现迁移示例

步骤 1：原始单个组件发现配置：

发现主题单个：homeassistant/device_automation/0AFFD2/bla1/config 发现 ID：0AFFD2 bla1 （发现主题中的 0AFFD2 和 bla1） 发现负载单个：

{
  "device": {
    "identifiers": ["0AFFD2"],
    "name": "Test device"
  },
  "o": {
    "name": "foobar"
  },
  "automation_type": "trigger",
  "payload": "short_press",
  "topic": "foobar/triggers/button1",
  "type": "button_short_press",
  "subtype": "button_1"
}

发现主题单个：homeassistant/sensor/0AFFD2/bla2/config 发现 ID：0AFFD2 bla2 （发现主题中的 0AFFD2 和 bla2） 发现负载单个：

{
  "device": {
    "identifiers": ["0AFFD2"],
    "name": "Test device"
  },
  "o": {
    "name": "foobar"
  },
  "state_topic": "foobar/sensor/sensor1",
  "unique_id": "bla_sensor001"
}

步骤 2：通过发布到两个发现主题启动迁移：

当这些单个组件发现负载被处理时，并且我们希望启动迁移到基于设备的发现，我们需要发布 …

{"migrate_discovery": true }

… 到两个发现主题 …

  • homeassistant/device_automation/0AFFD2/bla1/config
  • homeassistant/sensor/0AFFD2/bla2/config

Important

检查日志以确保此步骤正确执行。

步骤 3：发布新的基于设备的发现配置：

发现主题设备：homeassistant/device/0AFFD2/config 发现 ID：0AFFD2 bla （发现主题中的 0AFFD2，bla：发现负载中的 cmp 键） 发现负载设备：

{
  "device": {
    "identifiers": [
      "0AFFD2"
    ]
  },
  "o": {
    "name": "foobar"
  },
  "cmps": {
    "bla1": {
      "p": "device_automation",
      "automation_type": "trigger",
      "payload": "short_press",
      "topic": "foobar/triggers/button1",
      "type": "button_short_press",
      "subtype": "button_1"
    },
    "bla2": {
      "p": "sensor",
      "state_topic": "foobar/sensor/sensor1",
      "unique_id": "bla_sensor001"
    }
  }
}

Important

检查日志以确保迁移成功。

步骤 4：成功迁移后进行清理：

在日志显示迁移成功后，可以通过发布空负载安全地清理单个组件发现主题。 日志应指示发现迁移是否成功。

可选：回滚迁移：

要回滚发布 …

{"migrate_discovery": true }

到基于设备的发现主题。 之后，重新发布单个组件发现负载。 最后，通过发布空负载清理基于设备的发现负载。

检查每个步骤的日志。

单个组件发现负载

发现主题中的 <component> 部分必须是支持的 MQTT 平台之一。 负载中的选项仅用于设置一个特定组件。如果有更多组件，则需要为其他组件发送更多发现负载，建议使用 基于设备的发现 代替。

示例发现负载：

{
  "dev": {
    "ids": "ea334450945afc",
    "name": "Kitchen",
    "mf": "Bla electronics",
    "mdl": "xya",
    "sw": "1.0",
    "sn": "ea334450945afc",
    "hw": "1.0rev2"
  },
  "o": {
    "name":"bla2mqtt",
    "sw": "2.1",
    "url": "https://bla2mqtt.example.com/support"
  },
  "device_class":"temperature",
  "unit_of_measurement":"°C",
  "value_template":"{{ value_json.temperature}}",
  "unique_id":"temp01ae_t",
  "state_topic":"sensorBedroom/state",
  "qos": 2
}

要删除组件，请将空字符串发布到发现主题。这将删除组件并清除已发布的发现负载。如果没有进一步引用它，它还将删除设备条目。

更多示例 请参阅。

发现负载

负载必须是序列化的 JSON 字典，并将像您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中的条目一样进行检查，如果添加了新设备，未知的配置键将被忽略。这意味着缺少的变量将使用集成的默认值填充。允许未知文档键的原因是为了提供一些向后兼容性，生成 MQTT 发现消息的软件可以与旧版本的 Home Assistant 一起使用，这些版本将简单地忽略新功能。

可以使用保留标志发送发现负载。在这种情况下，发现消息将存储在 MQTT broker 上，并在 MQTT 集成启动时自动处理。这种方法消除了重新发送的需要。不过，更好的方法是让生成 MQTT 发现消息的软件在 MQTT 集成发送 出生消息 时发送发现负载。

在接收到有效负载的主题上发布的后续消息将被视为配置更新，带有空负载的配置更新将导致先前发现的设备被删除。

可以在负载中定义基本主题 ~ 以节省内存，当多次使用相同的主题基础时。 在以 _topic 结尾的配置变量的值中，如果 ~ 出现在值的开头或结尾，则 ~ 将替换为基本主题。

发现负载中的配置变量名称可以缩写，以节省从内存受限设备发送发现消息时的内存。

建议通过在发现负载中包含 origin 选项（缩写为 o）来添加有关 MQTT 实体来源的信息。对于基于设备的发现，此信息是必需的。当项目被发现或更新时，核心事件日志中将记录来源详细信息。添加来源信息有助于故障排除，并提供有关 Home Assistant 设置中 MQTT 消息来源的有价值的上下文。

注意：这些选项也支持缩写，如下表所示。

name

发现的 MQTT 项目的来源应用程序的名称。（必需）

sw_version

提供发现的 MQTT 项目的应用程序的软件版本。

support_url

提供发现的 MQTT 项目的应用程序的支持 URL。

支持的 MQTT 发现消息缩写

支持的缩写 
    'act_t':               'action_topic',
    'act_tpl':             'action_template',
    'atype':               'automation_type',
    'aux_cmd_t':           'aux_command_topic',
    'aux_stat_t':          'aux_state_topic',
    'aux_stat_tpl':        'aux_state_template',
    'av_tones':            'available_tones',
    'avty':                'availability',
    'avty_mode':           'availability_mode',
    'avty_t':              'availability_topic',
    'avty_tpl':            'availability_template',
    'away_mode_cmd_t':     'away_mode_command_topic',
    'away_mode_stat_t':    'away_mode_state_topic',
    'away_mode_stat_tpl':  'away_mode_state_template',
    'b_tpl':               'blue_template',
    'bri_cmd_t':           'brightness_command_topic',
    'bri_cmd_tpl':         'brightness_command_template',
    'bri_scl':             'brightness_scale',
    'bri_stat_t':          'brightness_state_topic',
    'bri_tpl':             'brightness_template',
    'bri_val_tpl':         'brightness_value_template',
    'clr_temp_cmd_tpl':    'color_temp_command_template',
    'clr_temp_cmd_t':      'color_temp_command_topic',
    'clr_temp_k':           'color_temp_kelvin',
    'clr_temp_stat_t':     'color_temp_state_topic',
    'clr_temp_tpl':        'color_temp_template',
    'clr_temp_val_tpl':    'color_temp_value_template',
    'clrm':                'color_mode',
    'clrm_stat_t':         'color_mode_state_topic',
    'clrm_val_tpl':        'color_mode_value_template',
    'cmd_off_tpl':         'command_off_template',
    'cmd_on_tpl':          'command_on_template',
    'cmd_t':               'command_topic',
    'cmd_tpl':             'command_template',
    'cmps':                'components',
    'cod_arm_req':         'code_arm_required',
    'cod_dis_req':         'code_disarm_required',
    'cod_trig_req':        'code_trigger_required',
    'cont_type':           'content_type',
    'curr_temp_t':         'current_temperature_topic',
    'curr_temp_tpl':       'current_temperature_template',
    'dev':                 'device',
    'dev_cla':             'device_class',
    'dir_cmd_t':           'direction_command_topic',
    'dir_cmd_tpl':         'direction_command_template',
    'dir_stat_t':          'direction_state_topic',
    'dir_val_tpl':         'direction_value_template',
    'dsp_prc':             'display_precision',
    'e':                   'encoding',
    'en':                  'enabled_by_default',
    'ent_cat':             'entity_category',
    'ent_pic':             'entity_picture',
    'evt_typ':             'event_types',
    'exp_aft':             'expire_after',
    'fanspd_lst':          'fan_speed_list',
    'flsh_tlng':           'flash_time_long',
    'flsh_tsht':           'flash_time_short',
    'fx_cmd_t':            'effect_command_topic',
    'fx_cmd_tpl':          'effect_command_template',
    'fx_list':             'effect_list',
    'fx_stat_t':           'effect_state_topic',
    'fx_tpl':              'effect_template',
    'fx_val_tpl':          'effect_value_template',
    'fan_mode_cmd_t':      'fan_mode_command_topic',
    'fan_mode_cmd_tpl':    'fan_mode_command_template',
    'fan_mode_stat_t':     'fan_mode_state_topic',
    'fan_mode_stat_tpl':   'fan_mode_state_template',
    'frc_upd':             'force_update',
    'g_tpl':               'green_template',
    'hs_cmd_t':            'hs_command_topic',
    'hs_cmd_tpl':          'hs_command_template',
    'hs_stat_t':           'hs_state_topic',
    'hs_val_tpl':          'hs_value_template',
    'ic':                  'icon',
    'img_e':               'image_encoding',
    'img_t':               'image_topic',
    'init':                'initial',
    'hum_cmd_t':           'target_humidity_command_topic',
    'hum_cmd_tpl':         'target_humidity_command_template',
    'hum_stat_t':          'target_humidity_state_topic',
    'hum_state_tpl':       'target_humidity_state_template',
    'json_attr':           'json_attributes',
    'json_attr_t':         'json_attributes_topic',
    'json_attr_tpl':       'json_attributes_template',
    'l_ver_t':             'latest_version_topic',
    'l_ver_tpl':           'latest_version_template',
    'lrst_t':              'last_reset_topic',
    'lrst_val_tpl':        'last_reset_value_template',
    'max':                 'max',
    'max_hum':             'max_humidity',
    'max_k':               'max_kelvin',
    'max_mirs':            'max_mireds',
    'max_temp':            'max_temp',
    'migr_discvry':        'migrate_discovery',
    'min':                 'min',
    'min_hum':             'min_humidity',
    'min_k':               'min_kelvin',
    'min_mirs':            'min_mireds',
    'min_temp':            'min_temp',
    'mode':                'mode',
    'mode_cmd_t':          'mode_command_topic',
    'mode_cmd_tpl':        'mode_command_template',
    'mode_stat_t':         'mode_state_topic',
    'mode_stat_tpl':       'mode_state_template',
    'modes':               'modes',
    'name':                'name',
    'o':                   'origin',
    'obj_id':              'object_id',
    'off_dly':             'off_delay',
    'on_cmd_type':         'on_command_type',
    'ops':                 'options',
    'opt':                 'optimistic',
    'osc_cmd_t':           'oscillation_command_topic',
    'osc_cmd_tpl':         'oscillation_command_template',
    'osc_stat_t':          'oscillation_state_topic',
    'osc_val_tpl':         'oscillation_value_template',
    'p':                   'platform',
    'pct_cmd_t':           'percentage_command_topic',
    'pct_cmd_tpl':         'percentage_command_template',
    'pct_stat_t':          'percentage_state_topic',
    'pct_val_tpl':         'percentage_value_template',
    'pl':                  'payload',
    'pl_arm_away':         'payload_arm_away',
    'pl_arm_custom_b':     'payload_arm_custom_bypass',
    'pl_arm_home':         'payload_arm_home',
    'pl_arm_nite':         'payload_arm_night',
    'pl_arm_vacation':     'payload_arm_vacation',
    'pl_avail':            'payload_available',
    'pl_cln_sp':           'payload_clean_spot',
    'pl_cls':              'payload_close',
    'pl_dir_fwd':          'payload_direction_forward',
    'pl_dir_rev':          'payload_direction_reverse',
    'pl_disarm':           'payload_disarm',
    'pl_home':             'payload_home',
    'pl_inst':             'payload_install',
    'pl_loc':              'payload_locate',
    'pl_lock':             'payload_lock',
    'pl_not_avail':        'payload_not_available',
    'pl_not_home':         'payload_not_home',
    'pl_off':              'payload_off',
    'pl_on':               'payload_on',
    'pl_open':             'payload_open',
    'pl_osc_off':          'payload_oscillation_off',
    'pl_osc_on':           'payload_oscillation_on',
    'pl_paus':             'payload_pause',
    'pl_stop':             'payload_stop',
    'pl_strt':             'payload_start',
    'pl_prs':              'payload_press',
    'pl_ret':              'payload_return_to_base',
    'pl_rst':              'payload_reset',
    'pl_rst_hum':          'payload_reset_humidity',
    'pl_rst_mode':         'payload_reset_mode',
    'pl_rst_pct':          'payload_reset_percentage',
    'pl_rst_pr_mode':      'payload_reset_preset_mode',
    'pl_stop':             'payload_stop',
    'pl_stpa':             'payload_start_pause',
    'pl_strt':             'payload_start',
    'pl_toff':             'payload_turn_off',
    'pl_ton':              'payload_turn_on',
    'pl_trig':             'payload_trigger',
    'pl_unlk':             'payload_unlock',
    'pos':                 'reports_position',
    'pos_clsd':            'position_closed',
    'pos_open':            'position_open',
    'pr_mode_cmd_t':       'preset_mode_command_topic',
    'pr_mode_cmd_tpl':     'preset_mode_command_template',
    'pr_mode_stat_t':      'preset_mode_state_topic',
    'pr_mode_val_tpl':     'preset_mode_value_template',
    'pr_modes':            'preset_modes',
    'ptrn':                'pattern',
    'r_tpl':               'red_template',
    'rel_s':               'release_summary',
    'rel_u':               'release_url',
    'ret':                 'retain',
    'rgb_cmd_t':           'rgb_command_topic',
    'rgb_cmd_tpl':         'rgb_command_template',
    'rgb_stat_t':          'rgb_state_topic',
    'rgb_val_tpl':         'rgb_value_template',
    'rgbw_cmd_t':          'rgbw_command_topic',
    'rgbw_cmd_tpl':        'rgbw_command_template',
    'rgbw_stat_t':         'rgbw_state_topic',
    'rgbw_val_tpl':        'rgbw_value_template',
    'rgbww_cmd_t':         'rgbww_command_topic',
    'rgbww_cmd_tpl':       'rgbww_command_template',
    'rgbww_stat_t':        'rgbww_state_topic',
    'rgbww_val_tpl':       'rgbww_value_template',
    'send_cmd_t':          'send_command_topic',
    'send_if_off':         'send_if_off',
    'set_fan_spd_t':       'set_fan_speed_topic',
    'set_pos_t':           'set_position_topic',
    'set_pos_tpl':         'set_position_template',
    'pos_t':               'position_topic',
    'pos_tpl':             'position_template',
    'spd_rng_min':         'speed_range_min',
    'spd_rng_max':         'speed_range_max',
    'src_type':            'source_type',
    'stat_cla':            'state_class',
    'stat_closing':        'state_closing',
    'stat_clsd':           'state_closed',
    'stat_jam':            'state_jammed',
    'stat_locked':         'state_locked',
    'stat_locking':        'state_locking',
    'stat_off':            'state_off',
    'stat_on':             'state_on',
    'stat_open':           'state_open',
    'stat_opening':        'state_opening',
    'stat_stopped':        'state_stopped',
    'stat_unlocked':       'state_unlocked',
    'stat_unlocking':      'state_unlocking',
    'stat_t':              'state_topic',
    'stat_tpl':            'state_template',
    'stat_val_tpl':        'state_value_template',
    'step':                'step',
    'stype':               'subtype',
    'sug_dsp_prc':         'suggested_display_precision',
    'sup_clrm':            'supported_color_modes',
    'sup_dur':             'support_duration',
    'sup_vol':             'support_volume_set',
    'sup_feat':            'supported_features',
    'swing_mode_cmd_t':    'swing_mode_command_topic',
    'swing_mode_cmd_tpl':  'swing_mode_command_template',
    'swing_mode_stat_t':   'swing_mode_state_topic',
    'swing_mode_stat_tpl': 'swing_mode_state_template',
    't':                   'topic',
    'temp_cmd_t':          'temperature_command_topic',
    'temp_cmd_tpl':        'temperature_command_template',
    'temp_hi_cmd_t':       'temperature_high_command_topic',
    'temp_hi_cmd_tpl':     'temperature_high_command_template',
    'temp_hi_stat_t':      'temperature_high_state_topic',
    'temp_hi_stat_tpl':    'temperature_high_state_template',
    'temp_lo_cmd_t':       'temperature_low_command_topic',
    'temp_lo_cmd_tpl':     'temperature_low_command_template',
    'temp_lo_stat_t':      'temperature_low_state_topic',
    'temp_lo_stat_tpl':    'temperature_low_state_template',
    'temp_stat_t':         'temperature_state_topic',
    'temp_stat_tpl':       'temperature_state_template',
    'temp_unit':           'temperature_unit',
    'tilt_clsd_val':       'tilt_closed_value',
    'tilt_cmd_t':          'tilt_command_topic',
    'tilt_cmd_tpl':        'tilt_command_template',
    'tilt_max':            'tilt_max',
    'tilt_min':            'tilt_min',
    'tilt_opnd_val':       'tilt_opened_value',
    'tilt_opt':            'tilt_optimistic',
    'tilt_status_t':       'tilt_status_topic',
    'tilt_status_tpl':     'tilt_status_template',
    'tit':                 'title',
    'uniq_id':             'unique_id',
    'unit_of_meas':        'unit_of_measurement',
    'url_t':               'url_topic',
    'url_tpl':             'url_template',
    'val_tpl':             'value_template',
    'whit_cmd_t':          'white_command_topic',
    'whit_scl':            'white_scale',
    'xy_cmd_t':            'xy_command_topic',
    'xy_cmd_tpl':          'xy_command_template',
    'xy_stat_t':           'xy_state_topic',
    'xy_val_tpl':          'xy_value_template',
设备注册表配置支持的缩写 
    'cu':                  'configuration_url',
    'cns':                 'connections',
    'ids':                 'identifiers',
    'name':                'name',
    'mf':                  'manufacturer',
    'mdl':                 'model',
    'mdl_id':              'model_id',
    'hw':                  'hw_version',
    'sw':                  'sw_version',
    'sa':                  'suggested_area',
    'sn':                  'serial_number',
来源信息支持的缩写 
    'name':                'name',
    'sw':                  'sw_version',
    'url':                 'support_url',

发现消息和可用性

当设置了 MQTT 发现，并且设备或服务发送发现消息时， 在接收到消息后，将直接设置 MQTT 实体、标签或设备自动化。 当 Home Assistant 重新启动时，具有唯一 ID 的已发现 MQTT 项目将不可用，直到收到新的 发现消息。没有唯一 ID 的 MQTT 项目在启动时不会添加。 因此，使用 MQTT 发现的设备或服务必须确保在 MQTT 集成（重新）启动后提供配置消息。 确保在启动时设置已发现项目的两种常见方法：

  1. 使用出生和遗嘱消息触发设置
  2. 使用保留消息

最后，最好发布您的设备或服务的可用性状态。

使用出生和遗嘱消息触发发现

当 MQTT 集成启动时，默认情况下会在 homeassistant/status 上发布出生消息。 连接到共享 mqtt broker 的设备或服务可以订阅此主题，并使用 online 消息 触发发现消息。另请参阅 出生和遗嘱消息 部分。在发布配置后，状态主题将需要更新，因此需要重新发布。

使用保留配置消息

设备或服务的另一种方法是发布带有 retain 标志的发现消息。这将确保 当 MQTT 集成连接到 broker 时，发现消息会重放。 在发布配置后，状态主题将需要更新。

使用保留状态消息

状态更新也需要在处理配置后重新发布。 这也可以通过发布 保留 消息来完成。一旦接收到配置（或从保留消息重放）， 设置将订阅任何状态主题。如果状态主题上有保留消息， 此消息将重放，以便可以恢复此主题的状态。

Warning

使用保留消息的缺点是这些消息会保留在 broker 上， 即使设备或服务停止工作。即使在系统或 broker 重新启动后，它们仍会保留。 保留消息可能会创建幽灵实体，这些实体会不断出现。

特别是当您有很多实体时，（不必要的）发现消息可能会导致过多的系统负载。因此，请谨慎使用发现消息。

使用可用性主题

设备或服务可以通过在 broker 上发布出生消息并设置遗嘱消息来宣布其可用性。 当设备或服务失去与 broker 的连接时，broker 将发布遗嘱消息。 这允许 MQTT 集成使实体不可用。

平台特定的可用性设置仅适用于 mqtt 实体平台。

平台特定的可用性设置

Configuration Variables

Looking for your configuration file?
availability list (Optional)

订阅以接收可用性（在线/离线）更新的 MQTT 主题列表。不得与 availability_topic 一起使用。

payload_available string (Optional, default: online)

表示可用状态的负载。

payload_not_available string (Optional, default: offline)

表示不可用状态的负载。

topic string Required

订阅以接收可用性（在线/离线）更新的 MQTT 主题。

value_template template (Optional)

定义一个 模板 以从 topic 中提取设备的可用性。要确定设备的可用性，将此模板的结果与 payload_available 和 payload_not_available 进行比较。

availability_topic string (Optional)

订阅以接收可用性（在线/离线）更新的 MQTT 主题。不得与 availability 一起使用。

availability_mode string (Optional, default: latest)

当配置了 availability 时，这控制将实体设置为 available 所需的条件。有效条目为 all、any 和 latest。如果设置为 all，则必须在所有配置的可用性主题上接收到 payload_available，然后实体才会标记为在线。如果设置为 any，则必须在至少一个配置的可用性主题上接收到 payload_available，然后实体才会标记为在线。如果设置为 latest，则在任何配置的可用性主题上接收到的最后一个 payload_available 或 payload_not_available 控制可用性。

availability_template template (Optional)

定义一个 模板 以从 availability_topic 中提取设备的可用性。要确定设备的可用性，将此模板的结果与 payload_available 和 payload_not_available 进行比较。

payload_available string (Optional, default: online)

表示可用状态的负载。

payload_not_available string (Optional, default: offline)

表示不可用状态的负载。

发现示例与组件发现

运动检测（二进制传感器）

一个可以通过 binary sensor 表示的花园运动检测设备将其配置作为 JSON 负载发送到配置主题。第一次发送到 config 后，发送到状态主题的 MQTT 消息将更新 Home Assistant 中的状态。

  • 配置主题：homeassistant/binary_sensor/garden/config
  • 状态主题：homeassistant/binary_sensor/garden/state
  • 派生设备名称的配置负载：
{
   "name":null,
   "device_class":"motion",
   "state_topic":"homeassistant/binary_sensor/garden/state",
   "unique_id":"motion01ad",
   "device":{
      "identifiers":[
         "01ad"
      ],
      "name":"Garden"
   }
}
  • 保留：添加 -r 开关以在 broker 中保留配置主题。没有这个，传感器在 Home Assistant 重新启动后将不可用。

最好添加一个 unique_id 以允许更改实体，并添加一个 device 映射，以便我们可以将所有传感器分组在一起。我们可以将“name”设置为 null，如果我们希望实体继承设备名称。如果我们设置实体名称，friendly_name 将是设备和实体名称的组合。如果省略“name”并设置了 device_class，则实体名称部分将从 device_class 派生。

  • 示例配置负载，未设置名称并派生 device_class 名称：
{
   "name":null,
   "device_class":"motion",
   "state_topic":"homeassistant/binary_sensor/garden/state",
   "unique_id":"motion01ad",
   "device":{
      "identifiers":[
         "01ad"
      ],
      "name":"Garden"
   }
}

如果未设置名称，MQTT 将设置默认名称（请参阅 MQTT 平台文档）。

要手动创建一个新传感器，并将名称设置为 null 以派生设备名称“Garden”：

mosquitto_pub -r -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '{"name": null, "device_class": "motion", "state_topic": "homeassistant/binary_sensor/garden/state", "unique_id": "motion01ad", "device": {"identifiers": ["01ad"], "name": "Garden" }}'

更新状态：

mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/state" -m ON

通过发送空消息删除传感器。

mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m ''

有关更多详细信息，请参阅 MQTT 测试部分。

传感器

设置具有多个测量值的传感器需要多次连续配置主题提交。

  • 配置主题 no1：homeassistant/sensor/sensorBedroomT/config
  • 配置负载 no1：
{
   "device_class":"temperature",
   "state_topic":"homeassistant/sensor/sensorBedroom/state",
   "unit_of_measurement":"°C",
   "value_template":"{{ value_json.temperature}}",
   "unique_id":"temp01ae",
   "device":{
      "identifiers":[
          "bedroom01ae"
      ],
      "name":"Bedroom",
      "manufacturer": "Example sensors Ltd.",
      "model": "Example Sensor",
      "model_id": "K9",
      "serial_number": "12AE3010545",
      "hw_version": "1.01a",
      "sw_version": "2024.1.0",
      "configuration_url": "https://example.com/sensor_portal/config"
   }
}
  • 配置主题 no2：homeassistant/sensor/sensorBedroomH/config
  • 配置负载 no2：
{
   "device_class":"humidity",
   "state_topic":"homeassistant/sensor/sensorBedroom/state",
   "unit_of_measurement":"%",
   "value_template":"{{ value_json.humidity}}",
   "unique_id":"hum01ae",
   "device":{
      "identifiers":[
         "bedroom01ae"
      ]
   }
}

传感器 identifiers 或 connections 选项允许设置共享同一设备的多个实体。

Note

如果设备配置是共享的，则不需要将所有设备详细信息添加到其他实体配置中。对于其他实体配置负载，只需将共享标识符或连接添加到设备映射中即可。

可以使用 value_template 在传感器配置中解析的公共状态负载：

{
   "temperature":23.20,
   "humidity":43.70
}

具有命令主题的实体

设置灯光、开关等类似，但需要 command_topic，如 MQTT switch 文档 中所述。

  • 配置主题：homeassistant/switch/irrigation/config
  • 状态主题：homeassistant/switch/irrigation/state
  • 命令主题：homeassistant/switch/irrigation/set
  • 负载：
{
   "name":"Irrigation",
   "command_topic":"homeassistant/switch/irrigation/set",
   "state_topic":"homeassistant/switch/irrigation/state",
   "unique_id":"irr01ad",
   "device":{
      "identifiers":[
         "garden01ad"
      ],
      "name":"Garden"
   }
}
  • 保留：添加 -r 开关以在 broker 中保留配置主题。没有这个，传感器在 Home Assistant 重新启动后将不可用。
mosquitto_pub -r -h 127.0.0.1 -p 1883 -t "homeassistant/switch/irrigation/config" \
  -m '{"name": "Irrigation", "command_topic": "homeassistant/switch/irrigation/set", "state_topic": "homeassistant/switch/irrigation/state", "unique_id": "irr01ad", "device": {"identifiers": ["garden01ad"], "name": "Garden" }}'

设置状态：

mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/switch/irrigation/set" -m ON

使用缩写和基本主题

使用主题前缀和缩写配置变量名称设置开关以减少负载长度。

  • 配置主题：homeassistant/switch/irrigation/config
  • 命令主题：homeassistant/switch/irrigation/set
  • 状态主题：homeassistant/switch/irrigation/state
  • 配置负载：
{
   "~":"homeassistant/switch/irrigation",
   "name":"garden",
   "cmd_t":"~/set",
   "stat_t":"~/state"
}

使用缩写主题名称和基本主题的另一个示例

使用缩写配置变量名称设置 接收 JSON 负载的灯光：

  • 配置主题：homeassistant/light/kitchen/config

  • 命令主题：homeassistant/light/kitchen/set

  • 状态主题：homeassistant/light/kitchen/state

  • 示例状态负载：{"state": "ON", "brightness": 255}

  • 配置负载：

    {
  "~": "homeassistant/light/kitchen",
  "name": "Kitchen",
  "uniq_id": "kitchen_light",
  "cmd_t": "~/set",
  "stat_t": "~/state",
  "schema": "json",
  "brightness": true
}

使用缩写设备和来源信息的发现消息示例 

{
  "~": "homeassistant/light/kitchen",
  "name": null,
  "uniq_id": "kitchen_light",
  "cmd_t": "~/set",
  "stat_t": "~/state",
  "schema": "json",
  "dev": {
    "ids": "ea334450945afc",
    "name": "Kitchen",
    "mf": "Bla electronics",
    "mdl": "xya",
    "mdl_id": "ABC123",
    "sw": "1.0",
    "sn": "ea334450945afc",
    "hw": "1.0rev2"
  },
  "o": {
    "name":"bla2mqtt",
    "sw": "2.1",
    "url": "https://bla2mqtt.example.com/support"
  }
}

使用 object_id 影响实体 id

实体 id 是根据实体的名称自动生成的。所有 MQTT 集成都支持提供 object_id，如果提供，将使用它。

  • 配置主题：homeassistant/sensor/device1/config
  • 示例配置负载：
{
  "name":"My Super Device",
  "object_id":"my_super_device",
  "state_topic": "homeassistant/sensor/device1/state"
 }

在上面的示例中，entity_id 将是 sensor.my_super_device 而不是 sensor.device1。

第三方工具支持

以下软件内置支持 MQTT 发现：

以下软件还支持使用 Home Assistant 的 MQTT 发现信息。 兼容性和功能会有所不同，并非所有设备都能正常工作。

手动配置的 MQTT 项目

对于大多数集成，也可以在 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 中手动设置 MQTT 项目。阅读更多 关于 YAML 中的配置。

MQTT 支持两种样式的 YAML 配置项。所有配置项都直接放置在 mqtt 集成键下。请注意，不能混合使用这些样式。如果不确定，请使用 每个项目列出的 YAML 配置 样式。

每个项目列出的 YAML 配置

此方法期望所有项目都在 YAML 列表中。每个项目都有一个 {domain} 键，项目配置直接放置在域键下。此方法被认为是最佳实践。在所有示例中，我们使用此格式。

mqtt:
  - {domain}:
      name: ""
      ...
  - {domain}:
      name: ""
      ...

按 {domain} 键和捆绑的 YAML 配置

所有项目按 {domain} 分组，并列出所有配置。

mqtt:
  {domain}:
    - name: ""
      ...
    - name: ""
      ...

如果您有大量手动配置的项目，您可能需要考虑 拆分配置。

Note

支持 YAML 的 MQTT 组件文档 可以在此处找到。

实体状态更新

实体通过 MQTT 订阅接收状态更新。接收到状态主题上的负载后，将处理这些负载以确定是否存在显著变化。如果检测到变化，实体将更新。

请注意，MQTT 设备负载通常包含用于更新订阅相同主题的多个实体的信息。例如，灯光状态更新可能包含有关链接质量的信息。此数据可以更新链接质量传感器，但不会用于更新灯光本身。MQTT 会在没有变化时过滤掉实体状态更新。

最后报告的状态属性

由于 MQTT 状态更新通常频繁重复，即使没有实际变化，MQTT 订阅者需要确定是否接收到状态更新。如果错过了最新更新，可能需要一些时间才能收到下一个更新。如果 broker 上存在保留负载，则首先会重放该值，但这将是先前最后状态的更新。

MQTT 设备通常会连续生成大量状态更新。除非设置了 force_update，否则 MQTT 不会更新 last_reported 以避免影响系统稳定性。或者，可以创建一个 MQTT 传感器来测量最后一次更新。

使用模板

MQTT 集成支持模板。阅读更多 关于使用 MQTT 集成的模板。

示例

REST API

使用 REST API 向给定主题发送消息。

$ curl -X POST \
    -H "Authorization: Bearer ABCDEFGH" \
    -H "Content-Type: application/json" \
    -d '{"payload": "Test message from HA", "topic": "home/notification"}' \
    http://IP_ADDRESS:8123/api/services/mqtt/publish

自动化

在自动化中用作 script。

automation:
  alias: "Send me a message when I get home"
  triggers:
    - trigger: state
      entity_id: device_tracker.me
      to: "home"
  actions:
    - action: script.notify_mqtt
      data:
        target: "me"
        message: "I'm home"

script:
  notify_mqtt:
    sequence:
      - action: mqtt.publish
        data:
          payload: "{{ message }}"
          topic: home/"{{ target }}"
          retain: true

发布和转储操作

MQTT 集成将注册 mqtt.publish 操作，允许将消息发布到 MQTT 主题。

操作 mqtt.publish

数据属性 可选 描述
topic no 发布负载的主题。
payload yes 要发布的负载。省略 payload 时将发布空负载。
evaluate_payload yes 是否应评估 payload 中的 bytes 字面量以发布原始数据。（默认值：false）
qos yes 要使用的服务质量。（默认值：0）
retain yes 消息是否应设置保留标志。（默认值：false）

Note

当在 YAML 脚本或自动化中从 模板 渲染 payload 时，如果模板渲染为 bytes 字面量，则只有在 evaluate_payload 选项标志设置为 true 时，传出的 MQTT 负载才会作为 raw 数据发送。

topic: homeassistant/light/1/command
payload: on

topic: homeassistant/light/1/state
payload: "{{ states('device_tracker.paulus') }}"

topic: "homeassistant/light/{{ states('sensor.light_active') }}/state"
payload: "{{ states('device_tracker.paulus') }}"

请注意，payload 必须是字符串。 如果要使用 YAML 编辑器发送 JSON，则需要正确格式化/转义。 例如：

topic: homeassistant/light/1/state
payload: "{\"Status\":\"off\", \"Data\":\"something\"}"`

下面的示例显示了如何发布温度传感器“Bathroom Temperature”。 设置了 device_class，因此不需要设置“name”选项。实体 将从设置的 device_class 继承名称，并支持翻译。 如果在负载中设置“name”，实体名称将以设备名称开头。

action: mqtt.publish
data:
  topic: homeassistant/sensor/Acurite-986-1R-51778/config
  payload: >-
    {"device_class": "temperature",
    "unit_of_measurement": "\u00b0C",
    "value_template": "{{ value|float }}",
    "state_topic": "rtl_433/rtl433/devices/Acurite-986/1R/51778/temperature_C",
    "unique_id": "Acurite-986-1R-51778-T",
    "device": {
    "identifiers": "Acurite-986-1R-51778",
    "name": "Bathroom",
    "model": "Acurite",
    "model_id": "986",
    "manufacturer": "rtl_433" }
    }

使用 qos 和 retain 的示例：

topic: homeassistant/light/1/command
payload: on
qos: 2
retain: true

操作 mqtt.dump

监听指定的主题匹配器，并在特定持续时间内将所有接收到的消息转储到配置文件夹中的 mqtt_dump.txt 文件中。这在调试问题时非常有用。

数据属性 可选 描述
topic no 要转储的主题。可以包含通配符（# 或 +）。
duration yes 我们将监听消息的持续时间（以秒为单位）。默认值为 5 秒。 
topic: zigbee2mqtt/#

日志记录

logger 集成允许记录接收到的 MQTT 消息。

# 示例 configuration.yaml 条目
logger:
  default: warning
  logs:
    homeassistant.components.mqtt: debug

事件 event_mqtt_reloaded

事件 event_mqtt_reloaded 在手动配置的 MQTT 实体重新加载并且实体可能已更改时触发。

此事件没有附加数据。