Comment on page
Energy
By defining the energy usage (or generation) of the devices your app supports users can generate detailed reports of their energy consumption.
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).
A consuming device is a regular device in Homey, for example a light bulb or TV. There are three strategies to determine energy usage.
When a device has the
measure_power capability, e.g. a smart socket, Homey automatically uses this value for that device.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.
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
}
}
}
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;
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.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.
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.
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:
LS14250CAAAAAAAAAA23A27PP3CR123ACR2CR1632CR2032CR2430CR2450CR2477CR3032CR14250INTERNALOTHER
Last modified 2yr ago