diff --git a/source/_integrations/alarm_control_panel.mqtt.markdown b/source/_integrations/alarm_control_panel.mqtt.markdown index 674744ff142..761e60b4164 100644 --- a/source/_integrations/alarm_control_panel.mqtt.markdown +++ b/source/_integrations/alarm_control_panel.mqtt.markdown @@ -177,7 +177,7 @@ json_attributes_topic: required: false type: string name: - description: The name of the alarm. + description: The name of the alarm. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT Alarm diff --git a/source/_integrations/binary_sensor.mqtt.markdown b/source/_integrations/binary_sensor.mqtt.markdown index bbb8a6020cf..26967f0510e 100644 --- a/source/_integrations/binary_sensor.mqtt.markdown +++ b/source/_integrations/binary_sensor.mqtt.markdown @@ -155,7 +155,7 @@ json_attributes_topic: required: false type: string name: - description: The name of the binary sensor. + description: The name of the binary sensor. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT Binary Sensor diff --git a/source/_integrations/button.mqtt.markdown b/source/_integrations/button.mqtt.markdown index 8dbdf862597..259746f7b16 100644 --- a/source/_integrations/button.mqtt.markdown +++ b/source/_integrations/button.mqtt.markdown @@ -145,7 +145,7 @@ json_attributes_topic: required: false type: string name: - description: The name to use when displaying this button. + description: The name to use when displaying this button. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT Button diff --git a/source/_integrations/camera.mqtt.markdown b/source/_integrations/camera.mqtt.markdown index aa9537404e4..4e09c0bad5a 100644 --- a/source/_integrations/camera.mqtt.markdown +++ b/source/_integrations/camera.mqtt.markdown @@ -146,7 +146,7 @@ json_attributes_topic: required: false type: string name: - description: The name of the camera. + description: The name of the camera. Can be set to `null` if only the device name is relevant. required: false type: string object_id: diff --git a/source/_integrations/climate.mqtt.markdown b/source/_integrations/climate.mqtt.markdown index 075c78eb316..ed249fd213e 100644 --- a/source/_integrations/climate.mqtt.markdown +++ b/source/_integrations/climate.mqtt.markdown @@ -236,7 +236,7 @@ modes: default: ['auto', 'off', 'cool', 'heat', 'dry', 'fan_only'] type: list name: - description: The name of the HVAC. + description: The name of the HVAC. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT HVAC diff --git a/source/_integrations/cover.mqtt.markdown b/source/_integrations/cover.mqtt.markdown index 487db0c79b7..b42a4230b2d 100644 --- a/source/_integrations/cover.mqtt.markdown +++ b/source/_integrations/cover.mqtt.markdown @@ -157,7 +157,7 @@ json_attributes_topic: required: false type: string name: - description: The name of the cover. + description: The name of the cover. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT Cover diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index e32e426c354..c6a4f87daf3 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -147,7 +147,7 @@ json_attributes_topic: required: false type: string name: - description: The name of the fan. + description: The name of the fan. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT Fan diff --git a/source/_integrations/humidifier.mqtt.markdown b/source/_integrations/humidifier.mqtt.markdown index f0ebdb99f53..f0204270dd5 100644 --- a/source/_integrations/humidifier.mqtt.markdown +++ b/source/_integrations/humidifier.mqtt.markdown @@ -181,7 +181,7 @@ min_humidity: type: integer default: 0 name: - description: The name of the humidifier. + description: The name of the humidifier. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT humidifier diff --git a/source/_integrations/image.mqtt.markdown b/source/_integrations/image.mqtt.markdown index efe74f16070..f2fa9c9ee6e 100644 --- a/source/_integrations/image.mqtt.markdown +++ b/source/_integrations/image.mqtt.markdown @@ -159,7 +159,7 @@ json_attributes_topic: required: false type: string name: - description: The name of the image. + description: The name of the image. Can be set to `null` if only the device name is relevant. required: false type: string object_id: diff --git a/source/_integrations/light.mqtt.markdown b/source/_integrations/light.mqtt.markdown index e8ec82a8a01..9b3987a16c9 100644 --- a/source/_integrations/light.mqtt.markdown +++ b/source/_integrations/light.mqtt.markdown @@ -257,7 +257,7 @@ min_mireds: required: false type: integer name: - description: The name of the light. + description: The name of the light. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT Light diff --git a/source/_integrations/lock.mqtt.markdown b/source/_integrations/lock.mqtt.markdown index 0d7370dffc2..b1d2af6e785 100644 --- a/source/_integrations/lock.mqtt.markdown +++ b/source/_integrations/lock.mqtt.markdown @@ -154,7 +154,7 @@ json_attributes_topic: required: false type: string name: - description: The name of the lock. + description: The name of the lock. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT Lock diff --git a/source/_integrations/mqtt.markdown b/source/_integrations/mqtt.markdown index 2c9c861a228..10e550c4ef9 100644 --- a/source/_integrations/mqtt.markdown +++ b/source/_integrations/mqtt.markdown @@ -188,6 +188,25 @@ For reading all messages sent on the topic `homeassistant` to a broker running o mosquitto_sub -h 127.0.0.1 -v -t "homeassistant/#" ``` +## Sharing of device configuration + +MQTT entities can share device configuration, meaning one entity can include the full device configuration and other entities can link to that device by only setting mandatory fields. +The mandatory fields were previously limited to at least one of `connection` and `identifiers`, but have now been extended to at least one of `connection` and `identifiers` as well as the `name`. + +## Naming of MQTT Entities + +For every configured MQTT entity Home Assistant automatically assigns a unique `entity_id`. If the `unique_id` option is configured, you can change the `entity_id` after creation, and the changes are stored in the Entity Registry. The `entity_id` is generated when an item is loaded the first time. + +If the `object_id` option is set, then this will be used to generate the `entity_id`. +If, for example, we have configured a `sensor`, and we have set `object_id` to `test`, then Home Assistant will try to assign `sensor.test` as `entity_id`, but if this `entity_id` already exits it will append it with a suffix to make it unique, for example, `sensor.test_2`. + +This means any MQTT entity which is part of a device will [automatically have it's `friendly_name` attribute prefixed with the device name](https://developers.home-assistant.io/docs/core/entity/#has_entity_name-true-mandatory-for-new-integrations) + +Unnamed `binary_sensor`, `button`, `number` and `sensor` entities will now be named by their device class instead of being named "MQTT binary sensor" etc. +It's allowed to set an MQTT entity's name to `None` (use `null` in YAML) to mark it as the main feature of a device. + +Note that on each MQTT entity, the `has_entity_name` attribute will be set to `True`. More details [can be found here](https://developers.home-assistant.io/docs/core/entity/#has_entity_name-true-mandatory-for-new-integrations). + ## MQTT Discovery The discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](/integrations/http/#binary-sensor) and the [HTTP sensor](/integrations/http/#sensor). To prevent multiple identical entries if a device reconnects, a unique identifier is necessary. Two parts are required on the device side: The configuration topic which contains the necessary device type and unique identifier, and the remaining device configuration without the device type. diff --git a/source/_integrations/number.mqtt.markdown b/source/_integrations/number.mqtt.markdown index 3443d36623b..77e759a8449 100644 --- a/source/_integrations/number.mqtt.markdown +++ b/source/_integrations/number.mqtt.markdown @@ -154,7 +154,7 @@ mode: type: string default: '"auto"' name: - description: The name of the Number. + description: The name of the Number. Can be set to `null` if only the device name is relevant. required: false type: string object_id: diff --git a/source/_integrations/select.mqtt.markdown b/source/_integrations/select.mqtt.markdown index aa23cc5cc0b..6527266d3f8 100644 --- a/source/_integrations/select.mqtt.markdown +++ b/source/_integrations/select.mqtt.markdown @@ -145,7 +145,7 @@ json_attributes_topic: required: false type: string name: - description: The name of the Select. + description: The name of the Select. Can be set to `null` if only the device name is relevant. required: false type: string object_id: diff --git a/source/_integrations/sensor.mqtt.markdown b/source/_integrations/sensor.mqtt.markdown index 2f53f1aaeb5..4f293d70f34 100644 --- a/source/_integrations/sensor.mqtt.markdown +++ b/source/_integrations/sensor.mqtt.markdown @@ -153,7 +153,7 @@ last_reset_value_template: required: false type: template name: - description: The name of the MQTT sensor. + description: The name of the MQTT sensor. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT Sensor diff --git a/source/_integrations/siren.mqtt.markdown b/source/_integrations/siren.mqtt.markdown index ca7b5213cc2..2ec96b1b92f 100644 --- a/source/_integrations/siren.mqtt.markdown +++ b/source/_integrations/siren.mqtt.markdown @@ -156,7 +156,7 @@ json_attributes_topic: required: false type: string name: - description: The name to use when displaying this siren. + description: The name to use when displaying this siren. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT Siren diff --git a/source/_integrations/switch.mqtt.markdown b/source/_integrations/switch.mqtt.markdown index 8c766b376df..aa911fd80e9 100644 --- a/source/_integrations/switch.mqtt.markdown +++ b/source/_integrations/switch.mqtt.markdown @@ -148,7 +148,7 @@ json_attributes_topic: required: false type: string name: - description: The name to use when displaying this switch. + description: The name to use when displaying this switch. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT Switch diff --git a/source/_integrations/text.mqtt.markdown b/source/_integrations/text.mqtt.markdown index bb24c5eed58..1c765e45fb9 100644 --- a/source/_integrations/text.mqtt.markdown +++ b/source/_integrations/text.mqtt.markdown @@ -150,7 +150,7 @@ mode: type: string default: text name: - description: The name of the text entity. + description: The name of the text entity. Can be set to `null` if only the device name is relevant. required: false type: string default: "MQTT Text" diff --git a/source/_integrations/update.mqtt.markdown b/source/_integrations/update.mqtt.markdown index b3f82ef3371..ed6d5535b1c 100644 --- a/source/_integrations/update.mqtt.markdown +++ b/source/_integrations/update.mqtt.markdown @@ -154,7 +154,7 @@ latest_version_topic: required: false type: string name: - description: The name of the Update. + description: The name of the Update. Can be set to `null` if only the device name is relevant. required: false type: string object_id: diff --git a/source/_integrations/vacuum.mqtt.markdown b/source/_integrations/vacuum.mqtt.markdown index 96528a1a3cd..8df9daa95c7 100644 --- a/source/_integrations/vacuum.mqtt.markdown +++ b/source/_integrations/vacuum.mqtt.markdown @@ -153,7 +153,7 @@ json_attributes_topic: required: false type: string name: - description: The name of the vacuum. + description: The name of the vacuum. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT Vacuum @@ -429,7 +429,7 @@ json_attributes_topic: required: false type: string name: - description: The name of the vacuum. + description: The name of the vacuum. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT Vacuum diff --git a/source/_integrations/water_heater.mqtt.markdown b/source/_integrations/water_heater.mqtt.markdown index ee42de2ed78..0cdf545e8a0 100644 --- a/source/_integrations/water_heater.mqtt.markdown +++ b/source/_integrations/water_heater.mqtt.markdown @@ -175,7 +175,7 @@ modes: default: ['off', 'eco', 'electric', 'gas', 'heat_pump', 'high_demand', 'performance'] type: list name: - description: The name of the Water Heater. + description: The name of the Water Heater. Can be set to `null` if only the device name is relevant. required: false type: string default: MQTT Water Heater