Changes in naming of MQTT entities (#27954)

Co-authored-by: Franck Nijhof <frenck@frenck.nl>

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

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

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

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:

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

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

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

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

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:

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

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

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.

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:

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:

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

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

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

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"

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:

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

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