Energy
By defining the energy usage (or generation) of the devices your app supports users can generate detailed reports of their energy consumption.
Devices in Homey can either consume energy (e.g. a light bulb), generate energy (e.g. solar panels) or measure the home's total usage (e.g. a P1 meter or current clamp).
Consuming devices
A consuming device is a regular device in Homey, for example a light bulb or TV. There are three strategies to determine energy usage.
Built-in power meter
When a device supports the measure_power capability (real-time energy usage in Watts), such as a smart socket, Homey automatically uses this value for that device.
Same goes for devices that support the meter_power capability (cumulative energy usage in kWh). For example, a washing machine that tracks its energy consumption would use the meter_power capability to keep track of how much energy is consumed over longer periods of time.
If a device can measure both imported and exported energy—such as a smart plug connected to portable solar panels or a small home battery—the smart plug driver should define the meterPowerImportedCapability and meterPowerExportedCapability energy properties, as shown below.
Imported energy refers to the energy consumed by the device.
Exported energy refers to the energy produced by the device.
Note: the
meter_powercapability must always be positive and ever-increasing (cumulative). Homey Energy calculates energy usage over a given period by analyzing the difference in this value over time. Ifmeter_powercapability values are periodically reset to zero or decrease unexpectedly, it may lead to data loss.
Approximated power usage
In cases where devices do not support measure_power real-time energy usage in Watts, there are a few options to approximate the device's energy consumption. Homey can calculate the energy usage based on the onoff and dim capabilities when there is no measure_power capability available. Homey will provide the user with settings to configure the energy consumption when the device is turned on, turned off, or (when a device can't be turned on or off) its constant energy consumption. Using these settings Homey approximates the energy usage by calculating the total on-time, optionally taking into account the brightness level.
Constant usage
If you already know the energy consumption of the device (often this can be found on the packaging or the device itself) add the usageOnand usageOff properties to the energy.approximation object of your driver's manifest. Below you can find an example of a light bulb driver that consumes 15W when turned on, and 1W when turned off. This eliminates the need for the user to configure it manually.
Keep in mind that a user can always overwrite these values under the device's settings.
Some devices, such as a router, use a constant amount of energy. In this case you can add the usageConstant property.
Dynamic usage
The power usage of some devices depends on their configuration. For example, Nanoleaf light panels let the user add more panels to the system, increasing the total energy consumption of the device.
In these kind of scenarios you need to add the measure_power capability with the approximated: true flag as capability option. Then programmatically calculate and update the measure_power value yourself.
By adding the approximated: true flag the user will be shown that this value is an approximation and not a precisely measured value.
Generating devices
Some Devices can generate their own energy. Homey will show these devices separately in the UI.
Solar panels
Solar panels are a common device in Homey that can generate their own energy.
You should provide the generated power (measure_power) as a positive value. When providing a negative value, e.g. -13 watt, Homey assumes the solar panel is currently consuming instead of generating energy.
In order for cumulative electricity generation (kWh) to be tracked in Energy the driver must have a meter_power capability that will be set to the total generated electricity in kWh as a positive value. Use the meterPowerExportedCapability energy property to use a different meter_power capability for generated energy (see Built-in power meter).
Note: the
meter_powercapability must always be positive and ever-increasing (cumulative). Homey Energy calculates energy generation over a given period by analyzing the difference in this value over time. Ifmeter_powercapability values are periodically reset to zero or decrease unexpectedly, it may lead to data loss.
Smart plugs
Some smart plugs (with device class socket) can measure energy being generated. A user can choose a different device class in the What's plugged in? setting.
Solar panels
Important difference with the regular solarpanel device class is that the generated power must be set as a negative value (e.g. setCapabilityValue('measure_power', -200)). Homey will then invert this value automatically.
Homey will use the value of the meter_power capability to determine the energy generated by the solar panels in kWh. Use the meterPowerExportedCapability energy property to use a different meter_power capability for generated energy (see Built-in power meter).
Batteries
Small portable home batteries can be connected to a smart plug in order to charge and discharge. Users can choose "Batteries" as device class in the What's plugged in? setting.
The smart plug driver should have the measure_power capability. The value must be positive when the smart plug is consumed power (charging the battery) and negative when producing power (discharging the battery).
For the charged and discharged energy to be registered correctly by Homey, smart plug drivers must include the meterPowerExportedCapability and meterPowerExportedCapability energy properties (see Home batteries).
Note: the
meter_powercapability must always be positive and ever-increasing (cumulative). Homey Energy calculates energy generation over a given period by analyzing the difference in this value over time. Ifmeter_powercapability values are periodically reset to zero or decrease unexpectedly, it may lead to data loss.
Measuring devices
Certain devices, such as a P1 meter or a current clamp, can measure the total energy usage of a home or a specific power group. Their measurements contribute to the overall energy consumption data for the entire home. This means that these are the highest level measuring devices in a home. All other energy consuming or generating devices in a home are measured by these devices.
To mark a device that measures cumulative energy usage, set the cumulative property to true in your driver's configuration. In case of a gas or water meter device, the cumulative property can also be applied. Homey will then read the meter_gas and meter_water capabilities to determine the gas and water usage of the whole home.
Note: the
meter_power,meter_gasandmeter_watercapabilities must always be positive and ever-increasing (cumulative). Homey Energy calculates energy consumption over a given period by analyzing the difference in this value over time. Ifmeter_powercapability values are periodically reset to zero or decrease unexpectedly, it may lead to data loss.
Most devices that track the total energy usage of a home or power group are capable of measuring both imported and exported energy. For instance, a P1 meter can measure energy imported from the grid as well as energy exported back to the grid, such as solar-generated power.
To enable Homey to distinguish between imported and exported energy, you must define the capabilities used for these measurements by setting the cumulativeImportedCapability and cumulativeExportedCapability properties. These properties should be assigned to the corresponding capability of your device responsible for measuring imported and exported energy. If your device only supports measurement of imported energy you can omit the cumulativeExportedCapability and only include the cumulativeImportedCapability. If your device does not support separate measurement of imported and exported energy at all, you should omit these properties, this will result in the device being excluded from features that require the distinction between imported and exported energy.
Note: the
meter_powercapabilities used for imported and exported energy must always be positive and ever-increasing (cumulative). Homey Energy calculates energy consumption over a given period by analyzing the difference in this value over time. Ifmeter_powercapability values are periodically reset to zero or decrease unexpectedly, it may lead to data loss.
Note: the
cumulativeImportedCapabilityandcumulativeExportedCapabilityare only used on Homey Pro (Early 2023), or newer, and Homey Cloud.
Home batteries
Home batteries are devices that can store energy for later use. When creating a driver for a home battery device, apply the device class battery and set the homeBattery property in the energy object of the driver.
Home batteries should have the measure_power capability. This represents the real-time energy consumption of the home battery in Watts. Provide positive values to indicate the battery is consuming energy (charging), provide negative values to indicate the battery is delivering energy back to the home (discharging).
In case the home battery does not support this, you can fallback to the battery_charging_state capability. This indicates the current state of the battery, charging, discharging or idle. By omitting the measure_power capability some functionality in Homey Energy will be lost.
Additionally, home batteries should have the measure_battery capability to indicate the current state of charge of the battery.
Note: the
homeBatteryenergy property is available as of Homey v12.3.0.
To enable Homey to distinguish between the charged and discharged energy of the battery, you must define the capabilities used for these measurements by setting the meterPowerImportedCapability (charged) and meterPowerExportedCapability (discharged) properties. These properties should be assigned to the corresponding capability of your device responsible for measuring charged and discharged energy. If your device does not support separate measurement of charged and discharged energy, you should omit these properties, this will result in the device being excluded from features that require the distinction between charged and discharged energy.
Note: the
meter_powercapabilities used for charged and discharged energy must always be positive and ever-increasing (cumulative). Homey Energy calculates energy consumption over a given period by analyzing the difference in this value over time. Ifmeter_powercapability values are periodically reset to zero or decrease unexpectedly, it may lead to data loss.
Note: the
meterPowerImportedCapabilityandmeterPowerExportedCapabilityare only used on Homey Pro (Early 2023), or newer, and Homey Cloud, and are available as of v12.4.5.
EVs
EVs are battery electric cars. These cars can be charged by an EV charger. When creating a driver for an EV, apply the device class car and set the electricCar property in the energy object of the driver.
EVs should have the measure_battery capability which reflects the current state of charge of the battery. Additionally, the ev_charging_state capability should be added when the EV can report its current charging state (plugged in/out, charging, discharging).
Batteries
All devices with the measure_battery or alarm_battery capability must specify which type and the amount of batteries they use. This will be shown to the user in the UI. If the device is a home battery you can leave this out, please see #home-battery.
For example, a device with 2x AAA batteries:
Possible battery values are:
LS14250CAAAAAAAAAA23A27PP3CR123ACR2CR1632CR2032CR2430CR2450CR2477CR3032CR14250INTERNALOTHER
Settings
Homey provides a couple of settings to Energy devices under certain conditions:
Always on
This setting is provided to devices that have device class socket and the onoff capability. By default it is disabled, but when enabled, Homey will prevent the user from turning off the device through Homey. An error message will be returned when this is attempted.
Exclude from Energy
This setting is provided to devices that have the meter_power or measure_power capability, have device class solarpanel(or Solar panel in the What's plugged in? setting), or are marked as cumulative measuring devices (see Measuring devices). By default it is disabled, but when enabled Homey will no longer show the device in the Zone Control Energy, nor will it be included in future Energy reports (note: this will not remove the device from existing Energy reports).
Tracks total home energy consumption
This setting is provided to devices that are marked as cumulative measuring devices (see Measuring devices). By default this setting is enabled, this will make sure Homey considers this device as a device that measures energy consumption at the highest level in the home. When disabled it will consider the device as a regular device in the home that measures energy consumption.
Invert power measurement
Power usage when off
This setting is provided to devices that do not have the measure_power capability and do have the onoff capability. The default value for this setting can be determined by the driver (see Constant usage). It will be used to approximate the device's energy consumption.
Power usage when on
This setting is provided to devices that do not have the measure_power capability and do have the onoff capability. The default value for this setting can be determined by the driver (see Constant usage). It will be used to approximate the device's energy consumption.
Constant power usage
This setting is provided to devices that do not have the measure_power, onoff, measure_battery or alarm_battery capability. Devices that have defined batteries in the driver's manifest will also not get this setting, nor will devices with a device class listed below. The default value for this setting can be determined by the driver (see Constant usage). It will be used to approximate the device's energy consumption.
buttonwindowcoveringsblindscurtainsunshadekettlecoffeemachineremotesolarpanelvacuumcleanerthermostat
Dynamically changing the energy configuration
Note: try not to use these methods too often, as they are quite impactful. They should only be used when initially configuring the device.
Last updated
Was this helpful?