2025.3.4
首页 ▸ Integrations ▸

MQTT 状态流

mqtt_statestream integration集成将 Home Assistant 与您的设备、服务等连接和集成。 [Learn more] 将 Home Assistant 中的状态变化发布到各个 MQTT 主题。MQTT 集成 是 MQTT 状态流正常工作的前提条件。

配置

要在 Home Assistant 中启用 MQTT 状态流，请在您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中添加以下部分。 在更改了configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件后，重启 Home Assistant 以应用更改。

# 示例 configuration.yaml 条目
mqtt_statestream:
  base_topic: homeassistant
  publish_attributes: true
  publish_timestamps: true

Configuration Variables

Looking for your configuration file?
base_topic string Required

用于生成实际发布主题的基础主题。

publish_attributes boolean (Optional, default: false)

发布实体的属性以及状态。

publish_timestamps boolean (Optional, default: false)

发布实体的 last_changed 和 last_updated 时间戳。

exclude list (Optional)

配置哪些集成应该从记录中排除。(配置过滤器)

entities list (Optional)

要从记录中排除的实体 ID 列表。

entity_globs list (Optional)

从记录中排除匹配列出模式的所有实体（例如，sensor.weather_*）。

domains list (Optional)

要从记录中排除的域列表。

include list (Optional)

配置哪些集成应该包含在记录中。如果设置，将不会记录所有其他实体。(配置过滤器)

entities list (Optional)

要包含在记录中的实体 ID 列表。

entity_globs list (Optional)

在记录中包含匹配列出模式的所有实体（例如，sensor.weather_*）。

domains list (Optional)

要包含在记录中的域列表。

配置过滤器

默认情况下，所有实体都不会被排除。要限制哪些实体被暴露给 MQTT 状态流，可以使用 include 和 exclude 参数。

# 示例过滤器以包含指定的域并排除指定的实体
mqtt_statestream:
  base_topic: homeassistant
  include:
    domains:
      - alarm_control_panel
      - light
    entity_globs:
      - binary_sensor.*_occupancy
  exclude:
    entities:
      - light.kitchen_light

Filters are applied as follows:

  1. 不使用过滤器
    • 包含所有实体
  2. 仅包含
    • 实体列表中的实体包含：include
    • 否则，实体匹配域包含：include
    • 否则，实体匹配通配符包含：include
    • 否则：排除
  3. 仅排除
    • 实体列表中的实体排除：exclude
    • 否则，实体匹配域排除：exclude
    • 否则，实体匹配通配符排除：exclude
    • 否则：包含
  4. 域和/或通配符包含（还可能有排除）
    • 实体列表中的实体包含：include
    • 否则，实体列表中的排除：exclude
    • 否则，实体匹配通配符包含：include
    • 否则，实体匹配通配符排除：exclude
    • 否则，实体匹配域包含：include
    • 否则：排除
  5. 域和/或通配符排除（没有域和/或通配符包含）
    • 实体列表中的实体包含：include
    • 否则，实体列表中的排除：exclude
    • 否则，实体匹配通配符排除：exclude
    • 否则，实体匹配域排除：exclude
    • 否则：包含
  6. 没有域和/或通配符的包含或排除
    • 实体列表中的实体包含：include
    • 否则：排除

以下字符可用于实体通配符：

* - 星号表示零个、一个或多个字符
? - 问号表示零个或一个字符

常见过滤示例 

# 排除实体的示例
mqtt_statestream:
  base_topic: homeassistant
  exclude:
    domains:
      - switch
    entities:
      - sensor.nopublish

在上面的示例中，除了 switch.x 和 sensor.nopublish，所有实体都将被发布到 MQTT。

# 排除实体的示例
mqtt_statestream:
  base_topic: homeassistant
  include:
    domains:
      - sensor
    entities:
      - lock.important

在此示例中，仅 sensor.x 和 lock.important 将被发布。

# 排除实体的示例
mqtt_statestream:
  base_topic: homeassistant
  include:
    domains:
      - sensor
  exclude:
    entities:
      - sensor.noshow

在此示例中，所有传感器除了 sensor.noshow 将被发布。

操作

当任何 Home Assistant 实体发生变化时，此集成将向 MQTT 发布该变化。

每个实体的主题是不同的，因此您可以轻松地仅订阅您感兴趣的实体。主题将采用 base_topic/domain/entity/state 的形式。

例如，在上述示例配置中，如果名为 ‘light.master_bedroom_dimmer’ 的实体被打开，则此集成将向 homeassistant/light/master_bedroom_dimmer/state 发布 on。

如果该实体还有一个名为 brightness 的属性，则集成还将发布该属性的值到 homeassistant/light/master_bedroom_dimmer/brightness。

所有状态和属性在发布前都会经过 JSON 序列化。请注意，这会导致字符串被引用（例如，字符串 ‘on’ 将被发布为 ‘“on”’）。您可以通过使用 value_json 而不是 value 在许多地方访问 JSON 反序列化值（以及未引用的字符串）。

实体的 last_updated 和 last_changed 值将分别发布到 homeassistant/light/master_bedroom_dimmer/last_updated 和 homeassistant/light/master_bedroom_dimmer/last_changed。时间戳采用 ISO 8601 格式 - 例如，2017-10-01T23:20:30.920969+00:00。

相关主题