2025.3.4
首页 ▸ Integrations ▸

MQTT 警报器

mqtt 警报器平台允许您控制启用 MQTT 的警报器和基于文本的通知设备。

配置

在理想情况下，MQTT 设备将具有一个 state_topic 来发布状态变化。如果这些消息带有 RETAIN 标志发布，MQTT 警报器将在订阅后接收即时状态更新，并将以正确的状态开始。否则，警报器的初始状态将为 false / off。

当 state_topic 不可用时，警报器将在乐观模式下工作。在此模式下，警报器将在每个命令后立即更改状态。否则，警报器将等待来自设备的状态确认（来自 state_topic 的消息）。

即使 state_topic 可用，也可以强制使用乐观模式。如果您遇到不正确的操作，请尝试启用它。

要在您的安装中启用此警报器，请将以下内容添加到您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中：

# 示例 configuration.yaml 条目
mqtt:
  - siren:
      command_topic: "home/bedroom/siren/set"

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)

Defines a template to extract device’s availability from the topic. To determine the devices’s availability result of this template will be compared to payload_available and payload_not_available.

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)

Defines a template to extract device’s availability from the availability_topic. To determine the devices’s availability result of this template will be compared to payload_available and payload_not_available.

availability_topic string (Optional)

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

available_tones list (Optional)

警报器支持的可用音调列表。当配置时，这将启用设置 tone 的支持，并启用 tone 状态属性。

command_template template (Optional)

Defines a template to generate a custom payload to send to command_topic. The variable value will be assigned with the configured payload_on or payload_off setting. The siren turn on action parameters tone, volume_level or duration can be used as variables in the template. When operation in optimistic mode the corresponding state attributes will be set. Turn on parameters will be filtered if a device misses the support.

command_off_template template (Optional)

Defines a template to generate a custom payload to send to command_topic when the siren turn off action is called. By default command_template will be used as template for action turn off. The variable value will be assigned with the configured payload_off setting.

command_topic string (Optional)

发表用于更改警报器状态的命令的 MQTT 主题。没有命令模板时，会发布默认 JSON 有效负载，如 {"state":"ON", "tone": "bell", "duration": 10, "volume_level": 0.5 }。当执行警报器开启操作时，启动参数将被添加到 JSON 有效负载中。JSON 有效负载的 state 值将设置为配置的 payload_on 或 payload_off 有效负载。

device map (Optional)

关于该警报器所所属设备的信息，以将其绑定到 设备注册表。仅在设置了 unique_id 时有效。必须至少提供 identifiers 或 connections 之一以识别设备。

configuration_url string (Optional)

可以管理此设备配置的网页链接。可以是 http://，https:// 或内部 homeassistant:// URL。

connections list (Optional)

设备与外界连接的列表，作为元组 [connection_type, connection_identifier] 的列表。例如网络接口的 MAC 地址："connections": [["mac", "02:5b:26:a8:dc:12"]]。

hw_version string (Optional)

设备的硬件版本。

identifiers string | list (Optional)

唯一标识设备的 ID 列表。例如序列号。

manufacturer string (Optional)

设备的制造商。

model string (Optional)

设备的型号。

model_id string (Optional)

设备的型号标识符。

name string (Optional)

设备的名称。

serial_number string (Optional)

设备的序列号。

suggested_area string (Optional)

如果设备尚未在某一区域，建议一个区域。

sw_version string (Optional)

设备的固件版本。

via_device string (Optional)

路由此设备与 Home Assistant 之间消息的设备标识符。这类设备的实例有集线器，或子设备的父设备。此标识符用于在 Home Assistant 中显示设备拓扑。

enabled_by_default boolean (Optional, default: true)

定义在首次添加时实体是否应启用的标志。

encoding string (Optional, default: utf-8)

接收和发布消息的有效负载的编码。设置为 "" 以禁用传入有效负载的解码。

entity_category string (Optional)

实体的 类别。

entity_picture string (Optional)

实体的图片URL。

icon icon (Optional)

图标 用于实体。

json_attributes_template template (Optional)

Defines a template to extract the JSON dictionary from messages received on the json_attributes_topic. Usage example can be found in MQTT sensor documentation.

json_attributes_topic string (Optional)

订阅的 MQTT 主题，用于接收 JSON 字典有效负载，然后设置为传感器属性。用法示例可以在 MQTT 传感器 文档中找到。

name string (Optional, default: MQTT 警报器)

显示此警报器时使用的名称。如果仅设备名称相关，可以设置为 null。

object_id string (Optional)

用于自动生成 entity_id 的替代 name

optimistic boolean (Optional)

定义警报器是否在乐观模式下工作的标志。

Default:

true 如果未定义 state_topic，否则为 false。

payload_available string (Optional, default: online)

表示可用状态的有效负载。

payload_not_available string (Optional, default: offline)

表示不可用状态的有效负载。

payload_off string (Optional, default: OFF)

表示 off 状态的有效负载。如果指定，将用于与 state_topic 中的值进行比较（详细信息见 value_template 和 state_off）并发送为 off 命令到 command_topic。

payload_on string (Optional, default: ON)

表示 on 状态的有效负载。如果指定，将用于与 state_topic 中的值进行比较（详细信息见 value_template 和 state_on），并发送为 on 命令到 command_topic。

platform string Required

必须为 siren。仅在 MQTT 自动发现设备消息 中被允许和要求。

qos integer (Optional, default: 0)

接收和发布消息时使用的最大 QoS 级别。

retain boolean (Optional, default: false)

发布的消息是否应该具有保留标志。

state_off string (Optional)

表示 off 状态的有效负载。当 state_topic 中表示 off 状态的值与应发送到 command_topic 的值不同。

Default:

payload_off 如果定义，则为 'OFF'

state_on string (Optional)

表示 on 状态的有效负载。当 state_topic 中表示 on 状态的值与应发送到 command_topic 的值不同。

Default:

payload_on 如果定义，则为 'ON'

state_topic string (Optional)

订阅的 MQTT 主题，以接收状态更新。状态更新可以是 JSON 或简单字符串。当检测到 JSON 有效负载时，JSON 有效负载的 state 值应提供 payload_on 或 payload_off 定义的有效负载，以打开或关闭警报器。此外，状态属性 duration、tone 和 volume_level 可以更新。使用 value_template 将接收到的状态更新转换为符合的 JSON 有效负载。仅在设备支持该功能并提供有效值时，属性才会被设置。当检测到非 JSON 有效负载时，它应为定义的 payload_on 或 payload_off 中的一个有效负载，或者为 None 以将警报器的状态重置为 unknown。初始状态将为 unknown。如果接收到 None 有效负载或 null JSON 值作为状态更新，状态将重置为 unknown。

state_value_template template (Optional)

Defines a template to extract device’s state from the state_topic. To determine the siren’s state result of this template will be compared to state_on and state_off. Alternatively value_template can be used to render to a valid JSON payload.

support_duration boolean (Optional, default: true)

如果 MQTT 警报器支持 duration 开启操作参数并启用 duration 状态属性，则设置为 true。

support_volume_set boolean (Optional, default: true)

如果 MQTT 警报器支持 volume_set 开启操作参数并启用 volume_level 状态属性，则设置为 true。

unique_id string (Optional)

唯一标识此警报器设备的 ID。如果两个警报器具有相同的唯一 ID，Home Assistant 将引发异常。在使用基于设备的发现时必需。

Important

确保您的主题完全匹配。 some-topic/ 和 some-topic 是不同的主题。

示例

在本节中，您将找到使用此警报器平台的示例。

完整配置

下面的示例显示了警报器的完整配置。

# 示例 configuration.yaml 条目
mqtt:
  - siren:
      unique_id: custom_siren
      name: "入侵警报器"
      state_topic: "home/alarm/siren1"
      command_topic: "home/alarm/siren1/set"
      available_tones:
        - ping
        - siren
      availability:
        - topic: "home/alarm/siren1/available"
      payload_on: "ON"
      payload_off: "OFF"
      state_on: "ON"
      state_off: "OFF"
      optimistic: false
      qos: 0
      retain: true

仅打开/关闭的控制 Tasmota 继电器的警报器

下面的示例显示了一种不接受 JSON 命令的打开/关闭类型警报器的配置。

# 示例 configuration.yaml 条目
mqtt:
  - siren:
      unique_id: tasmota_siren
      name: "车库"
      state_topic: "stat/SIREN/RESULT"
      command_topic: "cmnd/SIREN/POWER"
      availability_topic: "tele/SIREN/LWT"
      command_template: "{{ value }}"
      state_value_template: "{{ value_json.POWER }}"
      payload_on: "ON"
      payload_off: "OFF"
      payload_available: "在线"
      payload_not_available: "离线"

为了检查，您可以使用与 mosquitto 一起提供的命令行工具 mosquitto_pub 发送 MQTT 消息。这允许您手动操作您的警报器：

mosquitto_pub -h 127.0.0.1 -t home/alarm/siren1 -m "ON"