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.

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

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

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.

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.

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).

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.

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.

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:

• https://github.com/home-assistant/core/pull/78031
• https://github.com/home-assistant/core/pull/78578
• https://github.com/home-assistant/core/pull/79370

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.

As of Home Assistant Core 2022.10, the following utilities are deprecated:

• homeassistant/util/distance
• homeassistant/util/pressure
• homeassistant/util/speed
• homeassistant/util/temperature
• homeassistant/util/volume

Please use the corresponding static classes from homeassistant/util/unit_conversion:

• DistanceConverter
• PressureConverter
• SpeedConverter
• TemperatureConverter
• VolumeConverter

Several new sensor device classes have been added:

• distance, a distance measured in either of cm, ft, in, km, m, mi, mm, yd
• speed, a speed measured in either of ft/s, in/d, in/h, km/h, kn, m/s, mm/d, mph
• volume, a volume measured in either of fl. oz., ft³, gal, L, mL, m³
• weight, a mass measured in either of g, kg, lb, mg, oz, µg

Like pressure and temperatures sensors, users can freely choose the display unit from the UI for sensors using any of the new device classes.

Long term statistics​

Long term statistics will store distance as m, speed as m/s, volume as m³ and weight as g. For existing sensors which are modified to one of the new device classes, statistics will continue to be recorded in the sensor's state_unit but users will be given the option to have existing statistics converted to the normalized unit.