Energy

By defining the energy (kWh) and power (W) usage or generation of the devices your app supports, Homey can provide detailed reports and insights into their energy consumption.

Energy overview

Capabilities

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). For this the measure_power and meter_power capabilities are used by Energy.

Measure Power

The measure_power capability represents the instantaneous power usage or generation of a device, measured in watts (W). It indicates how much power a device is currently consuming or producing at a given moment.

Meter Power

The meter_power capability (or meter_power sub capabilities) represents energy in kilowatt-hours (kWh) and can be used in two ways:

1. Cumulative energy

Tracks the total amount of energy consumed or generated over time, with values that continuously and only increase. It is typically reset only when the device is reset or reinstalled. Example: A smart meter displaying 12,345 kWh since installation.

1. Non-cumulative

Represents energy used or generated during a specific time interval, without accumulating past values. Example: Energy consumed in the last 24 hours, or current battery state of charge in kWh.

In the following sections, when meter_power is referenced, it always refers to cumulative energy, unless explicitly stated otherwise. In this context, meter_power tracks the total energy consumed or generated over time, measured in kilowatt-hours (kWh).

Energy calculates energy consumption over a given period by analyzing the difference in the meter_power value over time. If the values are periodically reset to zero or decrease unexpectedly, it may lead to data loss or invalid interpretations.

Target Power

The target_power capability allows Homey to control the power consumption or production of devices in Watts. This enables energy management scenarios such as:

• Solar power curtailment

• Smart EV charging

• Controlling Home Batteries

The target_power capability automatically generates a Flow card action "Set target power".

The target_power capability is available as of Homey v12.13.0.

Target Power Mode

The target_power_mode capability controls whether Homey or the device itself is in charge of power management. Adding this capability is optional and only useful when the device has its own smart logic such as internal scheduling, self-consumption optimization, cloud control, or app-based control. Without target_power_mode, Homey assumes full control at all times, which is suitable for simple devices without built-in power management.

The target_power_mode capability automatically generates Flow cards for triggers, actions, and conditions.

The target_power_mode capability is available as of Homey v12.13.0.

Energy configuration

Throughout this document the energy configuration is often referred to. It describes the energy configuration object as defined in the drivers manifest, for example:

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "energy": {
    "meterPowerImportedCapability": "meter_power.imported",
    "meterPowerExportedCapability": "meter_power.exported"
  }
}

This object is used to set various properties defined in the sections below. By default any changes made to the energy configuration in this file will be applied directly to existing and already connected devices. However, this is not the case when the device has applied an energy configuration override using Device.setEnergy() (see Dynamically changing the energy configurationfor more details).

To access the energy configuration as set in this file use the Driver.manifest property.

Dynamically changing the energy configuration

In some cases, you need to set the energy configuration dynamically. For example when the required properties depend on the specific device or its capabilities which are not known upfront. In this case it is possible to override the energy configuration from driver.compose.json.

To set the energy configuration dynamically use Device.setEnergy() . You must provide the complete energy configuration to Device.setEnergy() as it will overwrite all the existing properties. Note that once Device.setEnergy() is called, the device will disregard all properties set in the energy configuration in driver.compose.json.

When required to restore to the energy configuration from driver.compose.json after using Device.setEnergy() it is possible to call Device.setEnergy() with the original energy configuration as read from the driver's manifest. However, once Device.setEnergy() has been used, any changes made to the energy configuration in driver.compose.json will no longer be applied automatically.

Use Device.getEnergy() to get the energy configuration override as set by Device.setEnergy() . Note that this will not return the energy configuration from driver.compose.json, but only the configuration set with Device.setEnergy() .

/drivers/<driver_id>/device.js

const DeviceApi = require("device-api");
class MyDevice extends Homey.Device {
  async onInit() {
    const energyConfig = this.getEnergy();
    DeviceApi.on("energy-settings", (energySettings) => {
      if (energySettings.isSmartMeter() && energyConfig.cumulative !== true) {
        this.setEnergy({
          cumulative: true,
          cumulativeImportedCapability: "meter_power.imported",
        }).catch(this.error);
      }
    });
  }
}
module.exports = MyDevice;

Try not to use these methods too often, as they are quite impactful. They should only be used when initially configuring the device.

Power

Devices in Homey can consume power, for example a light bulb or TV, and generate power, for example solar panels or home batteries (by discharging). There are two strategies to determine power usage:

1. Measuring Power Usage When the device itself provides actual power measurements ( Measuring power usage).

2. Approximating Power Usage When a device does not provide actual power measurements, its can be estimated in two ways:

   1. Using configurable power usage properties Define static values in the device's energy configuration (e.g., usageConstant, usageOff, or usageOn) to approximate consumption based on the device's state (Constant power usage).

   2. Using approximated measure_power values Provide values for the measure_power capability and explicitly mark them as approximations using the measure_power.approximation flag (Dynamic power usage). This indicates that the values are not based on actual measurements.

Measuring power usage

When a device supports the measure_power capability (real-time power usage in Watts), such as a smart socket, Homey automatically uses this value for that device.

/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": "socket",
  "capabilities": ["onoff", "measure_power"]
}

Approximating power usage

In cases where devices do not support measure_power real-time power usage in Watts, there are a few options to approximate the device's power consumption. Homey can calculate the power usage based on the onoff and dim capabilities when there is no measure_power capability available. Homey will provide the user with settings to configure the power consumption when the device is turned on, turned off, or (when a device can't be turned on or off) its constant power consumption. Using these settings Homey approximates the power usage by calculating the total on-time, optionally taking into account the brightness level.

Constant power usage

If you already know the power consumption of the device (often this can be found on the packaging or the device itself) add the usageOnand usageOff properties to the energy.approximation object of your driver's manifest. Below you can find an example of a light bulb driver that consumes 15W when turned on, and 1W when turned off. This eliminates the need for the user to configure it manually.

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

Some devices, such as a router, use a constant amount of power. 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
    }
  }
}

Keep in mind that a user can always overwrite these values under the device's settings.

Dynamic power usage

The power usage of some devices depends on their configuration. For example, Nanoleaf light panels let the user add more panels to the system, increasing the total power consumption of the device.

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;

Controlling target power usage

The target_power capability allows Homey to control the power consumption or production of devices in Watts. This enables energy management scenarios such as:

• Solar power curtailment

• Smart EV charging

• Controlling Home Batteries

For device-specific target_power configuration and driver examples, see Solar panels, EV chargers, and Home batteries.

The target_power capability is a setable number capability measured in Watts (W). It represents the desired power level that a device should consume or produce. The actual power consumption is reported via the measure_power capability.

• Positive values = power consumption (charging), or maximum allowed production (solar curtailment)

• Negative values = power production (discharging)

• Zero = idle, or full curtailment (solar)

When the device cannot achieve the requested target power, the driver should throw an error from the capability listener.

For devices with a minimum operating power (like EV chargers requiring 6A minimum), use the excludeMin/excludeMax capability options to define a range around zero where the device cannot operate. Values inside this range are automatically set to 0.

Range must include zero: The min/max range of target_power must always include 0 (min <= 0 <= max). All devices need the ability to idle. If your device has a minimum operating threshold, use excludeMin/excludeMax instead of setting min above zero.

Exclude range validation: The exclude range must include 0 (excludeMin <= 0 <= excludeMax). Values exactly at the boundaries are valid; only values strictly between them become 0.

Step rounding: Values are rounded toward zero to the nearest step, preventing Homey from requesting more power than intended. Values inside the exclude range become 0. Values outside the min/max range are clamped to the nearest boundary.

The target_power_mode capability controls whether Homey or the device itself is in charge of power management. Adding this capability is optional.

When to use: Add target_power_mode when the device has its own smart logic such as internal scheduling, self-consumption optimization, cloud control, or app-based control. Without target_power_mode, Homey assumes full control at all times, which is suitable for simple devices without built-in power management.

Value	Description
device	Device in control. The device operates autonomously using its own internal logic (e.g., built-in scheduling, self-consumption optimization). Target power values set by Homey are ignored. This is the default mode.
homey	Homey in control. Homey actively controls the device via target_power. The device should execute exactly what Homey requests, disabling any built-in smart logic.

When using the Set target power Flow card, Homey automatically switches target_power_mode to homey.

When switching from homey to device mode, the driver should discard any target_power setpoint and resume internal device logic.

The values for the target_power_mode capability cannot be changed. They will always be replaced with the original values.

Example

For device-specific implementation examples, see Solar panels, EV chargers, and Home batteries.

For devices with target_power_mode (e.g. home batteries), use registerMultipleCapabilityListener to handle both capabilities as a single operation.

You can also use separate registerCapabilityListener calls per capability. This is simpler but means the driver receives each change individually, potentially sending multiple API calls to the device for what is logically a single operation.

/drivers/<driver_id>/device.js

const Homey = require("homey");

class MyDevice extends Homey.Device {
  async onInit() {
    this.registerMultipleCapabilityListener(
      ["target_power", "target_power_mode"],
      async ({ target_power, target_power_mode }) => {
        // Only the changed capabilities are present in the object
        if (target_power_mode === "device") {
          // Device should resume autonomous operation
          await this.enableBuiltInScheduling();
          this.log("Switched to device mode - device controls itself");
          return;
        }

        if (target_power_mode === "homey") {
          // Homey is now controlling the device
          await this.disableBuiltInScheduling();
          this.log("Switched to homey mode");
        }

        // Apply target power (use changed value or fall back to current)
        const value =
          target_power ?? this.getCapabilityValue("target_power") ?? 0;
        const mode =
          target_power_mode ?? this.getCapabilityValue("target_power_mode");

        if (mode !== "homey") {
          this.log("Ignoring target_power - not in homey mode");
          return;
        }

        await this.applyTargetPower(value);
      },
      500, // debounce timeout in ms
    );
  }

  async applyTargetPower(value) {
    if (value >= 0) {
      await this.setChargingPower(value);
    } else {
      await this.setDischargingPower(Math.abs(value));
    }
  }
}

module.exports = MyDevice;

Energy

Devices in Homey can report energy (kWh) consumption, for example a washing machine, and energy generation, for example solar panels or home batteries (by discharging). These devices should have the meter_power capability (cumulative energy usage in kWh). For example, a washing machine that tracks its energy consumption would use the meter_power capability to keep track of how much energy is consumed over longer periods of time.

If a device can measure both imported and exported energy, such as a smart plug connected to portable solar panels or a home battery, the driver should define the meterPowerImportedCapability and meterPowerExportedCapability energy properties, as shown below.

• Imported energy refers to the energy consumed or charged by the device.

• Exported energy refers to the energy produced or discharged by the device.

/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": "socket",
  "capabilities": [
    "onoff",
    "measure_power",
    "meter_power.imported",
    "meter_power.exported"
  ],
  "energy": {
    "meterPowerImportedCapability": "meter_power.imported",
    "meterPowerExportedCapability": "meter_power.exported"
  }
}

You can set any capability as the value of meterPowerImportedCapability and meterPowerExportedCapability as long it is an instance of the meter_power capability and is present in the capabilities array of the driver.

The meterPowerImportedCapability and meterPowerExportedCapability are only used on Homey Pro (Early 2023), Homey Pro mini, and Homey Cloud and are available as of v12.4.5.

Devices

There are various types of devices that have some special features or requirements in Energy.

Multi-purpose devices require separate Homey devices

When integrating hardware that combines multiple energy functions (e.g., an EV charger with built-in solar inverter, or a hybrid inverter with battery storage), you must create separate Homey devices for each function, each with its own device class.

This separation is required because each device class is treated differently in Energy.

Solar panels

Solar panels are a common device in Homey that can generate their own power. These devices must have the solarpanel device class.

Measure & meter power

The measure_power value should positive when generating power. When providing a negative value, e.g. -13 watt, Homey assumes the solar panel is currently consuming instead of generating power.

In order for cumulative energy generation (kWh) to be tracked in Energy the driver must have a meter_power capability that will be set to the total generated energy in kWh as a positive value. Use the meterPowerExportedCapability energy property to configure a different meter_power capability for generated energy.

/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"],
  "energy": {
    "meterPowerExportedCapability": "meter_power" // Optional: defaults to meter_power
  }
}

Target power

Solar inverters with curtailment support can use target_power to limit their power output and optionally target_power_mode to determine who controls the target_power. This is useful when grid export limits apply or when energy prices are negative.

For solar inverters, target_power acts as a maximum production limit (cap), not a production target. Setting target_power to 1500W means "produce up to 1500W maximum".

To disable curtailment: Set target_power to its maximum value (max). The driver should interpret this as "produce at maximum capacity".

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "Solar Inverter" },
  "class": "solarpanel",
  "capabilities": [
    "measure_power",
    "meter_power",
    "target_power",
    "target_power_mode"
  ],
  "capabilitiesOptions": {
    "target_power": {
      "min": 0,
      "max": 10000
    }
  }
}

Optionally add the target_power_mode capability:

• In device mode, the inverter produces at maximum capacity using its own logic

• In homey mode, Homey controls curtailment:

  • Set to 5000 → limit production to 5000W

  • Set to 10000 (max) → no curtailment, produce at full capacity

  • Set to 0 → full curtailment, stop producing

/drivers/<driver_id>/device.js

const Homey = require("homey");

class MySolarInverter extends Homey.Device {
  async onInit() {
    this.registerCapabilityListener("target_power", async (value) => {
      const mode = this.getCapabilityValue("target_power_mode");
      if (mode !== "homey") return;
      await this.applyTargetPower(value);
    });

    this.registerCapabilityListener("target_power_mode", async (mode) => {
      if (mode === "homey") {
        const value = this.getCapabilityValue("target_power");
        await this.applyTargetPower(value);
      } else {
        // "device" mode: disable curtailment, produce at maximum
        await this.disableCurtailment();
      }
    });
  }

  async applyTargetPower(value) {
    const capabilityOptions = this.getCapabilityOptions("target_power");
    const maxPower = capabilityOptions.max;

    if (value >= maxPower) {
      // Max value means "no curtailment"
      await this.disableCurtailment();
      this.log("Curtailment disabled, producing at maximum");
    } else {
      await this.setCurtailmentLimit(value);
      this.log(`Curtailment set to ${value}W`);
    }
  }
}

module.exports = MySolarInverter;

Smart plugs

Devices with device class socket (often smart plugs), can measure power and energy being consumed and generated. To learn how to configure this see Measuring power usage. A user can choose a different device class in the What's plugged in? setting. Among others, solarpanel, battery and evcharger. To properly support these three device classes please take the following into account.

Solar panels

Important difference with the regular solarpanel device class is that the generated power must be set as a negative value (e.g. setCapabilityValue('measure_power', -200)). Homey will then invert this value automatically.

Users will get the Invert power measurement setting to manually switch the generated power from positive to negative or vice versa.

Homey will use the value of the meter_power capability to determine the energy generated by the solar panels in kWh. Use the meterPowerExportedCapability energy property to use a different meter_power capability for generated energy (see Solar panels).

Batteries

Small portable home batteries can be connected to a smart plug in order to charge and discharge.

The measure_power value must be positive when the smart plug is consuming power (charging the battery) and negative when producing power (discharging the battery).

By default the meter_power capability of the smart plug will be used to determine the energy charged by the battery. Additionally, for the charged and discharged energy to be registered separately by Homey, smart plug drivers must include the meterPowerImportedCapability and meterPowerExportedCapability energy properties (see Home batteries).

EV chargers

Users can charge EVs using smart plugs. To allow the smart plug to act as an EV charger in Energy the user can choose "EV Charger" as device class in the What's plugged in? setting of smart plugs. This will include the smart plug's power measurements in Energy as if it were an EV charger.

The measure_power value must be positive when the smart plug is consuming power (charging the EV's battery) and negative when producing power (discharging the EV's battery).

By default the meter_power capability of the smart plug will be used to determine the energy charged by the EV charger. Additionally, for the charged and (if applicable) discharged energy to be registered separately by Homey, smart plug drivers must include the meterPowerImportedCapability and meterPowerExportedCapability energy properties (see EV chargers).

Cumulative measuring devices

Certain devices, such as a P1 meter or a current clamp, can measure the total power and energy usage of a home or a specific power group. Their measurements contribute to the overall power consumption data for the entire home. This means that these are the highest level measuring devices in a home. All other power consuming or generating devices in a home are measured by these devices. This is called cumulative measuring.

To mark a device that measures cumulative power and 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 and meter_water capabilities to determine the gas and water usage of the whole home.

• The meter_gas capability tracks the total amount of gas consumed over time, measured in cubic metres (m3).

• The meter_water capability tracks the total amount of water consumed over time, measured in cubic metres (m3).

Both capabilities should be positive and continuously increase. It is typically reset only when the device is reset or reinstalled.

/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 power-consuming devices in Homey are subtracted from the total measured power usage of all cumulative devices. The remaining, unaccounted-for power usage will be displayed as "other."

Most devices that track the total power 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 (e.g. solar-generated energy).

If a device can measure both imported and exported energy for the whole home or power group, the driver should define the cumulativeImportedCapability and cumulativeExportedCapability energy properties, as shown below.

• Imported energy refers to the cumulative energy imported from the device's perspective.

• Exported energy refers to the cumulative energy exported from the device's perspective.

These properties should be assigned to the corresponding capabilities of the device responsible for measuring imported and exported energy. If the device only supports measuring imported energy you can omit the cumulativeExportedCapability . If the device does not support separate measurement of imported and exported energy at all, you should omit these properties, this will result in the device being excluded from features that require the distinction between imported and exported energy.

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

The cumulativeImportedCapability and cumulativeExportedCapability properties are only used on Homey Pro (Early 2023), Homey Pro mini, and Homey Cloud and are available as of Homey v12.3.0.

Home batteries

Home batteries are devices that can store energy for later use. When creating a driver for a home battery device, apply the device class battery and set the homeBattery property in the energy object of the driver.

Measure & meter power

Home batteries should have the measure_power capability. This represents the real-time power consumption of the home battery in Watts. Provide positive values to indicate the battery is consuming power (charging), provide negative values to indicate the battery is delivering power back to the home (discharging).

The sign convention for measure_power matches target_power: positive values indicate charging (consuming power), negative values indicate discharging (producing power). This differs from solar panels where positive measure_power indicates generation.

In case the home battery does not support this, you can fallback to the battery_charging_state capability. This indicates the current state of the battery, charging, discharging or idle. By omitting the measure_power capability some functionality in Energy will be lost.

Additionally, home batteries should have the measure_battery capability to indicate the current state of charge of the battery.

/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": "battery",
  "capabilities": ["measure_power", "measure_battery"],
  "energy": {
    "homeBattery": true
  }
}

The homeBattery energy property is available as of Homey v12.3.0.

Since home batteries both consume and produce energy, drivers should define separate meterPowerImportedCapability and meterPowerExportedCapability energy properties. This enables Homey to accurately track charged versus discharged energy. If these properties are omitted, the device will be excluded from features that require the distinction between charged and discharged energy.

• Imported energy refers to the energy charged by the battery.

• Exported energy refers to the energy discharged by the battery.

/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": "battery",
  "capabilities": [
    "measure_power",
    "measure_battery",
    "meter_power.charged",
    "meter_power.discharged"
  ],
  "capabilitiesOptions": {
    "meter_power.charged": {
      "title": { "en": "Charged Energy" }
    },
    "meter_power.discharged": {
      "title": { "en": "Discharged Energy" }
    }
  },
  "energy": {
    "homeBattery": true,
    "meterPowerImportedCapability": "meter_power.charged",
    "meterPowerExportedCapability": "meter_power.discharged"
  }
}

The meterPowerImportedCapability and meterPowerExportedCapability are only used on Homey Pro (Early 2023), Homey Pro mini, and Homey Cloud, and are available as of v12.4.5.

Target power

Home batteries that support power control use target_power to set charging and discharging power, and optionally target_power_mode to determine who controls the target_power. Adding this capability is optional and only useful when the device has its own smart logic such as internal scheduling, self-consumption optimization, cloud control, or app-based control. Without target_power_mode, Homey assumes full control at all times, which is suitable for simple devices without built-in power management.

Unlike EV chargers, home batteries respond immediately to target_power changes, there is no separate start/stop capability.

If the battery has a minimum charge/discharge threshold, use the excludeMin/excludeMax capability options to define the dead zone.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "Home Battery" },
  "class": "battery",
  "capabilities": [
    "measure_power",
    "measure_battery",
    "meter_power.charged",
    "meter_power.discharged",
    "target_power",
    "target_power_mode"
  ],
  "capabilitiesOptions": {
    "meter_power.charged": {
      "title": { "en": "Charged Energy" }
    },
    "meter_power.discharged": {
      "title": { "en": "Discharged Energy" }
    },
    "target_power": {
      "min": -5000,
      "max": 5000
    }
  },
  "energy": {
    "homeBattery": true,
    "meterPowerImportedCapability": "meter_power.charged",
    "meterPowerExportedCapability": "meter_power.discharged"
  }
}

It is recommended to add the target_power_mode capability:

• In device mode, the battery uses its own optimization logic (e.g., self-consumption, time-of-use)

• In homey mode, Homey directly controls power flow:

  • Set to 3000 → charge at 3000W

  • Set to 0 → idle

  • Set to −3000 → discharge at 3000W

/drivers/<driver_id>/device.js

const Homey = require("homey");

class MyHomeBattery extends Homey.Device {
  async onInit() {
    this.registerCapabilityListener("target_power", async (value) => {
      const mode = this.getCapabilityValue("target_power_mode");
      if (mode !== "homey") return;
      await this.applyTargetPower(value);
    });

    this.registerCapabilityListener("target_power_mode", async (mode) => {
      if (mode === "homey") {
        const value = this.getCapabilityValue("target_power");
        await this.applyTargetPower(value);
      } else {
        // "device" mode: let device firmware resume internal balancing
        await this.enableBuiltInScheduling();
      }
    });
  }

  async applyTargetPower(value) {
    if (value > 0) {
      await this.setDeviceChargingPower(value);
      this.log(`Charging at ${value}W`);
    } else if (value < 0) {
      await this.setDeviceDischargingPower(Math.abs(value));
      this.log(`Discharging at ${Math.abs(value)}W`);
    } else {
      await this.setDeviceIdle();
      this.log("Battery idle");
    }
  }
}

module.exports = MyHomeBattery;

EV chargers

EV chargers are devices that can be used at home to charge EVs. When creating a driver for an EV charger, apply the device class evcharger and set the evCharger property in the energy object of the driver.

Measure & meter power

EV chargers should have the measure_power capability. This represents the real-time power consumption of the EV charger in Watts. This value can be positive and negative.

• Positive when the EV charger is charging the connected EV.

• Negative when the EV charger supports bi-directional charging and is currently discharging the connected EV.

To accurately reflect the charging state of the EV charger add the evcharger_charging_state capability. This allows the user to easily see the state of the EV charger and act on state changes like "EV is plugged in".

Finally, to allow for easy control of the EV charger add the evcharger_charging capability. This capability acts like the on/off switch with regards to charging, and automatically generates useful Flow cards like "Start charging" and "Is charging".

By default the meter_power capability will be used to determine the energy charged by the EV charger. To enable Homey to distinguish between the charged and discharged energy of the EV charger, the driver should define the meterPowerImportedCapability and meterPowerExportedCapability energy properties, as shown below.

• Imported energy refers to the energy charged by the EV charger.

• Exported energy refers to the energy discharged by the EV charger.

These properties should be assigned to the corresponding capabilities of your device responsible for measuring charged and discharged energy. If your device does not support discharging just omit the meterPowerExportedCapability 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"
  },
  "class": "evcharger",
  "capabilities": [
    "measure_power",
    "evcharger_charging",
    "evcharger_charging_state",
    "meter_power.charged",
    "meter_power.discharged"
  ],
  "capabilitiesOptions": {
    "meter_power.charged": {
      "title": { "en": "Charged Energy" }
    },
    "meter_power.discharged": {
      "title": { "en": "Discharged Energy" }
    }
  },
  "energy": {
    "evCharger": true,
    "meterPowerImportedCapability": "meter_power.charged",
    "meterPowerExportedCapability": "meter_power.discharged"
  }
}

The evCharger property and the evcharger_charging and evcharger_charging_state capabilities are available as of v12.4.5.

Target power

EV chargers that support power control should use target_power to set the charging/discharging power and optionally target_power_mode to determine who controls the target_power. Adding this capability is optional and only useful when the device has its own smart logic such as internal scheduling, self-consumption optimization, cloud control, or app-based control. Without target_power_mode, Homey assumes full control at all times, which is suitable for simple devices without built-in power management.

Auto start/stop charging: When using the Set target power Flow card Homey automatically:

• Sets target_power_mode to homey

• Sets evcharger_charging to true (positive value) or false (zero/negative)

Configure the widest possible min/max range

Set min and max to represent the full operating range across all configurations. Homey uses these values to determine what power levels it can request.

For EV chargers that support multiple phase configurations (1/2/3-phase), use the widest range: 1-phase minimum to 3-phase maximum. The driver must handle phase switching internally.

"capabilitiesOptions": {
  "target_power": {
    "min": 0,         // allows idle (0W)
    "max": 22000,     // 3-phase maximum
    "step": 230,      // finest step size
    "excludeMin": 0,
    "excludeMax": 1380  // 1-phase minimum (6A × 230V)
  }
}

You can use setCapabilityOptions() to update values dynamically, but don't do this often as it is an expensive call.

Use exclude range for minimum charging power: Most EVs cannot charge below 6A (~1380W single-phase). Use excludeMin/excludeMax to define this dead zone. Values inside the exclude range automatically become 0 (idle).

Example: Unidirectional EV charger

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "EV Charger" },
  "class": "evcharger",
  "capabilities": [
    "measure_power",
    "evcharger_charging",
    "evcharger_charging_state",
    "meter_power",
    "target_power",
    "target_power_mode"
  ],
  "capabilitiesOptions": {
    "target_power": {
      "min": 0,
      "max": 22000,
      "step": 230,
      "excludeMin": 0,
      "excludeMax": 1380
    }
  },
  "energy": {
    "evCharger": true
  }
}

Example: Bidirectional EV charger

Bidirectional chargers use negative values for discharging.

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "EV Charger" },
  "class": "evcharger",
  "capabilities": [
    "measure_power",
    "evcharger_charging",
    "evcharger_charging_state",
    "meter_power.charged",
    "meter_power.discharged",
    "target_power",
    "target_power_mode"
  ],
  "capabilitiesOptions": {
    "meter_power.charged": {
      "title": { "en": "Charged Energy" }
    },
    "meter_power.discharged": {
      "title": { "en": "Discharged Energy" }
    },
    "target_power": {
      "min": -11000,
      "max": 22000,
      "step": 230,
      "excludeMin": -1380,
      "excludeMax": 1380
    }
  },
  "energy": {
    "evCharger": true,
    "meterPowerImportedCapability": "meter_power.charged",
    "meterPowerExportedCapability": "meter_power.discharged"
  }
}

Configuration

The excludeMin/excludeMax range handles the minimum operating threshold (6A × 230V = 1380W), any value between 1–1379W automatically becomes 0. step: 230 corresponds to 1A at 230V, the finest granularity for single-phase charging.

• In device mode, the charger uses its own built-in charging logic

• In homey mode, Homey controls the charging rate via target_power. Use evcharger_charging to start or stop charging

• When charging stops, the target_power value is preserved for the next session

Example: Capability value processing

Requested	Result	Reason
5000W	Charge at 4830W	Rounded down to nearest step (230W)
1000W	Idle (0W)	Inside exclude range (−1380 to 1380)
−1000W	Idle (0W)	Inside exclude range
−5000W	Discharge at 4830W	Rounded toward zero to nearest step
25000W	Charge at 22000W	Clamped to max (22000)
−15000W	Discharge at 11000W	Clamped to min (−11000)

Example: Capability listeners

/drivers/<driver_id>/device.js

const Homey = require("homey");

class MyEVCharger extends Homey.Device {
  async onInit() {
    this.registerMultipleCapabilityListener(
      ["target_power", "target_power_mode", "evcharger_charging"],
      async ({ target_power, target_power_mode, evcharger_charging }) => {
        // All capability changes arrive as a single debounced batch.
        // Only the changed capabilities are present in the object.

        // Handle mode switch
        if (target_power_mode === "device") {
          await this.enableBuiltInScheduling();
          this.log("Switched to device mode");
          return;
        }

        // Handle stop charging
        if (evcharger_charging === false) {
          await this.stopCharging();
          this.log("Stopped charging/discharging");
          return;
        }

        // Handle start charging / power adjustment
        const isCharging =
          evcharger_charging === true ||
          this.getCapabilityValue("evcharger_charging");
        const power =
          target_power ?? this.getCapabilityValue("target_power") ?? 0;

        if (evcharger_charging === true) {
          // Start charging at the current target power
          const amps = Math.round(Math.abs(power) / 230);
          if (power >= 0) {
            await this.startCharging(amps);
            this.log(`Started charging at ${power}W (${amps}A)`);
          } else {
            await this.startDischarging(amps);
            this.log(`Started discharging at ${Math.abs(power)}W (${amps}A)`);
          }
        } else if (target_power != null && isCharging) {
          // Adjust charging rate while already charging
          const amps = Math.round(Math.abs(target_power) / 230);
          if (target_power > 0) {
            await this.setChargingCurrent(amps);
            this.log(`Charging power adjusted to ${target_power}W (${amps}A)`);
          } else if (target_power < 0) {
            await this.setDischargingCurrent(amps);
            this.log(
              `Discharging power adjusted to ${Math.abs(target_power)}W (${amps}A)`,
            );
          } else {
            await this.setChargingCurrent(0);
            this.log("Power set to idle (0W)");
          }
        } else if (target_power !== undefined && !isCharging) {
          this.log(
            `Target power set to ${target_power}W, will apply when charging starts`,
          );
        }
      },
      500, // debounce timeout in ms
    );
  }
}

module.exports = MyEVCharger;

Why registerMultipleCapabilityListener? When a Flow sets target_power, Homey also sets target_power_mode and evcharger_charging in quick succession. registerMultipleCapabilityListener debounces these into a single callback, reducing API calls to the physical device. This is especially important when target_power is updated frequently by a Flow.

You can also use separate registerCapabilityListener calls per capability. This is simpler but means the driver receives each change individually, potentially sending multiple API calls to the device for what is logically a single operation.

Example: Dynamic phase configuration

If your EV charger switches between phase configurations (e.g., automatically or via a setting), you can update the capability options dynamically. But, use this sparingly as setCapabilityOptions() is an expensive operation.

/drivers/<driver_id>/device.js

async onPhaseConfigChanged(phaseMode) {
  // phaseMode: 1, 2, or 3
  const voltage = 230;
  const minAmps = 6;
  const minPower = minAmps * phaseMode * voltage;

  await this.setCapabilityOptions("target_power", {
    min: -32 * phaseMode * voltage,     // Max discharge
    max: 32 * phaseMode * voltage,      // Max charge (32A per phase)
    step: phaseMode * voltage,          // 230W, 460W, or 690W
    excludeMin: -minPower,              // -1380W, -2760W, or -4140W
    excludeMax: minPower,               // 1380W, 2760W, or 4140W
  });

  this.log(`Phase configuration changed to ${phaseMode}-phase`);
}

Range must include zero: The min/max range of target_power must always include 0 (min <= 0 <= max). All devices need the ability to idle. If your device has a minimum operating threshold, use the excludeMin/excludeMax capability options instead of setting min above zero.

Exclude range validation: The exclude range must include 0 (excludeMin <= 0 <= excludeMax). Values exactly at the boundaries are valid; only values strictly between them become 0.

EVs

EVs are battery electric cars. These cars can be charged by an EV charger. When creating a driver for an EV, apply the device class car and set the electricCar property in the energy object of the driver.

EVs should have the measure_battery capability which represents the current state of charge of the battery. Additionally, the ev_charging_state capability should be added when the EV can report its current charging state (plugged in/out, charging, discharging).

/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": "car",
  "capabilities": ["measure_battery", "ev_charging_state"],
  "energy": {
    "electricCar": true
  }
}

The electricCar energy property and ev_charging_state capability are available as of Homey v12.4.5.

Batteries

All devices with the measure_battery or alarm_battery capability (except home batteries and EVs) 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

Settings

Homey provides a couple of settings to Energy devices under certain conditions:

Always on

This setting is provided to devices that have device class socket and the onoff capability. By default it is disabled, but when enabled, Homey will prevent the user from turning off the device through Homey. An error message will be returned when this is attempted.

Exclude from Energy

This setting is provided to devices that have the meter_power or measure_power capability, have device class solarpanel(or Solar panel in the What's plugged in? setting), or are marked as cumulative measuring devices (see Cumulative measuring devices). By default it is disabled, but when enabled Homey will no longer show the device in the Zone Control Energy, nor will it be included in future Energy reports (note: this will not remove the device from existing Energy reports).

Tracks total home energy consumption

This setting is provided to devices that are marked as cumulative measuring devices (see Cumulative measuring devices). By default this setting is enabled, this will make sure Homey considers this device as a device that measures energy consumption at the highest level in the home. When disabled it will consider the device as a regular device in the home that measures energy consumption.

Invert power measurement

This setting is available for devices with the socket device class when the user selects "Solar panel" in the What's plugged in? setting. It allows the user to invert the sign (positive or negative) of the measure_power capability for this device. This is useful for accurately representing power flow, ensuring that produced power is displayed correctly. For more details, see Smart plugs.

Power usage when off

This setting is provided to devices that do not have the measure_power capability and do have the onoff capability. The default value for this setting can be determined by the driver (see Constant power usage). It will be used to approximate the device's power consumption.

Power usage when on

This setting is provided to devices that do not have the measure_power capability and do have the onoff capability. The default value for this setting can be determined by the driver (see Constant power usage). It will be used to approximate the device's power consumption.

Constant power usage

This setting is provided to devices that do not have the measure_power, onoff, measure_battery or alarm_battery capability. Devices that have defined batteries in the driver's manifest will also not get this setting, nor will devices with a device class listed below. The default value for this setting can be determined by the driver (see Constant power usage). It will be used to approximate the device's power consumption.

• button

• windowcoverings

• blinds

• curtain

• sunshade

• kettle

• coffeemachine

• remote

• solarpanel

• vacuumcleaner

• thermostat