{"id":50775378,"url":"https://github.com/circuitsetup/circuitsetup-energy-analyzer","last_synced_at":"2026-06-27T04:00:47.608Z","repository":{"id":362385354,"uuid":"1258349606","full_name":"CircuitSetup/CircuitSetup-Energy-Analyzer","owner":"CircuitSetup","description":"Analyze energy patterns in your home. Identify potential issues with appliances. For Home Assistant","archived":false,"fork":false,"pushed_at":"2026-06-22T20:30:06.000Z","size":17865,"stargazers_count":9,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-06-22T22:16:21.728Z","etag":null,"topics":["circuitsetup","energy","energy-data","energy-meter","home-assistant","homeassistant","metering","nilm"],"latest_commit_sha":null,"homepage":"https://circuitsetup.us/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CircuitSetup.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-03T13:51:21.000Z","updated_at":"2026-06-22T20:30:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CircuitSetup/CircuitSetup-Energy-Analyzer","commit_stats":null,"previous_names":["circuitsetup/circuitsetup-energy-analyzer"],"tags_count":57,"template":false,"template_full_name":null,"purl":"pkg:github/CircuitSetup/CircuitSetup-Energy-Analyzer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CircuitSetup%2FCircuitSetup-Energy-Analyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CircuitSetup%2FCircuitSetup-Energy-Analyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CircuitSetup%2FCircuitSetup-Energy-Analyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CircuitSetup%2FCircuitSetup-Energy-Analyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CircuitSetup","download_url":"https://codeload.github.com/CircuitSetup/CircuitSetup-Energy-Analyzer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CircuitSetup%2FCircuitSetup-Energy-Analyzer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34840899,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circuitsetup","energy","energy-data","energy-meter","home-assistant","homeassistant","metering","nilm"],"created_at":"2026-06-11T23:00:28.767Z","updated_at":"2026-06-27T04:00:47.598Z","avatar_url":"https://github.com/CircuitSetup.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CircuitSetup Energy Analyzer\n\nCircuitSetup Energy Analyzer is a Home Assistant custom integration that turns circuit-level energy-meter data into useful appliance and circuit diagnostics.\n\n[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=CircuitSetup\u0026repository=CircuitSetup-Energy-Analyzer\u0026category=Integration)\n\nIt is designed for the [CircuitSetup Expandable 6 Channel ESP32 Energy Meter Main Board](https://circuitsetup.us/index.php/product/expandable-6-channel-esp32-energy-meter/) exposed through [ESPHome ATM90E32](https://esphome.io/components/sensor/atm90e32/) sensors, but it can also work with other meters when they expose compatible Home Assistant sensor entities for:\n\n- Power\n- Current\n- Voltage\n- Energy\n- Frequency\n- Reactive power\n- Apparent power\n- Power factor\n\n**CircuitSetup-first, not CircuitSetup-only:** the integration is optimized for the CircuitSetup meter layout, but other compatible meters can be used when they expose power, current, voltage, energy, frequency, reactive power, apparent power, or power factor entities with usable Home Assistant metadata.\n\nThe integration does **not** replace Home Assistant's Energy Dashboard. Use the Energy Dashboard for long-term energy history, tariffs, costs, device hierarchies, and normal energy cards. Use CircuitSetup Energy Analyzer when you want to understand what your circuits and appliances are doing, whether their behavior has changed, and whether your meter data looks trustworthy.\n\n## What you can use it for\n\nUse this integration when you want answers like:\n\n- Is this appliance running, idle, on standby, or not showing recent activity?\n- Is today's energy use unusually high for this circuit?\n- Is my refrigerator, washer, dryer, pump, HVAC, water heater, or EV charger behaving differently from its learned baseline?\n- Is a 240 V appliance balanced across both legs?\n- Are watts, amps, volts, VA, and power factor internally consistent?\n- Is a circuit approaching a configured breaker or capacity limit?\n- Which monitored circuits explain my mains power, and how much power is still unmonitored?\n- Is solar being exported, self-consumed, or available for flexible loads?\n- Do my measured kWh totals roughly agree with utility or Opower data?\n- Are there recurring unknown whole-home load signatures worth investigating?\n\nThe analyzer is intentionally conservative. It learns before alerting, requires repeated evidence, and reports a **possible issue** or **behavior change** instead of claiming to diagnose a failed appliance part.\n\n## What this integration is not\n\nCircuitSetup Energy Analyzer is not:\n\n- A replacement for Home Assistant's Energy Dashboard.\n- A substitute for an electrician, appliance technician, or code-compliance review.\n- A guarantee that a breaker, wire, CT, panel, or appliance is safe.\n- A definitive appliance-failure diagnosis tool.\n- A full NILM system that can always identify every unknown load automatically.\n\nTreat alerts as evidence to review. Check the source entities, CT orientation, phase mapping, units, and appliance assignment before assuming the appliance is the problem.\n\n## Requirements\n\nYou need:\n\n- Home Assistant `2025.1.0` or newer.\n- HACS, if installing through the recommended method.\n- One or more energy-meter sensors already available in Home Assistant.\n- For CircuitSetup meters, ESPHome entities from an ATM90E32-based meter are the expected source (uncomment [power quality](https://github.com/CircuitSetup/Expandable-6-Channel-ESP32-Energy-Meter/blob/63c6f8935700eeee3c033c74a1d3ebdd15e706b3/Software/ESPHome/6chan_energy_meter_main_board.yaml#L80) in your config)\n- Cumulative kWh sensors if you want daily energy, goals, billing-cycle, cost, utility comparison, or Energy Dashboard readiness checks.\n- Current sensors, or power plus voltage, if you want capacity/amp checks.\n- Mains or aggregate sensors if you want mains balance, experimental Mains NILM, solar-flow, or utility comparison features.\n- An outdoor temperature sensor if you want HVAC weather context.\n- A rain sensor if you want sump, well, or water-pump activity compared with rainfall and HVAC condensate context.\n- A binary water-flow sensor or numeric flow-rate sensor if you want water movement compared with washer, water-heater, well-pump, or water-pump activity. Numeric flow sensors are treated as off at `0` and active when greater than `0`.\n\nThe integration works best when each important appliance or circuit has a clean group of related source sensors.\n\n## Installation\n\nThis repository is structured as a HACS custom integration. The integration files live under:\n\n```text\ncustom_components/circuitsetup_energy_analyzer\n```\n\n![CircuitSetup Energy Analyzer integration overview in Home Assistant Devices and services](docs/images/readme/integration-overview.png)\n\n### Install with HACS\n\n1. Open **HACS**.\n2. Add this repository as a custom repository.\n3. Choose category **Integration**.\n4. Install **CircuitSetup Energy Analyzer**.\n5. Restart Home Assistant.\n6. Go to **Settings \u003e Devices \u0026 services**.\n7. Add **CircuitSetup Energy Analyzer**.\n\n## Setup overview\n\nThe setup flow is designed so you do not need to hand-write JSON or edit YAML for normal configuration.\n\n![CircuitSetup Energy Analyzer options menu with setup actions](docs/images/readme/options-menu.png)\n\nDuring setup, you choose:\n\n| Setup item | What it is for |\n|---|---|\n| **Source Devices** | ESPHome meter devices, such as a CircuitSetup ATM90E32 meter. The integration expands selected devices into matching electrical sensors. |\n| **Extra Source Entities** | Individual sensors that are not attached to a selected source device, or sensors you want to add manually. |\n| **Mains Source Entities** | Optional whole-panel or aggregate sensors used for mains balance, experimental Mains NILM, solar-flow, and utility comparison. |\n| **Outdoor Temperature Entity** | Optional outdoor temperature source used only for HVAC weather context. |\n| **Rain Sensor** | Optional boolean rain sensor used to explain expected sump, well-pump, or water-pump activity. |\n| **Rain Intensity Sensor** | Optional numeric precipitation-rate sensor. If available, heavier rain can raise expected pump activity more than light rain. |\n| **Water Flow Sensors** | Optional binary or numeric water-flow sensors used to compare water movement with washer, water-heater, well-pump, or water-pump activity. Binary sensors are active when on; numeric flow-rate sensors are active when greater than `0`. |\n| **Circuit Assignments** | The review step where you confirm which sensors belong together and how each circuit should be analyzed. |\n| **Advanced Circuit Settings** | The screen used to tune thresholds, goals, billing, demand, capacity, standby, solar, and other per-circuit options after setup. |\n\n![Source selection panel showing Source Devices and Extra Source Entities](docs/images/readme/source-selection.png)\n\n![Circuit assignment editor showing circuit mode and power flow controls](docs/images/readme/assignment-editor.png)\n\n## Using The Integration\n\nUse the integration in this order:\n\n- **First-time setup checklist**: add the integration from **Settings \u003e Devices \u0026 services**, select source devices/entities, then use **Appliance Circuit Assignments**.\n- **Check setup health first**: `sensor.circuitsetup_energy_analyzer_setup_health` gives one next step, such as adding a cumulative kWh source, fixing stale sensors, adding rain/water-flow context, reviewing utility comparison setup, checking CT direction, or letting the analyzer learn.\n- **Classify circuits deliberately**: choose the appliance type, circuit mode, power-flow mode, and source sensors before trusting appliance evidence.\n- **Use it day to day**: start with Health Summary, Activity Summary, Electrical Health, Energy Summary, Daily Energy Usage, and the Running binary sensor.\n- **Configure the optional features you actually need**: open **Advanced Circuit Settings** for the appliance. The form only shows settings that apply to the selected appliance or circuit.\n- **Practical examples**: Washer or dryer running automation, Refrigerator monitoring, HVAC or 240 V appliance review, EV charger or high-current circuit tracking, and Utility or Opower comparison.\n- **When an alert appears**: read the notification, open the evidence graph if available, check `status_explanation`, and verify source data before treating it as an appliance problem.\n- **Common setup states**: learning, waiting for energy change, missing metrics, not dual phase, missing mains, and unconfigured optional checks usually mean the analyzer needs more data or a better assignment.\n\nYou do not need to enable every diagnostic entity. For behavior alerts, let the analyzer learn for at least 7 days or enough appliance cycles before tuning thresholds.\n\n## First-time setup checklist\n\n1. Install the integration, restart Home Assistant, and add it from **Settings \u003e Devices \u0026 services**.\n2. In **Source Devices**, select the ESPHome meter device or other meter device that owns your CT/channel sensors.\n3. Use **Extra Source Entities** only for sensors that are not already included through a selected source device.\n4. Leave **Mains Source Entities** empty unless you have whole-panel or aggregate measurements.\n5. Add mains sources if you want Mains NILM, mains balance, solar-flow, or utility/Opower comparison.\n6. Add an outdoor temperature entity if you want HVAC activity compared with outdoor conditions.\n7. Add a rain sensor if you want sump, well, or water-pump activity adjusted for rainfall.\n8. Add water-flow sensors if you want leak-style mismatch checks against water-using appliances.\n9. Open **Appliance Circuit Assignments**.\n10. For each detected group, confirm:\n   - Whether to include the circuit.\n   - The circuit name.\n   - The appliance type.\n   - The circuit mode.\n   - The power-flow mode.\n   - The selected source sensors.\n11. Save the configuration.\n12. Let the analyzer learn before acting on behavior alerts. Most behavior checks need at least 7 days or enough appliance cycles.\n13. Use **Advanced Circuit Settings** later if you need to tune thresholds, goals, billing, demand, capacity, standby, solar-flow, water context, or other feature settings.\n\n## Classify circuits carefully\n\nCorrect circuit classification is the most important part of setup.\n\n| Mode | Use for | Notes |\n|---|---|---|\n| **Single Phase** | One CT/channel tracking one main 120 V load, such as a refrigerator, washer, sump pump, microwave, or water pump. | Best for dedicated appliance circuits. |\n| **Dual Phase** | Two CT/channels that are the two legs of one 240 V appliance, such as HVAC, electric heat, water heater, dryer, oven, pool pump, or EV charger. | Enables leg-balance and combined-appliance analysis. |\n| **Mixed** | A branch circuit with multiple unrelated loads, such as plugs and lights. | The analyzer stays conservative and avoids appliance-specific claims. |\n| **Mains NILM** | Whole-home mains or feed circuits. | Required for experimental whole-home load-signature discovery. |\n\n## Choose the right power-flow mode\n\nPower-flow mode tells the analyzer how to interpret signed watts.\n\n| Power flow | Use for | How negative watts are treated |\n|---|---|---|\n| **Load** | Normal consuming circuits. | Sustained negative watts usually mean CT orientation or configuration should be checked. |\n| **Generation / Solar Export** | Solar inverter or generation circuits. | Negative power can be expected export/generation behavior. |\n| **Mains / Net** | Signed whole-home mains measurements. | Import and export direction are preserved. |\n\nIf a normal load circuit shows sustained negative watts, check CT orientation before using that data as appliance evidence.\n\n## Supported appliance profiles\n\nRecommended appliance types include:\n\n- `refrigerator`\n- `freezer`\n- `hvac`\n- `hvac_compressor`\n- `hvac_blower`\n- `electric_heat`\n- `water_heater`\n- `oven`\n- `microwave`\n- `washer`\n- `dryer`\n- `pool_pump`\n- `water_pump`\n- `well_pump`\n- `sump_pump`\n- `ev_charger`\n- `solar_inverter`\n- `motor_load`\n- `resistive_load`\n- `mixed`\n\nChoose the closest profile. The profile controls which checks are useful, which sensors are recommended, and how learning works.\n\n## Summary-First Diagnostics\n\nMost users should build dashboards from the summary entities first. Detailed diagnostic entities are still available, but advanced troubleshooting entities are disabled by default so Home Assistant does not record unnecessary state history unless you opt in.\n\nThe integration has an **Entity Detail Level** option under **Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure**:\n\n- **Simple**: default for most homes. Enables the main summary entities, Daily Energy Usage when usable, and appliance Running sensors.\n- **Standard**: also enables configured feature-status entities, such as energy goals, billing/cost, weather context, water-flow context, and other features you turned on.\n- **Expert**: creates only the diagnostic or graph groups you select under **Expert Entity Groups**, useful for troubleshooting and custom diagnostic dashboards.\n\nChanging **Entity Detail Level** reloads the integration so the entity set matches the selected profile. Expert creates only the diagnostic or graph groups you select, such as Developer Diagnostics, Energy Detail, Demand and Capacity, Mains and Solar Detail, NILM Detail, Cycle Metrics, Electrical Scores, Power Quality Drift, Billing Forecasts, Standby, Weather, and Water. Existing manual entity-registry customizations are respected; use **Migrate To Compact Entity Model** when you want to remove preserved legacy rows.\n\nFor a configured circuit ID such as `refrigerator`, `hvac`, or `car_charger`, the main entities follow this pattern:\n\n| Entity | Example | What it tells you |\n|---|---|---|\n| **Setup Health / Next Step** | `sensor.circuitsetup_energy_analyzer_setup_health` | The highest-priority setup action across the integration, with attributes for the reason, affected circuit, blocking issue count, and configuration path. |\n| **Health Summary** | `sensor.\u003ccircuit\u003e_health_summary` | Whether the circuit is ready, learning, missing data, paused, or showing a possible issue. |\n| **Activity Summary** | `sensor.\u003ccircuit\u003e_activity_summary` | What the appliance appears to be doing now: running, idle, standby, on, off, or no recent activity. |\n| **Electrical Health** | `sensor.\u003ccircuit\u003e_electrical_health` | Combined electrical condition, including power-quality, metric-consistency, and leg-balance evidence when available. |\n| **Energy Summary** | `sensor.\u003ccircuit\u003e_energy_summary` | Combined daily usage, goal, billing, cost, and high-usage evidence. |\n| **Daily Energy Usage** | `sensor.\u003ccircuit\u003e_daily_energy_usage` | Today's derived kWh when a cumulative energy source is available. |\n| **Running** | `binary_sensor.\u003ccircuit\u003e_running` | Simple on/off running state for automations. |\n| **Settings Suggestions** | `sensor.\u003ccircuit\u003e_settings_suggestions` | Count of pending advanced-setting recommendations. Available from the Expert Developer Diagnostics group or by enabling the entity. |\n\nUse summary sensors for dashboards and automations. When a summary changes, open the entity attributes or the alert evidence page from the notification. The evidence page explains what happened, why it matters, observed versus expected values, sample count, first/last seen times, and what to check first. Use advanced detail entities only when you are investigating deeper setup or data-quality evidence.\n\nFor power-meter interpretation:\n\n- **Watts**: what the circuit is doing right now.\n- **kWh**: how much energy it used over time.\n- **Amps**: how hard the circuit is loaded.\n- **Power factor, reactive power, and apparent power**: electrical evidence used for health and consistency checks.\n\n## Build a useful dashboard\n\nThe fastest path is to let the integration create a starter dashboard:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Create Or Update Dashboard**\n\nChoose one layout:\n\n1. **Simple**: compact appliance status, mains rollup, and energy tracking sections built from summary entities.\n2. **Standard**: Simple plus feature-level mains, HVAC, solar, utility, weather, water, billing, and cost cards when matching Standard entities exist.\n3. **Expert**: Standard plus analyzer evidence links for each circuit. It does not add diagnostic/detail entity cards automatically.\n\nThe dashboard form has three setup paths:\n\n1. Create or update the recommended dashboard with the selected **Dashboard Layout**.\n2. Check **Match Entity Detail Level To Layout** when the selected layout needs more analyzer entities than your current Entity Detail Level creates.\n3. Check **Remove Existing Dashboard** when you want to delete the stored recommended dashboard instead of updating it.\n\nYou can also choose the preferred layout from `select.circuitsetup_energy_analyzer_dashboard_layout`, but the dashboard action still runs from Configure \u003e Create Or Update Dashboard; there is no dashboard action button entity.\n\nThe generated dashboard uses Home Assistant's current entity registry IDs, so renamed analyzer entities are respected. It matches the included example dashboard structure with appliance status, mains/NILM, shared energy tracking, and HVAC weather-context sections when those circuits exist. It keeps each appliance card to four summary rows: Activity, Electrical Health, Energy Summary, and Daily Energy Usage. It does not add dropdown, switch, number, or button control cards. When the registry is available, the dashboard treats absent analyzer entities as missing and shows a note instead of falling back to guessed IDs. Missing, disabled, or unavailable entities are shown as dashboard notes instead of broken cards. Existing starter dashboards are matched before update so the integration does not create duplicate dashboard entries when Home Assistant returns storage items in a different shape.\n\nFor manual dashboards, start with one simple card per important appliance:\n\n1. Activity Summary\n2. Electrical Health\n3. Energy Summary\n4. Daily Energy Usage\n\nAdd the Running binary sensor where you want automations, such as washer finished, dryer finished, pump running, or microwave activity.\n\nFor YAML reference, an example dashboard is still included:\n\n```text\ndocs/dashboard-example.yaml\n```\n\n![Appliance-first Energy Analyzer dashboard with appliance status rollups and mains analysis cards](docs/images/readme/demo-dashboard.png)\n\nA good dashboard order is:\n\n1. **Appliance status**: Activity Summary, Electrical Health, Energy Summary, Daily Energy Usage.\n2. **Automations**: Running binary sensors for appliance-complete notifications.\n3. **Energy tracking**: Daily Energy Usage and Energy Summary.\n4. **Electrical review**: Electrical Health, plus detailed diagnostics only when needed.\n5. **Setup/data quality**: Repairs, notifications, and entity attributes.\n\n### Appliance Drilldown Pattern\n\nWhen a single appliance needs review, use this pattern:\n\n1. **Appliance status card**: Health Summary, Activity Summary, Electrical Health, Energy Summary, and Daily Energy Usage.\n2. **Appliance automations**: Running binary sensor for washer, dryer, pump, microwave, or appliance-complete automations.\n3. **Energy tracking**: Daily Energy Usage, Energy Usage Status, goals, billing, and cost where those features are enabled.\n4. **Electrical review**: power-quality, metric-consistency, leg-imbalance, and capacity entities only when the summary points there.\n5. **Setup and data quality**: advanced diagnostic entities, Repairs, source entity attributes, and `status_explanation`.\n\n## Let the analyzer learn\n\nDuring the first week, expect many entities to say `Learning`, `Needs data`, or `Waiting For Energy Change`.\n\nThe analyzer learns conservative baselines before sending behavior alerts. Depending on the feature, it needs:\n\n- At least 7 days of retained history.\n- Enough run cycles.\n- Enough daily kWh samples.\n- Enough steady samples for standby, demand, or power-quality checks.\n\nIf something looks confusing, open the entity details and review attributes such as:\n\n- `status_explanation`\n- `observed_evidence`\n- `source_entities`\n- `threshold`\n- `sample_count`\n- `first_seen`\n- `last_seen`\n\nDo this before changing thresholds or assuming an appliance has failed.\n\n## Retained analyzer data\n\nCircuitSetup Energy Analyzer keeps compact diagnostic evidence for its own\nanalysis. It does not try to replace Home Assistant's recorder, statistics, or\nEnergy Dashboard history.\n\nRetention modes control time-based circuit evidence:\n\n| Retention mode | Time window |\n|---|---:|\n| Lightweight | 14 days |\n| Standard | 45 days |\n| Diagnostic | 180 days |\n\nAdditional persisted structures have hard caps so storage cannot grow without\nbound:\n\n| Stored structure | Cap |\n|---|---:|\n| Alert history | 500 items or 180 days |\n| Alert feedback | 500 items or 365 days; expected alert feedback expires after about 90 days, not-helpful feedback after about 45 days |\n| Weather context history | 1,008 samples per circuit plus the retention window |\n| Rain/water-flow context history | 1,008 samples per circuit plus the retention window |\n| NILM signatures | 64 signatures per mains circuit |\n| NILM unknown-load inventory | 32 unknown loads per mains circuit |\n| Settings suggestions | 200 recommendations or 180 days, pending suggestions kept first |\n| Settings suggestion decisions | 500 decisions or 365 days |\n| Settings suggestion notification history | 100 notification episode keys |\n\n## Optional features\n\nEnable and tune optional features from the integration options screen. Manual YAML editing is not required.\n\nGo to:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Advanced Circuit Settings**\n\n![Advanced circuit settings panel with sensitivity and energy window controls](docs/images/readme/advanced-settings.png)\n\nUse **Advanced Circuit Settings** to configure circuit-specific options such as:\n\n- Energy-usage spike thresholds\n- Daily energy goals\n- Billing-cycle settings\n- Cost and Time-of-Use estimates\n- Demand settings\n- Circuit capacity limits\n- Dual-phase leg-imbalance settings\n- Metric-consistency tolerances\n- Mains-balance settings\n- Solar-flow thresholds\n- Standby and Always On settings\n- Activity-alert sensitivity\n- Rain, pump, and water-flow context\n\nAlert sensitivity uses the same names everywhere: **Quiet**, **Balanced**, and **Sensitive**. Older stored presets are automatically migrated to those names.\n\nMost users should configure these options from the Home Assistant UI. Developer Tools actions are available for automations, scripts, dashboards, backups, and advanced workflows, but they are not required for normal setup.\n\nDaily actions are exposed as Home Assistant entities so you do not need to copy IDs into service calls. Use the circuit buttons and controls for normal actions. If you do call a circuit service from an automation, you can target a renamed analyzer entity instead of typing the circuit ID.\n\n- `button.\u003ccircuit\u003e_relearn_baseline`\n- `select.\u003ccircuit\u003e_alert_sensitivity`\n- `number.\u003ccircuit\u003e_daily_energy_goal`\n- `switch.\u003ccircuit\u003e_maintenance`\n\nIntegration-level controls are grouped on the CircuitSetup Energy Analyzer device:\n\n- `button.circuitsetup_energy_analyzer_run_mapping_checks`\n- `button.circuitsetup_energy_analyzer_recalculate_suggestions`\n- `select.circuitsetup_energy_analyzer_entity_detail_level`\n- `select.circuitsetup_energy_analyzer_dashboard_layout`\n\nDashboard create, update, and remove actions are available from **Configure \u003e Create Or Update Dashboard**, not from a button entity.\n\n## Normal User Paths\n\nThe integration still exposes service actions for scripts, blueprints, dashboards, backups, and Developer Tools. Those actions intentionally keep fields such as `circuit_id`, `alert_id`, `signature_id`, and `recommendation_id` for backwards compatibility and automation use.\n\nFor day-to-day use, prefer these paths instead:\n\n| User intent | Normal path |\n|---|---|\n| Circuit action | Circuit action -\u003e button/select/number entity |\n| Alert action | Alert action -\u003e evidence panel button |\n| NILM signature action | NILM signature action -\u003e NILM/evidence panel button |\n| Recommendation action | Recommendation action -\u003e Suggested Settings UI button |\n| Setup/data-quality fix | Setup/data-quality fix -\u003e Repairs flow |\n\nThis keeps IDs inside the integration wherever possible. You should not need to copy `circuit_id`, `alert_id`, `signature_id`, or `recommendation_id` from attributes into Developer Tools for ordinary setup, tuning, alert review, or appliance maintenance.\n\n### Feedback teaches the analyzer\n\nWhen you mark an alert as expected, the analyzer remembers that evidence pattern by a stable local fingerprint. Future matching evidence under similar conditions is retained for review, but it is shown as an expected pattern instead of repeatedly creating a new active possible-issue alert or notification. Expected alert feedback expires after about 90 days unless refreshed.\n\nWhen you mark an alert as not helpful, the analyzer records that pattern separately from acknowledgement. Future matching evidence must repeat more times before it can become a new alert, and the evidence panel shows the adjusted repeated-evidence requirement when it applies. If the same daily energy spike pattern is repeatedly marked not helpful, the analyzer can suggest a safer daily spike ratio change for you to approve, undo, or reset to the built-in default. Not-helpful feedback expires after about 45 days unless refreshed. Acknowledgement only clears the current alert episode; it does not permanently suppress future alerts after conditions clear and recur.\n\nWhen you label, ignore, mark expected, or merge an experimental NILM signature, the analyzer preserves that review decision in local storage and reflects it in the evidence panel and unknown-load inventory. Review decisions follow a stable electrical fingerprint across future reclustering when the direction, value buckets, and split-phase topology still match; substantially different signatures are treated as new review items.\n\nSuggested settings remember apply, deny, and dismiss decisions. Denying a suggestion suppresses the same value for the same evidence during its cooldown. Dismissing hides it until the evidence changes or the recommendation expires.\n\n| Feature | What it does | Needs |\n|---|---|---|\n| **Energy usage spikes** | Compares today's kWh with a learned rolling window and reports repeated high-usage evidence. | Cumulative energy sensor. |\n| **Daily energy goals** | Lets you set a per-circuit daily kWh goal and receive repeated goal notices. | Cumulative energy sensor. |\n| **Run-cycle diagnostics** | Tracks start count, runtime, duty cycle, and running state for appliance-style circuits. | Real-power data and enough cycles. |\n| **HVAC weather context** | Compares HVAC runtime with similar outdoor temperatures before treating runtime as unusual. | HVAC-like circuit plus outdoor temperature sensor. |\n| **Rain and pump correlation** | Compares pump runtime with rain, optional rain intensity, and HVAC compressor activity before flagging unusual pump behavior. | Sump pump, water pump, or well pump plus rain sensor. |\n| **Water-flow correlation** | Compares binary or numeric water-flow sensors with water-using appliance activity to find unexplained flow or missing expected flow. | Water-flow sensor plus washer, water heater, water pump, or well pump. |\n| **Recent activity timeline** | Keeps recent start/stop/steady-window events and recent possible-issue evidence. | Configured circuit with retained evidence. |\n| **Billing-cycle forecasts** | Tracks current-cycle kWh and projected end-of-cycle usage. | Cumulative energy sensor. |\n| **Cost and Time-of-Use estimates** | Estimates current-cycle and projected cost from configured rates. | Cumulative energy sensor and configured rates. |\n| **History CSV export** | Exports retained analyzer history for one circuit. | Retained analyzer history. |\n| **Peak demand tracking** | Tracks rolling demand and today's peak demand. | Real-power data. |\n| **Circuit capacity tracking** | Compares amps with a configured breaker/circuit rating. | Current sensor, or power plus voltage. |\n| **Dual-phase leg imbalance** | Checks whether both legs of a 240 V appliance are behaving as expected. | Dual-phase circuit with leg A/B power. |\n| **Power metric consistency** | Checks whether W, VA, V, A, and PF relationships make sense. | Voltage/current/apparent power/power factor where available. |\n| **Mains balance** | Compares mains power with the sum of monitored load circuits. | Mains or aggregate source. |\n| **Solar flow** | Shows solar generation, grid import/export, site consumption, surplus, and flexible-load hints. | Signed mains/net source plus solar generation circuit. |\n| **Utility / Opower comparison** | Compares utility-reported kWh with measured kWh for the same period. | Utility/Opower entity or statistic plus measured energy. |\n| **Always On and standby** | Estimates the low-power always-on load and current standby/on/off state. | Real-power data. |\n| **Experimental NILM** | Looks for recurring unknown whole-home load signatures, pairs likely on/off sessions, and lets you review or publish user-confirmed estimated appliances. | Mains aggregate source; optional known-load circuits improve results. |\n\n## Feature notes\n\n### Energy usage spikes\n\nFor circuits with cumulative kWh sensors, the analyzer derives daily usage from positive energy deltas. By default, it compares today's usage with a learned rolling window and treats a large repeated increase as possible issue evidence.\n\nUse this for appliances where daily usage should usually stay within a predictable range, such as refrigerators, freezers, water heaters, HVAC, pumps, or EV charging circuits.\n\nConfigure this from:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Advanced Circuit Settings**\n\nUse the energy-usage settings to adjust the comparison window and spike threshold without editing YAML.\n\n### Seasonal and contextual baselines\n\nSome appliances behave differently depending on weather, season, time of day, rain, water use, and solar production. The analyzer keeps compact contextual samples and compares a circuit with the most relevant learned baseline when enough similar history exists. If there is not enough matching context yet, it falls back to the existing broader rolling baseline.\n\nThis helps avoid noisy alerts when context explains the usage, such as HVAC energy on very hot summer afternoons, while still preserving conservative possible-issue evidence when behavior is unusual for the current context.\n\n### Daily energy goals\n\nDaily goals add a notification layer around a kWh target. Use Home Assistant's Energy Dashboard for normal energy charts; use this feature when you want per-circuit goal evidence.\n\nConfigure this from:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Advanced Circuit Settings**\n\nSet a daily kWh goal for the circuit. Set the goal back to `0` to clear it.\nThe daily goal control is only created when the circuit has usable energy data,\nso stale saved goals do not add a confusing control before a cumulative kWh\nsource is configured.\n\n### Run-cycle diagnostics\n\nFor appliance-style circuits, the analyzer tracks today's:\n\n- Run-cycle count\n- Runtime\n- Duty cycle\n- Current running state\n\nThis is useful for refrigerators, freezers, pumps, HVAC, washers, dryers, and other loads where cycling behavior matters.\n\n### HVAC weather context\n\nHVAC runtime depends strongly on outdoor temperature. A compressor running longer on a very hot afternoon may be normal, while the same runtime on a mild day may deserve review.\n\nAdd an outdoor temperature entity during setup or later from **Configure**. Use a real outdoor sensor, weather-station sensor, or reliable outdoor helper. Indoor thermostat temperature is usually not a good source for this feature.\n\n### Rain and pump correlation\n\nRain and pump correlation applies to `sump_pump`, `water_pump`, and `well_pump` circuits. It compares recent pump runtime with the learned dry-weather baseline, current rain state, optional rain intensity, and recent HVAC compressor activity.\n\nThis matters because a sump pump may run more during rain, and it may also run more when an AC compressor is removing humidity and sending condensate to a drain or sump. When both rain and AC activity are present, higher pump activity can be expected instead of automatically becoming a possible issue.\n\nConfigure the global rain source during setup or later from **Configure**. Tune the per-circuit rain response window and activity threshold from:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Advanced Circuit Settings**\n\nThe analyzer can report weather-explained pump activity, possible excess pump activity, or possible missing pump activity. Treat those as prompts to inspect the pump, sensor mapping, discharge path, or recent weather conditions.\n\n### Water-flow correlation\n\nWater-flow correlation applies to `water_pump`, `well_pump`, `water_heater`, and `washer` circuits when at least one global or circuit-linked binary water-flow sensor or numeric flow-rate sensor is configured. Numeric flow-rate sensors are treated as off at `0` and active when greater than `0`.\n\nThe analyzer compares how long the water-flow sensor has been active with recent mapped appliance runtime. It can report:\n\n- Flow without a matching water-using appliance, which can point to an unmapped load, leak, running faucet, irrigation, or sensor mapping problem.\n- Appliance activity without expected flow, which can point to a stuck sensor, closed valve, dry-running pump, or assignment problem.\n- A likely sensor problem when both mismatch directions repeat.\n\nConfigure global flow sensors during setup or later from **Configure**. Use **Advanced Circuit Settings** to link specific flow sensors to a specific appliance, turn off flow expectations for an appliance, or adjust the mismatch-minute threshold.\n\n### Billing, cost, and Time-of-Use\n\nBilling and cost features estimate usage and cost from analyzer-retained data. They do not include every possible utility billing rule, such as taxes, fixed fees, tiered rates, or demand charges.\n\nConfigure billing-cycle and cost settings from:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Advanced Circuit Settings**\n\nUse these estimates for household awareness and alerts, not for exact utility-bill reproduction.\n\nTime-of-use settings use a time picker for the peak start/end times and a weekday selector for peak days, so normal setup does not require typing comma-separated weekday numbers.\n\n### Demand and capacity\n\nDemand tracking uses rolling average watts. Capacity tracking compares amps with a configured breaker or circuit rating.\n\nConfigure this from:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Advanced Circuit Settings**\n\nUse the demand and capacity settings to set the breaker or circuit rating, warning threshold, and demand-window behavior.\n\nCapacity diagnostics are operational evidence only. They do not verify breaker, wire, plug, appliance, or code suitability.\n\n### Dual-phase leg imbalance\n\nFor 240 V loads, the analyzer can compare leg A and leg B while the appliance is drawing meaningful power. Repeated imbalance can point to:\n\n- CT pairing mistakes\n- CT orientation problems\n- Phase mapping problems\n- Appliance behavior changes\n\nConfigure leg-imbalance settings from:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Advanced Circuit Settings**\n\nA leg imbalance alert means \"review the evidence,\" not \"replace the appliance.\"\n\n### Power metric consistency\n\nWhen voltage, current, watts, VA, and power factor are available, the analyzer checks whether the reported values agree with expected AC power relationships.\n\nA mismatch can point to:\n\n- Source-entity mixups\n- CT/channel pairing mistakes\n- Incorrect units\n- Stale sensors\n- Calibration problems\n\nConfigure metric-consistency tolerances from:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Advanced Circuit Settings**\n\nThis is especially useful with CircuitSetup/ATM90E32 data because multiple electrical measurements are available per channel.\n\n### Mains balance\n\nMains balance compares whole-home mains power with the sum of directly monitored load circuits.\n\nA positive balance often represents ordinary unmonitored loads, such as lights or plug loads. A strongly negative balance can suggest CT direction, phase pairing, solar configuration, multiplier, or double-counting problems.\n\nConfigure mains-balance settings from:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Advanced Circuit Settings**\n\n### Solar flow\n\nFor homes with a signed mains/net source and solar generation circuits, the analyzer can estimate:\n\n- Solar generation\n- Site consumption\n- Grid import\n- Grid export\n- Solar self-consumption\n- Solar-powered share\n- Solar surplus\n- Flexible-load solar support\n\nConfigure solar-flow thresholds from:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Advanced Circuit Settings**\n\nThis feature is read-only. Use ordinary Home Assistant automations if you want to turn on an EV charger, water heater, pool pump, or other flexible load when solar surplus is available.\n\n### Utility / Opower comparison\n\nUtility comparison checks whether utility-reported kWh roughly agrees with measured kWh over the same period.\n\nConfigure it on a mains or aggregate circuit. You can use a utility/Opower entity, a recorder statistic ID, or let the analyzer choose automatically when possible.\n\nUtility comparison settings are available from:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Advanced Circuit Settings**\n\nBefore acting on a mismatch, verify that the utility and measured sources cover the same time period. Utility integrations can update late.\n\n### Always On and standby\n\nFor load circuits with real-power data, the analyzer estimates an Always On load from the lowest retained power level in the standby window. It can also classify the current state as off, standby, or on.\n\nConfigure this from:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Advanced Circuit Settings**\n\nUse the standby and Always On settings to set standby thresholds, Always On alert limits, and related sensitivity options.\n\n### Experimental NILM\n\nExperimental NILM is opt-in. It can look for recurring unknown load signatures from mains or mixed circuits, especially when known directly monitored circuits are masked out. With a mains source, the NILM workspace can also pair compatible on/off edges into likely sessions, show known-load overlays, and keep manual interval labels for review.\n\nOn generated Standard and Expert dashboards, use **Open NILM Graph \u0026 Review** in the **Mains, Solar, and NILM** section to open the mains NILM workspace graph and review actions.\n\nUnknown load estimates may include:\n\n- Likely load type\n- 120 V versus 240 V hint\n- Dominant leg\n- Typical W/VAR/VA\n- Power factor\n- Confidence\n- First seen / last seen\n- Running state\n- Estimated runtime and kWh\n\nThese are clues, not confirmed appliance names. If multiple loads overlap, the analyzer should keep the evidence ambiguous instead of forcing a guess.\n\nUse the NILM workspace from the evidence panel to label signatures, save graph intervals, merge duplicate signatures, assign a signature/session/interval to an appliance, and publish that confirmed assignment as estimated Home Assistant appliance entities. Use **Adjust Label** to correct saved intervals and **Validate History** after adding manual or sensor labels; assignment cards show confirmed/rejected sessions, false-positive and false-negative rates, and power/energy error when matching data is available. The workspace passes NILM IDs internally, offers appliance-profile choices, and uses known-load sensors as selectable ground-truth sources when they are available. Published NILM appliances are marked as estimated and can expose estimated running, power, daily energy, health, activity, and energy summaries. Keep assignments unpublished until the workspace evidence looks trustworthy; use **Disable Publishing** or **Retire** when an estimate should stop creating entities. NILM estimates are inferred from aggregate power and are not safety evidence.\n\n## Suggested settings\n\nAfter enough history, the analyzer can suggest advanced settings based on observed evidence. These are tuning recommendations for thresholds and windows, not appliance diagnoses.\n\nReview them from:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Review Suggested Settings**\n\nFor each suggestion, you can:\n\n| Action | Meaning |\n|---|---|\n| **Apply Suggestion** | Update the circuit's advanced setting. |\n| **Deny Suggestion** | Suppress the same suggestion for the same evidence. |\n| **Dismiss For Now** | Hide it until the evidence changes or the recommendation expires. |\n\nYou can also expose `sensor.\u003ccircuit\u003e_settings_suggestions` if you want a dashboard-visible count of pending recommendations.\n\n## Alerts and evidence\n\nThe analyzer uses two different Home Assistant surfaces:\n\n| Surface | Used for |\n|---|---|\n| **Persistent notifications** | Important repeated evidence about appliance or circuit behavior. |\n| **Repairs** | Setup, source-data, configuration, stale-sensor, CT orientation, or data-quality problems. |\n\nWhen an alert appears:\n\n1. Read the notification and related summary entity first.\n2. Open the entity details.\n3. Review `status_explanation`, observed values, thresholds, sample counts, source entities, and timestamps.\n4. Use the **Open evidence graph** link when available.\n5. Check easy setup causes before appliance causes:\n   - CT direction\n   - Phase pairing\n   - Stale sensors\n   - Wrong units\n   - Missing voltage/current/PF/VA sensors\n   - Wrong appliance type\n   - Wrong circuit mode\n   - Wrong power-flow mode\n6. Use Repairs for configuration and data-quality problems.\n7. If work is planned on an appliance or circuit, use maintenance or pause-alert actions before service begins.\n\nPersistent notifications include a Markdown link to **Open evidence graph** when the analyzer has enough context. The link uses the `evidence_path` attribute and opens the dynamic Alert Evidence panel at `/circuitsetup-energy-analyzer-evidence`.\n\nThe dynamic Alert Evidence panel reads the alert payload, including `graph_entities`, and dynamically selects graph entities for appliance, mains, nilm, weather-context, and energy-overview cards. Companion App notifications can use the same target through `clickAction`.\n\nFor a dashboard-first view of the same concepts, see `docs/dashboard-example.yaml`.\n\n![Home Assistant notification drawer showing a CircuitSetup Energy Analyzer possible-issue notification](docs/images/readme/notifications-panel.png)\n\n![Dynamic Energy Analyzer evidence graph opened from a notification link](docs/images/readme/notifications-repairs.png)\n\n## Alert automation blueprint\n\nThe repository includes a Home Assistant automation blueprint:\n\n```text\nblueprints/automation/circuitsetup_energy_analyzer/energy_alert_notification.yaml\n```\n\nUse it to create persistent notifications or custom follow-up actions when selected analyzer entities report possible issue states.\n\nCompanion App mobile notifications can use the `evidence_path` template variable for `data.url` and Android `data.clickAction`, so tapping the notification opens the same Home Assistant evidence view.\n\n## Practical automations\n\nAutomations can be created from the Home Assistant automation editor. Manual YAML editing is not required for normal setup or advanced circuit settings.\n\nThe examples below show the underlying automation/action structure for users who prefer YAML or want to copy service calls into scripts, blueprints, or Developer Tools.\n\n### Washer finished notification\n\nUse the Running binary sensor for simple appliance-finished notifications.\n\n```yaml\nalias: Washer finished\ntrigger:\n  - platform: state\n    entity_id: binary_sensor.washer_running\n    from: \"on\"\n    to: \"off\"\n    for: \"00:03:00\"\naction:\n  - service: notify.mobile_app_phone\n    data:\n      message: Washer cycle appears finished.\n```\n\n### Pause alerts during service\n\nUse maintenance mode before servicing an appliance, replacing equipment, moving CTs, or making wiring changes that could make analyzer evidence temporarily misleading.\n\n```yaml\naction: circuitsetup_energy_analyzer.start_maintenance\ndata:\n  circuit_id: refrigerator\n  note: Cleaned coils\n  duration: \"02:00:00\"\n  relearn_on_end: false\n```\n\nEnd maintenance and optionally relearn:\n\n```yaml\naction: circuitsetup_energy_analyzer.end_maintenance\ndata:\n  circuit_id: refrigerator\n  relearn: true\n```\n\n### Relearn a circuit baseline\n\nUse this after maintenance, appliance replacement, CT remapping, or any other change that makes the old learned baseline no longer useful.\n\n```yaml\naction: circuitsetup_energy_analyzer.relearn_baseline\ndata:\n  circuit_id: refrigerator\n```\n\n## Optional Developer Tools actions\n\nMost users should configure the analyzer from the Home Assistant UI:\n\n**Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e Advanced Circuit Settings**\n\nThe service actions below are optional. They are useful when you want to call analyzer functions from Home Assistant automations, scripts, dashboards, blueprints, or Developer Tools.\n\n| Purpose | Actions |\n|---|---|\n| Usage and goals | `set_energy_usage_settings`, `set_energy_goal_settings` |\n| Billing, cost, utility comparison | `set_billing_cycle_settings`, `set_cost_settings`, `set_utility_comparison_settings` |\n| Demand and capacity | `set_demand_settings`, `set_capacity_settings` |\n| Dual-phase and electrical checks | `set_leg_imbalance_settings`, `set_metric_consistency_settings` |\n| Mains and solar | `set_mains_balance_settings`, `set_solar_flow_settings` |\n| Appliance behavior | `set_activity_alert_settings`, `set_standby_settings` |\n| Alert handling | `pause_alerts`, `acknowledge_alert`, `mark_alert_expected`, `mark_alert_unhelpful` |\n| Maintenance | `start_maintenance`, `end_maintenance`, `relearn_baseline` |\n| Experimental NILM | `label_nilm_signature`, `ignore_nilm_signature`, `mark_nilm_signature_expected`, `merge_nilm_signatures`, `label_nilm_interval`, `delete_nilm_label_interval`, `generate_nilm_sensor_label_intervals`, `assign_signature_to_appliance`, `assign_session_to_appliance`, `assign_interval_to_appliance`, `validate_nilm_session`, `reject_nilm_session`, `validate_nilm_assignment_history`, `rename_nilm_appliance`, `change_nilm_appliance_profile`, `merge_nilm_assignments`, `publish_nilm_appliance_assignment`, `unpublish_nilm_appliance_assignment`, `retire_nilm_appliance_assignment` |\n| Suggested settings | `recalculate_setting_recommendations`, `apply_setting_recommendation`, `deny_setting_recommendation`, `dismiss_setting_recommendation` |\n| Export and diagnostics | `export_diagnostics`, `export_history_csv`, `run_mapping_checks` |\n\nWhen calling actions manually or from an automation, set `circuit_id` to the configured circuit ID, such as `refrigerator`, `hvac`, `car_charger`, or `mains`.\n\n## Common setup states\n\n| State | Meaning |\n|---|---|\n| `Needs data` | Required source sensors are missing, stale, unavailable, or not producing usable samples. |\n| `Learning` | The analyzer has data but does not yet have enough retained samples or cycles. |\n| `Waiting For Energy Change` | A cumulative kWh sensor exists, but the analyzer has not yet observed a positive energy increase. |\n| `Missing Metrics` | Optional electrical metrics needed for a check are not available. |\n| `Possible issue` | Repeated evidence crossed a configured or learned threshold. Review evidence before making a diagnosis. |\n| Negative watts on a load | Usually export power or reversed CT orientation. Check power-flow mode and CT direction. |\n\nDaily Energy Usage can show `0 kWh` for two different reasons:\n\n1. The circuit truly has not used energy today.\n2. The analyzer is still waiting to observe the first positive increase from the cumulative kWh source.\n\nUse `sensor.\u003ccircuit\u003e_energy_usage_status` and the `status_explanation` attribute to tell the difference.\n\n## Source measurement inputs\n\nThese are the sensors you select during setup. The analyzer does not require every role for every appliance, but additional roles improve the evidence it can produce.\n\n| Source role | Used for |\n|---|---|\n| **Energy** | Daily kWh, billing-cycle usage, goals, utility comparison, Energy Dashboard readiness. |\n| **Active Power / Watts** | Appliance state, demand, cycles, NILM, balance, solar flow, negative-power checks. |\n| **Current** | Capacity checks, dual-phase evidence, metric consistency. |\n| **Voltage** | Metric consistency and current estimation. Split-phase mains L1/L2 voltage can help appliance circuits. |\n| **Frequency** | Line-frequency context from the meter. |\n| **Power Factor** | Motor/load behavior and metric consistency evidence. |\n| **Reactive Power** | Motor, compressor, pump, and power-quality drift evidence. |\n| **Apparent Power** | VA relationship checks with watts and power factor. |\n\nExample source entity names commonly look like this:\n\n| Friendly name | Entity pattern | Purpose | Visibility | Possible outputs |\n|---|---|---|---|---|\n| Energy | `sensor.\u003cappliance\u003e_energy` | Cumulative kWh source used for daily usage, billing, goals, and utility comparison. | Source entity selected by the user. | Increasing kWh total |\n| Active Power | `sensor.\u003cappliance\u003e_active_power` or `sensor.\u003cappliance\u003e_watts` | Instantaneous real power used for activity, demand, NILM, balance, and run-cycle checks. | Source entity selected by the user. | Watts, including signed watts when the meter reports export |\n\nFor single-phase appliances, use one matching set of source entities.\n\nFor dual-phase appliances, use L1/L2 or leg A/B source entities where possible.\n\nFor mains, use aggregate L1/L2 sources.\n\nFor solar inverters, set circuit Power Flow to **Generation / Solar Export**.\n\n## Output entity groups\n\nEntity IDs use your configured circuit ID. For example, a circuit named `refrigerator` may expose entities such as:\n\n```text\nsensor.refrigerator_health_summary\nsensor.refrigerator_activity_summary\nsensor.refrigerator_electrical_health\nsensor.refrigerator_energy_summary\nsensor.refrigerator_daily_energy_usage\nbinary_sensor.refrigerator_running\n```\n\nUse **Entity Detail Level** for normal entity creation: Simple keeps the core summary set, Standard adds configured feature entities, and Expert creates only the selected diagnostic or graph groups. You can still use Home Assistant's entity registry for one-off manual entity changes.\n\n## Compact entity model\n\nThe analyzer uses a compact entity model so Home Assistant gets appliance-focused\nentities instead of every intermediate calculation as a standalone entity.\n\n- **Simple** creates summary entities, Running, Daily Energy Usage when available,\n  and the small daily control set.\n- **Standard** adds canonical status and graph entities for features you configured.\n- **Expert** adds only the diagnostic or graph groups you explicitly select.\n\nSee `docs/entity-model.md` for the full compact model and migration notes.\n\nExisting installs can keep enabled legacy entities for one compatibility release\nso dashboards and automations do not break during upgrade. To migrate explicitly,\nopen **Settings \u003e Devices \u0026 services \u003e CircuitSetup Energy Analyzer \u003e Configure \u003e\nMigrate To Compact Entity Model**. The preview lists entities that will be\nremoved, replacements, entities that will remain, the new maintenance switch,\nbefore/after counts, and any customization warning.\n\nLegacy replacement highlights:\n\n| Legacy replacement | Compact location |\n|---|---|\n| Sensitivity sensor | `select.\u003ccircuit\u003e_alert_sensitivity` |\n| Readiness and learning progress | `sensor.\u003ccircuit\u003e_health_summary` attributes |\n| Data quality checklist | Setup Health, Repairs, and Health Summary attributes |\n| Alert evidence and last event | Dynamic Alert Evidence panel and recent activity |\n| Power-quality evidence and metric/leg status | `sensor.\u003ccircuit\u003e_electrical_health` attributes |\n| Run-cycle status | `sensor.\u003ccircuit\u003e_activity_summary` and `binary_sensor.\u003ccircuit\u003e_running` |\n| Billing and cost forecast/status details | `sensor.\u003ccircuit\u003e_billing_cycle_usage` and `sensor.\u003ccircuit\u003e_cost_cycle` attributes |\n| Standby threshold | Advanced Circuit Settings and `sensor.\u003ccircuit\u003e_standby_status` attributes |\n| Outdoor temperature mirror | configured outdoor temperature source entity and Weather Context attributes |\n| Start/End Maintenance buttons | `switch.\u003ccircuit\u003e_maintenance` |\n\n## Sensor reference\n\nThe analyzer creates entities based on the circuit mode, appliance profile, source sensors, enabled feature settings, and the selected **Entity Detail Level**. Not every circuit will have every entity.\n\nIn the **Visibility** column:\n\n- **Core/default visible** means created in Simple, Standard, and Expert when the circuit has the required source data.\n- **Standard feature entity** means created in Standard and Expert when the related feature, circuit type, and source data apply.\n- **Expert group** means created only when Entity Detail Level is Expert and that Expert Entity Group is selected.\n- **Legacy compatibility** means preserved for existing installs during the compatibility window; new dashboards should use the listed replacement.\n\nIn the patterns below, `\u003ccircuit\u003e` is the configured circuit ID, such as `refrigerator`, `hvac`, `car_charger`, `solar`, or `mains`.\n\n### Core Appliance Status Sensors\n\nStart with these on dashboards.\n\n| Friendly name | Entity pattern | Purpose | Visibility | Possible outputs |\n|---|---|---|---|---|\n| Setup Health / Next Step | `sensor.circuitsetup_energy_analyzer_setup_health` | One integration-level next step for setup, source-data quality, context-source setup, utility comparison setup, and learning readiness. Attributes include `ready`, `issue_count`, `next_step`, `recommended_action`, `affected_circuits`, `stale_sources`, `stale_source_circuits`, grouped issue lists, `open_path`, `reason`, and the full issue list with `circuit_id`, `issue`, `fix`, and `source_entities`. | Core/default visible. | `Ready`, `Review circuit assignments`, `Add cumulative kWh source`, `Fix stale source sensor`, `Check CT direction`, `Let analyzer learn`, `Configure breaker amps`, `Add mains source`, `Add outdoor temperature source`, `Add rain source`, `Add water-flow source`, `Review utility comparison` |\n| Health Summary | `sensor.\u003ccircuit\u003e_health_summary` | One short state for the circuit or appliance. It rolls learning, readiness, data quality, maintenance, and possible issue evidence into one dashboard-friendly value. | Core/default visible for configured circuits. | `Ready`, `Learning`, `Needs data`, `Possible issue`, `Paused`, `Mixed observation`, `NILM review` |\n| Activity Summary | `sensor.\u003ccircuit\u003e_activity_summary` | Human-readable activity state with run-cycle and standby context in attributes. | Core/default visible for configured circuits. | `Running`, `Idle`, `Standby`, `On`, `Off`, `No Activity` |\n| Electrical Health | `sensor.\u003ccircuit\u003e_electrical_health` | Combined electrical condition for power quality, metric consistency, dual-phase balance, mains balance, and solar flow. | Core/default visible for configured circuits. | `Normal`, `Needs Metrics`, `Possible Imbalance`, `Possible Metric Mismatch`, `Possible Power Quality Change` |\n| Energy Summary | `sensor.\u003ccircuit\u003e_energy_summary` | Combined daily usage, goals, billing, cost, and high-usage evidence. | Core/default visible for configured circuits. | `Normal`, `Learning`, `Needs Energy Data`, `Watch`, `High Usage` |\n| Daily Energy Usage | `sensor.\u003ccircuit\u003e_daily_energy_usage` | Today's kWh derived from a cumulative energy source. | Core/default visible when usable energy data exists. | `0.0 kWh` and higher daily totals |\n| Running | `binary_sensor.\u003ccircuit\u003e_running` | Simple appliance-running state for automations. | Core/default visible for appliance circuits with active-power sensors. | `on`, `off` |\n\nDaily Energy Usage can show 0 kWh for two different reasons: true zero usage, or `Waiting For Energy Change` / `waiting_for_delta` when the analyzer has not observed a cumulative kWh increase yet.\n\n### Running Vs Observations Vs Alerts\n\n- Running is the current operating state used for automations.\n- Observation recorded means the analyzer noticed something unusual, but one observation alone is not an alert.\n- Possible issue means repeated evidence crossed the alert threshold.\n\n### Core diagnostic and evidence sensors\n\nThese help explain why a summary changed. They are useful for troubleshooting, automations, and temporary diagnostic dashboards.\n\n| Friendly name | Entity pattern | Purpose | Visibility | Possible outputs |\n|---|---|---|---|---|\n| **Anomaly Score** | `sensor.\u003ccircuit\u003e_anomaly_score` | Numeric summary of current repeated anomaly evidence. | Expert Developer Diagnostics group. | `0.0` when quiet; higher values as evidence accumulates |\n| **Energy Dashboard Status** | `sensor.\u003ccircuit\u003e_energy_dashboard_status` | Whether the configured energy or power source has metadata that Home Assistant's Energy Dashboard can use. | Expert Energy Detail group. | `ready`, `needs_energy_source`, or metadata issue states |\n| **Recent Activity** | `sensor.\u003ccircuit\u003e_recent_activity` | Latest retained start, stop, steady-window, or possible-issue event. Attributes show a bounded preview of up to five recent items; use the evidence panel or diagnostics for the full retained timeline. | Expert Developer Diagnostics group. | `No recent activity`, `start`, `stop`, issue summary text |\n| **Settings Suggestions** | `sensor.\u003ccircuit\u003e_settings_suggestions` | Count of pending advanced-setting recommendations. Attributes show a bounded preview of up to five suggestions with IDs, setting labels, current values, and suggested values. Open Review Suggested Settings or the evidence panel for full evidence and actions. | Expert Developer Diagnostics group. | `0`, `1`, or higher counts |\n\n### Appliance behavior and power-quality sensors\n\nThese are most useful for dedicated appliance circuits such as refrigerators, freezers, HVAC, electric heat, water heaters, ovens, washers, dryers, pumps, EV chargers, motor loads, and resistive loads. Mixed circuits may expose fewer appliance-specific signals.\n\n| Friendly name | Entity pattern | Purpose | Visibility | Possible outputs |\n|---|---|---|---|---|\n| **Power Quality Score** | `sensor.\u003ccircuit\u003e_power_quality_score` | Numeric score for observed voltage, current, PF, VAR, or VA relationship changes. | Expert Electrical Scores group. | `0.0` when quiet; higher values when relationships drift |\n| **Reactive Power Drift** | `sensor.\u003ccircuit\u003e_reactive_power_drift` | Ratio-style drift in VAR behavior compared with the learned baseline. | Expert Power Quality Drift group. | `0.0` or positive drift values |\n| **Apparent Power Drift** | `sensor.\u003ccircuit\u003e_apparent_power_drift` | Ratio-style drift in VA behavior compared with the learned baseline. | Expert Power Quality Drift group. | `0.0` or positive drift values |\n| **Power Factor Drift** | `sensor.\u003ccircuit\u003e_power_factor_drift` | Ratio-style drift in power factor compared with the learned baseline. | Expert Power Quality Drift group. | `0.0` or positive drift values |\n| **Run Cycle Count** | `sensor.\u003ccircuit\u003e_run_cycle_count` | Today's retained start count for cyclic appliances. | Expert Cycle Metrics group. | Integer cycle counts |\n| **Run Cycle Runtime** | `sensor.\u003ccircuit\u003e_run_cycle_runtime` | Today's total active runtime from retained start/stop evidence. | Expert Cycle Metrics group. | Seconds |\n| **Run Cycle Duty Cycle** | `sensor.\u003ccircuit\u003e_run_cycle_duty_cycle` | Percent of today spent active. | Expert Cycle Metrics group. | `0` to `100%` |\n| **Weather Context** | `sensor.\u003ccircuit\u003e_weather_context` | HVAC weather-adjusted activity state. Attributes can include outdoor temperature, temperature bin, observed runtime, duty cycle, expected range, and explanation. | Standard feature entity for HVAC-like circuits when outdoor temperature context is configured. | `No Temperature Source`, `Learning`, `Weather Correlated`, `Above Weather-Adjusted Range` |\n| **Rain Pump Correlation** | `sensor.\u003ccircuit\u003e_rain_pump_correlation` | Pump runtime compared with rain, optional rain intensity, HVAC compressor context, and learned dry-weather runtime. Attributes include rain source, rain activity, compressor context, observed runtime, dry baseline, and explanation. | Standard feature entity for sump pump, water pump, and well pump circuits when a rain source is configured. | `Unconfigured`, `Learning`, `Normal`, `Rain Explained`, `Compressor Explained`, `Weather Explained`, `Possible Excess Pump Activity`, `Possible Missing Pump Activity` |\n| **Water Flow Correlation** | `sensor.\u003ccircuit\u003e_water_flow_correlation` | Boolean water-flow activity compared with mapped water-using appliance runtime. Attributes include flow sources, active-flow minutes, appliance runtime, mismatch minutes, and explanation. | Standard feature entity for water pump, well pump, water heater, and washer circuits when a global or circuit-linked flow sensor is configured. | `Unconfigured`, `Learning`, `Normal`, `Possible Flow Without Load`, `Possible Load Without Flow`, `Possible Sensor Problem`, `Sensor Unavailable` |\n| **Water Flow Mismatch Minutes** | `sensor.\u003ccircuit\u003e_water_flow_mismatch_minutes` | Current minutes of unexplained flow or water-using appliance activity. | Expert Water group. | Minutes |\n| **Metric Consistency Score** | `sensor.\u003ccircuit\u003e_metric_consistency_score` | Largest W/VA/PF consistency mismatch. | Expert Electrical Scores group. | Percentage mismatch |\n\n### Energy usage, goals, billing, and cost sensors\n\nThese require cumulative energy inputs. Use Home Assistant's Energy Dashboard for normal energy history; these entities exist for analyzer evidence, alerts, and per-circuit summaries.\n\n| Friendly name | Entity pattern | Purpose | Visibility | Possible outputs |\n|---|---|---|---|---|\n| **Daily Energy Usage** | `sensor.\u003ccircuit\u003e_daily_energy_usage` | Today's kWh derived from positive cumulative-energy deltas. | Core/default visible when energy data exists. | `kWh` |\n| **Energy Usage Share** | `sensor.\u003ccircuit\u003e_energy_usage_share` | Today's usage as a percent of the learned rolling energy window. | Expert Energy Detail group. | Percentage values |\n| **Energy Usage Status** | `sensor.\u003ccircuit\u003e_energy_usage_status` | Daily kWh tracker state. Use this to tell true zero usage from \"waiting for first kWh increase.\" | Expert Energy Detail group. | `waiting_for_delta`, `learning`, `tracking`, `over_threshold` |\n| **Energy Goal Usage** | `sensor.\u003ccircuit\u003e_energy_goal_usage` | Today's usage as a percent of the configured daily goal. | Expert Energy Detail group. | Percentage values |\n| **Energy Goal Status** | `sensor.\u003ccircuit\u003e_energy_goal_status` | Daily goal tracker state. | Expert Energy Detail group. | `unconfigured`, `tracking`, `near_goal`, `over_goal` |\n| **Billing Cycle Usage** | `sensor.\u003ccircuit\u003e_billing_cycle_usage` | Current billing-cycle kWh for the circuit. | Standard feature entity when billing tracking exists. | `kWh` |\n| **Cost Cycle** | `sensor.\u003ccircuit\u003e_cost_cycle` | Current cycle cost estimate. | Standard feature entity when cost tracking exists. | Numeric cost estimates |\n\n### Demand, capacity, and dual-phase sensors\n\nThese are aimed at high-power circuits such as HVAC, electric heat, water heaters, ovens, dryers, pool pumps, water pumps, sump pumps, EV chargers, mains feeds, and similar loads.\n\nCapacity sensors require either current sensors or real power plus voltage, and a configured breaker or capacity value.\n\n| Friendly name | Entity pattern | Purpose | Visibility | Possible outputs |\n|---|---|---|---|---|\n| **Current Demand** | `sensor.\u003ccircuit\u003e_current_demand` | Current rolling average demand. | Expert Demand and Capacity group. | Watts |\n| **Peak Demand** | `sensor.\u003ccircuit\u003e_peak_demand` | Highest rolling demand observed today. | Expert Demand and Capacity group. | Watts |\n| **Demand Limit Usage** | `sensor.\u003ccircuit\u003e_demand_limit_usage` | Current demand as a percent of a configured demand limit. | Expert Demand and Capacity group. | Percentage values |\n| **Demand Peak Rank** | `sensor.\u003ccircuit\u003e_demand_peak_rank` | Rank of the current rolling demand among retained monthly peak windows. | Expert Demand and Capacity group. | `0` when unavailable; integer ranks such as `1`, `2`, `3` |\n| **Demand Peak Status** | `sensor.\u003ccircuit\u003e_demand_peak_status` | Whether current demand is notable for the month. | Expert Demand and Capacity group. | `unavailable`, `below_monthly_peak`, `near_monthly_peak`, `monthly_peak` |\n| **Demand Status** | `sensor.\u003ccircuit\u003e_demand_status` | Demand tracker state. | Expert Demand and Capacity group. | `unconfigured`, `tracking`, over-limit evidence states |\n| **Circuit Capacity Usage** | `sensor.\u003ccircuit\u003e_capacity_usage` | Current amps as a percent of configured circuit capacity. | Standard feature entity when capacity is configured. | Percentage values |\n| **Circuit Capacity Status** | `sensor.\u003ccircuit\u003e_capacity_status` | Capacity tracker state. | Expert Demand and Capacity group. | `unconfigured`, `missing_current`, `tracking`, `over_limit` |\n| **Leg Imbalance** | `sensor.\u003ccircuit\u003e_leg_imbalance` | Difference between dual-phase legs while the load is meaningful. | Standard feature entity for dual-phase circuits. | Percentage imbalance |\n\n### Mains NILM, balance, solar, and utility comparison sensors\n\nThese apply mainly to whole-home mains circuits, Mains NILM circuits, homes with solar generation, and homes using utility or Opower comparison data.\n\n| Friendly name | Entity pattern | Purpose | Visibility | Possible outputs |\n|---|---|---|---|---|\n| **NILM Discovered Signatures** | `sensor.\u003ccircuit\u003e_nilm_discovered_signatures` | Count of recurring aggregate NILM signatures. | Expert NILM Detail group. | Integer counts |\n| **NILM Unknown Loads** | `sensor.\u003ccircuit\u003e_nilm_unknown_loads` | Count of recurring unknown mains NILM virtual loads. Attributes show a bounded preview of up to five unknown loads with signature ID, display name, likely type, typical watts, confidence, and first seen time. Open the evidence panel for the full review inventory and actions. | Expert NILM Detail group. | `0`, `1`, or higher counts |\n| **NILM Unmatched Load Percentage** | `sensor.\u003ccircuit\u003e_nilm_unmatched_load_percentage` | Share of current aggregate mains power not matched to known loads. | Expert NILM Detail group. | Percentage values |\n| **NILM Topology Status** | `sensor.\u003ccircuit\u003e_nilm_topology_status` | Mains topology evidence for known-load matches. | Expert NILM Detail group. | `no_match`, `topology_match`, `topology_mismatch`, `leg_mismatch` |\n| **Balance Power** | `sensor.\u003ccircuit\u003e_balance_power` | Mains real power minus summed monitored load power. Positive values usually mean unmonitored load; strongly negative values can suggest mapping or sign issues. | Expert Mains and Solar Detail group. | Watts |\n| **Monitored Power** | `sensor.\u003ccircuit\u003e_monitored_power` | Sum of directly monitored non-generation load circuits. | Expert Mains and Solar Detail group. | Watts |\n| **Known Load Share** | `sensor.\u003ccircuit\u003e_monitored_coverage` | Shows how much of current mains power is explained by selected monitored load circuits. Low values usually mean normal unmonitored loads; values over `100%` can indicate CT sign, double-counting, solar/export, or mapping issues. | Expert Mains and Solar Detail group. | Percentage values |\n| **Balance Status** | `sensor.\u003ccircuit\u003e_balance_status` | Mains balance state. | Expert Mains and Solar Detail group. | `missing_mains`, `tracking`, `negative_balance` |\n| **Solar Generation Power** | `sensor.\u003ccircuit\u003e_solar_generation_power` | Instantaneous solar generation. | Expert Mains and Solar Detail group. | Watts |\n| **Solar Site Consumption Power** | `sensor.\u003ccircuit\u003e_solar_site_consumption_power` | Estimated site consumption from solar generation plus signed grid power. | Legacy compatibility; use Solar Flow Status attributes and the evidence panel. | Watts |\n| **Solar Grid Import Power** | `sensor.\u003ccircuit\u003e_solar_grid_import_power` | Current grid import. | Legacy compatibility; use Solar Flow Status attributes and the evidence panel. | Watts |\n| **Solar Grid Export Power** | `sensor.\u003ccircuit\u003e_solar_grid_export_power` | Current grid export. | Legacy compatibility; use Solar Flow Status attributes and the evidence panel. | Watts |\n| **Solar Self Consumption** | `sensor.\u003ccircuit\u003e_solar_self_consumption` | Percent of generated solar consumed on site. | Legacy compatibility; use Solar Flow Status attributes and the evidence panel. | Percentage values |\n| **Solar Powered** | `sensor.\u003ccircuit\u003e_solar_powered` | Percent of current site load powered by solar. | Legacy compatibility; use Solar Flow Status attributes and the evidence panel. | Percentage values |\n| **Solar Flow Status** | `sensor.\u003ccircuit\u003e_solar_flow_status` | Instantaneous solar-flow state. | Expert Mains and Solar Detail group. | `missing_mains`, `missing_generation`, `no_generation`, `importing`, `exporting`, `self_powered`, `inconsistent_export` |\n| **Solar Surplus Power** | `sensor.\u003ccircuit\u003e_solar_surplus_power` | Exported solar available as surplus. | Expert Mains and Solar Detail group. | Watts |\n| **Solar Load Shift Power** | `sensor.\u003ccircuit\u003e_solar_load_shift_power` | Surplus power above the configured load-shift threshold. Attributes show a bounded preview of up to five flexible-load candidates with counts for hidden candidates. | Legacy compatibility; use Solar Surplus Power and the evidence panel. | Watts |\n| **Solar Flexible Load Power** | `sensor.\u003ccircuit\u003e_solar_flexible_load_power` | Current power used by flexible loads such as EV chargers, water heaters, HVAC, or pool pumps. | Legacy compatibility; use load-shift evidence. | Watts |\n| **Solar Flexible Load Coverage** | `sensor.\u003ccircuit\u003e_solar_flexible_load_coverage` | Percent of active flexible-load power estimated to be solar-covered. | Legacy compatibility; use load-shift evidence. | Percentage values |\n| **Solar Load Shift Status** | `sensor.\u003ccircuit\u003e_solar_load_shift_status` | Flexible-load solar support state. Attributes show the same bounded flexible-load candidate preview as Solar Load Shift Power. | Legacy compatibility; use Solar Surplus Status and the evidence panel. | `not_applicable`, `waiting_for_surplus`, `surplus_candidate`, `active_solar_supported`, `active_grid_supported` |\n| **Solar Surplus Status** | `sensor.\u003ccircuit\u003e_solar_surplus_status` | Solar surplus state. | Expert Mains and Solar Detail group. | `missing_mains`, `missing_generation`, `no_generation`, `no_surplus`, `surplus_available`, `high_surplus`, `inconsistent_export` |\n| **Utility Comparison Difference** | `sensor.\u003ccircuit\u003e_utility_comparison_difference` | Difference between measured kWh and utility/Opower kWh. | Legacy compatibility; use Utility Comparison Status attributes. | Percentage difference |\n| **Utility Comparison Status** | `sensor.\u003ccircuit\u003e_utility_comparison_status` | Utility comparison state. | Expert Mains and Solar Detail group. | `unconfigured`, `missing_utility`, `missing_measured`, `tracking`, `mismatch` |\n\n### Standby and Always On sensors\n\nThese apply to non-mains load circuits with real-power data. They are useful for refrigerators, freezers, pumps, HVAC blower circuits, motor loads, electronics, and appliances with known standby behavior.\n\n| Friendly name | Entity pattern | Purpose | Visibility | Possible outputs |\n|---|---|---|---|---|\n| **Always On Power** | `sensor.\u003ccircuit\u003e_always_on_power` | Lowest retained power level in the standby window. | Standard feature entity for non-mains load circuits. | Watts |\n| **Standby Status** | `sensor.\u003ccircuit\u003e_standby_status` | Current standby state. | Standard feature entity for non-mains load circuits. | `learning`, `off`, `standby`, `on` |\n| **Always On Limit Usage** | `sensor.\u003ccircuit\u003e_always_on_limit_usage` | Always-on estimate as a percent of the configured limit. | Expert Standby group. | Percentage values |\n\n### Binary sensors\n\nDiagnostic binary sensors are created for configured circuits. Operational binary sensors appear only when the circuit has the required profile and source data.\n\n| Friendly name | Entity pattern | Purpose | Visibility | Possible outputs |\n|---|---|---|---|---|\n| **Learning** | `binary_sensor.\u003ccircuit\u003e_learning` | On while the circuit is still learning baseline evidence. | Expert Developer Diagnostics group. | `on`, `off` |\n| **Data Quality Problem** | `binary_sensor.\u003ccircuit\u003e_data_quality_problem` | On when the circuit has a current source-data quality issue. | Expert Developer Diagnostics group. | `on`, `off` |\n| **Maintenance** | `binary_sensor.\u003ccircuit\u003e_maintenance` | Legacy diagnostic state for maintenance; use `switch.\u003ccircuit\u003e_maintenance` for normal maintenance control. | Expert Developer Diagnostics group. | `on`, `off` |\n| **Running** | `binary_sensor.\u003ccircuit\u003e_running` | On when watts exceed the appliance running threshold or the cycle analyzer reports `running`. Not created for mixed circuits, Mains NILM, or solar inverter feeds. | Core/default visible for appliance circuits. | `on`, `off` |\n| **Water Flow Mismatch** | `binary_sensor.\u003ccircuit\u003e_water_flow_mismatch` | On when water-flow correlation currently has possible flow/load mismatch evidence. | Standard feature entity for water pump, well pump, water heater, and washer circuits when a global or circuit-linked flow sensor is configured. | `on`, `off` |\n\n## Status Glossary\n\nCommon status values include:\n\n| Display label | Raw status | Meaning |\n|---|---|---|\n| Active Grid Supported | `active_grid_supported` | A flexible load is running, but current solar surplus does not cover it. |\n| Active Solar Supported | `active_solar_supported` | A flexible load is running and appears to be covered by current solar surplus. |\n| Apparent Power Mismatch | `apparent_power_mismatch` | Reported VA does not match the relationship expected from voltage, current, and real power. |\n| Consistent | `consistent` | The available measurements are internally consistent. |\n| Exporting | `exporting` | Signed mains power currently indicates grid export. |\n| High Surplus | `high_surplus` | Solar export is above the configured high-surplus threshold. |\n| Idle | `idle` | The circuit is below the active-load threshold for this check. |\n| Imbalanced | `imbalanced` | Dual-phase leg difference is repeatedly above the warning threshold. |\n| Importing | `importing` | Signed mains power currently indicates grid import. |\n| Inconsistent Export | `inconsistent_export` | Grid export is larger than measured generation; check solar/mains mapping. |\n| Leg Mismatch | `leg_mismatch` | Mains NILM evidence repeatedly points to a different split-phase leg than the assignment. |\n| Metric Mismatch | `metric_mismatch` | One or more power relationships changed beyond tolerance. |\n| Missing Current | `missing_current` | The check needs a current sensor, or enough power and voltage data to estimate current. |\n| Missing Generation | `missing_generation` | Solar-flow checks need at least one generation circuit. |\n| Missing Mains | `missing_mains` | The check needs a mains, whole-home, or aggregate source. |\n| Missing Measured | `missing_measured` | Utility comparison needs a measured kWh source. |\n| Missing Metrics | `missing_metrics` | The check needs more matching voltage, current, real power, apparent power, or power factor sensors. |\n| Missing Utility | `missing_utility` | Utility comparison needs a utility or Opower source. |\n| Mismatch | `mismatch` | The measured value differs from the comparison source beyond tolerance. |\n| Monthly Peak | `monthly_peak` | The current rolling demand is the highest retained monthly demand window. |\n| Near Goal | `near_goal` | Daily energy usage is near the configured goal threshold. |\n| Near Monthly Peak | `near_monthly_peak` | The current rolling demand is near the highest retained monthly demand windows. |\n| Negative Balance | `negative_balance` | Monitored load power is higher than mains power beyond tolerance; check mapping, signs, solar, or CT orientation. |\n| No Activity | `no_activity` | No recent run-cycle activity has been observed. |\n| No Budget | `no_budget` | No billing-cycle budget is configured. |\n| No Generation | `no_generation` | No solar generation is currently being measured. |\n| No Match | `no_match` | No matching NILM event has been observed yet. |\n| No Monitored Circuits | `no_monitored_circuits` | Mains balance needs at least one monitored load circuit. |\n| No Surplus | `no_surplus` | No solar export surplus is currently available. |\n| Not Applicable | `not_applicable` | The check does not apply to the current circuit configuration. |\n| Not Dual Phase | `not_dual_phase` | The check only applies to dual-phase circuits. |\n| Off | `off` | Latest power is below the configured standby threshold. |\n| On | `on` | Latest power is above the standby range. |\n| Over Budget | `over_budget` | Billing-cycle usage is over the configured budget. |\n| Over Goal | `over_goal` | Daily energy usage is over the configured goal. |\n| Over Limit | `over_limit` | The measured value is above a configured limit. |\n| Over Threshold | `over_threshold` | The measured value is above a configured threshold. |\n| Possible Excess Pump Activity | `possible_excess_pump_activity` | Pump activity is above the weather-adjusted expected range. |\n| Possible Flow Without Load | `possible_flow_without_load` | Water flow has been active without matching mapped appliance activity. |\n| Possible Issue | `possible_issue` | Repeated evidence crossed an alert threshold. |\n| Possible Load Without Flow | `possible_load_without_flow` | A mapped water-using appliance appears active without matching water-flow sensor activity. |\n| Possible Missing Pump Activity | `possible_missing_pump_activity` | Rain or HVAC condensate context suggests pump activity may be expected but has not been observed. |\n| Possible Sensor Problem | `possible_sensor_problem` | Flow and appliance evidence conflict in both directions, so the flow sensor or mapping may need review. |\n| Power Factor Mismatch | `power_factor_mismatch` | Reported power factor does not match real power divided by apparent power. |\n| Projected Over Budget | `projected_over_budget` | Current usage projects above the billing-cycle budget. |\n| Ready | `ready` | The analyzer has enough data for this check. |\n| Running | `running` | The circuit is currently above the active-load threshold. |\n| Self Powered | `self_powered` | Solar generation is approximately covering current site load. |\n| Standby | `standby` | Latest power is within the configured standby range. |\n| Surplus Available | `surplus_available` | Solar export is above the configured surplus threshold. |\n| Surplus Candidate | `surplus_candidate` | An idle flexible load could be a candidate while solar surplus is available. |\n| Rain Explained | `rain_explained` | Pump activity is higher than dry baseline and rain context explains the increase. |\n| Compressor Explained | `compressor_explained` | Pump activity is higher than dry baseline and HVAC compressor condensate context explains the increase. |\n| Weather Explained | `weather_explained` | Pump activity is higher than dry baseline and combined rain/HVAC context explains the increase. |\n| Topology Match | `topology_match` | Mains NILM evidence matches the configured circuit mode. |\n| Topology Mismatch | `topology_mismatch` | Mains NILM evidence conflicts with the configured circuit mode. |\n| TOU Peak | `tou_peak` | Current time is inside the configured time-of-use peak period. |\n| Tracking | `tracking` | The analyzer has enough inputs and is tracking this check. |\n| Unavailable | `unavailable` | This check does not have enough retained data yet. |\n| Unconfigured | `unconfigured` | This optional check has not been configured. |\n| Waiting For Energy Change | `waiting_for_delta` | A cumulative kWh source is present, but no positive energy increase has been observed. |\n| Waiting For Surplus | `waiting_for_surplus` | No idle flexible load currently has enough solar surplus. |\n\nFor automations and debugging, status sensors may expose:\n\n- `raw_status`\n- `status_label`\n- `status_explanation`\n\nUse `raw_status` for automations because it is more stable than the display label.\n\n## Recommended workflow\n\n1. Get your meter data into Home Assistant first.\n2. Install CircuitSetup Energy Analyzer.\n3. Select source devices and any extra source entities.\n4. Add mains and outdoor temperature only if you need those features.\n5. Review every circuit assignment before saving.\n6. Start with the four summary entities on dashboards.\n7. Let the analyzer learn.\n8. Use alerts as evidence, not diagnoses.\n9. Tune advanced settings from **Configure \u003e Advanced Circuit Settings** when the evidence shows the defaults do not fit your system.\n10. Use Home Assistant's Energy Dashboard for long-term energy charts and this integration for behavior, data quality, and circuit diagnostics.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcircuitsetup%2Fcircuitsetup-energy-analyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcircuitsetup%2Fcircuitsetup-energy-analyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcircuitsetup%2Fcircuitsetup-energy-analyzer/lists"}