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"
  },
  "class": "light",
  "capabilities": ["onoff", "dim"],
  "energy": {
    "approximation": {
      "usageOn": 15, // in Watt
      "usageOff": 1 // in Watt
    }
  }
}

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": {
    "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.

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

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.

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

Some devices, such as example a P1 meter or current clamp, can measure the total energy usage of a home or power group. The device's measurements are added towards the total home's usage. You can mark a device measuring the cumulative energy usage by setting the cumulative property to true.

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

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