Smart Forecast Solar

A Home Assistant custom integration that enhances forecast.solar forecasts with machine learning. Learns from historical forecast accuracy and automatically adjusts future predictions.

Overview

Smart Forecast Solar is a companion integration to forecast.solar that:

• Mirrors all forecast.solar sensors with _adjusted suffix
• Learns forecast accuracy patterns from historical InfluxDB data
• Applies learned corrections automatically to future forecasts
• Provides adjusted forecasts to the Home Assistant energy dashboard
• Shows forecast vs actual comparisons in dashboard

Features

• Self-learning: Analyzes last 30 days of forecast vs actual data
• Hour-of-day patterns: Learns that forecasts are typically off by X watts at specific hours
• Persistent learning: Learned patterns survive Home Assistant restarts
• Dual confidence tracking: Separate sensors show baseline vs adjusted prediction accuracy
• Energy dashboard integration: Replaces official forecasts with learned ones
• Transparent adjustments: All sensors show original value + adjustment in attributes
• Validation tools: Monitor if learning is helping or hurting predictions

Requirements

• Home Assistant 2024.3+
• forecast.solar integration installed and configured
• InfluxDB integration installed and configured with historical sensor data
  • Required for storing and querying forecast vs actual data
  • Works with InfluxDB v1.x (InfluxQL)
  • Recommended: InfluxDB addon v5.0.2+
• Python 3.13+ (for development)

Installation

Prerequisites: InfluxDB Setup

Before installing this integration, you must have InfluxDB configured:

1. Install InfluxDB:

   • Home Assistant OS/Supervised: Install InfluxDB addon from Add-on Store
   • Other installations: Install InfluxDB integration

2. Configure InfluxDB to store sensor data:

   influxdb:
     host: localhost  # or addon hostname
     port: 8086
     database: home_assistant
     username: !secret influxdb_username
     password: !secret influxdb_password
     include:
       entities:
         - sensor.solar_production_hourly_actual  # Your actual production sensor
         - sensor.energy_next_hour  # forecast.solar sensor
   

3. Wait for historical data: InfluxDB needs at least a few days of historical data for learning to work effectively. Initial learning runs automatically 30 seconds after startup if no patterns exist.

Integration Installation

HACS (Recommended - when published)

1. Open HACS
2. Go to Integrations
3. Search for "Smart Forecast Solar"
4. Click Install

Manual

1. Copy custom_components/smart_forecast_solar to your HA config directory
2. Restart Home Assistant
3. Go to Settings → Devices & Services → Add Integration
4. Search for "Smart Forecast Solar"

Configuration

Via UI (Recommended)

1. Go to Settings → Devices & Services
2. Click "+ Add Integration"
3. Search for "Smart Forecast Solar"
4. Follow the setup wizard:
   • Select your InfluxDB connection
   • Choose actual production sensor
   • Optionally choose a 15-minute actual production sensor (see below)
   • Set learning parameters

Via YAML (Optional)

smart_forecast_solar:
  actual_production_sensor: sensor.solar_production_hourly_actual
  learning_lookback_days: 30
  learning_update_time: "03:00:00"

Quarter-hour (15-min) learning (optional, advanced)

In addition to the hour-of-day corrections above, the integration can learn a finer-grained correction per 15-minute slot. This is off by default and has no effect on any existing sensor until configured.

To enable it, set actual_production_sensor_quarter to the entity ID of a production sensor that resets every 15 minutes (the existing hourly sensor cannot be reused here — it only resets on the hour, so grouping it into 15-minute windows would return mid-accumulation values, not quarter totals). You will likely need to create this sensor yourself (e.g. a trigger-based template sensor sampling instantaneous power every 15 minutes) if one doesn't already exist in your setup.

Learned quarter-hour patterns are exposed via LearningEngine.get_correction_factor_for_quarter_timestamp() for other integrations to consume; they are not yet wired into any _adjusted sensor.

Sensors Created

Adjusted Forecast Sensors

The integration mirrors all forecast.solar sensors with adjusted values:

Original Sensor	Adjusted Sensor	Description
sensor.energy_current_hour	sensor.energy_current_hour_adjusted	Current hour production forecast
sensor.energy_next_hour	sensor.energy_next_hour_adjusted	Next hour production forecast
sensor.energy_production_today	sensor.energy_production_today_adjusted	Today's total forecast
sensor.energy_production_today_remaining	sensor.energy_production_today_remaining_adjusted	Remaining today
sensor.energy_production_tomorrow	sensor.energy_production_tomorrow_adjusted	Tomorrow's forecast
sensor.power_production_now	sensor.power_production_now_adjusted	Current power
sensor.power_production_next_hour	sensor.power_production_next_hour_adjusted	Next hour power

Confidence Sensors

Track prediction accuracy to validate learning effectiveness:

Sensor	Unit	Description
sensor.smart_forecast_solar_baseline_confidence	%	Accuracy of raw forecast.solar predictions vs actual
sensor.smart_forecast_solar_adjusted_confidence	%	Accuracy after applying learned patterns

Usage: Compare baseline vs adjusted confidence to see if learning is helping:

• Adjusted > Baseline: Learning is improving predictions ✅
• Adjusted < Baseline: Learning is making things worse ⚠️
• Adjusted = Baseline: No patterns learned yet (first run)

Sensor Attributes

Each adjusted sensor includes:

• official_value: Original forecast.solar value
• adjustment_w: Correction applied (in watts)
• adjusted_value: Final calculated value after adjustment
• baseline_confidence: Raw forecast.solar accuracy (0-1)
• adjusted_confidence: Accuracy with learned patterns (0-1)
• confidence: Same as adjusted_confidence (backwards compatibility)
• days_of_training: Number of days of historical data
• learning_status: Current learning state
• last_update: Timestamp of last pattern update

Usage

In Automations

Battery charging with confidence check:

- alias: "Battery Charging Decision"
  trigger:
    - platform: state
      entity_id: sensor.energy_next_hour_adjusted
  condition:
    - condition: template
      value_template: "{{ states('sensor.energy_next_hour_adjusted') | float > 0.5 }}"
    - condition: numeric_state
      entity_id: sensor.smart_forecast_solar_adjusted_confidence
      above: 80  # Only trust predictions with >80% confidence
  action:
    - service: switch.turn_on
      target:
        entity_id: switch.battery_charger

Alert if learning is making predictions worse:

- alias: "Learning Performance Alert"
  trigger:
    - platform: state
      entity_id: sensor.smart_forecast_solar_adjusted_confidence
  condition:
    - condition: template
      value_template: >
        {{ states('sensor.smart_forecast_solar_adjusted_confidence') | float <
           states('sensor.smart_forecast_solar_baseline_confidence') | float }}
  action:
    - service: notify.mobile_app
      data:
        message: "Smart Forecast Solar learning may need review - adjusted confidence is lower than baseline"

In Energy Dashboard

The integration automatically provides adjusted forecasts to the energy dashboard - no configuration needed!

In Custom Cards

Forecast comparison:

type: history-graph
title: "Forecast Accuracy"
hours_to_show: 24
entities:
  - entity: sensor.energy_next_hour
    name: "Official"
  - entity: sensor.energy_next_hour_adjusted
    name: "Adjusted (Learned)"
  - entity: sensor.solar_production_hourly_actual
    name: "Actual"

Confidence trend monitoring:

type: history-graph
title: "Learning Performance"
hours_to_show: 168  # 7 days
entities:
  - entity: sensor.smart_forecast_solar_baseline_confidence
    name: "Baseline (forecast.solar)"
  - entity: sensor.smart_forecast_solar_adjusted_confidence
    name: "Adjusted (with learning)"

How It Works

1. Data Collection: Every hour at :58, stores the current forecast to InfluxDB
2. Comparison: Next hour at :05, compares stored forecast vs actual production from InfluxDB
3. Learning: Daily at 03:00, queries InfluxDB for last 30 days of forecast vs actual data
4. Pattern Detection: Calculates mean error by hour-of-day (0-23)
5. Persistence: Saves learned patterns to .storage/smart_forecast_solar.learning_patterns
6. Application: Applies learned corrections to all forecast.solar forecasts in real-time

Data Storage

All historical forecast and actual production data is stored in InfluxDB, not Home Assistant's recorder:

• Forecast storage: Uses InfluxDB measurement smart_forecast_solar_stored_forecast
• Actual data: Reads from your existing InfluxDB sensor measurements
• Retention: Queries last 30 days (configurable) from InfluxDB for learning
• Learned patterns: Persisted to .storage/smart_forecast_solar.learning_patterns (survives restarts)
• No recorder dependency: Works independently of Home Assistant's SQLite/PostgreSQL recorder

Development

See DEVELOPMENT.md for development setup, testing, and contribution guidelines.

Architecture

See DESIGN.md for complete architecture documentation.

License

MIT License - see LICENSE file

Credits

• Built as a companion to the excellent forecast.solar integration
• Developed for use with Advanced Battery Strategy

Support

• Issues: GitHub Issues
• Forum: Home Assistant Community