Energy

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"]
}
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
  }
}
All known consuming devices will be subtracted from the total measured, showing the remaining usage as other.
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

Capabilities

Settings

Last modified 10mo ago

Copy link

Outline

Consuming devices

Built-in power meter

Approximated power usage

Constant usage

Dynamic usage

Generating devices

Smart plugs

Measuring devices

Batteries