2025.3.4
首页 ▸ Integrations ▸

MQTT 文本

mqtt 文本平台允许您集成可以远程设置文本的设备。可选地，也可以使用 MQTT 监控文本状态。

配置

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

# 示例 configuration.yaml 条目
mqtt:
  - text:
      command_topic: command-topic

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。

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)

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

max integer (Optional, default: 255)

设置或接收的文本的最大大小（最大为 255）。

min integer (Optional, default: 0)

设置或接收的文本的最小大小。

mode string (Optional, default: text)

文本实体的模式。必须是 text 或 password。

name string (Optional, default: MQTT 文本)

文本实体的名称。如果仅设备名称相关，可以设置为 null。

object_id string (Optional)

用于自动生成 entity_id 的替代 name

pattern string (Optional)

设置或接收的文本必须匹配的有效正则表达式。

platform string Required

必须是 text。仅在 MQTT 自动发现设备消息 中允许并且是必需的。

qos integer (Optional, default: 0)

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

retain boolean (Optional, default: false)

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

state_topic string (Optional)

订阅以接收文本状态更新的 MQTT 主题。文本状态更新应匹配 pattern（如果设置），并满足大小约束 min 和 max。可以与 value_template 一起使用，将传入有效负载渲染为文本更新。

unique_id string (Optional)

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

value_template template (Optional)

Defines a template to extract the text state value from the payload received on state_topic.

Important

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

示例

这是一个手动配置的 MQTT text 项的示例。

# 示例 configuration.yaml 条目
mqtt:
  - text:
      name: "远程 LCD 屏幕"
      icon: mdi:ab-testing
      mode: "text"
      command_topic: "txt/cmd"
      state_topic: "txt/state"
      min: 2
      max: 20