Skip to content

About

Priced daily, weekly and monthly solar, battery and grid summaries for Home Assistant

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

30 Commits

Folders and files

Repository files navigation

Solar & Battery reports

A daily, weekly and monthly summary of where your solar, battery and grid energy actually went, and what it was worth, delivered through any Home Assistant notify service.

In Telegram the figures come as tables, each one in a monospace block so the columns line up on a phone:

SOLAR & BATTERY REPORT
Last 24 hours (Mon 2 Nov 19:00 - Tue 3 Nov 19:00)

💷 Total earnings
House load saved  +£2.08
  6.4 kWh at 32.5p
Exported          +£3.92
Battery charging  -£1.88
                  ──────
Earnings           £4.12
  vs £3.91, 7-day average

🧾 Bill
Imported           £2.27
  22.1 kWh at 10.3p
Exported          -£3.92
  14.3 kWh at 27.4p
Standing charge    £0.42
                  ──────
Bill              -£1.23
  vs -£0.87, 7-day average

⚡ Energy
kWh    House  Batt  Grid Total
Solar    1.7   1.4   0.3   3.4
Batt     4.7     –  14.0  18.7
Grid     2.3  19.8     –  22.1
Total    8.7  21.2  14.3

☀️ Solar: generated 3.4 kWh (vs 4.6 kWh, 7-day average) with a power peak of 2.5 kW at 10:40
🔋 Battery: charged 21.2 kWh, discharged 18.7 kWh, full at 11:34
🔄 1.2 cycles (18.7 kWh out of a 15 kWh battery)
🌡️ About 2.8 kWh lost in charging and discharging (round trip about 87%)
🏠 House load: 8.7 kWh (vs 9.1 kWh, 7-day average)
🏠 74% of the house ran on solar & battery

💱 Grid prices
Grid         kWh  p/kWh      £
Import      22.1   10.3   2.27
 house       2.3   16.8   0.39
 battery    19.8    9.5   1.88
Export      14.3   27.4   3.92
 solar       0.3   19.5   0.06
 battery    14.0   27.6   3.86

💹 Bought at 9.5p, sold at 27.6p on average (30.2p in the evening, 17.9p overnight): an 18.1p spread (vs 17.2p, 7-day average)

Every other messaging method gets the same figures as sentences, and so does Telegram if you set its layout to text:

SOLAR & BATTERY REPORT
Last 24 hours (Fri 25 Sep 15:10 - Sat 26 Sep 15:10)

💷 Total earnings
£1.86 house load saved by solar & battery
+£0.55 exported
-£0.14 imported into the battery
= £2.27

☀️ Solar
Generated 13.5 kWh, with a power peak of 3.0 kW at 11:45
4.0 to the house, 7.7 into the battery, 1.8 exported at 12.0p for £0.21

🔋 Battery
Charged 8.5 kWh: 7.7 from solar, 0.8 imported at 16.5p for £0.14
Supplied 6.2 kWh: 3.3 to the house, 2.9 exported at 12.0p for £0.34
Level 94% → 100%: 0.9 kWh stored for later, counted when it's used; 1.4 lost in the battery
Peak charge 100%, first reached at 13:37

🏠 House
Used 7.7 kWh, 95% from solar & battery, 7.3 kWh worth £1.86
4.0 straight from solar, 3.3 from the battery, 0.4 imported at 16.8p for £0.07

⚡ Grid
4.7 kWh exported at 12.0p for £0.55: 1.8 from solar, 2.9 from the battery
1.2 kWh imported at 16.6p for £0.21: 0.4 to the house, 0.8 into the battery

🧾 Bill
Bill total £0.08: £0.21 imported, -£0.55 exported, £0.42 standing charge

That is a real day: solar filling the battery, a cheap overnight top-up from the grid, and the battery selling some back in the evening. Headings are bold in Telegram; other messaging methods get plain text.

Reading the tables

  • Total earnings and Bill: under a money line, its energy and average price (the house load saved, the import and the export); under each total, the same total for the stretch before, to compare with.
  • Energy: each row is where energy came from, each column where it went. Solar's row is what the panels made and where it ended up; the bottom row is what the house used, what the battery took in and what was exported. A dash is a flow that can't happen: the battery doesn't charge itself.
  • Under the Energy table, each line shown only when there's something to say:
    • ☀️ what solar generated, and its power peak (with a solar power sensor)
    • 🔋 what the battery took in and gave out, and when it was full or reached its highest (daily, with a battery level sensor)
    • 🔄 cycles: what the battery supplied, divided by its capacity
    • 🌡️ what was lost charging and discharging, and the round trip efficiency (with the battery capacity and a battery level sensor)
    • 🏠 the house load, and how much of it ran on solar and the battery
  • Grid prices: each import and export at its own average price, split by where it went or came from. The amounts add up to the Bill's lines and to the earnings, to the penny.
  • Under the Grid prices table:
    • 💹 the average price the battery charged from the grid at, against the average it exported at, when it did both. When it sold at two or more times of day at different prices, each is shown, dearest first: "sold at 27.0p on average (30.2p in the evening, 17.9p overnight)". The times of day go by the clock: overnight 00:00-07:00, morning 07:00-12:00, afternoon 12:00-16:00, evening 16:00-19:00 (the peak on most time-of-use tariffs) and night 19:00-24:00. One that carried under a tenth of the battery's export is left out.
    • 🐙 the Octopoints balance and how it moved (weekly and monthly, and on a day when some arrived)

Comparisons ("vs …") sit beside the earnings, the bill, solar, the house load and the spread:

  • a daily report against the average day of the 7 before it;
  • a weekly report against the previous week;
  • a monthly report against the previous calendar month, named, or, for 30 days asked for mid-month, the prior 30 days.

The money and kWh of a daily comparison are averaged over the days the statistics cover, so it starts working a day after installing. A weekly or monthly comparison needs at least 95% of the period before; until then it's left out rather than set against half a week. The spread compared is the whole stretch's, and a daily comparison's standing charge is a day's.

The Energy and Grid prices tables are both 30 characters wide, the width Telegram on a phone shows in portrait, so their blocks line up. Over a month a column widens to fit bigger numbers.

It works with any inverter that exposes lifetime kWh counters. There are no helper entities or utility meters to create and keep in step: everything is read from the long-term statistics Home Assistant already keeps.

What "total earnings" means

What your house's energy would have cost at the rates of the time, minus what you actually paid the grid, net of export income:

Term What it is
house load saved by solar & battery everything the house got from solar and from the battery, each kWh at the import rate in force when it was used
exported everything sold to the grid, solar or battery, at the export rate in force when it went. The solar and battery lines show their share
imported into the battery what was paid to charge the battery from the grid

The house's own grid import ("imported for" on the House line) is shown but is not a term: that energy would have been bought with or without solar and a battery, so it neither adds to nor takes from what they earned.

The Bill is what your supplier charged, not what solar and the battery earned. It is every import, house and battery together, less every export, plus the standing charge if you give one. The standing charge never goes into the earnings: you pay it with or without solar and a battery, so it would only make every day look worse by the same amount. A negative bill means you were paid. The meter hunting around zero (see below) is left out, as it is from every other line, so the Bill can differ from your supplier's by a penny or so a day.

Negative prices, such as those on Octopus Agile, keep each term's meaning and flip its sign: being paid to import reads "+£0.10 imported into the battery".

Every import and export shows its average price, "0.8 imported at 16.5p for £0.14". The price is worked out from the unrounded kWh and money, so it is the true average. The kWh beside it is rounded to 0.1, so multiplying the two out can be a penny or two away from the amount shown.

Every £ adds up the same way the kWh do. Each part is rounded to the penny once and every total is the sum of the rounded parts, so the solar and battery "exported for" amounts always make the export figure exactly.

Battery energy is valued once, when it is used or sold, never when it goes in. Valuing it on the way in as well would count the same kWh twice. So a day that fills the battery earns less than one that empties it, and the value shows up in the report for the day the energy comes back out. The battery's last line says which way it went.

What went in and didn't come out is not all stored. Some of it is lost in the battery: charging, discharging, and holding it full all cost energy. Over a month the level ends near where it began, so nearly all of the difference is loss, and a 15 kWh battery can show 20 kWh more charged than supplied. With a battery level sensor and the battery's capacity, the line splits the two using the level at each end of the period:

Level 94% → 100%: 0.9 kWh stored for later, counted when it's used; 1.4 lost in the battery

or, for a period that ran it down, "ran on 9.4 kWh stored earlier, counted now it's used". Stored, less drawn, plus lost is always charged minus supplied. Losses only ever take away, so if the level and capacity disagree slightly with the counters, the counters win. The level comes from state history while the recorder keeps it, and from the hourly statistics beside each end after that. Without the capacity the line says only "Net +2.3 kWh, stored for later or lost in the battery".

Battery charge and discharge counters normally sit on the battery side of the inverter, so this is loss in the battery itself. The inverter's conversion loss is part of the house load, which is worked out from the counters.

A trade needs no term of its own. Charge at 15p overnight and sell at 30p in the evening: the sale lands in exported, the purchase in imported into the battery, and the difference is the gain. The round-trip loss is already accounted for, because you pay for what went in and earn on what came out. If the two halves fall either side of a daily report's cut-off, the weekly and monthly reports still see the whole trade.

A planner's savings figure is shown but not added. Predbat, for example, measures its savings against the same solar and load with the battery doing plain self-consumption. That figure is the part of the total its decisions made, and those decisions are already in the flows above. Adding it on top would count them twice.

How the energy is split

Every figure is worked out per statistics bucket (five minutes for a daily report), not over the whole period. Over a day the house might use 7.4 kWh while the panels make 9.4 kWh, and those two totals alone can't tell you the battery supplied 4.0 kWh overnight.

In each bucket, house load is what the counters say it must have been: solar + import + discharge − export − charge. Solar serves the house first, then fills the battery, then goes to the grid. The battery covers what solar couldn't, and anything it gave beyond that was exported. Whatever the house still needed came from the grid, and so did any charge solar didn't explain.

Two kinds of noise within a single bucket are kept apart, so they can't pass for real flows:

  • churn: the battery charging and discharging within the same five minutes
  • hunting: the grid meter importing and exporting a few watt-hours as it settles on zero

Left in, churn would show as a grid charge and an export, and hunting would look like the battery selling. In practice each amounts to a few hundredths of a kWh up to about 0.2 kWh a day.

Every line adds up: each total is the sum of the parts printed beside it, and each flow reads the same wherever it appears. Solar's "into the battery" is the battery's "from solar". To guarantee that, each flow is rounded once and every total is built from the rounded parts, so a total can differ from your dashboard by 0.1 kWh.

Install

HACS

Open in HACS

Or add this repository as a custom repository (category: Integration). Then download Solar & Battery reports and restart Home Assistant.

Manually

Copy custom_components/energy_report into your config/custom_components/ folder and restart.

Then go to Settings → Devices & services → Add integration → Solar & Battery reports.

Setting it up

Energy entities

Pick your lifetime kWh counters. Each must be a sensor whose state_class is total or total_increasing, because that's what long-term statistics are built from. A power sensor in watts has no "change" to sum, so the setup form rejects one rather than let the report silently return zeros.

Field Required Notes
Solar generated yes lifetime PV kWh
Grid imported yes
Grid exported yes
Battery charged no leave both battery fields empty and the battery section disappears
Battery discharged no
Solar power no watts, state_class: measurement; adds the peak to the solar line
Battery level no %, a battery-class sensor; adds the peak charge to the daily report, and the start, end and lowest levels to the Telegram highlights
Battery capacity no usable kWh; with the battery level, splits what was stored from what was lost, and adds cycles and losses to the Telegram highlights

There's no house-load field. House load is calculated from the counters above, which keeps it in step with them inside every five-minute bucket.

The battery level gives the daily report a line saying how full the battery got and when: "Peak charge 100%, first reached at 14:05". If it reached that level more than once, the first time counts. A time on the day before the report was sent carries the day, as in the sample above. A battery that was already there as the period began says so, unless it got back there later. The time comes from the recorder's state history, to the minute, rather than from five-minute statistics. Weekly and monthly reports leave the line out: over a week the battery is full on most sunny days, and the first of them says little.

Prices

Point these at whatever holds your live rate: Predbat's predbat.rates and predbat.rates_export (pence), an Octopus rate sensor (pounds), or any tariff sensor. It doesn't have to be a sensor: predbat.rates is in its own domain and gets no statistics at all.

The integration records whatever you pick as Import rate (recorded) and Export rate (recorded). Those are copies of your price entity, and what every report is priced from, five minutes at a time. They are not the fallback.

Choose whether your source reports whole units (0.2635) or hundredths (26.35p).

Prices change on time. A price entity's state only moves when its integration next updates it, which can be minutes after the price does: Predbat's Octopus sensors reached the 16:00 peak export price at 16:05-16:10. Recorded as it stood, that priced the start of every evening export at the old rate, and an hourly report averaged it into the whole hour (25p over one week). When the entity carries its own schedule - a rates list of slots, as Predbat's and the Octopus Energy integration's rate sensors do, or a results list of changes, as predbat.rates does - the recorded price comes from that, on the minute each price starts. Otherwise the entity's state is used.

Free electricity sessions. Octopus's free hours don't appear in its tariff sensors, so a report priced from one values a free hour at the normal rate. Pick a second import price that does know about them, such as Predbat's predbat.rates, under Free sessions from, and the lower of the two is recorded. A free hour is priced at 0. A saving session is not: Predbat adds the reward to its rate, which makes it the higher of the two, so the normal tariff is kept and the reward shows up where it is paid, in Octopoints. The second price's units are read from the entity itself (Predbat's are pence), so it doesn't have to match the tariff's.

Periods from before recording started need a stand-in price. It is chosen in this order:

  1. the price entity's average attribute, if it has one (Predbat does)
  2. the fallback price you configure, if it isn't zero
  3. the average of the prices recorded elsewhere in the same period
  4. the price showing now, only as a last resort

The order matters. A daily report runs in the evening, which on a time-of-use tariff is the peak and can have a saving session on top. On the day that prompted this, the live price read 44p, and three-quarters of a day that really cost 26p was valued at it.

A report that used a stand-in price says so, and for how long:

7 h 45 min of this period had no recorded rate, so that part was priced at an estimated rate.

It appears only when some of the period is from before the rate sensors started recording: daily reports for the first day after installing, weekly ones for the first week, monthly ones for the first month. It also appears if a rate entity was unavailable for a while. Otherwise it doesn't appear at all.

Standing charge (optional)

Only for the Bill. Point it at an entity holding the daily charge, such as Predbat's sensor.predbat_octopus_…_import_standing, or type the number. Its units are set separately from the prices: Predbat's rates are in pence, but its standing charge sensor is in pounds. Each report charges today's figure for the days it covers: one for daily, seven for weekly, the month's length for monthly. If the entity has no number when a report runs, the typed number is used instead. Leave both empty to leave the standing charge out.

Octopoints (optional)

For Octopus customers on Octoplus. Point it at your points balance, such as the octoplus_points sensor from the Octopus Energy integration, and weekly and monthly reports get a section under the Bill:

🐙 Octopoints
1,396 points, worth £1.75, +352 this week

In Telegram's tables they are a line in the highlights instead: "🐙 Octopoints: 1,396 points, worth £1.75, +352 this week".

The balance is the one at the end of the period, valued at Octopus's 8 points to 1p, and the change includes redemptions, which show as a fall. It is read from long-term statistics, so the sensor needs a state class of total, and a monthly report can look a full month back. In the first week or month after adding the sensor, the change only covers the time since its statistics began and says so: "+4 since 2 Oct". Daily reports leave it out, because points land days after the saving session that earned them, except the tables on a day when some arrived: "+352 in the last 24 hours".

Messaging

Method What you pick Format
Telegram the chat entities your Telegram bot created, and/or chat IDs (group chats start with a minus sign) HTML: tables, or bold headings and sentences (the Telegram layout control)
Notify entity one or more notify.* entities, such as your phone's plain text
Notify service a notify.* service by name, such as notify.mobile_app_my_phone (or telegram_bot.send_message, sent as HTML in the Telegram layout) plain text
Don't send nothing; call energy_report.generate and deliver the message yourself

Only Telegram can show the tables, so every other method always gets the sentences. To have Telegram send the sentences as well, set Telegram layout on the device page to text.

The notify service can be changed from the device page by any user, so only notify.* services and telegram_bot.send_message are accepted, both when it is saved and again each time a report is sent.

Schedule

Daily, weekly (Mondays) and monthly (the 1st), each on or off with its own time. The daily report can wait for sunset when sunset falls after your chosen time.

The scheduled monthly report covers the calendar month just gone. A monthly report sent or previewed with a button, or from a service, on any other day than the 1st covers the last 30 full days instead, up to midnight: on 23 October that is 23 September to 22 October, headed "Last 30 days". On the 1st it is the calendar month, the same as the scheduled one.

The comparison uses the sunset time, worked out from your home location, rather than the sun entity's state. sun.sun changes to below_horizon several minutes after the astronomical sunset. That leaves a gap where neither the clock condition nor the sun condition is true, and the report is silently skipped.

The daily window ends on the last five-minute boundary, and the report waits a minute before reading. The recorder takes a few seconds to write each five-minute bucket, and without that pause the last five minutes before each report belonged to neither that report nor the next.

Optional: a planner's savings figure

If you run something that keeps its own arbitrage savings as a running total, point the last three fields of the Prices step at it. The gate is there because a planner that is only watching, or is stopped, hasn't saved you anything. In any state other than the one you set, the report shows zero and says why.

Changing settings later

Settings → Devices & services → Solar & Battery reports → Configure opens a menu that shows what is set now, with an entry for each part: messaging (Telegram, phone, notify), schedule, energy entities, and prices and planner savings. Each one saves on its own. The device page links there too (Visit).

Change an energy entity when you replace a device or picked the wrong one, not routinely. Reports reach back through history, so a weekly report covering a change reads the new counter for the whole week.

The device page has the everyday controls:

Entity What it does
Messaging method Telegram, notify entity, notify service, or don't send
Telegram layout tables (the default) or text: how Telegram gets the report. Other methods always get text
Messaging send to where it goes, comma separated: Telegram chat entities and/or chat IDs, notify entities, or one service name. A bad value is refused with the reason
Daily / Weekly / Monthly report switches that turn each report on or off
Daily / Weekly / Monthly report time when each one goes out
Daily report waits for sunset whether the daily one waits for a later sunset
Send daily / weekly / monthly report now buttons that build and send one straight away
Preview daily / weekly / monthly report buttons that build one without sending it. It appears as a notification in Home Assistant, formatted as it would be sent (tables included), and each new preview replaces the last
Report preview which report was last previewed; its message attribute holds the text
Next daily / weekly / monthly report when each one next goes out, sunset included; unknown while that report is off
Import / Export rate (recorded) the rate the reports are priced from, recorded from your price entity (its recorded_from attribute says which). Not the fallback. Keeps its last price across a restart

Services

energy_report.generate

Returns every figure without sending anything.

action: energy_report.generate
data:
  period: daily
response_variable: report

The response includes message (the sentences), message_tables (the tables Telegram gets, as HTML) and span (the window, as the report names it); the totals solar, house, imported, exported, charged and discharged; each flow (solar_to_house, solar_to_battery, solar_to_grid, battery_to_house, battery_to_grid, grid_to_house, grid_to_battery) and the noise terms (battery_churn, grid_hunting); battery_level_start and battery_level_end (with a battery level sensor); the money (home_value, export_value, house_cost, battery_cost, total_earnings, standing_charge, bill_total, octopoints, octopoints_change, arbitrage); and covered_percent, peak_watts, peak_at, battery_peak_percent, battery_peak_at, battery_low_percent, battery_low_at (daily only; a time is null when the battery was already at that level as the period began), estimated, buckets and unpriced_buckets; and previous, the comparison the tables show (label, total_earnings, bill_total, solar, house, spread), per day for a daily report, or null when there isn't enough of the period before. That's enough to build your own card or message instead.

energy_report.send

Does the same, then sends the message through the configured notify service. Both services accept start and end to override the window. Without them a monthly report follows the same rule as the buttons: the calendar month on the 1st, the last 30 days on any other day.

Resolution

Totals come out the same at any bucket size; the split and the pricing don't. On a half-hourly tariff an hourly bucket only has the hour's average price: the cheap rate starting at 00:30 makes 00:00-01:00 average halfway between the two, and a battery charges in the cheap half. Priced by the hour, a week of that read about 55p a day too dear.

So every report is priced at five minutes wherever it can be:

Period Read from
Daily five-minute statistics
Weekly, monthly and every comparison the hourly record for the hours it holds; five-minute statistics for any hour it doesn't, while the recorder keeps them (purge_keep_days, ten days by default); hourly statistics only before that

The hourly record is kept by the integration itself. A couple of minutes past every hour, once that hour's five-minute statistics are in, it splits and prices them the way a daily report does and adds the hour's flows and money to statistics of its own, energy_report:<entry id>_<field>. Home Assistant keeps those for good, so a month from a year ago adds up the way its days did. They are external statistics, so there are no extra entities; they start as far back as the five-minute statistics went when you installed 1.8.0, are rebuilt from what's still kept if you point the integration at different energy sensors, and go when the integration is removed. They grow by 23 rows an hour.

Testing

python3 tests/test_report.py

No Home Assistant install needed. The tests cover the split and the pricing, check that every counter balances across 5,000 random buckets, and parse every kWh out of rendered messages to confirm each line adds up.

pip install pytest-homeassistant-custom-component voluptuous-serialize
python3 tests/test_config_flow.py
python3 -m pytest

These need Home Assistant. The first builds every setup and Configure form with Home Assistant's own selector code. A selector setting Home Assistant rejects only fails when the form is built, which the user sees as "Unknown error occurred". The second runs setup, the Configure menu, the device-page entities and each delivery method against a real Home Assistant instance.

Licence

MIT.

About

Priced daily, weekly and monthly solar, battery and grid summaries for Home Assistant

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages