Skip to main content

· One min read

As of Home Assistant Core 2024.2 we have added two new flags into ClimateEntityFeature: TURN_ON, TURN_OFF.

Integrations implementing turn_on service call needs to set the TURN_ON feature flag. Integrations implementing turn_off service call needs to set the TURN_OFF feature flag.

There will be a 10 month deprecation period (2025.1) where ClimateEntity will set these on behalf of the integrations implementing the respective methods and from 2025.1 it will make integrations unable to use the respective methods if entity features has not been set accordingly.

Implementing the methods without setting the respective feature flag will create a warning log entry guiding the user to create an issue for the integration.

Integrations should set the attribute _enable_turn_on_off_backwards_compatibility in your ClimateEntity subclass instance to False once it has been migrated into using or not using the new feature flags. This will stop the automatic setting of the new feature flags during the deprecation period and can be removed once deprecation has ended.

· 2 min read

Background​

The primary reason for introducing light color modes was that a light's state should not be ambiguous. As an example, a light which supports color and white with adjustable color temperature must be in either color mode hs (for example) or color_temp.

However, effects complicate this because when the same light is rendering an effect, none of the hs_color, color_temp, or brightness state attributes may be meaningful.

Changes​

Requirements on color_mode are less strict when a light is rendering an effect​

More restrictive color modes than what's otherwise supported by the light are allowed when an effect is active:

  • A light which supports colors is allowed to indicate color modes on_off and brightness when controlled by an effect
  • A light which supports brightness is allowed to indicate color mode on_off when controlled by an effect.

For example, a light which has its supported_color_modes set to {"hs", "color_temp"} is allowed to set its color_mode to on_off when rendering an effect which can't be adjusted and to brightness when rendering an effect which allows brightness to be controlled.

A special effect EFFECT_OFF which means no effect / turn off effect has been added​

There was previously no standard way for a light which supports effects to show that no effect is active. This has been solved by adding an the pre-defined effect EFFECT_OFF to indicate no effect is active.

More details can be found in the documentation and in architecture discussion #960.

· One min read

In Home Assistant 2024.2, we will introduce hass.services.async_services_for_domain(), which is a new way to enumerate services by domain, allowing integrations to inspect which services are available without having to obtain all the services on the system. We found that most integrations are only interested in the services they provide, and it was expensive to enumerate all the services in the system when an integration was only interested in their services.

Integrations that call hass.services.async_services()[DOMAIN] to get services for a specific domain should replace the call with hass.services.async_services_for_domain(DOMAIN).

· One min read
Joost Lekkerkerker

It's now possible to provide static values to be used in an entity translation using placeholders. You can pass placeholders via the translation_placeholders property of an entity.

An example sensor:

class TestEntity(SensorEntity):
    """Example entity."""
    
    _attr_has_entity_name = True
    _attr_translation_key = "temperature"
    
    def __init__(self) -> None:
        """Initialize example entity."""
        self._attr_translation_placeholders = {"channel_id": "2"}
        self._attr_device_info = DeviceInfo(
            name="Example device"
        )

The strings.json file would look like:

{
  "entity": {
    "sensor": {
      "temperature": {
        "name": "Temperature channel {channel_id}"
      }
    }
  }
}

The resulting entity would be called Example device Temperature channel 2.

A warning is logged once when a translation placeholder is expected but not provided by the entity. When this happens on a system that is not on a stable version (dev, nightly, or beta), an error will be raised to be able to catch the mistakes quickly.

Please don't forget to be kind towards your translators, as they need to understand what kind of name or value will be passed in from the placeholder name ❤️.

· 2 min read
Franck Nijhof

In Home Assistant 2024.2, we will introduce a new way to provide icons for integrations: Icon translations.

Icon translations work similarly to our regular translations for entities, which can translate the state of an entity or entity attribute state into any language. Icon translations work in a similar way, but instead of translating the state into the end-user language, it translates the state into an icon.

Each integration can now provide an icons.json file, containing a mapping of states to icons. Here is an example of a Moon sensor entity that provides different icons for each state:

{
  "entity": {
    "sensor": {
      "phase": {
        "default": "mdi:moon",
        "state": {
          "new_moon": "mdi:moon-new",
          "first_quarter": "mdi:moon-first-quarter",
          "full_moon": "mdi:moon-full",
          "last_quarter": "mdi:moon-last-quarter"
        }
      }
    }
  }
}

Icon translations also support translating entity attribute states.

Read more about icon translations in our documentation.

Service icons​

This change is backward-compatible. The existing icon property of entities will continue to work as it did before. However, we recommend the use of the icon translation over the icon property.

Additionally, services provided by integrations now also support icons and can be provided in the same icon translations file. These icons are used in the Home Assistant UI when displaying the service in places like the automation and script editors. The following example shows how to provide icons for the light.turn_on and light.turn_off services:

{
  "services": {
    "turn_on": "mdi:lightbulb-on",
    "turn_off": "mdi:lightbulb-off"
  }
}

Read more about service icons in our documentation.

· One min read
Jan-Philipp Benecke

Since Home Assistant Core 2022.12, a warning is issued in the logs if a sensor entity that has a device class uses unit of measurement and state class incorrectly, taking their device class into account.

An invalid use would be a sensor entity that has a device class of SensorDeviceClass.TEMPERATURE but uses the unit of measurement % instead of °C or °F; or the state class SensorStateClass.TOTAL instead of SensorStateClass.MEASUREMENT.

There will be a six-month deprecation period to ensure all custom integration authors have time to adjust. As of Home Assistant Core 2024.8, the warning will then be replaced by an exception.

· One min read

FlowHandler.async_show_progress has been updated:

  • The step_id parameter is deprecated and will be removed in Home Assistant core release 2024.8
  • A new argument progress_task has been added, which will be mandatory in Home Assistant core release 2024.8

If progress_task is passed, FlowManager will:

  • Send an event to fronted once the task has finished
  • Cancel the progress_task if the user closes the config flow dialog before the task is done

This means derived classes are no longer responsible for interaction between the progress task state and the UI.

FlowHandler.async_show_progress will log a warning if it's called without a progress_task. In Home Assistant core release 2024.8, the call will instead fail.

More details can be found in the documentation and in core PR #107668 and "107802.

· One min read

As of Home Assistant Core 2024.1, all usage of magic numbers for supported features is deprecated, and each entity platform has provided an EntityFeature enum to replace them.

There will be a one-year deprecation period, and the magic numbers will stop working in 2025.1 to ensure all custom integration authors have time to adjust.

This applies to, the following platforms:

· One min read
Robert Resch

In recent years many constants have been replaced by Enums or other values by adding a code comment pointing to the successor. Using deprecated constants will now create a warning log entry containing the used integration, the replacement, and the version where the constant will be removed from core. There will be a one-year deprecation period to ensure all custom integration authors have time to adjust.

Most constants should already have been replaced, as we created several blog posts in the past about their deprecation. Some are listed below:

More details can be found in core PR #105736 or by checking the usage of the function check_if_deprecated_constant in the deprecation helper.

· One min read

Config entry now supports minor versions.

If minor versions differ, but major versions are the same, the integration setup will be allowed to continue even if the integration does not implement async_migrate_entry. This means a minor version bump is backwards compatible, unlike a major version bump which causes the integration to fail setup if the user downgrades HA Core without restoring configuration from backup.

Background​

We have been very conservative with versioning config entry data because it breaks downgrading to an older version of Home Assistant Core. This means in most cases, we don't version, and the integrations instead do a kind of soft upgrade where they may, for example, do dict.get on config entry data that was not in an initial version, transform the data during setup etc.

By introducing minor versions similar to that already offered by the storage helper, this pattern is no longer recommended. A bump of the minor version should be done instead whenever the newly added, or otherwise changed, data does not break older versions.

More details can be found in the documentation on config entry migration and in core PR #105749.