Library Structure

The library follows a multi-level tree structure:

• Top level: Manufacturer
• Second level: Model ID
• Optional: Sub-profiles for specific device behaviors

Each manufacturer directory must include a manufacturer.json file:

Each device profile resides in its own subdirectory: {manufacturer}/{modelid} (e.g., signify/LCT010) This directory contains a mandatory model.json file and, optionally, CSV files used for LUT (Look-Up Table) calculation strategy.

model.json

Every device profile must include a model.json file, which defines supported calculation modes and other configuration parameters. Refer to the JSON schema for full details.

Available Fields

Below is a comprehensive table of all fields that can be used in a model.json file:

Device specs

device_specs holds what the box or manufacturer datasheet says about the device, as opposed to what the measurements say. Some keys apply to every device type; selected device types have additional type-specific keys.

"device_specs": {
  "socket": ["E26", "E27"],
  "form_factor": "bulb",
  "lumens": 806,
  "rated_power": 9.5,
  "connectivity": ["zigbee"]
}

Generic device specifications:

Additional light specifications:

Additional smart switch and smart dimmer specifications:

For a smart switch or dimmer, only_self_usage: true implies power_monitoring: true: the profile models only the device's own consumption because the connected load is already measured by the device. The reverse is not required; a monitoring-capable device can still have a profile that models more than its own consumption.

Additional network device specifications:

Additional fan specifications:

Additional smart speaker specifications:

Leave a key out rather than guessing. These are manufacturer claims, and the website presents them as such.

Calculation Strategy Specific Fields

Depending on the calculation_strategy you choose, you'll need to provide specific configuration:

Fixed Strategy (fixed_config)

"fixed_config": {
  "power": 5.0,  // Fixed power value in watts
  "states_power": {  // Optional: power values for different states
    "idle": 2.0,
    "playing": 5.0,
    "off": 0.5
  }
}

Composite Strategy (composite_config)

Allows combining multiple calculation strategies based on conditions:

"composite_config": {
  "mode": "stop_at_first",  // or "sum_all"
  "strategies": [
    {
      "condition": {
        "condition": "state",
        "entity_id": "light.example",
        "state": "on"
      },
      // Strategy-specific config here
    }
  ]
}

Discovery Behavior

By default, Powercalc performs discovery on a per-entity basis. This can cause issues if a device has multiple entities, resulting in multiple discoveries.

To avoid this, you can set:

"discovery_by": "device"

This enables per-device discovery, which is more reliable. It is especially recommended for device types using sensor domain entities: network, power_meter, and generic_iot.

When one integration config entry creates several similar devices but should result in only one Powercalc discovery, use:

"discovery_by": "config_entry"

This enables per-config-entry discovery. Powercalc uses the first device belonging to the config entry to determine the manufacturer and model.

Aliases and Linked Profiles

• Use aliases to define alternative model names for discovery. This is helpful when the same device is reported differently across integrations (e.g., Hue vs. deCONZ).

• Use linked_profile to point to another profile that contains the measurement data. This creates a separate entry in the library.

Format: manufacturer/modelid Example: signify/LCT010

Sub-Profiles

Some devices may have different power usage based on their state. In these cases, you can define multiple sub-profiles within the same model.

See Sub Profiles for details.