Platform Home Assistant "MQTT Sensor”

3 minutes of reading
Proconductor: Home Assistant Community
Availability: included in thepersonale HUB Home Assistant
Category: software
Type: platform Home Assistant
Family: component "Sensor” Home Assistant
Implementation difficulties: low
Card revision: 1.1

The “MQTT Sensor”, daughter of the component "Sensor” di Home Assistant, serves to define in configuration one or more sensors powered by MQTT telemetry procoming from one or more home automation devices.

In fact, they exist sensors that, if questioned through MQTT, provide the proreadings (temperature, humidity, but also lumistrength, presence, level of charge of batteries and much more) through i payload of the telemetric topics dedicated to this purpose. Furthermore, such telemetry is usually published automatically and cyclically via MQTT, allowing those who subscribe to these telemetric topics to obtain readings as they arrive.

An example of telemetric topic, in the case of a Sonoff TH-16 or TH-10 updated to Tasmota is the following:


This topic returns via the proprio payload (or "payload") the readings of the sensor connected to the unit, typically temperature and humidity, for example (JSON payload):

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

Nb. To use this platform it is necessary that the "MQTT" component of Home Assistant has been previously configured (see first part of the card dedicated to the "MQTT" component). We also recommend to read carefully the guide dedicated to the theme of configuration of the MQTT components in the profirst home automation.


the configuration basis of any MQTT sensor in the file configuration.yaml it's pretty simple.
It is sufficient to insert an entry of this type:

- platform: mqtt
  state_topic: "home/bedroom/temperature"

where the example of "home / bedroom / temperature”Will evidently be the telemetric topic of which to collect the payload for the extraction of the information of interest.

The variables available for configuration customization are the following:

state_topic(string, request) - The MQTT topic to which to register to receive telemetry
name(string, optional) - Name of the MQTT sensor. Default: "MQTT Sensor”
qos(integer, optional) - The QoS level for the state_topic. Default: 0 (What is QoS?)
unit_of_measurement(string, optional) - The unit of measurement of the value displayed by the sensor, if present.
icon(string, optional) - The r iconappresentativa of the sensor.
expire_after(integer, optional) - The number of seconds after which, in the absence of receipt of a new value, the data is no longer considered valid. Default: 0 (not active)
value_template(template, optional) - Defines the template for the extraction (parsing) of the data.
force_update(Boolean, optional) - Send to the automation engine of Home Assistant the Update Searchnameof value even if it did not actually happen. Useful to keep historians graphs constant. Default: false
availability_topic(string, optional) - Topic MQTT to which to register to get the device online / offline status. Usually the topic is used LWT.
payload_available(string, optional) - The payload that rappit returns the "available" status. Example: "online". It is used in abbinameto the variable "availability_topic". Usually a payload is used LWT.
payload_not_available(string, optional) - The payload that rappit returns the status "not available". Example: "offline". It is used in abbinameto the variable "availability_topic". Usually a payload is used LWT.
json_attributes(list | string, optional) - A list of key values ​​to extract from the state_topic json payload.
unique_id(string, optional) - An ID that uniquely identifies the sensor in terms of configuration. If two sensors have the same ID, Home Assistant raises an error exception.
device_class(device_class, optional) - The type / class of sensor useful for setting the correct, relative icon on the frontend of Home Assistant.



The sensor of the following example extracts from the payload JSON received by state_topic indicated the measurement of the remaining battery of the monitored device. Specifically, we assume we are using the platform OWNTRACKS of the component family “Device Tracker", Or those dedicated to users' GPS tracking configured on Home Assistant.

Lo state_topic is the following:


The payload is similar to the following


For take out the battery level (or "92%"), the configured MQTT sensor will be:

  - platform: mqtt
    name: "Battery Tablet"
    state_topic: "owntracks/tablet/tablet"
    unit_of_measurement: '%'
    value_template: "{{ value_json.batt }}"
Temperature and humidity

Let us assume that you have a temperature and humidity sensor that you state_topic:


produke in the payload a JSON telemetry as follows:

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

We will therefore configure two different sensors, as follows:

  - platform: mqtt
    name: "Temperature"
    state_topic: "office/sensor1"
    unit_of_measurement: '°C'
    value_template: "{{ value_json.temperature }}"
  - platform: mqtt
    name: "Humidity"
    state_topic: "office/sensor1"
    unit_of_measurement: '%'
    value_template: "{{ value_json.humidity }}"

Home Assistant Official LogoATTENZIONE: remember that there is on our FORUM community an ad hoc section dedicated to Home Assistant, for any doubt, question, information on the specific merit of these components.

Please comment below