2025.3.4
首页 ▸ Integrations ▸

MQTT 开关

mqtt 开关平台让您控制支持 MQTT 的开关。

配置

在理想情况下，MQTT 设备将拥有一个 state_topic 来发布状态变化。如果这些消息使用 RETAIN 标志发布，MQTT 开关将在订阅后接收到即时状态更新，并将以正确的状态开始。否则，开关的初始状态将为 unknown。MQTT 设备可以使用 None 负载将当前状态重置为 unknown。

当 state_topic 不可用时，开关将在乐观模式下工作。在此模式下，每个命令后开关都会立即改变状态。否则，开关将等待来自设备的状态确认（来自 state_topic 的消息）。乐观模式下，初始状态设置为 False / off。

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

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

# 示例 configuration.yaml 条目
mqtt:
  - switch:
      command_topic: "home/bedroom/switch1/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 时，这控制了将实体设置为可用所需的条件。有效条目为 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 一起使用。

command_template template (Optional)

Defines a template to generate the payload to send to command_topic. The switch command template accepts the parameters value. The value parameter will contain the configured value for either payload_on or payload_off.

command_topic string Required

用于发布命令以更改开关状态的 MQTT 主题。

device map (Optional)

有关此开关所隶属设备的信息，以将其绑定到 设备注册表。仅在设置了 unique_id 时有效。必须存在标识符或连接中的至少一个以识别设备。

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 中显示设备拓扑。

device_class device_class (Optional)

开关的 类型/类，用于在前端设置图标。device_class 可以是 null。

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)

订阅以接收 JSON 字典负载的 MQTT 主题，然后将其设置为传感器属性。使用示例请参见 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

必须为 switch。仅在 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 主题。“None” 负载将重置为 unknown 状态。空负载将被忽略。默认情况下，有效状态负载为 OFF 和 ON。可以使用 payload_off 和 payload_on 配置选项覆盖接受的负载。

unique_id string (Optional)

唯一标识此开关设备的 ID。如果两个开关具有相同的唯一 ID，Home Assistant 将引发异常。在设备基础的发现中是必需的。

value_template template (Optional)

Defines a template to extract device’s state from the state_topic. To determine the switches’s state result of this template will be compared to state_on and state_off.

Important

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

示例

在本节中，您将找到一些如何使用此传感器的真实示例。

完整配置

下面的示例显示了开关的完整配置。

# 示例 configuration.yaml 条目
mqtt:
  - switch:
      unique_id: bedroom_switch
      name: "卧室开关"
      state_topic: "home/bedroom/switch1"
      command_topic: "home/bedroom/switch1/set"
      availability:
        - topic: "home/bedroom/switch1/available"
      payload_on: "ON"
      payload_off: "OFF"
      state_on: "ON"
      state_off: "OFF"
      optimistic: false
      qos: 0
      retain: true

为了进行检查，您可以使用随 mosquitto 附带的命令行工具 mosquitto_pub 发送 MQTT 消息。这使您能够手动操作您的开关。首先，我们可以模拟发送给开关的可用性消息：

mosquitto_pub -h 127.0.0.1 -t home/bedroom/switch1/available -m "online"

我们可以通过发布 ON 命令消息来模拟开关打开：

mosquitto_pub -h 127.0.0.1 -t home/bedroom/switch1/set -m "ON"

最后，我们可以模拟开关向 Home Assistant 报告更改的状态：

mosquitto_pub -h 127.0.0.1 -t home/bedroom/switch1 -m "ON"

使用 ESPEasy 设置设备状态

假设您已经用 ESPEasy 刷写了您的 ESP8266 单元。在“配置”下设置了设备的名称（“单元名称：”），这里是“浴室”。存在一个用于 MQTT 的“控制器”配置，协议为“OpenHAB MQTT”，并且条目（“控制器订阅：”和“控制器发布：”）已调整以满足您的需求。在此示例中，主题以“home”为前缀。由于 GPIO 可以直接通过 MQTT 控制，因此无需进一步配置。

您可以使用 mosquitto_pub 或其他 MQTT 工具手动将引脚 13 设置为高：

mosquitto_pub -h 127.0.0.1 -t home/bathroom/gpio/13 -m "1"

配置将如下所示：

# 示例 configuration.yaml 条目
mqtt:
  - switch:
      name: 浴室
      state_topic: "home/bathroom/gpio/13"
      command_topic: "home/bathroom/gpio/13"
      payload_on: "1"
      payload_off: "0"