home-assistant/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-12-10 13:05:27 -06:00
Code Issues Packages Projects Releases Wiki Activity

Introduce default_entity_id to replace object_id for mqtt entity platforms (#40749)

Browse Source
This commit is contained in:
Jan Bouwhuis 2025-09-10 08:03:41 +02:00 committed by GitHub
parent 48592c6b30
commit ff07674653
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
27 changed files with 124 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
source/_integrations/alarm_control_panel.mqtt.markdown
View File

@ -108,6 +108,10 @@ command_topic:
description: The MQTT topic to publish commands to change the alarm state.
required: true
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `alarm_control_panel.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this alarm panel is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -196,10 +200,6 @@ name:
required: false
type: string
default: MQTT Alarm
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
payload_arm_away:
description: The payload to set armed-away mode on your Alarm Panel.
required: false

8
source/_integrations/binary_sensor.mqtt.markdown
View File

@ -69,6 +69,10 @@ availability_topic:
description: "The MQTT topic subscribed to receive birth and LWT messages from the MQTT device. If `availability` is not defined, the binary sensor will always be considered `available` and its state will be `on`, `off` or `unknown`. If `availability` is defined, the binary sensor will be considered as `unavailable` by default and the sensor's initial state will be `unavailable`. Must not be used together with `availability`."
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `binary_sensor.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this binary sensor is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/device_registry_index/). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -170,10 +174,6 @@ name:
required: false
type: string
default: MQTT binary sensor
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
off_delay:
description: "For sensors that only send `on` state updates (like PIRs), this variable sets a delay in seconds after which the sensor's state will be updated back to `off`."
required: false

8
source/_integrations/button.mqtt.markdown
View File

@ -69,6 +69,10 @@ command_topic:
description: The MQTT topic to publish commands to trigger the button.
required: true
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `button.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this button is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -161,10 +165,6 @@ name:
required: false
type: string
default: MQTT Button
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
payload_available:
description: The payload that represents the available state.
required: false

8
source/_integrations/camera.mqtt.markdown
View File

@ -69,6 +69,10 @@ availability_topic:
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `camera.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this camera is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -160,10 +164,6 @@ name:
description: The name of the camera. Can be set to `null` if only the device name is relevant.
required: false
type: string
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
topic:
description: The MQTT topic to subscribe to.
required: true

8
source/_integrations/climate.mqtt.markdown
View File

@ -88,6 +88,10 @@ current_temperature_topic:
description: The MQTT topic on which to listen for the current temperature. A `"None"` value received will reset the current temperature. Empty values (`'''`) will be ignored.
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `climate.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: 'Information about the device this HVAC device is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
required: false
@ -240,10 +244,6 @@ name:
required: false
type: string
default: MQTT HVAC
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
optimistic:
description: Flag that defines if the climate works in optimistic mode
required: false

8
source/_integrations/cover.mqtt.markdown
View File

@ -80,6 +80,10 @@ command_topic:
description: The MQTT topic to publish commands to control the cover.
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `cover.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this cover is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -172,10 +176,6 @@ name:
required: false
type: string
default: MQTT Cover
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
optimistic:
description: Flag that defines if switch works in optimistic mode.
required: false

8
source/_integrations/device_tracker.mqtt.markdown
View File

@ -69,6 +69,10 @@ availability_topic:
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `device_tracker.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this device tracker is a part of that ties it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). At least one of identifiers or connections must be present to identify the device."
required: false
@ -141,10 +145,6 @@ name:
description: The name of the MQTT device_tracker.
required: false
type: string
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
payload_available:
description: The payload that represents the available state.
required: false

8
source/_integrations/event.mqtt.markdown
View File

@ -63,6 +63,10 @@ availability_topic:
description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`.
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `event.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this event is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -159,10 +163,6 @@ name:
required: false
type: string
default: MQTT Event
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
payload_available:
description: The payload that represents the available state.
required: false

8
source/_integrations/fan.mqtt.markdown
View File

@ -75,6 +75,10 @@ command_topic:
description: The MQTT topic to publish commands to change the fan state.
required: true
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `fan.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this fan is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -163,10 +167,6 @@ name:
required: false
type: string
default: MQTT Fan
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
optimistic:
description: Flag that defines if fan works in optimistic mode
required: false

8
source/_integrations/humidifier.mqtt.markdown
View File

@ -94,6 +94,10 @@ command_topic:
description: The MQTT topic to publish commands to change the humidifier state.
required: true
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `humidifier.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this humidifier is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -197,10 +201,6 @@ name:
required: false
type: string
default: MQTT humidifier
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
optimistic:
description: Flag that defines if humidifier works in optimistic mode
required: false

10
source/_integrations/image.mqtt.markdown
View File

@ -18,7 +18,7 @@ An alternative setup is to use the `url_topic` option to receive an image URL fo
## Configuration
To use an MQTT image entity in your installation, add the following to your {% term "`configuration.yaml`" %} file.
To use an MQTT image entity in your installation, [add a MQTT device as a subentry](/integrations/mqtt/#configuration), or add the following to your {% term "`configuration.yaml`" %} file.
{% include integrations/restart_ha_after_config_inclusion.md %}
```yaml
@ -72,6 +72,10 @@ content_type:
required: false
type: string
default: image/jpeg
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `image.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this image is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -167,10 +171,6 @@ name:
description: The name of the image. Can be set to `null` if only the device name is relevant.
required: false
type: string
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
unique_id:
description: An ID that uniquely identifies this image. If two images have the same unique ID Home Assistant will raise an exception. Required when used with device-based discovery.
required: false

8
source/_integrations/lawn_mower.mqtt.markdown
View File

@ -70,6 +70,10 @@ availability_template:
description: "Defines a [template](/docs/configuration/templating/#using-value-templates-with-mqtt) to extract device's availability from the `availability_topic`. To determine the devices's availability, the result of this template will be compared to `payload_available` and `payload_not_available`."
required: false
type: template
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `lawn_mower.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this lawn mower is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when the [`unique_id`](#unique_id) is set. At least one of the identifiers or connections must be present to identify the device."
required: false
@ -165,10 +169,6 @@ name:
description: The name of the lawn mower. Can be set to `null` if only the device name is relevant.
required: false
type: string
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
optimistic:
description: Flag that defines if the lawn mower works in optimistic mode.
required: false

36
source/_integrations/light.mqtt.markdown
View File

@ -105,7 +105,7 @@ brightness_scale:
type: integer
default: 255
brightness_state_topic:
description: The MQTT topic subscribed to receive brightness state updates. Zero brightness values are ignored.
description: The MQTT topic subscribed to receive brightness state updates.
required: false
type: string
brightness_value_template:
@ -145,6 +145,10 @@ command_topic:
description: The MQTT topic to publish commands to change the switch state.
required: true
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `light.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
required: false
@ -290,10 +294,6 @@ name:
required: false
type: string
default: MQTT Light
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
on_command_type:
description: "Defines when on the payload_on is sent. Using `last` (the default) will send any style (brightness, color, etc) topics first and then a `payload_on` to the `command_topic`. Using `first` will send the `payload_on` and then any style topics. Using `brightness` will only send brightness commands instead of the `payload_on` to turn the light on."
required: false
@ -616,6 +616,10 @@ command_topic:
description: The MQTT topic to publish commands to change the light’s state.
required: true
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `light.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
required: false
@ -726,10 +730,6 @@ name:
required: false
type: string
default: MQTT JSON Light
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
optimistic:
description: Flag that defines if the light works in optimistic mode.
required: false
@ -765,7 +765,7 @@ schema:
type: string
default: basic
state_topic:
description: 'The MQTT topic subscribed to receive state updates in a JSON-format. The JSON payload may contain the elements: `"state"`: `"ON"` the light is on, `"OFF"` the light is off, `null` the state is `unknown`; `"color_mode"`: one of the `supported_color_modes`; `"color"`: A dict with the color attributes*; `"brightness"`: The brightness; `"color_temp"`: The color temperature; `"effect"`: The effect of the light. Zero brightness values are ignored.'
description: 'The MQTT topic subscribed to receive state updates in a JSON-format. The JSON payload may contain the elements: `"state"`: `"ON"` the light is on, `"OFF"` the light is off, `null` the state is `unknown`; `"color_mode"`: one of the `supported_color_modes`; `"color"`: A dict with the color attributes*; `"brightness"`: The brightness; `"color_temp"`: The color temperature; `"effect"`: The effect of the light.'
required: false
type: string
supported_color_modes:
@ -939,7 +939,7 @@ mqtt:
- [ESPHome](https://esphome.io) implements the JSON schema for MQTT based installs and supports [MQTT discovery](/integrations/mqtt/#mqtt-discovery).
- [AiLight](https://github.com/stelgenhof/AiLight) is a custom firmware for the Ai-Thinker (and equivalent) RGBW WiFi light bulbs that has an ESP8266 onboard and controlled by the MY9291 LED driver. It implements the [MQTT JSON light](/integrations/light.mqtt) platform and supports ON/OFF, RGBW colours, brightness, color temperature, flashing and transitions. Also it includes [MQTT Auto Discovery](/integrations/mqtt/#mqtt-discovery) and the MQTT Last Will and Testament is enabled as well.
- [AiLight](https://github.com/stelgenhof/AiLight) is a custom firmware for the Ai-Thinker (and equivalent) RGBW WiFi light bulbs that has an ESP8266 onboard and controlled by the MY9291 LED driver. It implements the [MQTT JSON light](/integrations/light.mqtt) platform and supports ON/OFF, RGBW colours, brightness, color temperature, flashing and transitions. Also it includes [MQTT Auto Discovery](/integrations/mqtt/#mqtt-discovery)) and the MQTT Last Will and Testament is enabled as well.
- [h801-mqtt-json](https://github.com/starkillerOG/h801-mqtt-json) is a custom firmware for the H801 LED dimmer, a 5 channel (RGBWWCW) WiFi LED strip controller for 12V LED strips. The firmware is meant to control the 5 channels of the H801 to simultaneously control an RGB and a Warm-white/Cold-white LED strip such as a 5050 RGB LED strip and a 5025 Dual White strip. It implements the [MQTT JSON light](/integrations/light.mqtt) platform and supports ON/OFF, RGBW colours (RGB strip), brightness, color temperature (CW/WW strip) and transitions.
@ -1015,7 +1015,7 @@ blue_template:
required: false
type: template
brightness_template:
description: "[Template](/docs/configuration/templating/#using-value-templates-with-mqtt) to extract brightness from the state payload value. Expected result of the template is an integer from 1-255 range."
description: "[Template](/docs/configuration/templating/#using-value-templates-with-mqtt) to extract brightness from the state payload value. Expected result of the template is an integer from 0-255 range."
required: false
type: template
color_temp_kelvin:
@ -1039,6 +1039,10 @@ command_topic:
description: The MQTT topic to publish commands to change the light’s state.
required: true
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `light.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: 'Information about the device this light is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
required: false
@ -1137,10 +1141,6 @@ name:
required: false
type: string
default: MQTT Template Light
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
optimistic:
description: Flag that defines if the light works in optimistic mode.
required: false
@ -1266,7 +1266,7 @@ mqtt:
This example comes from a configuration of Shelly RGBW Bulb working in White mode.
`max_mireds` and `min_mireds` set color temperature boundaries to 3000K - 6500K. Notice the same limits are applied in `command_on_template`, but in kelvin units this time. It's due to conversion from mired to kelvin which causes exceeding boundary values accepted by the device.
The code also ensures bi-directional conversion of brightness scale between 1-100 (required by the device) and 1-255 (required by Home Assistant). Note that Home Assistant ignores a zero brightness value. So when the light is off, it should publish an off state instead.
The code also ensures bi-directional conversion of brightness scale between 0-100 (required by the device) and 0-255 (required by Home Assistant).
Add the following to your {% term "`configuration.yaml`" %} file:
{% raw %}
@ -1299,7 +1299,7 @@ mqtt:
min_mireds: 153
qos: 1
retain: false
optimistic: false
optimistic: false
```
{% endraw %}

8
source/_integrations/lock.mqtt.markdown
View File

@ -83,6 +83,10 @@ command_topic:
description: The MQTT topic to publish commands to change the lock state.
required: true
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `lock.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: 'Information about the device this lock is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
required: false
@ -171,10 +175,6 @@ name:
required: false
type: string
default: MQTT Lock
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
optimistic:
description: Flag that defines if lock works in optimistic mode.
required: false

10
source/_integrations/mqtt.markdown
View File

@ -310,8 +310,8 @@ The mandatory fields were previously limited to at least one of `connection` and
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`.
If the `default_entity_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 `default_entity_id` to `sensor.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 its `friendly_name` attribute prefixed with the device name](https://developers.home-assistant.io/docs/core/entity/#has_entity_name-true-mandatory-for-new-integrations)
@ -734,6 +734,7 @@ support_url:
'cont_type': 'content_type',
'curr_temp_t': 'current_temperature_topic',
'curr_temp_tpl': 'current_temperature_template',
'def_ent_id': 'default_entity_id',
'dev': 'device',
'dev_cla': 'device_class',
'dir_cmd_t': 'direction_command_topic',
@ -801,7 +802,6 @@ support_url:
'modes': 'modes',
'name': 'name',
'o': 'origin',
'obj_id': 'object_id',
'off_dly': 'off_delay',
'on_cmd_type': 'on_command_type',
'ops': 'options',
@ -1326,9 +1326,9 @@ Setting up a [light that takes JSON payloads](/integrations/light.mqtt/#json-sch
}
```
#### Use object_id to influence the entity id
#### Use object_id to influence the entity ID
The entity id is automatically generated from the entity's name. All MQTT integrations optionally support providing an `object_id` which will be used instead if provided.
The entity ID is automatically generated from the entity's name. All MQTT integrations optionally support providing an `object_id` which will be used instead if provided.
- Configuration topic: `homeassistant/sensor/device1/config`
- Example configuration payload:

8
source/_integrations/notify.mqtt.markdown
View File

@ -72,6 +72,10 @@ command_topic:
description: The MQTT topic to publish send message commands at.
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `notify.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this notify entity is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of the identifiers or connections must be present to identify the device."
required: false
@ -160,10 +164,6 @@ name:
required: false
type: string
default: MQTT notify
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
payload_available:
description: The payload that represents the available state.
required: false

8
source/_integrations/number.mqtt.markdown
View File

@ -61,6 +61,10 @@ command_topic:
description: The MQTT topic to publish commands to change the number.
required: true
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `number.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this Number is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -167,10 +171,6 @@ name:
description: The name of the Number. Can be set to `null` if only the device name is relevant.
required: false
type: string
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
optimistic:
description: Flag that defines if number works in optimistic mode.
required: false

8
source/_integrations/scene.mqtt.markdown
View File

@ -65,6 +65,10 @@ command_topic:
description: The MQTT topic to publish `payload_on` to activate the scene.
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `scene.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this scene is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -153,10 +157,6 @@ name:
required: false
type: string
default: MQTT Scene
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
payload_available:
description: The payload that represents the available state.
required: false

8
source/_integrations/select.mqtt.markdown
View File

@ -73,6 +73,10 @@ command_topic:
description: The MQTT topic to publish commands to change the selected option.
required: true
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `select.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this Select is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -160,10 +164,6 @@ name:
description: The name of the Select. Can be set to `null` if only the device name is relevant.
required: false
type: string
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
optimistic:
description: Flag that defines if the select works in optimistic mode.
required: false

8
source/_integrations/sensor.mqtt.markdown
View File

@ -63,6 +63,10 @@ availability_topic:
description: The MQTT topic subscribed to receive availability (online/offline) updates.
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `sensor.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this sensor is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/device_registry_index/). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -169,10 +173,6 @@ name:
required: false
type: string
default: MQTT Sensor
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
options:
description: List of allowed sensor state value. An empty list is not allowed. The sensor's `device_class` must be set to `enum`. The `options` option cannot be used together with `state_class` or `unit_of_measurement`.
required: false

8
source/_integrations/siren.mqtt.markdown
View File

@ -84,6 +84,10 @@ command_topic:
The MQTT topic to publish commands to change the siren state. Without command templates, a default JSON payload like `{"state":"ON", "tone": "bell", "duration": 10, "volume_level": 0.5 }` is published. When the siren turn on action is performed, the startup parameters will be added to the JSON payload. The `state` value of the JSON payload will be set to the the `payload_on` or `payload_off` configured payload.
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `siren.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this siren is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -172,10 +176,6 @@ name:
required: false
type: string
default: MQTT Siren
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
optimistic:
description: Flag that defines if siren works in optimistic mode.
required: false

8
source/_integrations/switch.mqtt.markdown
View File

@ -75,6 +75,10 @@ command_topic:
description: The MQTT topic to publish commands to change the switch state.
required: true
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `swicth.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this switch is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -167,10 +171,6 @@ name:
required: false
type: string
default: MQTT Switch
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
optimistic:
description: Flag that defines if switch works in optimistic mode.
required: false

8
source/_integrations/text.mqtt.markdown
View File

@ -69,6 +69,10 @@ command_topic:
description: The MQTT topic to publish the text value that is set.
required: true
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `text.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this of text capability is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -168,10 +172,6 @@ name:
required: false
type: string
default: "MQTT Text"
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
pattern:
description: A valid regular expression the text being set or received must match with.
required: false

8
source/_integrations/update.mqtt.markdown
View File

@ -66,6 +66,10 @@ command_topic:
description: The MQTT topic to publish `payload_install` to start installing process.
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `update.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this Update is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -170,10 +174,6 @@ name:
description: The name of the Update. Can be set to `null` if only the device name is relevant.
required: false
type: string
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
payload_install:
description: The MQTT payload to start installing process.
required: false

8
source/_integrations/vacuum.mqtt.markdown
View File

@ -66,6 +66,10 @@ command_topic:
description: The MQTT topic to publish commands to control the vacuum.
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `vacuum.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this switch is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."
required: false
@ -141,10 +145,6 @@ name:
required: false
type: string
default: MQTT Vacuum
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
payload_available:
description: The payload that represents the available state.
required: false

8
source/_integrations/valve.mqtt.markdown
View File

@ -104,6 +104,10 @@ command_topic:
description: The MQTT topic to publish commands to control the valve. The value sent can be a value defined by `payload_open`, `payload_close` or `payload_stop`. If `reports_position` is set to `true`, a numeric value will be published instead.
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `valve.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: "Information about the device this valve is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of the identifiers or connections must be present to identify the device."
required: false
@ -196,10 +200,6 @@ name:
required: false
type: string
default: MQTT valve
object_id:
description: Used instead of `name` to have the `entity_id` generated automatically.
required: false
type: string
optimistic:
description: Flag that defines if a switch works in optimistic mode.
required: false

8
source/_integrations/water_heater.mqtt.markdown
View File

@ -70,6 +70,10 @@ current_temperature_topic:
description: The MQTT topic on which to listen for the current temperature. A `"None"` value received will reset the current temperature. Empty values (`'''`) will be ignored.
required: false
type: string
default_entity_id:
description: Use `default_entity_id` instead of name for automatic generation of the entity ID. For example, `water_heater.foobar`. When used without a `unique_id`, the entity ID will update during restart or reload if the entity ID is available. If the entity ID already exists, the entity ID will be created with a number at the end. When used with a `unique_id`, the `default_entity_id` is only used when the entity is added for the first time. When set, this overrides a user-customized entity ID if the entity was deleted and added again.
required: false
type: string
device:
description: 'Information about the device this water heater device is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works through [MQTT discovery](/integrations/mqtt/#mqtt-discovery) and when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device.'
required: false
@ -191,10 +195,6 @@ name:
required: false
type: string
default: MQTT water heater
object_id:
description: Used `object_id` instead of `name` for automatic generation of `entity_id`. This only works when the entity is added for the first time. When set, this overrides a user-customized Entity ID in case the entity was deleted and added again.
required: false
type: string
optimistic:
description: Flag that defines if the water heater works in optimistic mode
required: false