Energy

In order for you driver to be automatically taken into account by Homey Energy it needs to define an energy object. This object contains basic data and preset used by Homey Energy.

Homey Energy has a unified front-end in the "energy" tab of the mobile application. Where you will be able to find the live power usage of devices, zones and the entire house.

Format

  "energy": {
    "approximation": {
      "functionType": string,
      "usageOn": number,
      "usageOff": number
    },
    "generating": boolean,
    "reduceWaste": boolean
  }

As seen above the energy object consists of multiple parts. The first part is an approximation object, for devices that do not report their power usage. The second part is a set of flags to indicate device properties and behaviour.

Approximation

In this object you specify the mathematical function that the power usage of the device follows out of constant, linear or exponential. Devices that only support on/off will often be constant, single light sources such as bulbs will often be linear and devices such as LED strips will often be exponential.

Besides describing the mathematical function you also have to provide 2 data points for the function calculation. One power measurement when the device is off/in stand-by mode and one with the device on at full power.

These approxmiation values can also be defined by the user if you choose omit them, and users are always able to change the given data.

Flags

The following section are two boolean flags. These indicate certain things about the device. generating indicates that a device delivers power instead of using power. Whilst reduceWaste is a flag to enable/disable the automatic power saving features of Homey Energy for this device. Again both of these flags can be user defined if you choose to omit them, and users are always able to change these flags.

JSON example

/app.json

  {
    "id": "energy-example-driver",
    "name": "Example Energy Driver",
    "capabilities": [],
    "energy": {
      "approximation": {
        "functionType": "linear",
        "usageOn": 8,
        "usageOff": 2
      },
      "generating": false,
      "reduceWaste": true
    }
  }

Programmatic example

The energy object can be passed along with the other device information in the pairing step. To do so you will need to create and append the energy object to your device object in the onPairListDevices step.

  onPairListDevices( state, data, callback ) {
    let deviceObj = {
      name: 'device name',
      icon: 'path/to/icon',
      data: {...},
      energy: {
        approximation: {
          functionType: 'linear',
          usageOn: 8,
          usageOff: 2
        },
        generating: false,
        reduceWaste: true
      }
    };

    callback( null, deviceObj );
  }

This way of appending the energy object to a device allows for more flexibility. This is especially helpful if different device types and specifications share one driver. This allows all the different device specifications and types to share a driver but still differ in power approximation data.