From 19845c516dd3799f44e996a9cb9bbe27fcb3042f Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Wed, 1 Mar 2023 16:02:10 +0100 Subject: [PATCH] Document ENERGY_STORAGE and VOLUME_STORAGE device classes. (#1698) --- docs/core/entity/number.md | 6 ++++-- docs/core/entity/sensor.md | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/core/entity/number.md b/docs/core/entity/number.md index 9ef1f843..3ec8875b 100644 --- a/docs/core/entity/number.md +++ b/docs/core/entity/number.md @@ -41,7 +41,8 @@ If specifying a device class, your number entity will need to also return the co | `NumberDeviceClass.DATA_RATE` | bit/s, kbit/s, Mbit/s, Gbit/s, B/s, kB/s, MB/s, GB/s, KiB/s, MiB/s, GiB/s | Data rate | `NumberDeviceClass.DATA_SIZE` | bit, kbit, Mbit, Gbit, B, kB, MB, GB, TB, PB, EB, ZB, YB, KiB, MiB, GiB, TiB, PiB, EiB, ZiB, YiB | Data size | `NumberDeviceClass.DISTANCE` | km, m, cm, mm, mi, yd, in | Generic distance -| `NumberDeviceClass.ENERGY` | Wh, kWh, MWh, MJ, GJ | Energy. Represents _power_ over _time_. Not to be confused with `power`. +| `NumberDeviceClass.ENERGY` | Wh, kWh, MWh, MJ, GJ | Energy, this device class should used to represent energy consumption, for example an electricity meter. Represents _power_ over _time_. Not to be confused with `power`. +| `NumberDeviceClass.ENERGY_STORAGE` | Wh, kWh, MWh, MJ, GJ | Stored energy, this device class should be used to represent stored energy, for example the amount of electric energy currently stored in a battery or the capacity of a battery. Represents _power_ over _time_. Not to be confused with `power`. | `NumberDeviceClass.FREQUENCY` | Hz, kHz, MHz, GHz | Frequency | `NumberDeviceClass.GAS` | m³, ft³, CCF | Volume of gas. Gas consumption measured as energy in kWh instead of a volume should be classified as energy. | `NumberDeviceClass.HUMIDITY` | % | Relative humidity @@ -69,7 +70,8 @@ If specifying a device class, your number entity will need to also return the co | `NumberDeviceClass.TEMPERATURE` | °C, °F, K | Temperature. | `NumberDeviceClass.VOLATILE_ORGANIC_COMPOUNDS` | µg/m³ | Concentration of volatile organic compounds | `NumberDeviceClass.VOLTAGE` | V, mV | Voltage -| `NumberDeviceClass.VOLUME` | L, mL, gal, fl. oz., m³, ft³, CCF | Generic volume +| `NumberDeviceClass.VOLUME` | L, mL, gal, fl. oz., m³, ft³, CCF | Generic volume, this device class should be used to represent a consumption, for example the amount of fuel consumed by a vehicle. +| `NumberDeviceClass.VOLUME_STORAGE` | L, mL, gal, fl. oz., m³, ft³, CCF | Generic stored volume, this device class should be used to represent a stored volume, for example the amount of fuel in a fuel tank. | `NumberDeviceClass.WATER` | L, gal, m³, ft³, CCF | Water consumption | `NumberDeviceClass.WEIGHT` | kg, g, mg, µg, oz, lb, st | Generic mass; `weight` is used instead of `mass` to fit with every day language. | `NumberDeviceClass.WIND_SPEED` | ft/s, km/h, kn, m/s, mph | Wind speed diff --git a/docs/core/entity/sensor.md b/docs/core/entity/sensor.md index 2a9ef560..61270150 100644 --- a/docs/core/entity/sensor.md +++ b/docs/core/entity/sensor.md @@ -44,7 +44,8 @@ If specifying a device class, your sensor entity will need to also return the co | `SensorDeviceClass.DATE` | | Date. Requires `native_value` to be a Python `datetime.date` object, or `None`. | `SensorDeviceClass.DISTANCE` | km, m, cm, mm, mi, yd, in | Generic distance | `SensorDeviceClass.DURATION` | d, h, min, s | Time period. Should not update only due to time passing. The device or service needs to give a new data point to update. -| `SensorDeviceClass.ENERGY` | Wh, kWh, MWh, MJ, GJ | Energy. Represents _power_ over _time_. Not to be confused with `power`. +| `SensorDeviceClass.ENERGY` | Wh, kWh, MWh, MJ, GJ | Energy, this device class should used for sensors representing energy consumption, for example an electricity meter. Represents _power_ over _time_. Not to be confused with `power`. +| `SensorDeviceClass.ENERGY_STORAGE` | Wh, kWh, MWh, MJ, GJ | Stored energy, this device class should be used for sensors representing stored energy, for example the amount of electric energy currently stored in a battery or the capacity of a battery. Represents _power_ over _time_. Not to be confused with `power`. | `SensorDeviceClass.ENUM` | | The sensor has a limited set of (non-numeric) states. The `options` property must be set to a list of possible states when using this device class. | `SensorDeviceClass.FREQUENCY` | Hz, kHz, MHz, GHz | Frequency | `SensorDeviceClass.GAS` | m³, ft³, CCF | Volume of gas. Gas consumption measured as energy in kWh instead of a volume should be classified as energy. @@ -74,7 +75,8 @@ If specifying a device class, your sensor entity will need to also return the co | `SensorDeviceClass.TIMESTAMP` | | Timestamp. Requires `native_value` to return a Python `datetime.datetime` object, with time zone information, or `None`. | `SensorDeviceClass.VOLATILE_ORGANIC_COMPOUNDS` | µg/m³ | Concentration of volatile organic compounds | `SensorDeviceClass.VOLTAGE` | V, mV | Voltage -| `SensorDeviceClass.VOLUME` | L, mL, gal, fl. oz., m³, ft³, CCF | Generic volume +| `SensorDeviceClass.VOLUME` | L, mL, gal, fl. oz., m³, ft³, CCF | Generic volume, this device class should be used for sensors representing a consumption, for example the amount of fuel consumed by a vehicle. +| `SensorDeviceClass.VOLUME_STORAGE` | L, mL, gal, fl. oz., m³, ft³, CCF | Generic stored volume, this device class should be used for sensors representing a stored volume, for example the amount of fuel in a fuel tank. | `SensorDeviceClass.WATER` | L, gal, m³, ft³, CCF | Water consumption | `SensorDeviceClass.WEIGHT` | kg, g, mg, µg, oz, lb, st | Generic mass; `weight` is used instead of `mass` to fit with every day language. | `SensorDeviceClass.WIND_SPEED` | ft/s, km/h, kn, m/s, mph | Wind speed