home-assistant-blueprints/inovelli/power-monitoring.md

# Power & Energy Monitoring Properties

Properties for power consumption measurement, energy usage tracking, and reporting thresholds via Zigbee2MQTT.

## Sensor Properties (Read-Only)

### power

- **Type**: Sensor (read-only)
- **Unit**: Watts (W)
- **Description**: Instantaneous measured power consumption of the connected load.
- **Home Assistant Entity**: `sensor.[device_name]_power`
- **Updates**: Based on activePowerReports threshold or periodicPowerAndEnergyReports interval
- **Use cases**:
  - Real-time power monitoring
  - Detect when lights turn on/off
  - Track power consumption changes
  - Trigger automations based on power usage

### energy

- **Type**: Sensor (read-only)
- **Unit**: Kilowatt-hours (kWh)
- **Description**: Cumulative energy consumption over time.
- **Home Assistant Entity**: `sensor.[device_name]_energy`
- **Updates**: Based on activeEnergyReports threshold or periodicPowerAndEnergyReports interval
- **Use cases**:
  - Long-term energy tracking
  - Billing/cost calculations
  - Energy usage analytics
  - Historical consumption trends

## Reporting Configuration

### activePowerReports

- **Type**: Number
- **Range**: 0-100
- **Default**: 10 (10% change)
- **Description**: Percent power level change that will result in a new power report being sent. 0 = Disabled.
- **Home Assistant Entity**: `number.[device_name]_active_power_reports`
- **Special values**:
  - `0` = Disabled (no automatic power reports based on change)
  - `1-100` = Percentage change threshold
- **Use cases**:
  - Real-time power monitoring
  - Detect significant power changes
  - Trigger automations based on power delta
- **Common values**:
  - Sensitive monitoring: `5` (5% change)
  - Default: `10` (10% change)
  - Reduce network traffic: `20` (20% change)
- **Network impact**: Lower values generate more Zigbee traffic

### periodicPowerAndEnergyReports

- **Type**: Number
- **Range**: 0-32767
- **Default**: 3600 seconds (1 hour)
- **Description**: Time period between consecutive power & energy reports being sent (in seconds). The timer is reset after each report is sent.
- **Home Assistant Entity**: `number.[device_name]_periodic_power_and_energy_reports`
- **Units**: Seconds
- **Special values**:
  - `0` = Disabled (no periodic reports)
  - `1-32767` = Report interval in seconds
- **Use cases**:
  - Regular energy usage logging
  - Dashboard updates
  - Long-term consumption tracking
  - Backup reporting if active reports miss changes
- **Common values**:
  - Frequent updates: `300` (5 minutes)
  - Default: `3600` (1 hour)
  - Reduce traffic: `7200` (2 hours)
  - Daily: `86400` (24 hours)
- **Note**: Works alongside activePowerReports and activeEnergyReports (not instead of)

### activeEnergyReports

- **Type**: Number
- **Range**: 0-32767
- **Default**: 10 (0.10 kWh)
- **Description**: Energy level change which will result in sending a new energy report. 0 = disabled, 1-32767 = 0.01kWh-327.67kWh.
- **Home Assistant Entity**: `number.[device_name]_active_energy_reports`
- **Units**: 0.01 kWh (value of 10 = 0.10 kWh = 100 Wh)
- **Special values**:
  - `0` = Disabled (no automatic energy reports based on accumulation)
  - `1-32767` = Threshold in 0.01 kWh increments
- **Use cases**:
  - Track cumulative energy consumption
  - Billing/cost calculations
  - Energy usage analytics
  - Trigger automations at energy milestones
- **Common values**:
  - Sensitive: `1` (0.01 kWh = 10 Wh)
  - Default: `10` (0.10 kWh = 100 Wh)
  - Reduce traffic: `100` (1.0 kWh)
- **Example**: Default of 10 means report every 100 Wh (0.1 kWh) consumed

## Performance Tuning

### quickStartTime

- **Type**: Number
- **Range**: 0-60
- **Default**: 0 (disabled)
- **Description**: Duration of full power output while lamp transitions from Off to On. In 60th of second. 0 = disable, 1 = 1/60s, 60 = 1s.
- **Home Assistant Entity**: `number.[device_name]_quick_start_time`
- **Units**: 1/60th of a second
- **Use cases**:
  - Help LED bulbs start reliably
  - Overcome LED driver inrush requirements
  - Prevent flickering on startup
- **Common values**:
  - Disabled: `0`
  - Short boost: `10` (0.17 seconds)
  - Default boost: `20` (0.33 seconds)
  - Long boost: `60` (1 second)

### quickStartLevel

- **Type**: Number
- **Range**: 1-254
- **Default**: 254 (near full power)
- **Description**: Level of power output during Quick Start Light time (quickStartTime).
- **Home Assistant Entity**: `number.[device_name]_quick_start_level`
- **Use cases**:
  - Ensure LED bulbs receive enough initial power to start
  - Match bulb requirements for startup
- **Requires**: quickStartTime > 0

### higherOutputInNonNeutral

- **Type**: Select
- **Values**: "Disabled (default)", "Enabled"
- **Default**: "Disabled (default)"
- **Description**: Increase output level in non-neutral mode to help bulbs start and operate properly.
- **Home Assistant Entity**: `select.[device_name]_higher_output_in_non_neutral`
- **Use cases**:
  - Non-neutral installations with LED bulbs
  - Improve dimming range in non-neutral mode
  - Help bulbs work better without neutral wire
- **Note**: Only applies to non-neutral wiring configurations

## Power Type Detection

### powerType

- **Type**: Sensor (read-only)
- **Values**: "Non Neutral", "Neutral"
- **Description**: Detected power wiring type.
- **Home Assistant Entity**: `sensor.[device_name]_power_type`
- **Read-only**: Cannot be changed by user, automatically detected
- **Use cases**:
  - Diagnostic information
  - Verify wiring configuration
  - Troubleshooting installation issues
- **Note**: Automatically detected by switch hardware

## Configuration Patterns

### Real-Time Power Monitoring

```yaml
# Sensitive power change detection
service: number.set_value
target:
  entity_id: number.bedroom_switch_active_power_reports
data:
  value: 5  # Report on 5% power change

# Frequent periodic backup
service: number.set_value
target:
  entity_id: number.bedroom_switch_periodic_power_and_energy_reports
data:
  value: 300  # Every 5 minutes

# Disable energy threshold reports (focus on power)
service: number.set_value
target:
  entity_id: number.bedroom_switch_active_energy_reports
data:
  value: 0  # Disabled
```

### Energy Usage Tracking

```yaml
# Less sensitive power reports
service: number.set_value
target:
  entity_id: number.bedroom_switch_active_power_reports
data:
  value: 20  # Report on 20% change

# Hourly periodic reports
service: number.set_value
target:
  entity_id: number.bedroom_switch_periodic_power_and_energy_reports
data:
  value: 3600  # Every hour

# Energy threshold reporting
service: number.set_value
target:
  entity_id: number.bedroom_switch_active_energy_reports
data:
  value: 10  # Report every 0.1 kWh
```

### Low Network Traffic

```yaml
# High power change threshold
service: number.set_value
target:
  entity_id: number.bedroom_switch_active_power_reports
data:
  value: 25  # 25% change

# 2-hour periodic reports
service: number.set_value
target:
  entity_id: number.bedroom_switch_periodic_power_and_energy_reports
data:
  value: 7200

# High energy threshold
service: number.set_value
target:
  entity_id: number.bedroom_switch_active_energy_reports
data:
  value: 100  # Every 1 kWh
```

### LED Bulb Quick Start

```yaml
# Enable quick start with 1/3 second boost
service: number.set_value
target:
  entity_id: number.bedroom_switch_quick_start_time
data:
  value: 20  # 20/60 = 0.33 seconds

# Full power during quick start
service: number.set_value
target:
  entity_id: number.bedroom_switch_quick_start_level
data:
  value: 254  # Near maximum
```

### Non-Neutral Optimization

```yaml
# Enable higher output for non-neutral
service: select.select_option
target:
  entity_id: select.bedroom_switch_higher_output_in_non_neutral
data:
  option: "Enabled"

# May also need quick start
service: number.set_value
target:
  entity_id: number.bedroom_switch_quick_start_time
data:
  value: 30  # 0.5 seconds
```

### Disable All Monitoring

```yaml
# Turn off all automatic reporting
service: number.set_value
target:
  entity_id:
    - number.bedroom_switch_active_power_reports
    - number.bedroom_switch_periodic_power_and_energy_reports
    - number.bedroom_switch_active_energy_reports
data:
  value: 0
```

## Reporting Behavior

The switch can send reports via three independent mechanisms:
1. **Active Power Reports**: Sent when power changes by threshold percentage
2. **Active Energy Reports**: Sent when accumulated energy reaches threshold
3. **Periodic Reports**: Sent at regular time intervals

All three work independently and can be used together for comprehensive monitoring.

## Home Assistant Integration Example

### Power-Based Automation

```yaml
automation:
  - alias: "Detect Light On"
    trigger:
      - platform: numeric_state
        entity_id: sensor.bedroom_switch_power
        above: 5  # 5W threshold
    action:
      - service: notify.mobile_app
        data:
          message: "Bedroom light turned on ({{ states('sensor.bedroom_switch_power') }}W)"

  - alias: "Detect Light Off"
    trigger:
      - platform: numeric_state
        entity_id: sensor.bedroom_switch_power
        below: 1  # Less than 1W
        for:
          seconds: 5
    action:
      - service: notify.mobile_app
        data:
          message: "Bedroom light turned off"
```

### Energy Cost Tracking

```yaml
automation:
  - alias: "Daily Energy Report"
    trigger:
      - platform: time
        at: "23:59:00"
    action:
      - service: notify.mobile_app
        data:
          message: >
            Bedroom light energy today: {{ states('sensor.bedroom_switch_energy') }} kWh
            Estimated cost: ${{ (states('sensor.bedroom_switch_energy') | float * 0.12) | round(2) }}
```

## Example Calculations

### Power Threshold
activePowerReports = `20` → Report when power changes by 20%
- Load at 40W, dims to 35W: Change is 12.5%, no report
- Load at 40W, dims to 30W: Change is 25%, report sent

### Energy Threshold
activeEnergyReports = `50` → Report every 0.5 kWh (500 Wh)
- 100W bulb for 5 hours: 500 Wh consumed → Report sent

### Periodic Reporting
periodicPowerAndEnergyReports = `1800` → Report every 30 minutes
- Regardless of power/energy changes, status sent every 30min

## Important Notes

- All reporting properties work independently
- Power and energy sensors update based on configured thresholds
- quickStartTime/Level only applies to the transition from off to on
- higherOutputInNonNeutral only helps in non-neutral wiring setups
- Sensors are read-only; only configuration properties can be set
- Lower reporting thresholds increase Zigbee network traffic
- Power readings may have ~1W accuracy tolerance