DOCSEARCHbyAlgolia
Submit Docs

Solcast PV Solar Forecast for Home Assistant

repository·main·Indexed 19 days ago

https://github.com/bjreplay/ha-solcast-solar

A Home Assistant custom component that integrates Solcast PV solar forecasts. It enables solar forecast visualization in the Energy dashboard and provides sensors for predicted solar production, including 50%, 10%, and 90% estimates. Key features include forecast dampening for shading, hard limits for over-sized PV systems, multi-site support, and detailed 30-minute and hourly forecast attributes for automations.

Tokens
21.7K
Snippets
34
Records
77
Agent score
64%

What's inside ha-solcast-solar

  1. Overview of HA Solcast PV Solar Forecast Integration

    main

    The ha-solcast-solar integration brings Solcast PV solar forecasts into Home Assistant. It enables solar forecast visualization in the Home Assistant Energy dashboard and provides a comprehensive set of sensors and configuration entities.

    Key features include:

    • Energy Dashboard Support: Visualizes solar forecasts and can display either past forecasts or "estimated actual" data.
    • Forecast Dampening: Allows for flexible dampening of forecasted values to account for predictable shading.
    • Hard Limits: Supports applying a hard limit for over-sized PV systems to ensure expected generation does not exceed inverter maximum ratings.
    • Detailed Sensor Attributes: Provides full forecast details (30-minute and hourly intervals) via sensor attributes for use in automations and custom visualizations.
    • Multi-site Support: Can combine forecasts from multiple Solcast 'rooftop sites' (up to two for free hobbyist accounts) into single integration sensor values.

    Note: This integration is a replacement for the deprecated oziee/ha-solcast-solar. Installing this over the old version preserves history and configuration. If you uninstalled the old version first, you must re-select Solcast Solar as the forecast source in your Energy dashboard settings.

  2. Understand sensor update behavior and performance

    main

    The integration optimizes sensor updates by splitting them into two groups:

    1. High-frequency sensors: Updated every 5 minutes (e.g., forecast_remaining_today, now/next hour sensors).
    2. Daily value sensors: Updated only when data is refreshed or the date changes.

    Note: forecast_remaining_today is updated every 5 minutes by calculating the remaining energy from the current 30-minute interval.

  3. How Solcast forecast estimates work

    main

    Solcast provides three different solar generation estimates for every half-hour period across the forecasted days. The integration exposes these as follows:

    • estimate: The 'central' or 50% most likely forecast.
    • estimate10: The '10%' or 1 in 10 'worst case' forecast (assuming more cloud coverage).
    • estimate90: The '90%' or 1 in 10 'best case' forecast (assuming less cloud coverage).

    Detailed breakdown of these estimates (including 30-minute daily intervals and calculated hourly intervals) is available within the sensor attributes. The integration typically references Solcast sites by their 'site resource ID', which can be found at the Solcast Toolkit.

  4. Understand Solcast API usage and quota consumption

    main

    The integration performs several types of API calls, some of which consume your Solcast API quota and some of which do not.

    Calls that DO NOT use quota:

    • Gathering Rooftop Sites: Occurs on first setup and every reload. This is used to retrieve rooftop IDs and metadata (location, azimuth, etc.).
    • Integration Startup/Restart: Loading cached forecast history or site data from local files does not use quota.

    Calls that DO use quota:

    • Fetching Forecasts: Triggered by auto-updates or the solcast_solar.update_forecasts service call.
    • Fetching Estimated Actuals: Occurs on new installs, if the solcast.json cache is deleted, or if the integration has been disabled for over a week (to fill data gaps).
    • Updating Estimated Actuals: Occurs automatically just after midnight local time or when requested via an action.

    Important Configuration Note: If you have a specific API limit (e.g., 50 calls), ensure this is correctly set in the integration configuration. If it is set incorrectly (e.g., to 10), the integration will artificially limit its own calls.

  5. Understand Solcast Azimuth Convention

    main

    Solcast uses a specific azimuth numbering convention based on degrees pointed away from North (0°). This differs from many mapping services that use degrees pointed away from South.

    Azimuth Rules:

    • Westerly facing: Use a positive value from 0 to 180.
    • Easterly facing: Use a negative value from 0 to -179.
    • North: 0°.

    Important Notes:

    • Hemisphere Difference: If you are in the Northern Hemisphere, be careful with online mapping tools that use South-based orientation. A Solcast configuration of North-facing in the Northern Hemisphere might be flagged as 'unusual' by the integration because it is not directly facing the sun. If you have confirmed your settings are correct, you can ignore these warnings in the Home Assistant logs.
    • Verification: You can verify your azimuth using the Solcast Toolkit or by checking the azimuth and direction attributes in the rooftop site sensor provided by this integration.

  6. Best practices for Solcast API polling

    main

    To reduce impact on the Solcast backend, Solcast requests that users avoid polling services at the exact same time (e.g., exactly at 10:00).

    Recommendation: When setting up automations to poll for data, use a random minute and second offset. For example, instead of polling at 10:00:00, set your automation to trigger at 10:04:10.

  7. How automated dampening works

    main

    Automated dampening is a dynamic feature that adjusts solar forecasts to account for shading. It compares actual generation history with Solcast's "estimated actual" generation (a best-guess of what should have been generated on sunny days) over a rolling 14-day period.

    Key Mechanics:

    • Comparison: It identifies periods where actual generation is consistently lower than the estimated actual, suggesting shading (e.g., from trees or buildings).
    • Normalization: It adjusts for sun geometry (sunrise/sunset arcs) to ensure fair comparisons across seasons.
    • Cloud Adaptation: It uses a logarithmic difference calculation so that if a forecast is already significantly lower than the historical "best" (indicating heavy cloud cover), the dampening factor is reduced (moved closer to 1.0) to avoid over-correcting.
    • Scope: By default, automated dampening applies the same factors to all rooftop sites based on total location generation.

    Important Constraints:

    • API Usage: Enabling this requires an additional API call per configured rooftop site per day to fetch "estimated actual" data.
    • Data Requirements: It requires a minimum of 14 days of history to build an accurate model. When first enabled, it may not model factors immediately until the next midnight update.
    • Conflicts: When automated dampening is enabled, you cannot manually set dampening factors via service actions, integration options, or the solcast-dampening.json file.

  8. Understand the difference between Watt, Watt-hour, and kWh sensors

    main

    The integration provides different sensor types based on how the data is processed from Solcast's raw output:

    • Watt (W): Represents instantaneous power. These are the raw values received from Solcast, representing the expected power at a specific point in time (or an average for a half-hourly interval).
    • Watt-hour (Wh) / kilo-Watt-hour (kWh): Represents energy (power over time). These are calculated by the integration by summing the half-hourly power intervals and adjusting for the time period (e.g., dividing by two because intervals are half-hourly).

  9. How forecast data and history are managed

    main

    The integration manages solar forecast data using the following logic:

    • Forecast Range: Produces forecasts from today through up to 13 days into the future (14 days total). The first seven days are exposed as separate sensors representing total predicted daily generation.
    • Data Storage: Forecast history is not stored as Home Assistant statistics. Instead, it is maintained in a json cache file managed by the integration. Data is retained for up to two years.
    • Energy Dashboard Display: You can choose to display either past forecasts or "estimated actual" data in the Energy dashboard. "Estimated actual" data is generally more accurate as it uses high-resolution satellite and weather observations.
    • Data Manipulation: Forecasted values can only be manipulated via two mechanisms:
      1. Dampening: Setting factors for hourly or half-hourly periods to account for shading.
      2. Hard Limits: Setting a maximum generation cap for over-sized arrays.

  10. Completely remove the Solcast PV Forecast integration

    main

    To perform a total removal of the integration, follow these steps to ensure both the configuration and the cached data are deleted:

    1. Delete the Integration via UI: Navigate to Settings | Devices & Services | Solcast PV Forecast. Click the three dots next to the gear icon and select Delete. This resets the configuration settings.
    2. Remove Data Caches: The integration stores forecast information in JSON files. To prevent a re-installation from reusing old cached data, delete these files. They are typically located in your Home Assistant configuration folder (e.g., /config/solcast_solar or /homeassistant/solcast_solar).
    3. Remove Integration Code: Delete the custom component folder located at /config/custom_components/solcast_solar to remove the integration files entirely.
    # Example commands to remove caches and code (adjust paths as necessary)
rm /config/solcast_solar/solcast*.json
rm -rf /config/custom_components/solcast_solar

  11. Exclude Solcast sites from totals and Energy dashboard

    main

    You can exclude specific Solcast sites from the combined sensor totals and the Home Assistant Energy dashboard forecast. This is useful if you want a "main" site to represent your primary household forecast while visualizing "remote" sites separately using template sensors and Apex charts.

    Setup:

    1. Open the integration CONFIGURE dialogue.
    2. Select the sites you wish to exclude.
    3. Click SUBMIT.

    Note: Site names and resource IDs are loaded at startup. If you add a new API key, you must restart Home Assistant before you can select sites from that new account to exclude.

  12. Prepare Solcast API and Site Requirements

    main

    Before configuring the integration, ensure you have completed the following steps with Solcast:

    1. Obtain an API Key: Sign up at solcast.com. Note that account creation may take up to 24 hours.
    2. Configure Rooftop Sites: Set up your sites correctly in the Solcast dashboard.
    3. Remove Sample Sites: You must remove any sample sites from your Solcast dashboard. Failure to do so may cause a configuration error: Error Exception in __sites_data(): 'azimuth' for API key.
    4. Verify Azimuth: Ensure your site's azimuth is correct. Incorrect azimuth can shift forecasts by up to an hour.