Solcast

Solcast

Solcast is a commercial service that forecasts how much your specific roof will generate. It is optional — and it is the one part of this otherwise entirely local system that talks to the internet.

Do you need an account?

Only if you want the Forecasted charge mode. That mode replaces the simple "wait until the home battery is full" gate with a forecast-driven plan for the day, so the car can start charging well before the battery fills — because the plan knows the sun is still coming.

Without Solcast	With Solcast
Off, Solar and FastNoBattery all work normally. The worker logs a warning at startup and skips forecast refreshes. Nothing else is affected.	Forecasted becomes usable, along with the day-plan sensors: plan state, charge window, EV energy budget, projected shortfall, required SOC floor, tomorrow's forecast and forecast accuracy.

So: skip it entirely if you only ever want surplus-following behaviour. Set it up when you want the controller to plan the day rather than react to it.

Creating the account

Solcast offers a free tier aimed at home users — usually called the hobbyist or home-user plan. The sign-up produces the two values the controller needs.

1. Register at solcast.com. Pick the free home-user tier. Commercial plans exist and are not needed here.

2. Define your rooftop site. Create a rooftop site describing your installation — location, panel tilt, azimuth (orientation), and installed capacity in kW. The forecast is only as good as these numbers, so take them from your actual installation rather than estimating.

3. Copy the resource id and API key. The saved site has a resource id identifying that rooftop. Your API key comes from your account settings and is a secret — it is not site-specific and should never be committed.

Configuring it

Non-secret settings live in appsettings.json. The API key never does.

"Solcast": {
  "BaseUrl": "https://api.solcast.com.au/",
  "ResourceId": "your-solcast-resource-id",  // rooftop site id
  "RefreshInterval": "03:00:00"              // hh:mm:ss between refreshes
}

In Docker, supply both through the environment:

SOLCAST_API_KEY=<your-api-key>
SOLCAST_RESOURCE_ID=<your-rooftop-site-id>

# or directly, using the config-section convention
Solcast__ApiKey=<your-api-key>
Solcast__ResourceId=<your-rooftop-site-id>

For local development there are two other routes: a gitignored .env in the repo root, which the worker loads on startup so it works from both dotnet run and the debugger, or .NET user-secrets:

cp .env.example .env
# then edit .env:  Solcast__ApiKey=<your-api-key>

# or, using user-secrets
cd src/Solax.Worker
dotnet user-secrets set "Solcast:ApiKey" "<your-api-key>"

A real environment variable always takes precedence over .env.

Looking at the forecast

The web UI has a Forecast page at /forecast: today and tomorrow, 30-minute period by 30-minute period, drawn as a chart and then printed as a table beneath it. The chart is the median as a line with the p10–p90 range as a band behind it, because on an uncertain day the width of that gap is the whole story. The dashboard's own Solar forecast table is the same two days in four numbers each, for a glance rather than a look.

Two things about it are worth knowing before they look like faults:

• It never fetches. The page reads the cached forecast the controller is already deciding on, so opening it costs nothing against the quota below. It shows when that forecast was last fetched.
• After a restart, this morning is missing. A forecast provider only ever answers what is still to come, so the controller can say what this morning was expected to bring only if it was running through it. A controller started at 10:44 has nothing for today before then, and the page says so rather than drawing an empty morning.

Quota — why the forecast is cached

Warning

The free tier caps daily API calls. This is why the forecast is cached locally and refreshed only every 3 hours by default — eight calls a day, raised from a twelve-hourly refresh when the Forecasted mode landed, because a day plan built at breakfast is worthless by afternoon. If you shorten RefreshInterval further, keep it within your plan's quota — check Solcast's current limits, which have changed over time. Exhausting the quota means failed refreshes, not a broken controller, but the plan then runs on stale data.

Note

Don't share one key between dev and production. A development machine and a deployed Pi polling the same resource share a single daily quota and can exhaust it between them. If you run both regularly, give them separate keys or accept that one will start failing its refreshes.

What happens when the internet is down

The forecast refresh fails and is logged. The cached forecast continues to be used, and every other part of the controller — polling, surplus-following, charge control, the battery hold, session recording, Home Assistant — is unaffected, because none of them leave the LAN. This is the one dependency that can degrade, and it degrades to "yesterday's plan" rather than to a stopped service.

---

Previous: MQTT · Next: Weather