Add Inovelli Blue Dimmer switch hardware documentation

2025-12-21 15:51:08 -08:00
parent 40e03d0300
commit 63dec6c5ee
9 changed files with 2540 additions and 0 deletions
--- a/inovelli/power-monitoring.md
+++ b/inovelli/power-monitoring.md
@@ -0,0 +1,364 @@
+# 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