Energy

By defining the energy (kWh) and power (W) usage or generation of the devices your app supports, Homey can provide detailed reports and insights into their energy consumption.

Capabilities

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). For this the measure_power and meter_power capabilities are used by Energy.

Power – `measure_power` capability

The measure_power capability represents the instantaneous power usage or generation of a device, measured in watts (W). It indicates how much power a device is currently consuming or producing at a given moment.

Energy – `meter_power` capability

The meter_power capability (or meter_power sub capabilities) tracks the total amount of energy consumed or generated over time, measured in kilowatt-hours (kWh). This value should be positive and continuously increase. It is typically reset only when the device is reset or reinstalled.

Energy calculates energy consumption over a given period by analyzing the difference in the meter_power value over time. If the values are periodically reset to zero or decrease unexpectedly, it may lead to data loss or invalid interpretations.

Energy configuration

Throughout this document the energy configuration is often referred to. It describes the energy configuration object as defined in the drivers manifest, for example:

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "energy": {
    "meterPowerImportedCapability": "meter_power.imported",
    "meterPowerExportedCapability": "meter_power.exported"
  }
}

This object is used to set various properties defined in the sections below. By default any changes made to the energy configuration in this file will be applied directly to existing and already connected devices. However, this is not the case when the device has applied an energy configuration override using Device.setEnergy() (see Dynamically changing the energy configurationfor more details).

To access the energy configuration as set in this file use the Driver.manifest property.

Dynamically changing the energy configuration

In some cases, you need to set the energy configuration dynamically. For example when the required properties depend on the specific device or its capabilities which are not known upfront. In this case it is possible to override the energy configuration from driver.compose.json.

To set the energy configuration dynamically use Device.setEnergy() . You must provide the complete energy configuration to Device.setEnergy() as it will overwrite all the existing properties. Note that once Device.setEnergy() is called, the device will disregard all properties set in the energy configuration in driver.compose.json.

When required to go back to the energy configuration from driver.compose.json after using Device.setEnergy() it is possible to call Device.setEnergy(null) with a null value to undo the energy configuration override.

Use Device.getEnergy() to get the energy configuration override as set by Device.setEnergy() . Note that this will not return the energy configuration from driver.compose.json, but only the configuration set with Device.setEnergy() .

/drivers/<driver_id>/device.js

const DeviceApi = require("device-api");
class MyDevice extends Homey.Device {
  async onInit() {
    const energyConfig = this.getEnergy();
    DeviceApi.on("energy-settings", (energySettings) => {
      if (energySettings.isSmartMeter() && energyConfig.cumulative !== true) {
        this.setEnergy({
          cumulative: true,
          cumulativeImportedCapability: "meter_power.imported",
        }).catch(this.error);
      }
    });
  }
}
module.exports = MyDevice;

Try not to use these methods too often, as they are quite impactful. They should only be used when initially configuring the device.

Power

Devices in Homey can consume power, for example a light bulb or TV, and generate power, for example solar panels or home batteries (by discharging). There are two strategies to determine power usage:

Measuring Power Usage When the device itself provides actual power measurements ( Measuring power usage).
Approximating Power Usage When a device does not provide actual power measurements, its can be estimated in two ways:
1. Using configurable power usage properties Define static values in the device's energy configuration (e.g., usageConstant, usageOff, or usageOn) to approximate consumption based on the device's state (Constant power usage).
2. Using approximated measure_power values Provide values for the measure_power capability and explicitly mark them as approximations using the measure_power.approximation flag (Dynamic power usage). This indicates that the values are not based on actual measurements.

Measuring power usage

When a device supports the measure_power capability (real-time power usage in Watts), such as a smart socket, Homey automatically uses this value for that device.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "class": "socket",
  "capabilities": ["onoff", "measure_power"]
}

Approximating power usage

In cases where devices do not support measure_power real-time power usage in Watts, there are a few options to approximate the device's power consumption. Homey can calculate the power 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 power consumption when the device is turned on, turned off, or (when a device can't be turned on or off) its constant power consumption. Using these settings Homey approximates the power usage by calculating the total on-time, optionally taking into account the brightness level.

Constant power usage

If you already know the power 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.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "platforms": ["local", "cloud"],
  "connectivity": "zigbee",
  "class": "light",
  "capabilities": ["onoff", "dim"],
  "energy": {
    "approximation": {
      "usageOn": 15, // in Watt
      "usageOff": 1 // in Watt
    }
  }
}

When a device has a stand-by function, use the stand-by value for usageOff.

Some devices, such as a router, use a constant amount of power. In this case you can add the usageConstant property.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "energy": {
    "approximation": {
      "usageConstant": 5 // in Watt
    }
  }
}

Keep in mind that a user can always overwrite these values under the device's settings.

Dynamic power 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 power 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.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "class": "sensor",
  "capabilities": ["onoff", "measure_power"],
  "capabilitiesOptions": {
    "measure_power": {
      "approximated": true
    }
  }
}

/drivers/<driver_id>/device.js

const Homey = require('homey');
const DeviceApi = require('device-api');

class MyDevice extends Homey.Device {
  async onInit() {
    DeviceApi.on('power-usage-changed', (watts) => {
      this.setCapabilityValue('measure_power', watts).catch(this.error);
    });
  }
}

module.exports = MyDevice;

Energy

Devices in Homey can report energy (kWh) consumption, for example a washing machine, and energy generation, for example solar panels or home batteries (by discharging). These devices should have 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 home battery—the driver should define the meterPowerImportedCapability and meterPowerExportedCapability energy properties, as shown below.

Imported energy refers to the energy consumed or charged by the device.
Exported energy refers to the energy produced or discharged by the device.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "class": "socket",
  "capabilities": ["onoff", "measure_power", "meter_power.imported", "meter_power.exported"],
  "energy": {
    "meterPowerImportedCapability": "meter_power.imported",
    "meterPowerExportedCapability": "meter_power.exported"
  }
}

You can set any capability as the value of meterPowerImportedCapability and meterPowerExportedCapability as long it is in instance of the meter_power capability and is present in the capabilities array of the driver.

The meterPowerImportedCapability and meterPowerExportedCapability are only used on Homey Pro (Early 2023), Homey Pro mini, and Homey Cloud and are available as of v12.4.5.

Devices

There are various types of devices that have some special features or requirements in Energy.

Solar panels

Solar panels are a common device in Homey that can generate their own power. These devices must have the solarpanel device class.

The measure_power value should positive when generating power. When providing a negative value, e.g. -13 watt, Homey assumes the solar panel is currently consuming instead of generating power.

In order for cumulative energy generation (kWh) to be tracked in Energy the driver must have a meter_power capability that will be set to the total generated energy in kWh as a positive value. Use the meterPowerExportedCapability energy property to configure a different meter_power capability for generated energy.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "class": "solarpanel",
  "capabilities": ["measure_power", "meter_power"],
  "energy": {
    "meterPowerExportedCapability": "meter_power" // Optional: defaults to meter_power
  }
}

Smart plugs

Devices with device class socket (often smart plugs), can measure power and energy being consumed and generated. To learn how to configure this see Measuring power usage. A user can choose a different device class in the What's plugged in? setting. Among others, solarpanel, battery and evcharger. To properly support these three device classes please take the following into account.

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.

Users will get the Invert power measurement setting to manually switch the generated power from positive to negative or vice versa.

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

Batteries

Small portable home batteries can be connected to a smart plug in order to charge and discharge.

The measure_power value must be positive when the smart plug is consuming power (charging the battery) and negative when producing power (discharging the battery).

By default the meter_power capability of the smart plug will be used to determine the energy charged by the battery. Additionally, for the charged and discharged energy to be registered separately by Homey, smart plug drivers must include the meterPowerImportedCapability and meterPowerExportedCapability energy properties (see Home batteries).

EV chargers

Users can charge EVs using smart plugs. To allow the smart plug to act as an EV charger in Energy the user can choose "EV Charger" as device class in the What's plugged in? setting of smart plugs. This will include the smart plug's power measurements in Energy as if it were an EV charger.

The measure_power value must be positive when the smart plug is consuming power (charging the EV's battery) and negative when producing power (discharging the EV's battery).

By default the meter_power capability of the smart plug will be used to determine the energy charged by the EV charger. Additionally, for the charged and (if applicable) discharged energy to be registered separately by Homey, smart plug drivers must include the meterPowerImportedCapability and meterPowerExportedCapability energy properties (see EV chargers).

Cumulative measuring devices

Certain devices, such as a P1 meter or a current clamp, can measure the total power and energy usage of a home or a specific power group. Their measurements contribute to the overall power consumption data for the entire home. This means that these are the highest level measuring devices in a home. All other power consuming or generating devices in a home are measured by these devices. This is called cumulative measuring.

To mark a device that measures cumulative power and 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.

The meter_gas capability tracks the total amount of gas consumed over time, measured in cubic metres (m3).
The meter_water capability tracks the total amount of water consumed over time, measured in cubic metres (m3).

Both capabilities should be positive and continuously increase. It is typically reset only when the device is reset or reinstalled.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "class": "sensor",
  "capabilities": ["measure_power"],
  "energy": {
    "cumulative": true
  }
}

All power-consuming devices in Homey are subtracted from the total measured power usage of all cumulative devices. The remaining, unaccounted-for power usage will be displayed as "other."

Most devices that track the total power 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 (e.g. solar-generated energy).

If a device can measure both imported and exported energy for the whole home or power group, the driver should define the cumulativeImportedCapability and cumulativeExportedCapability energy properties, as shown below.

Imported energy refers to the cumulative energy imported from the device's perspective.
Exported energy refers to the cumulative energy exported from the device's perspective.

These properties should be assigned to the corresponding capabilities of the device responsible for measuring imported and exported energy. If the device only supports measuring imported energy you can omit the cumulativeExportedCapability . If the 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.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "class": "sensor",
  "capabilities": ["measure_power", "meter_power.imported", "meter_power.exported"],
  "capabilitiesOptions": {
    "meter_power.imported": {
      "title": { "en": "Imported Energy" }
    },
    "meter_power.exported": {
      "title": { "en": "Exported Energy" }
    }
  },
  "energy": {
    "cumulative": true,
    "cumulativeImportedCapability": "meter_power.imported",
    "cumulativeExportedCapability": "meter_power.exported"
  }
}

The cumulativeImportedCapability and cumulativeExportedCapability properties are only used on Homey Pro (Early 2023), Homey Pro mini, and Homey Cloud and are available as of Homey v12.3.0.

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 power consumption of the home battery in Watts. Provide positive values to indicate the battery is consuming power (charging), provide negative values to indicate the battery is delivering power 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 Energy will be lost.

Additionally, home batteries should have the measure_battery capability to indicate the current state of charge of the battery.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "class": "battery",
  "capabilities": ["measure_power", "measure_battery"],
  "energy": {
    "homeBattery": true
  }
}

The homeBattery energy property is available as of Homey v12.3.0.

By default the meter_power capability will be used to determine the energy charged by the battery. To enable Homey to distinguish between the charged and discharged energy of the battery, the driver should define the meterPowerImportedCapability and meterPowerExportedCapability energy properties, as shown below.

Imported energy refers to the energy charged by the battery.
Exported energy refers to the energy discharged by the battery.

These properties should be assigned to the corresponding capabilities 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.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "class": "battery",
  "capabilities": ["measure_power", "measure_battery", "meter_power.charged", "meter_power.discharged"],
  "capabilitiesOptions": {
    "meter_power.charged": {
      "title": { "en": "Charged Energy" }
    },
    "meter_power.discharged": {
      "title": { "en": "Discharged Energy" }
    }
  },
  "energy": {
    "homeBattery": true,
    "meterPowerImportedCapability": "meter_power.charged",
    "meterPowerExportedCapability": "meter_power.discharged"
  }
}

The meterPowerImportedCapability and meterPowerExportedCapability are only used on Homey Pro (Early 2023), Homey Pro mini, and Homey Cloud, and are available as of v12.4.5.

EV chargers

EV chargers are devices that can be used at home to charge EVs. When creating a driver for an EV charger, apply the device class evcharger and set the evCharger property in the energy object of the driver. EV chargers should have the measure_power capability. This represents the real-time power consumption of the EV charger in Watts. This value can be positive and negative.

Positive when the EV charger is charging the connected EV.
Negative when the EV charger supports bi-directional charging and is currently discharging the connected EV.

To accurately reflect the charging state of the EV charger add the evcharger_charging_state capability. This allows the user to easily see the state of the EV charger and act on state changes like "EV is plugged in".

Finally, to allow for easy control of the EV charger add the evcharger_charging capability. This capability acts like the on/off switch with regards to charging, and automatically generates useful Flow cards like "Start charging" and "Is charging".

By default the meter_power capability will be used to determine the energy charged by the EV charger. To enable Homey to distinguish between the charged and discharged energy of the EV charger, the driver should define the meterPowerImportedCapability and meterPowerExportedCapability energy properties, as shown below.

Imported energy refers to the energy charged by the EV charger.
Exported energy refers to the energy discharged by the EV charger.

These properties should be assigned to the corresponding capabilities of your device responsible for measuring charged and discharged energy. If your device does not support discharging just omit the meterPowerExportedCapability property.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "class": "evcharger",
  "capabilities": [
    "measure_power",
    "evcharger_charging",
    "evcharger_charging_state",
    "meter_power.charged",
    "meter_power.discharged"
  ],
  "capabilitiesOptions": {
    "meter_power.charged": {
      "title": { "en": "Charged Energy" }
    },
    "meter_power.discharged": {
      "title": { "en": "Discharged Energy" }
    }
  },
  "energy": {
    "evCharger": true,
    "meterPowerImportedCapability": "meter_power.charged",
    "meterPowerExportedCapability": "meter_power.discharged"
  }
}

The evCharger property and the evcharger_charging and evcharger_charging_state capabilities 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 represents 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).

/drivers/<driver_id>/driver.compose.json

  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "class": "car",
  "capabilities": ["measure_battery", "ev_charging_state"],
  "energy": {
    "electricCar": true
  }
}

The electricCar energy property and ev_charging_state capability are available as of Homey v12.4.5.

Batteries

All devices with the measure_battery or alarm_battery capability (except home batteries and EVs) must specify which type and the amount of batteries they use. This will be shown to the user in the UI.

For example, a device with 2x AAA batteries:

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "class": "thermostat",
  "capabilities": ["measure_battery", "measure_temperature", "target_temperature"],
  "energy": {
    "batteries": ["AAA", "AAA"]
  }
}

Possible battery values are:

LS14250
C
AA
AAA
AAAA
A23
A27
PP3
CR123A
CR2
CR1632
CR2032
CR2430
CR2450
CR2477
CR3032
CR14250
INTERNAL
OTHER

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 Cumulative 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 Cumulative 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

This setting is available for devices with the socket device class when the user selects "Solar panel" in the What's plugged in? setting. It allows the user to invert the sign (positive or negative) of the measure_power capability for this device. This is useful for accurately representing power flow, ensuring that produced power is displayed correctly. For more details, see Smart plugs.

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 power usage). It will be used to approximate the device's power consumption.

Power usage when on

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 power usage). It will be used to approximate the device's power consumption.

button
windowcoverings
blinds
curtain
sunshade
kettle
coffeemachine
remote
solarpanel
vacuumcleaner
thermostat

PreviousCapabilities NextSettings

Last updated 23 days ago

Was this helpful?

Capabilities

Power – measure_power capability

Energy – meter_power capability

Energy configuration

Dynamically changing the energy configuration

Power

Measuring power usage

Approximating power usage

Constant power usage

Dynamic power usage

Energy

Devices

Solar panels

Smart plugs

Solar panels

Batteries

EV chargers

Cumulative measuring devices

Home batteries

EV chargers

EVs

Batteries

Settings

Always on

Exclude from Energy

Tracks total home energy consumption

Invert power measurement

Power usage when off

Power usage when on

Constant power usage

Power – `measure_power` capability

Energy – `meter_power` capability