feat(forecast): add weather-based solar PV forecast (Option A)

- New collector/forecast.py: fetches Open-Meteo hourly weather, computes
clear-sky PV via pvlib for array tilt/azimuth, applies cloud cover and
bifacial gain, stores predicted watts.
- Adds forecast settings (lat/lon, array kWp/azimuth/tilt/bifacial gain,
provider, horizon, refresh interval) with UI metadata.
- New MariaDB table lux_solar_forecast and /api/forecast endpoint.
- Writes same forecast to InfluxDB as 'PV power predicted' and
'Cloud cover' so existing Grafana panels render it.
- Dashboard card shows next 24h peak and today's predicted kWh.
- Refresh scheduler piggybacks the collector writer loop.

Specs for this deployment: 1.56 kWp, due south, 21° tilt, 10% bifacial
gain, Waller TX (30.0591N, -95.9324W).

Author: jmewing

api/__init__.py

@@ -441,6 +441,54 @@ def api_energy(
 
 
 
+@app.get("/api/forecast")
+def api_forecast(
+    hours: int = Query(48, ge=1, le=168, description="Hours of forecast to return"),
+):
+    """Return the stored solar PV forecast from MariaDB.
+
+    Returns hourly predicted PV watts, newest forecast first. Optionally filter
+    to a specific number of hours from now.
+    """
+    from datetime import datetime, timedelta
+
+    conn = _get_conn()
+    try:
+        with conn.cursor() as cur:
+            cur.execute(
+                """
+                SELECT ts, predicted_watts, cloud_cover, source
+                FROM lux_solar_forecast
+                WHERE ts >= NOW()
+                  AND ts < NOW() + INTERVAL %s HOUR
+                ORDER BY ts ASC
+                """,
+                (hours,),
+            )
+            rows = cur.fetchall()
+
+        data = [
+            {
+                "ts": ts.isoformat() if ts else None,
+                "predicted_watts": float(predicted_watts),
+                "cloud_cover": float(cloud_cover) if cloud_cover is not None else None,
+                "source": source,
+            }
+            for ts, predicted_watts, cloud_cover, source in rows
+        ]
+
+        generated_at = datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+        return {
+            "hours": hours,
+            "count": len(data),
+            "generated_at": generated_at,
+            "unit": "W",
+            "data": data,
+        }
+    finally:
+        conn.close()
+
+
 # ── settings ────────────────────────────────────────────────────────────────
 
 class SettingUpdate(BaseModel):

api/static/index.html

@@ -149,6 +149,8 @@
                 <div class="label" id="solar-label">Solar PV</div>
                 <div class="property" id="sa-solar-total">--</div>
                 <div class="property small"><span class="name">Peak:</span><span id="sa-solar-peak">--</span></div>
+                <div class="property small"><span class="name">Next peak:</span><span id="sa-solar-forecast-peak">--</span></div>
+                <div class="property small"><span class="name">Forecast today:</span><span id="sa-solar-forecast-today">--</span></div>
               </div>
             </a></div>
             <div><a href="#" class="status" data-detail="grid" aria-labelledby="grid-label">
@@ -704,6 +706,43 @@ <h3 id="rule-editor-title">Edit Rule</h3>
   });
 }
 
+async function loadForecastCard() {
+  try {
+    const res = await fetchJson(API + '/api/forecast?hours=48');
+    const rows = res.data || [];
+    if (!rows.length) {
+      setText('sa-solar-forecast-peak', '--');
+      setText('sa-solar-forecast-today', '--');
+      return;
+    }
+    // Find the max predicted watts in the next 24h.
+    const next24h = rows.filter(r => new Date(r.ts) <= new Date(Date.now() + 24 * 3600 * 1000));
+    let peak = null;
+    let peakTs = null;
+    for (const r of next24h) {
+      if (peak === null || r.predicted_watts > peak) {
+        peak = r.predicted_watts;
+        peakTs = r.ts;
+      }
+    }
+    // Sum today's predicted energy (kWh).
+    const now = new Date();
+    const todayStart = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    const todayRows = rows.filter(r => {
+      const d = new Date(r.ts);
+      return d >= todayStart && d < new Date(todayStart.getTime() + 24 * 3600 * 1000);
+    });
+    const todayKwh = todayRows.reduce((sum, r) => sum + (r.predicted_watts || 0), 0) / 1000;
+
+    setText('sa-solar-forecast-peak', peak !== null ? fmtInt(peak) + ' W ' + fmtTime(peakTs).replace('Updated ', '') : '--');
+    setText('sa-solar-forecast-today', fmt(todayKwh, 1) + ' kWh');
+  } catch (e) {
+    console.error('loadForecastCard error', e);
+    setText('sa-solar-forecast-peak', '--');
+    setText('sa-solar-forecast-today', '--');
+  }
+}
+
 async function loadMainCharts() {
   try {
     const res = await fetchJson(API + '/api/history?minutes=1440&max_points=300&fields=pv1_power,pv2_power,charge_power,discharge_power,grid_import_power,grid_export_power,load_power,battery_voltage,soc');
@@ -1270,10 +1309,11 @@ <h4 style="margin:1rem 0 0.5rem;">Set — action</h4>
   });
 
   refresh();
+  loadForecastCard();
   loadMainCharts();
   connectWS();
   setInterval(refresh, 15000);
-});
+  setInterval(loadForecastCard, 300000);;
 </script>
 </body>
 </html>

collector/collector.py

@@ -432,6 +432,7 @@ def __init__(self, config: CollectorConfig,
         self._last_write = 0.0
         self._config_fingerprint: Optional[str] = None
         self._loaded_restart_values: Dict[str, str] = {}
+        self._last_forecast_refresh = 0.0
 
         # Register handler for graceful shutdown
         signal.signal(signal.SIGINT, self._signal_handler)
@@ -703,11 +704,63 @@ def _writer_loop(self) -> None:
                     except Exception:
                         logger.exception("Snapshot callback failed")
 
+                # Periodic solar forecast refresh (Option A).
+                self._maybe_refresh_forecast()
+
             except Exception:
                 logger.exception("Failed to write snapshot")
 
         logger.info("Writer loop exiting")
 
+    def _maybe_refresh_forecast(self) -> None:
+        """Refresh the solar forecast on a configurable interval.
+
+        Reads forecast settings fresh from MariaDB each cycle, so enabling or
+        changing forecast settings takes effect without a restart.
+        """
+        try:
+            from .forecast import config_from_settings, refresh
+            from .settings import get_all
+            import pymysql
+
+            settings = self._read_db_settings()
+            if not settings:
+                return
+            cfg = config_from_settings(settings)
+            if not cfg.enabled:
+                return
+
+            now = time.time()
+            interval = max(60.0, float(cfg.refresh_min) * 60.0)
+            if now - self._last_forecast_refresh < interval:
+                return
+
+            conn = pymysql.connect(
+                host=self.cfg.outputs.mariadb_host,
+                port=self.cfg.outputs.mariadb_port,
+                user=self.cfg.outputs.mariadb_user,
+                password=self.cfg.outputs.mariadb_password,
+                database=self.cfg.outputs.mariadb_database,
+                autocommit=True,
+            )
+            try:
+                prefix = self.cfg.outputs.mariadb_table_prefix
+                influx_cfg = None
+                if self.cfg.outputs.influx_enabled and self.cfg.outputs.influx_token:
+                    influx_cfg = {
+                        "url": self.cfg.outputs.influx_url,
+                        "token": self.cfg.outputs.influx_token,
+                        "org": self.cfg.outputs.influx_org,
+                        "bucket": self.cfg.outputs.influx_bucket,
+                    }
+                written = refresh(conn, prefix, settings, influx_cfg)
+                if written is not None:
+                    self._last_forecast_refresh = now
+            finally:
+                conn.close()
+        except Exception:
+            logger.exception("Forecast refresh failed")
+
     # ── Sanity clamping ──────────────────────────────────────────────
     _SANITY_LIMITS: Dict = {
         "pv1_power": 8000,