2025.3.4
首页 ▸ Integrations ▸

MQTT 选择

mqtt 选择平台允许您将可能通过 MQTT 暴露配置选项的设备集成到 Home Assistant 作为一个选择。每当接收到配置中的 topic 下的消息时，选择实体将在 Home Assistant 中更新，反之亦然，保持设备和 Home Assistant 同步。

配置

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

# 示例 configuration.yaml 条目
mqtt:
  - select:
      command_topic: topic
      name: "测试选择"
      options:
        - "选项 1"
        - "选项 2"

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_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)

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.

command_template template (Optional)

Defines a template to generate the payload to send to command_topic.

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 list | string (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.

json_attributes_topic string (Optional)

订阅 MQTT 主题以接收 JSON 字典有效负载，然后将其设置为实体属性。在该主题上接收到消息时，隐含 force_update 当前选择状态。

name string (Optional)

选择的名称。如果仅设备名称相关，可以设置为 null。

object_id string (Optional)

用于自动生成 entity_id 的代替 name

optimistic boolean (Optional)

定义选择是否以乐观模式工作的标志。

Default:

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

options list Required

可以选择的选项列表。允许空列表或包含单个项目的列表。

platform string Required

必须为 select。仅在 MQTT 自动发现设备消息 中允许和必需。

qos integer (Optional, default: 0)

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

retain boolean (Optional, default: false)

发布的消息是否应该开启保留标志。

state_topic string (Optional)

订阅 MQTT 主题以接收所选选项的更新。“None” 有效负载重置为 unknown 状态。空有效负载将被忽略。

unique_id string (Optional)

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

value_template template (Optional)

Defines a template to extract the value.

Important

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