It is possible to alter the behaviour of some integration functions by creating a file called solcast-advanced.json in the Home Assistant configuration directory solcast_solar subdirectory.
This file has a JSON structure of a dictionary containing key/value pairs.
Example:
{
"option_key_one": value,
"option_key_two": value
}
Changes to this file will be detected in near-real time, changing code behaviour. The impact of that changed behaviour may only be seen at forecast or estimated actuals update. For other changes, reload_on_advanced_change can be set to true (see below), so that things like dampening modelling and entity set up can occur on reload.
The impact of not restarting will vary by advanced option, and you are left to decide when the outcome should occur. This is advanced, and you are expected to be advanced about option application. If you're unsure then just set reload_on_advanced_change while testing.
Support for these advanced options will be limited. (Well, "support" for this integration is limited at the best of times. You expect it, yet we are not obliged to provide it; we endeavour to.)
Understand the implication of setting any of these options before reporting any problem, and check that set values are sensible, and if you then need to seek help, clearly outline any problem faced in detail in a discussion. Any value set is logged at DEBUG level, so please include that detail.
These options modify otherwise predictable and well-tested behaviour, so you are wandering into poorly tested/test-it-yourself territory, where enabling DEBUG logging will likely be essential to see what's going on. That said, some of these options are quite well synthetically tested, but others are not at all. No exceptions should arise.
Values are validated for sanity individually, and in conjunction with other options set. Do not raise an issue report should validation fail to catch a weird set up. You broke it. You fix your config, or revert to defaults and reload. Please raise a discussion topic describing the experience, as we do want to know about weird combinations. These are advanced options so it is not "Issue" raising stuff, just for discussion. The maintainers watch discussions with the same attention as they do issues, so any "issue" raised in this context will likely be converted to a "discussion" very quickly anyway.
You are free to raise an issue should a code exception occur after setting an advanced option, and DEBUG logging is mandatory in this circumstance. Exceptions should not happen, and there will be no exception to requiring DEBUG logs in any raised issue. These will not be converted to discussions.
- Automated dampening
- Automated dampening adaptation
- Estimated actuals
- Forecasts
- Granular dampening
- General
Key: "automated_dampening_delta_adjustment_model"
Possible values: integer 0, 1 (default 0)
Allows the selection of different calculations to nudge the base dampening factors closer to 1.0 when forecast generation for an interval is below the recent peak.
Option 0 selects an adjustment based on the logarithmic difference between peak and forecast:
adjusted_factor = base_factor + ((1 - base_factor) * (ln(interval_peak) - ln(interval_forecast)))
Option 1 selects an adjustment based on the squared ratio of forecast and peak:
adjusted_factor = base_factor + ((1 - base_factor) * ((1-(interval_forecast/interval_peak))^2))
Adjusted dampening factors are constrained to lie within the range 0 to 1. The chart below illustrates the behaviour of the two different adjustment calculations for base factors of 0.5 and 0.9.
As the forecast generation decreases in relation to the recent generation peak the logarithmic difference calculation tends to give a higher adjusted factors than the squared ratio calculation. The logarithmic difference calculation will give an adjusted factor of 1.0 for any forecast below around 36% of the peak whereas the adjusted factor from the squared ratio calculation only approaches 1.0 as forecast generation approaches 0.
Key: "automated_dampening_generation_fetch_delay"
Possible values: int 0..120 (default 0)
A number of minutes to delay beyond midnight before generation history is retrieved.
This value must be less than the estimated actual fetch delay option.
If Home Assistant is restarted in the period between midnight and generation being retrieved then retrieval will be rescheduled.
Key: "automated_dampening_generation_history_load_days"
Possible values: integer 1..21 (default 7)
By default, the integration assumes that there will not be generation history available beyond seven days. If Home Assistant is configured with purge_keep_days of a longer period for recorder, then this option may be used to accelerate the time to accuracy for automated dampening results.
This history load occurs when there is no solcast-generation.json present. An integration reload is required after deleting the generation cache file.
Key: "automated_dampening_ignore_intervals"
Possible values: list of strings as "HH:MM" (default [])
Certain intervals of the day can be set to be ignored by dampening, at times when there is no possibility of shading.
A possible use case is to avoid situations where there are many matching estimated actual intervals and a small number of lower older generation intervals that lack an export limiting flag. This can only occur when automated_dampening_no_limiting_consistency is set to true, and may be seen as days get longer towards Summer.
Double quotes are valid JSON format (single quotes are not). Times are specified in local time zone, and must match the format "HH:MM" with one or two digit hour and a minute of either "00" or "30", and be unique in the list.
An example list: ["12:00", "12:30", "13:00", "13:30", "14:00", "14:30", "15:00"]
Key: "automated_dampening_insignificant_factor"
Possible values: float 0.0..1.0 (default 0.95)
Dampening values modelled as higher than a certain threshold are ignored as insignificant.
Key: "automated_dampening_insignificant_factor_adjusted"
Possible values: float 0.0..1.0 (default 0.95)
Dampening values adjusted by delta adjustment as higher than a certain threshold are ignored as insignificant.
Key: "automated_dampening_minimum_matching_generation"
Possible values: integer 1..21 (default 2)
Dampening modelling will skip intervals where there are a low number of matching generation samples for intervals. This is defaulted at two to get a "peak" generation value, but a value of one is also allowed for experimentation.
This value must be less than or equal to the minimum matching intervals or the number of past days considered for automated dampening.
Key: "automated_dampening_minimum_matching_intervals"
Possible values: integer 1..21 (default 2)
Dampening modelling will skip intervals where there are a low number of matching past intervals. A low number of matches are generally seen at the beginning and end of each day, and these are ignored by default.
This value must be greater than or equal to the minimum matching generation, or higher than the number of past days considered for automated dampening.
Key: "automated_dampening_model"
Possible values: integer 0..3 (default 0)
Selects the algorithm to be used to determine automated dampening factors.
Option 0 is the default model described in the documentation. This compares the recent peak estimated actual with the recent peak generation for each interval to calculate a dampening factor. In this model it is possible that the peak estimated actual and peak generation occur on different days.
Options 1 to 3 follow a similar approach to the above, but calculate a list of candidate factors from the paired generation and estimated actual data in each interval, so each candidate factor is calculated from a single day.
- Option
1returns the maximum of the candidate factors. - Option
2returns the mean of the candidate factors. - Option
3returns the minimum of the candidate factors.
Option 1 can be thought of as a most optimistic scenario which will tend to give a higher forecast than Option 2, with Option 3 as the most pessimistic scenario giving the lowest forecast.
Key: "automated_dampening_model_days"
Possible values: integer 2..21 (default 14)
The maximum number of days of past estimated actuals and generation to use for modelling future dampening.
Key: "automated_dampening_no_delta_adjustment"
Possible values: boolean true/false (default false)
If delta adjustment of dampening factors is not desired then this option may be set to true.
Key: "automated_dampening_no_limiting_consistency"
Possible values: boolean true/false (default false)
Default limiting behaviour is that whenever export limiting of generation is seen (either by export limit detection, or manual limiting by using the entity solcast_suppress_auto_dampening) then all of the same intervals of generation will be ignored over the period defined by automated_dampening_model_days, which is 14 by default.
Said another way, the default behaviour is that if there is limiting detected for any interval on any day, then that interval will be ignored for every day of the past fourteen days unless this option is enabled.
Set this option to true to prevent this behaviour.
Key: "automated_dampening_preserve_unmatched_factors"
Possible values: boolean true/false (default false)
Default behaviour when calculating base dampening factors is that any interval with insufficient matching intervals or generation (see automated_dampening_minimum_matching_generation and automated_dampening_minimum_matching_intervals) will have a dampening factor of 1.0. This can be an issue if there is a sustained period of poor solar generation (e.g. a sustained cloudy spell) when previously calculated dampening factors for these intervals may be reset to 1.0 leading to a higher generation forecast until sufficient 'good' intervals are recorded and the dampening factors can be recalculated.
Setting this option to true will retain the previously calculated factor for such an interval, with factors reverting to 1.0 when all recent estimated actuals for the interval are 0.
Key: "automated_dampening_similar_peak"
Possible values: float 0.0..1.0 (default 0.9)
Estimated actual peaks are compared to find a similar number of "matching" peaks from which to compare maximum generation. By default this is intervals within 90% to 100% of peak.
This option varies what is considered a similar interval from all modelled days.
Key: "automated_dampening_suppression_entity"
Possible values: string (default "solcast_suppress_auto_dampening")
A templated suppression entity in the sensor, binary_sensor or switch platform can be used to intentionally ignore intervals of generation. This option allows the entity name searched for to be changed.
Key: "automated_dampening_adaptive_model_configuration"
Possible values: boolean true/false (default false)
Setting this option to true will (in time) choose the combination of dampening model and delta adjustment that resulted in the lowest error between generation and dampened estimated actuals over previous days. The minimum number of days history required is defined by the setting automated_dampening_adaptive_model_minimum_history_days and the maximum number of days is defined by automated_dampening_model_days.
At the end of each day the integration calculates dampening factors for all possible dampening model and delta adjustment combinations and records the results to solcast-dampening-history.json. After updated estimated actuals are retrieved from Solcast the error between generation and dampened estimated actuals is calculated for every allowed combination of dampening model and delta adjustment, as well as for each model with no delta adjustment applied. The most consistently "accurate" configuration of dampening model and delta adjustment is then selected. "Accurate" here means the lowest error rather than a precise match.
This selected dampening configuration is then applied to the forecast and the settings for automated_dampening_model and automated_dampening_delta_adjustment_model are updated in solcast-advanced.json. No other values in solcast-advanced.json are affected, and entries for automated_dampening_model and automated_dampening_delta_adjustment_model will be added if they are not already defined in this file. When first enabling this option you do not need to amend your current settings for automated_dampening_model and automated_dampening_delta_adjustment_model.
When automated_dampening_no_delta_adjustment is true, the algorithm selects the most consistently accurate dampening model from the configurations that do not use delta adjustment. When it is false, the algorithm selects the combination of dampening model and delta adjustment option that are most consistently accurate.
A debug message will be logged whenever the automated_dampening_no_delta_adjustment setting disagrees with the overall best error results. This happens if automated_dampening_no_delta_adjustment is true but a delta adjusted model performs better, or if it is false but a model without delta adjustment achieves a lower error.
There are a number of other advanced options that can and should be used to tune the performance of adaptive dampening model configuration to suit your local conditions. These are described below, please read these carefully and decide on appropriate settings for each before setting automated_dampening_adaptive_model_configuration to true.
Key: "automated_dampening_adaptive_model_exclude"
Possible values: list of dictionaries {model, delta} (default [], with delta optional, model being mandatory)
Setting this option allows the user to specify combinations of dampening model (model) and delta adjustment model (delta) that will be excluded from the adaptive model configuration process. An alternative form of just model key specified will exclude all delta options, otherwise only the specified delta options will be excluded.
Dampening history will still be recorded for these combinations so they can be reinstated at any time. An example of configuration syntax in solcast-advanced.json is:
"automated_dampening_adaptive_model_exclude": [
{ "model": 2 },
{ "model": 3, "delta": 0 },
{ "model": 3, "delta": 1 }
]Can only be defined when automated_dampening_adaptive_model_configuration is true.
Key: "automated_dampening_adaptive_model_minimum_history_days"
Possible values: integer 1..21 (default 3)
Defines the minimum number of days of dampening history required before adaptive model configuration will set values for automated_dampening_model and automated_dampening_delta_adjustment_model.
Must not be greater than automated_dampening_model_days, and can only be defined when automated_dampening_adaptive_model_configuration is true.
Key: "estimated_actuals_fetch_delay"
Possible values: int 0..120 (default 0)
A number of minutes to delay beyond midnight before estimated actuals are retrieved (in addition to a randomised up-to fifteen minute delay). This may be of use should the retrieval of estimated actuals often fail just after midnight local time.
If automated dampening is enabled then modelling of new dampening factors will occur immediately following retrieval.
If Home Assistant is restarted in the period between midnight and estimated actuals being retrieved then retrieval will be rescheduled.
Key: "estimated_actuals_log_ape_percentiles"
Possible values: list[int] (default [50])
By default a 50th percentile Actual Percentage Error (APE) is logged on day change and at startup. Specify alternate or more percentiles to analyse with this option.
Key: "estimated_actuals_log_mape_breakdown"
Possible values: boolean true/false (default false)
A Mean Actual Percentage Error (MAPE) value for estimated actuals vs. actual generation is logged on day change and at startup. Enable this option to also log the daily percentage error (APE).
Both undampened and dampened are logged when automated dampening is enabled.
Note: Totals for both generation and estimated actuals do not include half-hourly intervals that have experienced site export limiting.
Key: "forecast_day_entities"
Possible values: integer 8..14 (default 8)
The number of forecast day entities to create (plus one). By default seven entities are created. Today, tomorrow, day 3, day 4, day 5, day 6 and day 7. This option enables creation of up to a day 13 entity.
An integration reload is required to vary the number of entities. New entities created will be disabled by default, and if this option is reduced then entities will be cleaned up.
This value must be less than or equal to the number of forecast future days.
Key: "forecast_future_days"
Possible values: integer 8..14 (default 14)
The number of days of forecasts to request from Solcast. Setting this lower than 14 will not remove forecasts already retrieved.
Consider the setting of forecast_day_entities when lowering this option.
Key: "granular_dampening_delta_adjustment"
Possible values: boolean true/false (default false)
Implements the option "automated_dampening_delta_adjustment_model" for granular dampening, to enable utilising this mechanism for automation-driven or manual dampening.
Fetching estimated actuals is required.
The adjustment will only apply to ALL factors, and not individual per-site dampening, which is in line with how automated dampening operates.
Key: "allow_exceed_api_limit_maximum"
Possible values: boolean true/false (default false)
The maximum configurable API limit is 50 by default. This value represents the maximum number of metered API calls that any Solcast hobbyist user has ever been able to make.
Do not set this option unless you are a developer and want to utilise the Solcast API Simulator, where a much larger available limit is possible.
Key: "api_raise_issues"
Possible values: boolean true/false (default true)
If repeated 429 / Try again later errors are received from Solcast that exhaust ten consecutive retries then the integration will raise an ignorable issue to alert that there has been an update failure. (You may hear this situation referred to as a '429 storm', as subsequent updates will also likely fail until Solcast staff intervene.)
This behaviour may be suppressed by setting this option to false.
Key: "entity_logging"
Possible values: boolean true/false (default false)
By default the value set in entities is not logged. This option enables that at DEBUG level.
An integration reload is required.
Key: "history_max_days"
Possible values: integer 22..3650 (default 730)
The number of days of history to retain for forecasts and estimated actuals.
There may be a performance implication when too much history data is retained, depending on the platform used for Home Assistant.
Key: "log_update_failure_only"
Possible values: boolean true/false (default false)
By default logging of forecast and estimated actuals attempts produces WARNING level messages for update retries, with a final ERROR message on complete failure. By setting this option to true the integration will log intermediate DEBUG level retry messages instead of WARNING level, and will conclude with a final WARNING that the update has not been successful should all retries fail.
Key: "reload_on_advanced_change"
Possible values: boolean true/false (default false)
Setting this option to true will cause the integration to reload whenever any advanced option is added or changed.
Key: "solcast_url"
Possible values: string URL (default "https://api.solcast.com.au")
Do not set this option unless you are a developer and want to utilise the Solcast API Simulator.
Do not add a trailing /. An integration reload is required.
Key: "trigger_on_api_available"
Possible values: string (default "")
When API availability has been determined (after a period of unavailability) then trigger the friendly name of an automation.
Key: "trigger_on_api_unavailable"
Possible values: string (default "")
When API unavailability has been determined then trigger the friendly name of an automation.
Key: "user_agent"
Possible values: string (default "default")
The HTTP header User-Agent is set to "ha-solcast-solar-integration/x.x.x" by default. This advanced option allows it to be set to another user agent string.