Grid Lens requires Home Assistant 2024.1 or later with the following already working:
Solar, battery, and EV sensors are optional but unlock more accurate modelling.
Add the Grid Lens repository to HACS as a custom repository:
https://github.com/dankasak/gridlens with category IntegrationCopy the custom_components/grid_lens folder from the GitHub repo into your HA config/custom_components/ directory, then restart.
After restarting, go to Settings → Devices & Services → Add Integration and search for Grid Lens.
Setup is four short screens:
If your Energy dashboard lists individual appliances, you'll also get a screen to pick which of them can be shifted to cheaper hours, and set each one's maximum power.
Everything else — controlled load, allowed run hours, modulating charger control, battery efficiency and charge limits — has a sensible default and can be changed later under Grid Lens → Configure. Nothing you skip at setup is lost.
Grid Lens adds a Grid Lens dashboard to your Home Assistant sidebar automatically — no cards to add, no YAML. It has three views:
The cards find their own entities, so they keep working as you add, remove, or reconfigure loads.
Grid Lens needs at least one of the following entity types, already configured in your Energy dashboard:
| Sensor type | Required? | Notes |
|---|---|---|
| Grid consumption (kWh) | Required | Total energy drawn from grid |
| Grid export (kWh) | Optional | Needed for feed-in tariff modelling |
| Solar production (kWh) | Optional | Enables solar self-consumption analysis |
| Battery charge / discharge (kWh) | Optional | Enables battery optimisation |
| EV / deferrable load (kWh) | Optional | Enables load-shifting recommendations |
A deferrable load is electricity usage you can shift to a cheaper time of day — for example an EV charger, pool pump, hot water system, or air conditioner.
To include a deferrable load in the optimisation, you need a sensor that measures its consumption. Grid Lens will model what each plan would cost if you shifted that load to its cheapest window.
Configure deferrable loads under Settings → Devices & Services → Grid Lens → Configure after setup.
No consumption sensor at all for a controllable appliance (common for an IR-remote-controlled aircon)? Grid Lens can estimate one for you — see Estimated loads under Load control below.
Each deferrable load has a weekly schedule — a per-weekday, half-hourly grid of when that appliance is allowed to run. Grid Lens picks the cheapest half-hours inside your rules; it never runs a load outside them.
Edit it on the Allowed Run Times card on the Grid Lens dashboard by painting hours with the mouse. A pool pump might be daytime-only; an EV charger might be unrestricted.
Grid Lens learns how much energy each deferrable load needs per day from its own sensor, averaged over the last 14 days. When today isn't typical — a long drive tomorrow, guests staying — override it with Today Boost on the Deferrable Loads card.
Set the kWh you actually need today; 0 means "use the historical average". The plan re-solves around it immediately.
A small bar chart next to the input shows each device's actual daily use over the last two weeks, with the average of those days beside it — so you can see what "typical" is before deciding how far above it to go.
If you ask for more than the load's allowed window can physically deliver, the card shows you that ceiling rather than silently ignoring the excess.
Comparison and planning are read-only. Battery control is the optional step where Grid Lens actually operates your inverter to follow the plan it found.
Turn on the Battery Control switch. From then on, every five minutes Grid Lens reconciles your battery against the current plan — charging from solar, charging from the grid during genuinely free or cheap windows, holding, or discharging into expensive periods.
Battery control is brand-agnostic by design. Sigenergy is supported today; more inverter drivers are being added.
Grid Lens can also switch simple on/off appliances — anything exposed to Home Assistant as a switch entity that draws roughly a fixed power when running (a pool pump, a smart-plug-fed charger, a resistive heater) — or as a climate entity, so an air conditioner works the same way. Grid Lens only ever decides when it runs, never its mode or target temperature — those stay under your own control.
An EV charger that accepts a charging-current limit is handled differently, and better — see EV chargers below.
Assign a control switch (or climate entity) to a deferrable load via Grid Lens → Configure. Each controllable load then gets its own controls on the Deferrable Loads card:
| Control | Default | What it does |
|---|---|---|
| Control switch | Off | Master opt-in — Grid Lens drives this appliance per the plan. |
| On now / Off now | — | Manual override. Forces the appliance and stops Grid Lens driving it entirely, until you choose Auto. |
| Auto | — | Hands control back to the plan. |
An EV charger is not really an on/off appliance. Most can be told how many amps to deliver, and Grid Lens will use that: instead of slamming the charger fully on or fully off, it dials the charging current up and down to match what the plan wants and what your solar is actually producing right now.
This works with any charger integration that exposes a charging-current limit as a Home Assistant number entity — which is essentially all of them. Known-good shapes include OCPP (number.…_maximum_current), Easee, Wallbox, Zaptec, go-e, openEVSE, Tesla and Sigenergy. Point Grid Lens at that entity under Grid Lens → Configure and it takes over from there; there's no per-brand setup.
| Setting | Default | What it does |
|---|---|---|
| Charging current entity | — | The charger's current-limit number entity. Leave it empty to keep plain on/off control. |
| Units / phases / voltage | Auto | Detected from the entity itself. Only set these if auto-detection gets it wrong. |
| Minimum current | 6 A | The lowest current your car will accept. Rarely needs changing. |
| Plugged-in sensor | — | Optional. Lets Grid Lens stop commanding a charger with no car attached. |
| Max Current | Charger maximum | Your own ceiling — "never charge above 10 A", whatever the plan wants. |
With Greedy Consumption switched on, a modulating charger does something an on/off one can't: it tracks your surplus continuously, every 30 seconds, ramping the current to absorb exactly what you're exporting. An on/off appliance has to wait until the whole of its draw is covered before it can switch on at all. For live surplus tracking you'll also need a grid power sensor configured — without one, the charger simply follows the optimiser's plan instead.
Some controllable appliances have no way to report their energy use at all — the classic case is an air conditioner driven by an infrared blaster, which can only send commands, never read anything back. You can still add these under Grid Lens → Configure → Estimated loads: give it a name, its control entity, and a rough estimate of its power draw in kW.
Turn on auto-refine and point Grid Lens at a whole-house load power sensor, and it will quietly improve that estimate over time: whenever the appliance switches on, it compares your house's power draw just before and a few minutes after (long enough for a compressor to spin up) and folds a plausible reading into a running estimate. It learns from ordinary use — you don't need to do anything for it to collect data — and discards anything that looks unreliable (another controlled device changing state at the same time, an implausible jump). Leave auto-refine off, or skip the load power sensor, and it simply stays on your manual estimate.
Once configured, an estimated load behaves exactly like any other deferrable load — it gets its own schedule, Today Boost, Greedy Consumption, and all the same controls above.
On most solar homes there are hours every day when your battery is full, your panels are still producing, and the surplus goes to the grid for a feed-in tariff of almost nothing. That's free energy leaving the house.
Greedy Consumption lets a load opportunistically run whenever energy is genuinely free, regardless of what the plan scheduled for that moment. Enable it per appliance. There are three triggers:
| Trigger | Fires when | Can it cost money? |
|---|---|---|
| Free import | Your plan's import price for this window is zero. | No |
| Export surplus | Your feed-in price is zero and you're already exporting at least as much as this appliance draws — so running it can't create new grid import. | No |
| Forecast surplus | Over the next few hours the plan expects to spill more free energy than this appliance could use running flat out for that entire window. | Yes — briefly |
The first two only fire once free energy is already flowing. That's often too late: mid-morning your battery absorbs every spare watt, so nothing looks free, even though the plan already knows the afternoon will spill far more than the appliance could ever consume. By the time surplus export actually appears, hours of run-time are gone.
Forecast surplus fixes that by starting the load early. It's a separate opt-in because it's the one trigger that can draw a little priced grid power in the moment, in exchange for capturing a much larger forecast spill — on a house with a battery, that gap gets refilled by energy that would otherwise have been exported for nothing.
The bar is deliberately high: it only fires when the plan would still be wasting free energy even with this appliance running continuously for the whole look-ahead window. A little spare solar never trips it.
The export surplus trigger needs a live signed grid power sensor — positive when importing, negative when exporting — configured as grid_power_sensor under Grid Lens → Configure. Without it that one trigger simply never fires; the other two still work.
Note this is a power (W) sensor, not one of the cumulative kWh sensors from your Energy dashboard.
Anything that acts on your house should be able to explain itself. Every automated decision Grid Lens makes is visible on the dashboard:
The free plan requires no API key — Grid Lens registers your installation automatically and grants access to model your current plan.
A Pro subscription ($1/month) gives you an API key that unlocks all available plans. Enter it under Grid Lens → Configure → API key & connection.
If you remove and re-add the integration, setup will tell you the installation is already registered and ask for your existing key. We only store a hashed copy, so we can't show it to you again — keep it somewhere safe, or email support@gridlens.au from your registered address for a replacement.
Ensure you fully restarted Home Assistant (not just reloaded). Custom integrations require a full restart to register.
Make sure your energy sensors appear in the Energy dashboard first. Grid Lens reads from the same sensor list.
Grid Lens needs at least 24 hours of sensor history to run the LP optimiser. If you've just set it up, check back the following day.
Add to your configuration.yaml:
logger:
logs:
custom_components.grid_lens: debugThen check Settings → System → Logs for grid_lens entries.
Still stuck? Email support@gridlens.au.