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 has the measure_power capability, e.g. a smart socket, Homey automatically uses this value for that device.

Approximated power usage

Homey can calculate the energy usage based on the onoff and dim capabilities, when there is no measure_power capability available.

Homey will approximate the energy usage by calculating the total on-time and optionally the brightness level.

Constant usage

If the energy usage of the device is known, you should add these values to the energy object of your driver's manifest. For example for a light bulb you can add the energy usage while the light is on and the usage while it is turned off like this:

/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

Some devices' power usage depend on their configuration. For example, Nanoleaf light panels let the user add more panels to the system.

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

Devices, such as solar panels, can generate their own energy. Homey shows these devices in the outer ring in the Energy tab.

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

Homey will show this device separately in the UI. You should provide the generated 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 generated electricity in kWh. This value should be ever increasing, do not reset this value periodically as it might result in minor data loss.

Smart plugs

Some smart plugs can measure energy being returned to the net. In this case, a user can choose Solar panel in the What's plugged in? setting. Set your generated energy value as a negative (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. 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/meter_water capabilities to determine the gas and water usage of the whole home.

/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 does not support separate measurement of imported and exported energy, you can omit these properties. These meter_power values should be ever increasing, do not reset these values periodically as that might result in minor 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"
  }
}

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.

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