Skip to main content

· One min read

The method for integrations to provide translations for states of its entities under other integrations, for example to translate an integration's sensors has changed.

Integrations should no longer use custom device classes together with a strings.<platform name>.json file. Instead, entities should set the translation_key property on an entity and include that translation_key in the integration's strings.json.

danger

Pointing to translations via the translation_key property is currently only supported for entities with a unique_id.

The following example strings.json is for a Moon domain sensor entity with its translation_key property set to phase:

{
"entity": {
"sensor": {
"phase": {
"state": {
"new_moon": "New moon",
"first_quarter": "First quarter",
"full_moon": "Full moon",
"last_quarter": "Last quarter"
}
}
}
}
}

For more details, see the translation and entity documentation.

· One min read

As of Home Assistant Core 2022.12, the following unit constants are deprecated and replaced by a corresponding enum:

  • UnitOfPrecipitationDepth enumerator replaces PRECIPITATION_*** constants

· 2 min read

Some changes have been made to the long-term statistics-related APIs to reduce response size and database load.

The changes are implemented in this PR.

This affects authors of code calling the following WS APIs:

  • recorder/statistics_during_period
    • A new optional parameter types has been added, which allows providing a list of statistics characteristics to include in the response. Possible values are: "last_reset", "max", "mean", "min", "state", "sum"
    • Timestamps start, end and last_reset are now an integer number of ms since the UNIX epoch instead of ISO-formatted strings. The new format means the timestamps can be passed directly to js Date() constructor.
    • The statistic_id is no longer repeated for each list item in the returned map. This was not used because the return type is a map, keyed by statistic_id.

This affects authors of code calling the following Python APIs:

  • homeassistant.recorder.statistics.get_last_short_term_statistics
    • A new parameter types has been added, which allows providing a set of statistics characteristics to include in the response. Possible values are: "last_reset", "max", "mean", "min", "state", "sum"
    • Timestamps start, end and last_reset are now an datetime objects instead of ISO-formatted strings.
    • The statistic_id is no longer repeated for each list item in the returned map. This was not used because the return type is a map, keyed by statistic_id.
  • homeassistant.recorder.statistics.get_latest_short_term_statistics
    • A new parameter types has been added, which allows providing a set of statistics characteristics to include in the response. Possible values are: "last_reset", "max", "mean", "min", "state", "sum"
    • Timestamps start, end and last_reset are now an datetime objects instead of ISO-formatted strings.
    • The statistic_id is no longer repeated for each list item in the returned map. This was not used because the return type is a map, keyed by statistic_id.
  • homeassistant.recorder.statistics.statistics_during_period
    • A new parameter types has been added, which allows providing a set of statistics characteristics to include in the response. Possible values are: "last_reset", "max", "mean", "min", "state", "sum"
    • Timestamps start, end and last_reset are now an datetime objects instead of ISO-formatted strings.
    • The statistic_id is no longer repeated for each list item in the returned map. This was not used because the return type is a map, keyed by statistic_id.

· One min read

As of Home Assistant Core 2022.11, the following unit constants are deprecated and replaced by a corresponding enum:

  • UnitOfEnergy enumerator replaces ENERGY_*** constants
  • UnitOfLength enumerator replaces LENGTH_*** constants
  • UnitOfMass enumerator replaces MASS_*** constants
  • UnitOfPower enumerator replaces POWER_*** constants
  • UnitOfPressure enumerator replaces PRESSURE_*** constants
  • UnitOfSpeed enumerator replaces SPEED_*** constants
  • UnitOfTemperature enumerator replaces TEMP_*** constants
  • UnitOfVolume enumerator replaces VOLUME_*** constants

· One min read

As of Home Assistant Core 2022.11, the following constants are deprecated for volumetric flux (like precipitation intensity), replaced by UnitOfVolumetricFlux enum:

  • PRECIPITATION_INCHES_PER_HOUR replaced by UnitOfVolumetricFlux.INCHES_PER_HOUR
  • PRECIPITATION_MILLIMETERS_PER_HOUR replaced by UnitOfVolumetricFlux.MILLIMETERS_PER_HOUR
  • SPEED_INCHES_PER_DAY replaced by UnitOfVolumetricFlux.INCHES_PER_DAY
  • SPEED_INCHES_PER_HOUR replaced by UnitOfVolumetricFlux.INCHES_PER_HOUR
  • SPEED_MILLIMETERS_PER_DAY replaced by UnitOfVolumetricFlux.MILLIMETERS_PER_DAY

· 3 min read

For the 2022.11 release, we have been adjusting our integration manifests to better differentiate between hubs, devices, and services. Additionally, we are introducing a new type of integration: A virtual integration.

Differentiating hubs, devices, and services

A confusing aspect: config entries can either integrate a single device (ESPHome), a whole range of devices via a hub (Hue), or a service (AdGuard).

We want to start to distinguish between those in the UI in the near future, but are not currently able to do this because integrations don’t expose this information.

We already have a integration_type manifest property, which we have extended to support these new types:

  • device: The integration integrates a single device at a time.
  • hub: The integration integrates multiple devices.
  • service: The integration integrates a service.

The difference between a hub and a service or device is defined by the nature of the integration. A hub provides a gateway to multiple other devices or services. service and device are integrations that provide a single device or service per config entry.

caution

When the integration_type isn't set, we default it automatically to hub. This is a temporary fallback. We will make setting integration_type explicitly mandatory in the future.

Please update your existing (custom) integrations to set the correct integration_type in the integration manifest.

Virtual integrations

Some products are supported by integrations that are not named after the product. For example, Roborock vacuums are integrated via the Xiaomi Miio integration.

There are also cases where a product line only supports a standard IoT standard like Zigbee or Z-Wave. For example, the U-tec ultraloq works via Z-Wave and has no specific dedicated integration.

For end-users, it can be confusing to find how to integrate those products with Home Asssistant. To help with these above cases, we introduce: Virtual integrations.

Virtual integrations are not real integrations but are used to help users find the right integration for their device. They only have a single manifest file without any additional code.

There are two types of virtual integrations: A virtual integration supported by another integration and one that uses an existing IoT standard.

Read more about it in our developer documentation.

Removing the supported brands feature

Virtual integrations replace the previous "supported brands" feature. This feature was only used by Home Assistant Core integrations, and all those have been migrated to use virtual integrations instead.

There is no usage left, therefore, the supported brands feature has been removed without a deprecation period.

· One min read

The Home Assistant service hub has been extended by Ludeeus with a new feature: GitHub commands for code owners.

This feature allows any code owner to triage issues that are labeled with their integration. The following commands are available starting today:

  • @home-assistant close
    Close the issue. Limited to when there is only 1 integration labeled

  • @home-assistant rename New Title
    Change the title of the issue. Limited to when there is only 1 integration labeled

  • @home-assistant unassign <your domain>
    Remove the integration label and related assignees.

The bot will include these commands when it posts a comment to notify a code owner of a new issue or pull request (example).

· One min read

As of Home Assistant Core 2022.11, the IMPERIAL_SYSTEM is deprecated, replaced by US_CUSTOMARY_SYSTEM. The is_metric and name properties of a unit system are likewise deprecated and should not be used.

Custom integrations referencing this unit system or these properties will need to be adjusted to use instance checks instead.

Correct:

if hass.config.units is METRIC_SYSTEM:
pass

if hass.config.units is US_CUSTOMARY_SYSTEM:
pass

To avoid confusion with future unit systems, the constants CONF_UNIT_SYSTEM_IMPERIAL and CONF_UNIT_SYSTEM_METRIC are also deprecated and should no longer be referenced:

  • if they were used to compare against the name of a unit system, then this is no longer needed.
  • if they were used for another reason, then local constants should be created instead.

· One min read

As of Home Assistant Core 2022.11, options is available as a standard property of SelectEntityDescription. This might cause issues in custom integrations if a custom options property was previously implemented.

Please adjust the custom integration by either dropping or renaming the custom options property.

· One min read

Long term statistics now allows showing statistics in a different unit than it's stored in. For example, it's possible to show statistics stored as kWh as Wh, kWh or MWh.

The changes are implemented in a series of PRs:

The background is that we allow overriding the unit of several sensor device classes, and this override should also be reflected when viewing long term statistics.

This affects authors of code calling the following WS APIs:

  • recorder/adjust_sum_statistics - A new mandatory parameter adjustment_unit_of_measurement has been added, which defines the unit used by the adjustment parameter.
  • recorder/statistics_during_period - In case of statistics generated from sensor entities, the unit of returned statistics will be converted to the sensor's unit_of_measurement. This behavior can be controlled by passing the optional units parameter.