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.

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. If meter_power capability 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_powerreal-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.

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

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.

/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
    }
  }
}

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.

/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;

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.

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. If meter_power capability values are periodically reset to zero or decrease unexpectedly, it may lead to data loss.

/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"]
}

Smart plugs

Some smart plugs (with device class socket) can measure energy being generated. In this case, a user can choose Solar panel in the What's plugged in? setting. Important difference with the solarpaneldevice class is that the generated energy must be set as a negative value (e.g. setCapabilityValue('measure_power', -200)). Homey will then invert this value automatically.

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_gasandmeter_water capabilities to determine the gas and water usage of the whole home.

Note: the meter_power, meter_gasand meter_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. If meter_power capability values are periodically reset to zero or decrease unexpectedly, it may lead to data loss.

/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 known energy-consuming devices are subtracted from the total measured energy usage of all cumulative devices. The remaining, unaccounted-for energy usage will be displayed as "other."

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. If meter_power capability values are periodically reset to zero or decrease unexpectedly, it may lead to data loss.

/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"
  }
}

Note: the cumulativeImportedCapabilityand cumulativeExportedCapabilityare 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 batteryand set the homeBatteryproperty 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_powercapability some functionality in Homey Energy will be lost.

Additionally, home batteries should have the measure_batterycapability 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
  }
}

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:

/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 socketand the onoffcapability. 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_poweror measure_powercapability, have device class solarpanel(or Solar panel in the What's plugged in? setting), or are marked as cumulativemeasuring 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 cumulativemeasuring 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.

Power usage when off

This setting is provided to devices that do not have the measure_powercapability and do have the onoffcapability. 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_powercapability and do have the onoffcapability. 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 batteriesin 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.

• button

• windowcoverings

• blinds

• curtain

• sunshade

• kettle

• coffeemachine

• remote

• solarpanel

• vacuumcleaner

• thermostat

Dynamically changing the energy configuration

In some cases a driver doesn't know upfront what the properties in the driver's energy object should be. For these cases use Device.getEnergy()and Device.setEnergy() . You must provide the complete energy configuration to setEnergy() as it will overwrite all the existing properties.

/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;

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