Update your manually configured MQTT entities

MQTT Changes in Home Assistant Core 2022.6

Previously, MQTT entities were configured directly under their respective platform keys, such as fan, light, or switch. However, with the new update, these configurations must be nested under the mqtt platform key. This guide will walk you through the necessary steps to update your configuration, ensuring your system remains compatible and efficient as Home Assistant continues to evolve.

To clarify this change, let's look at a practical example. Consider the following configuration for a manually configured MQTT switch:

Deprecated Configuration

switch:
  - platform: mqtt
    name: "Zigbee2MQTT - Main join"
    state_topic: "zigbee2mqtt/bridge/info"
    value_template: '{{ value_json.permit_join | lower }}'
    command_topic: "zigbee2mqtt/bridge/request/permit_join"
    payload_on: "true"
    payload_off: "false"

In the above example, the switch platform key is used directly. As of Home Assistant Core 2022.6, this method is deprecated. Here is how you need to update your configuration:

mqtt:
  switch:
    - name: "Zigbee2MQTT - Main join"
      state_topic: "zigbee2mqtt/bridge/info"
      value_template: '{{ value_json.permit_join | lower }}'
      command_topic: "zigbee2mqtt/bridge/request/permit_join"
      payload_on: "true"
      payload_off: "false"

Step-by-Step Guide to Update Your Configuration

1. Identify the MQTT Entities: Locate all the MQTT entities in your configuration.yaml file. These are typically found under the keys like switch, light, fan, etc.
2. Move Entities Under the mqtt Key: For each MQTT entity, remove it from its current platform key and nest it under the mqtt key. Retain the entity type (e.g., switch, light) as a nested key under mqtt.
3. Preserve the Existing Configuration: Ensure that the existing properties of your MQTT entities (such as state_topic, command_topic, payload_on, payload_off, etc.) are preserved during the move.
4. Validate Your Configuration: Use Home Assistant's built-in YAML validator to check for any syntax errors. You can do this by navigating to Configuration > Settings > Server Controls and clicking on Check Configuration.
5. Restart Home Assistant: Once your configuration is updated and validated, restart Home Assistant for the changes to take effect.

Example of Multiple Entity Types

Here's an example if you have multiple types of MQTT entities:

Before

switch:
  - platform: mqtt
    name: "Zigbee2MQTT - Main join"
    state_topic: "zigbee2mqtt/bridge/info"
    value_template: '{{ value_json.permit_join | lower }}'
    command_topic: "zigbee2mqtt/bridge/request/permit_join"
    payload_on: "true"
    payload_off: "false"

light:
  - platform: mqtt
    name: "Living Room Light"
    state_topic: "home/livingroom/light/state"
    command_topic: "home/livingroom/light/set"
    brightness_state_topic: "home/livingroom/light/brightness/state"
    brightness_command_topic: "home/livingroom/light/brightness/set"
    payload_on: "ON"
    payload_off: "OFF"

After

mqtt:
  switch:
    - name: "Zigbee2MQTT - Main join"
      state_topic: "zigbee2mqtt/bridge/info"
      value_template: '{{ value_json.permit_join | lower }}'
      command_topic: "zigbee2mqtt/bridge/request/permit_join"
      payload_on: "true"
      payload_off: "false"

  light:
    - name: "Living Room Light"
      state_topic: "home/livingroom/light/state"
      command_topic: "home/livingroom/light/set"
      brightness_state_topic: "home/livingroom/light/brightness/state"
      brightness_command_topic: "home/livingroom/light/brightness/set"
      payload_on: "ON"
      payload_off: "OFF"

Summary

By migrating your MQTT entities to the new configuration format, you ensure compatibility with Home Assistant Core 2022.9 and beyond. This change simplifies the configuration structure and enhances consistency across different entity types.

For more detailed information, refer to the Home Assistant MQTT documentation. If you encounter any issues or have questions, the Home Assistant community is always ready to help. Happy automating!