Solar & Weather Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Solar & Weather Integration feature in BMSview provides users with comprehensive solar energy estimation and battery charging correlation. It allows users to fetch solar energy production estimates based on their geographic location and panel specifications, compare this expected input with actual battery charging data from their BMS, and identify system inefficiencies or anomalies. This system leverages external APIs for solar and weather data, which are proxied through a Netlify serverless function.
The core goal is to provide actionable recommendations for system optimization by analyzing the relationship between solar availability, weather conditions, and battery performance. For more details on the overall architecture, see the System Architecture Guide.
Sources: README.md, SOLAR_INTEGRATION_GUIDE.md
Architecture
The integration is composed of backend and frontend components that work together to fetch, process, correlate, and visualize solar and battery data.
Backend: Netlify Function Proxy
A Netlify serverless function acts as a secure proxy to the external Solar Charge Estimator API. This approach avoids exposing API keys on the client-side and handles request validation, caching, and CORS.
Sources: netlify/functions/solar-estimate.ts, SOLAR_INTEGRATION_GUIDE.md:12-20
API Endpoint: solar-estimate
- Endpoint:
/.netlify/functions/solar-estimate - Method:
GET - Description: Proxies requests to the Solar Charge Estimator API, adding validation, error handling, and a 1-hour caching layer.
The following diagram illustrates the request flow through the Netlify proxy.
This diagram shows the data flow for a solar estimate request.
Sources: netlify/functions/solar-estimate.ts:14-55, SOLAR_INTEGRATION_GUIDE.md:14-20
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
location | string | Yes | US Zip Code or "latitude,longitude" format. |
panelWatts | string | Yes | Solar panel maximum power rating in Watts. |
startDate | string | Yes | Start date in YYYY-MM-DD format. |
endDate | string | Yes | End date in YYYY-MM-DD format. |
Sources: netlify/functions/solar-estimate.ts:16-22, README.md:65-71
Frontend Components
The frontend consists of services for API communication, utilities for data correlation, and React components for user interaction and visualization.
Solar & Weather Services
Two key services manage communication with backend and external APIs:
solarService.ts: Interacts with thesolar-estimateNetlify function. It includes an in-memory cache with a 1-hour TTL to reduce redundant API calls. Key functions includefetchSolarEstimate,calculateTotalEstimatedEnergy, andgetPeakSolarHour.weatherService.ts: Although aweatherService.tsfile exists, its functionality for fetching weather data appears to be a stub or placeholder, as thegetWeatherfunction is marked as aTODOand returns placeholder data. The primary weather data (cloud cover, irradiance) is integrated via a separate data merge process on the backend.
The sequence diagram below shows how the solarService fetches data, utilizing its cache.
This diagram shows the sequence of events for fetching a solar estimate, including the client-side caching logic.
Sources: services/solarService.ts:13-48, services/weatherService.ts:4-8, SOLAR_INTEGRATION_GUIDE.md:52-68
Solar Correlation Logic
The core analysis is performed by utilities in utils/solarCorrelation.ts. These functions correlate the expected solar generation with actual battery charging data extracted from BMS records.
Key functions in utils/solarCorrelation.ts:
ahToWh()/whToAh(): Convert between Amp-hours and Watt-hours.extractBatteryEnergyData(): Processes raw BMS records to extract charging gains.correlateSolarWithBattery(): The main function that matches solar estimates with battery data.analyzeEfficiency(): Calculates efficiency metrics based on the correlation results.detectChargingAnomalies(): Flags inconsistencies, such as no charging during high solar irradiance.getEfficiencyStatus(): Categorizes efficiency into "Good" (≥80%), "Warning" (60-79%), or "Critical" (<60%).generateEfficiencyRecommendations(): Provides actionable advice based on the analysis.
Sources: utils/solarCorrelation.ts, SOLAR_INTEGRATION_GUIDE.md:71-98
UI Components
SolarIntegrationDashboard.tsx: The main container component that orchestrates the solar analysis UI.SolarEstimatePanel.tsx: A UI panel for users to input their location, panel wattage, and select a date range.SolarEfficiencyChart.tsx: A chart that visualizes the correlation analysis, displaying metrics like average efficiency, anomaly counts, and a comparison of expected vs. actual energy gains. It also displays the recommendations generated by the correlation utilities.
Sources: components/SolarEfficiencyChart.tsx, SOLAR_INTEGRATION_GUIDE.md:100-132
Data and Analysis
Data Merging for Weather Context
To provide environmental context, hourly weather data (cloud cover and irradiance) is merged with BMS data points. This process is handled by the backend data-merge.cjs utility when a request is made to the /history?merged=true endpoint.
The frontend HistoricalChart.tsx component can then toggle this merged view, overlaying cloud cover as a gray area chart and solar irradiance as a dashed yellow line. This allows for direct visual correlation between weather conditions and battery charging behavior.
This diagram shows how BMS and hourly weather data are merged on the backend before being sent to the frontend for visualization.
Sources: HOURLY_CLOUD_SOLAR_INTEGRATION.md
Efficiency Analysis
The efficiency analysis compares the solar energy expected to be generated (estimatedWh) with the actual energy gained by the battery (actualGainWh).
Efficiency Thresholds:
- Good: ≥ 80%
- Warning: 60% - 79%
- Critical: < 60%
Anomalies are flagged under conditions such as:
- Efficiency drops below a configurable threshold (e.g., 70%).
- High solar irradiance is detected with no corresponding battery charging.
- Low solar irradiance is present, but high charging current is reported (suggesting another charge source).
The results, including an efficiency score and a list of anomalies, are displayed in the SolarEfficiencyChart.
Sources: utils/solarCorrelation.ts:119-130, 150-166, SOLAR_INTEGRATION_GUIDE.md:144-155
Key Data Types
The solar integration feature uses several custom TypeScript types to manage data structures.
| Type Name | Description | Source File |
|---|---|---|
SolarEstimateRequest | Defines the parameters for a solar estimate API request. | types/solar.ts |
SolarEstimateResponse | The structure of the data returned from the solar estimate API. | types/solar.ts |
DailyEstimate | Contains the total estimated Watt-hours for a single day. | types/solar.ts |
HourlyBreakdown | Provides hourly irradiance and estimated energy generation. | types/solar.ts |
EfficiencyAnalysis | The final analysis object containing all efficiency metrics and anomalies. | types/solar.ts |
Sources: SOLAR_INTEGRATION_GUIDE.md:134-142
Conclusion
The Solar & Weather Integration is a powerful feature within BMSview that transforms raw BMS data into meaningful, actionable insights. By fetching solar estimates, correlating them with real-world battery performance, and contextualizing the data with weather information, it enables users to diagnose inefficiencies, detect charging problems, and ultimately optimize the performance and longevity of their solar-battery systems. The architecture, with its proxy backend and client-side caching, is designed for security and efficiency.