首页 ▸ Integrations ▸

MQTT传感器

此 mqtt 传感器平台使用MQTT消息有效负载作为传感器值。如果在 state_topic 中发布带有 RETAIN 标志的消息，传感器将立即接收最后已知值的更新。否则，初始状态将是未定义的。

配置

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

# 示例 configuration.yaml 条目
mqtt:
  sensor:
    - name: "卧室温度"
      state_topic: "home/bedroom/temperature"

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主题。

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)

实体的分类。当设置时，实体类别必须为 diagnostic。

entity_picture string (Optional)

实体的图片URL。

expire_after integer (Optional, default: 0)

如果设置，它定义了传感器状态过期后（如果未更新）的秒数。过期后，传感器的状态变为 unavailable。默认情况下传感器状态永不过期。

force_update boolean (Optional, default: false)

即使值未更改也发送更新事件。如果您希望在历史中拥有有意义的值图形，那么这非常有用。

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)

订阅以接收JSON字典有效负载并然后设置为传感器属性的MQTT主题。在此主题上接收到消息时将隐含 force_update 当前传感器状态。

last_reset_value_template template (Optional)

Defines a template to extract the last_reset. When last_reset_value_template is set, the state_class option must be total. Available variables: entity_id. The entity_id can be used to reference the entity’s attributes.

name string (Optional, default: MQTT传感器)

MQTT传感器的名称。如果只有设备名称相关，则可以设置为 null。

object_id string (Optional)

用于自动生成 entity_id 时替代 name

options list (Optional)

允许的传感器状态值列表。不允许为空列表。传感器的 device_class 必须设置为 enum。 options 选项不能与 state_class 或 unit_of_measurement 一起使用。

payload_available string (Optional, default: online)

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

payload_not_available string (Optional, default: offline)

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

platform string Required

必须为 sensor。仅允许并在 MQTT自动发现设备消息中需要。

suggested_display_precision integer (Optional)

应在传感器状态中使用的十进制数，经过四舍五入后。

qos integer (Optional, default: 0)

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

state_class string (Optional)

传感器的 state_class。

state_topic string Required

订阅以接收传感器值的MQTT主题。如果设置了 device_class，state_class，unit_of_measurement 或 suggested_display_precision ，并且期望有数值，则会忽略空值 ''，并且不会更新状态，值为 'null' 将把传感器置为 unknown 状态。 device_class 可以为 null。

unique_id string (Optional)

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

unit_of_measurement string (Optional)

定义传感器的测量单位（如果有的话）。 unit_of_measurement 可以为 null。

value_template template (Optional)

Defines a template to extract the value. If the template throws an error, the current state will be used instead.

示例

在本节中，您会找到一些实际示例，展示如何使用此传感器。

处理Unix EPOCH时间戳

下面的示例展示了MQTT传感器如何处理Unix EPOCH有效负载。

通过YAML设置：

# 示例 configuration.yaml 条目
mqtt:
  sensor:
    - name: "开启时间"
      state_topic: "pump/timestamp_on"
      device_class: "timestamp"
      value_template: "{{ as_datetime(value) }}"
      unique_id: "hp_1231232_ts_on"
      device:
        name: "热泵"
        identifiers:
          - "hp_1231232"

或通过MQTT发现设置：

发现主题： homeassistant/sensor/hp_1231232/config

{
  "name": "开启时间",
  "state_topic": "pump/timestamp_on",
  "device_class": "timestamp",
  "value_template": "{{ as_datetime(value) }}",
  "unique_id": "hp_1231232_ts_on",
  "device": {
    "name": "热泵",
    "identifiers": [
      "hp_1231232"
    ]
  }
}

要进行测试，您可以使用与 mosquitto 一起提供的命令行工具 mosquitto_pub 或 mosquitto-clients 包发送MQTT消息。

有效负载主题： pump/timestamp_on 有效负载： 1707294116

要手动设置传感器的状态：

mosquitto_pub -h 127.0.0.1 -p 1883 -u username -P some_password -t pump/timestamp_on -m '1707294116'

确保使用您的MQTT代理的IP地址，并且用户凭据已正确设置。

value_template 将Unix EPOCH时间戳渲染为正确的格式：2024-02-07 08:21:56+00:00。

JSON属性主题配置

下面的示例传感器展示了一个配置示例，它使用以下单独的主题和JSON结构来添加额外属性。

主题： home/sensor1/attributes

{
   "ClientName": <string>,
   "IP": <string>,
   "MAC": <string>,
   "RSSI": <string>,
   "HostName": <string>,
   "ConnectedSSID": <string>
}

它还利用了 availability 主题。

额外属性将在前端显示，并且还可以在模板中提取。例如，要从下面的传感器中提取 ClientName 属性，请使用类似的模板： {{ state_attr('sensor.bs_rssi', 'ClientName') }}。

# 示例 configuration.yaml 条目
mqtt:
  sensor:
    - name: "RSSI"
      state_topic: "home/sensor1/infojson"
      unit_of_measurement: "dBm"
      value_template: "{{ value_json.RSSI }}"
      availability:
        - topic: "home/sensor1/status"
      payload_available: "online"
      payload_not_available: "offline"
      json_attributes_topic: "home/sensor1/attributes"

JSON属性模板配置

下面的示例传感器展示了一个配置示例，它使用以下主题和JSON结构以及模板，将 Timer1.Arm 和 Timer1.Time 作为额外属性添加。

主题： tele/sonoff/sensor

{
    "Timer1": {
        "Arm": <status>,
        "Time": <time>
    },
    "Timer2": {
        "Arm": <status>,
        "Time": <time>
    }
}

要仅将 Timer1.Arm 添加为额外属性，请将 json_attributes_template 更改为： "{{ {'Arm': value_json.Timer1} | tojson }}"。

额外属性将在前端显示，并且还可以在模板中提取。例如，要从下面的传感器中提取 Arm 属性，请使用类似的模板： {{ state_attr('sensor.timer1', 'Arm') }}。

# 示例 configuration.yaml 条目
mqtt:
  sensor:
    - name: "定时器 1"
      state_topic: "tele/sonoff/sensor"
      value_template: "{{ value_json.Timer1.Arm }}"
      json_attributes_topic: "tele/sonoff/sensor"
      json_attributes_template: "{{ value_json.Timer1 | tojson }}"

    - name: "定时器 2"
      state_topic: "tele/sonoff/sensor"
      value_template: "{{ value_json.Timer2.Arm }}"
      json_attributes_topic: "tele/sonoff/sensor"
      json_attributes_template: "{{ value_json.Timer2 | tojson }}"

Warning

如果 json_attributes_topic 和 state_topic 共享相同的主题，则状态更新将只发生一次，除非状态更新未更改状态或将 force_update 设置为 true。

建议避免设置包含在每次更新中变化的值（如时间戳）的MQTT传感器，其额外状态属性，或者启用 force_update 选项，因为这将触发每次更新的状态写入。这可能会对整体系统性能产生严重影响。更好的选择是创建单独的传感器。

在模板中使用 entity_id

下面的示例展示了如何在模板中实现一个简单的滤波器，通过将新值的90%和前一个值的10%相加来计算值。

# 示例 configuration.yaml 条目
mqtt:
  sensor:
    - name: "温度 1"
      state_topic: "sensor/temperature"
      value_template: |-
        {% if states(entity_id) == None %}
          {{ value | round(2) }}
        {% else %}
          {{ value | round(2) * 0.9 + states(entity_id) * 0.1 }}
        {% endif %}

Owntracks电池电量传感器

如果您使用 OwnTracks 并启用电池电量的报告，则可以使用MQTT传感器来跟踪您的电池。来自OwnTracks的常规MQTT消息如下所示：

主题： owntracks/tablet/tablet

{
    "_type": "location",
    "lon": 7.21,
    "t": "u",
    "batt": 92,
    "tst": 144995643,
    "tid": "ta",
    "acc": 27,
    "lat": 46.12
} 

因此，技巧是从有效负载中提取电池电量。

# 示例 configuration.yaml 条目
mqtt:
  sensor:
    - name: "平板电池"
      state_topic: "owntracks/tablet/tablet"
      unit_of_measurement: "%"
      value_template: "{{ value_json.batt }}"

温度和湿度传感器

如果您使用DHT传感器和NodeMCU板（esp8266），可以使用MQTT传感器获取温度和湿度。可以在这里找到代码示例。来自此示例的常规MQTT消息如下所示：

主题： office/sensor1

  {
    "temperature": 23.20,
    "humidity": 43.70
  }

然后使用以下配置示例从有效负载中提取数据：

# 示例 configuration.yaml 条目
mqtt:
  sensor:
    - name: "温度"
      state_topic: "office/sensor1"
      suggested_display_precision: 1
      unit_of_measurement: "°C"
      value_template: "{{ value_json.temperature }}"
    - name: "湿度"
      state_topic: "office/sensor1"
      unit_of_measurement: "%"
      value_template: "{{ value_json.humidity }}"

从带有ESPEasy的设备获取传感器值

假设您已用 ESPEasy 刷写了您的ESP8266单元。在“配置”下为您的设备设置一个名称（“单元名称：”）。存在一个MQTT的“控制器”，其协议为“OpenHAB MQTT”，并且条目（“控制器订阅：”和“控制器发布：”）已调整以满足您的需要。在此示例中，主题以“home”作为前缀。请记住，ESPEasy默认主题以 / 开头，并且在为 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件编写条目时仅包含名称。

控制器订阅： home/%sysname%/# （而不是 /%sysname%/#）
控制器发布： home/%sysname%/%tskname%/%valname% （而不是 /%sysname%/%tskname%/%valname%）

另外，在“设备”标签下添加一个名称为“analog”的传感器，值为“brightness”。

一旦单元在线，您将获得传感器的状态。

home/bathroom/status Connected
...
home/bathroom/analog/brightness 290.00

配置将如下所示：

# 示例 configuration.yaml 条目
mqtt:
  sensor:
    - name: "亮度"
      state_topic: "home/bathroom/analog/brightness"

帮助我们改进翻译

建议编辑此页面，或提供/查看此页面的反馈。

编辑提供反馈查看待处理的反馈