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 a device has constant usage, such as a light bulb, you should add these values to the energy object of your driver's app.json.

/app.json

{
  "id": "my_driver",
  "capabilities": [ "onoff" ],
  "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.

A user can always overwrite these values under the device's settings.

Constant usage

Some devices, such as a router, use a constant amount of energy.

/app.json

{
  "id": "my_driver",
  "capabilities": [ ],
  "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 should add the measure_power capability with the approximated: true flag as capability option.

/app.json

{
  "id": "my_driver",
  "class": "sensor",
  "capabilities": [ "onoff", "measure_power" ],
  "capabilitiesOptions": {
    "measure_power": {
      "approximated": true
    }
  }
}

Then programmatically calculate and update the measure_power value yourself.

Solar panels

Solar panels generate their own energy. Homey shows these devices in the outer ring in the Energy tab.

/app.json

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

Cumulative devices

Cumulative devices, for example a P1 meter or current clamp, measure a total of energy, usually for an entire home or power group.

/app.json

{
  "id": "my_driver",
  "class": "sensor",
  "capabilities": [ "measure_power" ],
  "energy": {
    "cumulative": true
  }
}

Cumulative devices' measurements are added towards the total home's usage. All known consuming devices will be substracted from the total, leaving an other value.

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:

/app.json

{
  "id": "my_driver",
  "class": "thermostat",
  "capabilities": [
    "measure_battery",
    "measure_temperature",
    "target_temperature"
  ],
  "energy": {
    "batteries": [ "AAA", "AAA" ]
  }
}

Possible battery values are:

• AA
• AAA
• A27
• PP3
• CR123A
• CR2
• CR1632
• CR2032
• CR2450
• CR2477
• LS14250
• INTERNAL
• OTHER