- Upgraded to pyPowerwall v0.14.6 with support for firmware 25.42.2+ gzip-compressed TEDAPI responses
- Added gzip decompression support for Gateway firmware 25.42.2 and later
- Improved error handling for UnicodeDecodeError in DIN decode operations
- Maintains backward compatibility with older firmware versions
- Updated Proxy power flow animation to match Powerflow Dashboard color scheme.
- Performance Caching System:
- Added comprehensive performance caching layer for high-impact API routes
- Implemented
cached_route_handler()pattern for consistent cache management across endpoints - Added performance caching to:
/aggregates,/api/meters/aggregates,/vitals,/strings,/temps/pw,/alerts/pw,/freq,/pod,/json,/csv,/csv/v2endpoints - Shared cache optimization:
/aggregatesand/api/meters/aggregatesuse same cache key for identical payloads - Optimized
/csvand/jsonendpoints from 9 API calls to 6 calls (33% reduction) using aggregates consolidation - Eliminated 400-600ms overhead from redundant
get_components()fallback calls - Typical performance improvements: 99.6% faster cached responses (764ms → 2.9ms for
/aggregates) - Cache memory monitoring added to
/statsendpoint with detailed memory usage breakdown - Average overall response time improvement: 58% reduction (165.7ms → 70.2ms)
Performance Metrics Comparison:
| API Route | Before (ms) | After (ms) | Improvement | Usage Count | Impact Reduction |
|---|---|---|---|---|---|
/api/meters/aggregates |
821.5 | 151.3 | 81.6% ⚡ | 7,992 | 5,355 seconds saved |
/aggregates |
764.8 | 150.7 | 80.3% ⚡ | 3,880 | 2,383 seconds saved |
/strings |
545.7 | 37.3 | 93.2% ⚡ | 3,945 | 2,006 seconds saved |
/vitals |
339.3 | 33.9 | 90.0% ⚡ | 3,946 | 1,205 seconds saved |
/alerts/pw |
382.9 | 87.8 | 77.1% 🚀 | 3,881 | 1,145 seconds saved |
/temps/pw |
266.0 | 253.6 | 4.7% ✅ | 3,880 | 48 seconds saved |
Total Impact Reduction: ~12,142 seconds (3.4 hours) of response time saved per 8-hour period
-
Performance Testing Tool:
- Added
perf_test.pyscript for comprehensive API performance testing and analysis - Tests 27 production API routes with impact scoring (response_time × usage_frequency)
- Provides min/max/average response times with color-coded performance indicators
- Added
-
Bug Fixes:
- Fixed undefined variable
cache_ttl_secondserror in graceful degradation system - Fixed TypeError in
/csv/v2endpoint: removed invalidforce=Falseparameter fromlevel(),grid_status(), andget_reserve()calls - Fixed variable shadowing bug in
grid_status()method wheretypeparameter shadowed Python's built-intype()function - Renamed
typeparameter tooutput_typethroughout codebase for consistency and correctness
- Fixed undefined variable
-
Code Quality & Maintainability:
- Centralized cache logic in reusable helper functions for improved consistency
- Improved error handling and logging in
safe_pw_call()wrapper - Added unit tests for CSV endpoints (
TestCSVEndpointsclass with 7 test cases) - Enhanced error tracking with network error summaries and endpoint statistics
- Enhanced documentation with comprehensive performance testing guide
-
Fix Expansion Pack Energy Data (#239):
- Removed complex subtraction-based energy calculation logic (83 lines) from
/podendpoint - Expansion packs now automatically appear via TEPOD entries from
vitals()with accurate energy data - Simplified implementation relies on improved TEDAPI
get_pw3_vitals()function that processes all BMS components - Better accuracy and reduced complexity for systems with battery expansion packs
- Removed complex subtraction-based energy calculation logic (83 lines) from
-
Credit: @rlerdorf for expansion pack energy fix implementation
-
Powerwall 3 Battery Expansion Pack Support (#227, #236):
- Enhanced
/podendpoint: Now detects and reports PW3 battery expansion packs (battery-only units without inverters) - Uses
get_blocks()TEDAPI method to identify expansion packs withType: "BatteryExpansion" - Calculates expansion pack energy by subtracting known battery values from system totals
- For single expansion: displays individual energy metrics (
PW{N}_POD_nom_energy_remaining,PW{N}_POD_nom_full_pack_energy) - For multiple expansions: first entry shows combined totals with "(combined)" suffix, additional entries show
nullvalues (individual data not exposed by Tesla) - Expansion pack entries include part number, serial number, and placeholder status fields
- Enhanced
-
TEMSA/MSA Grid Meter Support for Powerwall 3 (#236):
- Enhanced
/vitalsendpoint: Added support for PW3 TEMSA/MSA backup switch grid meter data - PW3 fallback logic: reads MSA data from
components.msawhenesCan.bus.MSAis unavailable - Automatic signals array format conversion to expected dictionary structure
- Voltage reference mapping: converts PW3 ground-referenced voltages (VL1G/VL2G/VL3G) to neutral-referenced (VL1N/VL2N/VL3N) for consistency
- TEMSA block includes grid voltage, current, and instantaneous power readings for monitoring backup switch/grid connection
- Enhanced
-
Credit: @rlerdorf for battery expansion pack and TEMSA/MSA grid meter implementation
- dd curl to Dockerfiles to use in healthchecks instead of wget by @goodoldme in http://github.com/jasonacox/pypowerwall/pull/223.
- Enhanced Control API: Added new
/controlroutes for grid charging and export management- GET
/control/grid_charging: Retrieve current grid charging configuration and status - POST
/control/grid_charging: Enable/disable grid charging with configurable parameters - GET
/control/grid_export: Get current grid export settings and state - POST
/control/grid_export: Control grid export behavior and limits - Provides comprehensive control over Powerwall grid interaction modes for advanced energy management
- GET
- Improve error logging: show poll() target URI on bad payload (TypeError) instead of generic message.
- Build descriptive function/endpoint name only when an error occurs (no added overhead on success path).
- Refactor safe_pw_call exception handlers to remove redundant code. No API or config changes.
-
Connection Health Robustness Fix (#651):
- Fixed issue where
consecutive_failuresin connection health tracking could reset to zero even when the Powerwall connection was not restored. - Now, health tracking only resets on true, fresh connection success (not when returning cached or fallback responses).
- Prevents misleading health status and ensures degraded mode is only exited after real network/API recovery.
- Improves reliability of
/healthand monitoring endpoints under extended network outages or degraded conditions.
- Fixed issue where
-
Internal Refactoring:
- Audited and updated health tracking logic in
safe_pw_callandsafe_endpoint_callwrappers to ensure correct behavior. - No user-facing API changes, but improved accuracy for health metrics and logs.
- Audited and updated health tracking logic in
-
Documentation:
- Updated release notes to clarify health tracking behavior and robustness improvements for network error handling.
-
Enhanced Health Endpoint: Added pypowerwall version and proxy build information to
/healthendpoint for better version tracking and debugging- Health response now includes:
"pypowerwall": "0.13.2 Proxy t79"combining version and build info in consistent format
- Health response now includes:
-
Code Quality: Added flake8 configuration (
.flake8) and cleaned up trailing whitespace issues- Configured to ignore common acceptable lint errors (E501, W503, E722)
- Fixed trailing whitespace issues throughout proxy codebase
- Power flow animation update: Show an image of a Powerwall 3 instead of a Powerwall 2 if it is a PW3 by @JEMcats in jasonacox#193
-
TEDAPI Lock Optimization and Error Handling: Enhanced proxy stability and performance with comprehensive fixes for TEDAPI-related issues.
- Fixed KeyError exceptions in proxy server when status response missing
versionorgit_hashkeys by implementing defensive key access with.get()method - Fixed KeyError exceptions when auth dictionary missing
AuthCookieorUserRecordkeys in cookie mode, now uses safe fallbacks - TEDAPI Performance Improvements: Optimized core TEDAPI functions (
get_config,get_status,get_device_controller,get_firmware_version,get_components,get_battery_block) with cache-before-lock pattern to reduce lock contention - Removed redundant API calls in TEDAPI wrapper functions to improve response times
- Enhanced multi-threading support for concurrent proxy requests with reduced lock timeout errors
- Improved error resilience for different connection modes (local vs TEDAPI) that return varying data structures
- Fixed KeyError exceptions in proxy server when status response missing
-
Enhanced Health Monitoring: Added comprehensive endpoint statistics tracking for better observability and debugging.
- Endpoint Call Statistics: Added tracking of successful and failed API calls per endpoint with success rate calculations
- Enhanced
/healthendpoint: Now includes detailed statistics showing:- Total calls, successful calls, and failed calls per endpoint
- Success rate percentage for each endpoint
- Time since last success and last failure for each endpoint
- Overall proxy response counters (total_gets, total_posts, total_errors, total_timeouts)
- Improved
/health/resetendpoint: Now also clears endpoint statistics along with health counters and cache - Automatic tracking: All endpoints using
safe_endpoint_call()automatically tracked (includes/aggregates,/soe,/vitals,/strings, etc.)
-
Advanced Network Robustness Features: Added comprehensive connection health monitoring and graceful degradation for improved reliability under poor network conditions, especially for frequent polling scenarios (e.g., telegraf every 5s).
-
Connection Health Monitoring (
PW_HEALTH_CHECK=yes, default enabled):- Tracks consecutive failures, total error/success counts, and connection status
- Automatically enters "degraded mode" after 5 consecutive failures
- Exits degraded mode after 3 consecutive successes
- Provides health status via
/healthendpoint for external monitoring
-
Fail-Fast Mode (
PW_FAIL_FAST=yes, default disabled):- When connection is in degraded state, immediately returns cached/empty data
- Prevents timeout delays for rapid polling scenarios
- Reduces system load during extended network outages
-
Graceful Degradation (
PW_GRACEFUL_DEGRADATION=yes, default enabled):- Maintains cache of last successful responses (TTL: 5 minutes)
- Returns cached data when fresh data is unavailable
- Ensures telegraf and other pollers receive valid data structures even during outages
- Automatic cache size management (max 50 entries)
-
Telegraf-Optimized Fallbacks:
/aggregatesreturns minimal valid power structure on failure/soereturns{"percentage": 0}on failure- CSV endpoints return zero values instead of empty responses
- Maintains data type consistency for monitoring tools
-
Enhanced API Endpoints:
/health- Connection health status and feature configuration/health/reset- Reset health counters and clear cache/stats- Now includes connection health metrics when enabled
-
Improved Error Handling:
- Enhanced
safe_pw_call()with health tracking integration - New
safe_endpoint_call()wrapper with automatic caching for JSON endpoints - Better separation of network vs API errors for targeted handling
- Enhanced
-
Configuration Options:
PW_FAIL_FAST=yes/no- Enable fail-fast mode (default: no)PW_GRACEFUL_DEGRADATION=yes/no- Enable cached fallbacks (default: yes)PW_HEALTH_CHECK=yes/no- Enable health monitoring (default: yes)
-
Operational Benefits:
- Reduced timeout delays during network issues (fail-fast mode)
- Improved telegraf reliability with consistent data structures
- Better visibility into connection issues via health endpoints
- Automatic recovery detection and logging
- Memory-efficient caching with automatic cleanup
-
-
Weak WiFi / Network Error Optimization: Added specialized handling for environments with poor network connectivity.
- Enhanced Exception Coverage: Now catches all requests and urllib3 timeout/connection exceptions (ReadTimeout, ConnectTimeout, MaxRetryError, etc.)
- Rate Limiting: Network errors are rate-limited to prevent log spam (default: 5 errors per minute per function)
- Summary Reporting: Periodic summary reports (every 5 minutes) show network error counts instead of individual error logs
- Configurable Suppression:
PW_SUPPRESS_NETWORK_ERRORS=yes- Completely suppress individual network error logs (summary only)PW_NETWORK_ERROR_RATE_LIMIT=N- Set max network errors logged per minute per function (default: 5)
- Thread Safety: Added proper locking for all global statistics and error tracking
- Log Level Optimization: Network errors use INFO level, API errors use WARNING level to reduce noise
-
Enhanced Error Handling: Implemented global exception handling for all pypowerwall function calls to provide clean error logging instead of deep stack traces.
- Added
safe_pw_call()wrapper function that catches and handles pypowerwall-specific exceptions - Catches connection errors (ConnectionError, TimeoutError, OSError) and logs descriptive messages
- Catches pypowerwall API exceptions (InvalidConfigurationParameter, TEDAPI, FleetAPI errors)
- Maintains API functionality through graceful error responses (returns "TIMEOUT!" for failed calls)
- Improves debugging with clean, descriptive error messages identifying the failing function
- Error Statistics: Automatically increments
proxystats['errors']for API errors andproxystats['timeout']for connection/timeout errors - Example log messages:
"Powerwall API Error in poll: Connection timeout","Connection Error in vitals: Network unreachable"
- Added
- Fix errant API base URL check - This PR fixes an API base URL check by removing an unreachable validation branch.
- Add additional data elements to
/jsonroute:
{
"grid": 2423,
"home": 3708.5000000000005,
"solar": 1307,
"battery": -26,
"soe": 70.88757396449705,
"grid_status": 1,
"reserve": 70.0,
"time_remaining_hours": 8.076041526223541,
"full_pack_energy": 42250,
"energy_remaining": 29950.000000000004,
"strings": {
"A": {
"State": "Pv_Active",
"Voltage": 188,
"Current": 1.5999999999999996,
"Power": 300.79999999999995,
"Connected": true
},
"B": {
"State": "Pv_Active",
"Voltage": 318,
"Current": 1.2999999999999998,
"Power": 413.3999999999999,
"Connected": true
},
"C": {
"State": "Pv_Active",
"Voltage": 152,
"Current": 1.7499999999999998,
"Power": 265.99999999999994,
"Connected": true
},
"D": {
"State": "Pv_Active",
"Voltage": 190,
"Current": 1.7499999999999998,
"Power": 332.49999999999994,
"Connected": true
},
"E": {
"State": "Pv_Active",
"Voltage": 0,
"Current": 0.09999999999999964,
"Power": 0.0,
"Connected": true
},
"F": {
"State": "Pv_Active_Parallel",
"Voltage": 0,
"Current": 0,
"Power": 0,
"Connected": true
}
}
}- Add
/jsonroute to return basic metrics:
{
"grid": -3,
"home": 917.5,
"solar": 5930,
"battery": -5030,
"soe": 61.391932759907306,
"grid_status": 1,
"reserve": 20,
"time_remaining_hours": 17.03651226158038
}- Add routes to map library functions into
/pw/APIs (e.g. /pw/power)
- Add routes for fan speeds:
/fansand/fans/pw(simple enumerated values for dashboard) - Add API routes /pw/* to expose Powerwall() API methods (e.g. /pw/power) by @JohnJ9ml in jasonacox#166
pyPowerwall v0.12.9:
- Add PVAC fan speeds to TEDAPI vitals monitoring (PVAC_Fan_Speed_Actual_RPM and PVAC_Fan_Speed_Target_RPM).
- Avoid divide by zero when nominalFullPackEnergyWh is zero by @rlpm in #150
- Add thread locking to TEDAPI by @Nexarian in #148
Proxy:
- Add PROXY_BASE_URL option for reverse proxying by @mccahan in jasonacox#155
- Fix issue with visualization showing blank with multiple tabs by @mccahan in jasonacox#156
- pyPowerwall v0.12.7 - Added new data features (Neurio Vitals, Aggregates Data) and fixed a critical issue (SystemConnectedToGrid Fix) while normalizing Alerts.
- Add option to get CSV headers by @mccahan in jasonacox#149
curl http://localhost:8675/csv/v2?headers
curl http://localhost:8675/csv?headers- pyPowerwall v0.12.3 - Adds Custom GW IP for TEDAPI.
- Add new API /csv/v2 which extends /csv by adding grids status (1/0) and battery reserve (%)setting:
# Grid,Home,Solar,Battery,Battery_Level,Grid_Status,Reserve- pyPowerwall v0.12.2 - Fix bug in cache timeout code that was not honoring pwcacheexpire setting. Raised by @erikgiesele in jasonacox#122 - PW_CACHE_EXPIRE=0 not possible? (Proxy)
- Add WARNING log in proxy for settings below 5s.
- pyPowerwall v0.12.0
- Add
PW_NEG_SOLARconfig option and logic to remove negative solar values for /aggregates and /csv APIs - Update http://pypowerwall:8675/stats and http://pypowerwall:8675/help to show config data.
- PR jasonacox#113
- Add PW3 features for pypowerwall v0.11.0
Updated APIs with PW3 payloads:
- http://localhost:8675/vitals
- http://localhost:8675/help (pw3 flag True/False)
- http://localhost:8675/tedapi/components
- http://localhost:8675/tedapi/battery
- Address pyLint code cleanup and minor command mode fixes.
- Add battery full_pack and remaining energy data to
/podAPI call for all cases.
- Fix 404 bug that would throw error when user requested non-supported URI.
- Add TEDAPI mode to stats.
- Add error handling for
/csvAPI to accommodateNonedata points.
- Minor fix to send less ambiguous debug information during client disconnects.
- Update Neurio block to include correct location and adjust RealPower based on power scale factor.
- Add support for pypowerwall v0.10.0 and TEDAPI with environmental variable
PW_GW_PWDfor Gateway Password. This unlocks new device vitals metrics (as seen with/vitals). It requires the user to have access to the Powerwall Gateway at 192.168.91.1, either via WiFi for by adding a route to their host or network. - Add FleetAPI, Cloud and TEDAPI specific GET calls,
/fleetapi,/cloud, and/tedapirespectively.
- Add pypowerwall v0.9.0 capabilities, specifically supporting Tesla FleetAPI for cloud connections (main data and control).
- Fix error with site_name on Solar Only systems.
- Fix
/podAPI to addtime_remaining_hoursandbackup_reserve_percentfor cloud mode. - Replaced t54 - Move control to POST see jasonacox#87
- Added GET APIs to retrieve backup reserve and operating mode settings
- Added POST command APIs to set backup reserve and operating mode settings. Requires setting
PW_CONTROL_SECRETfor the proxy. Use with caution.
# Set Mode
export MODE=self_consumption
export RESERVE=20
export PW_CONTROL_SECRET=mySecretKey
curl -X POST -d "value=$MODE&token=$PW_CONTROL_SECRET" http://localhost:8675/control/mode
# Set Reserve
curl -X POST -d "value=$RESERVE&token=$PW_CONTROL_SECRET" http://localhost:8675/control/reserve
# Read Settings
curl http://localhost:8675/control/mode
curl http://localhost:8675/control/reserve- Add DISABLED API handling logic.
- Update to pyPowerwall proxy v0.8.1
- Update to pypowerwall 0.8.0
- Minor bug fixes.
- Update to pypowerwall 0.7.12 and add
/api/solar_powerwallto ALLOWLIST. Using new API, proxy is able to produce/alerts/list and some/stringsdata for newer Firmware version (>23.44) that no longer support the vitals API.
- Add Power Flow Animation style (set
PW_STYLE="solar") for Solar-Only display. Removes the Powerwall image and related text to display a Grid + Solar + Home powerflow animation.
- Bug fixes for Solar-Only systems using
cloud mode(see jasonacox/Powerwall-Dashboard#437).
- Use /api/system_status battery blocks data to augment /pod and /freq macro data APIs.
- Fix Critical Bug - 404 HTTP Status Code Handling (Issue jasonacox#65).
- Add
PW_AUTH_PATHto set location for cloud auth and site files.
- Add
cloudmodesupport for pypowerwall v0.7.1.
- Fix "flashing animation" problem by matching
hashvariable in index.html to firmware versiongit_hash.
- Default page rendered by proxy (http://pypowerwall/) will render Powerflow Animation
- Animation assets (html, css, js, images, fonts, svg) will render from local filesystem instead of pulling from Powerwall TEG portal.
- Start prep for possible API removals from Powerwall TEG portal (see NOAPI settings)
- Add a
grafana-darkstyle forPW_STYLEsettings to accommodate placing as iframe in newer Grafana versions (e.g. v9.4.14). See jasonacox/Powerwall-Dashboard#371.
- Add Add Graceful Exit with SIGTERM to fix condition where container does not stop gracefully as raised in jasonacox#49 by @rcasta74 .
- Update default
PW_POOL_MAXSIZEfrom 10 to 15 to help address "Connection pool is full" errors reported by @jgleigh in jasonacox/Powerwall-Dashboard#261 - May the 4th be with you!
- Fix Cache-Control no-cache header and added option to set max-age, fixes #31 by @dkerr64 in jasonacox#32
- Added new alerts endpoint ('/alerts/pw') for retrieving the data in dictionary/object format (helps with telegraf usage).
- Updated to Python 3.10
- Added Powerwall Firmware version display to Power Flow Animation
- Added cache logic to better handle Powerwall firmware upgrades.
- Fix
clear.js(and others) to hide the compliance link button in the animation caused by the latest Powerwall firmware upgrade (22.26.1-foxtrot)
- Fix Bug with
/versionfor version numbers with alpha characters. #24 - Added error handling for socket error when sending response.
- Added uptime field for stats ('/stats') API.
- Enhanced help API ('/help') to provide HTML stats page and link to API documentation.
- Improved logging with timestamps.
- Released with pyPowerwall v0.6.0 Enhancement
- Added HTTP persistent connections for API requests to Powerwall Gateway by @mcbirse in #21
- Requests to Gateway will now re-use persistent http connections which reduces load and increases response time.
- Added env PW_POOL_MAXSIZE to proxy server to allow this to be controlled (persistent connections disabled if set to zero).
- Added env PW_TIMEOUT to proxy server to allow timeout on requests to be adjusted.
- Add support for specifying a bind address by @zi0r in jasonacox#16
- Add shebang for direct execution by @zi0r in jasonacox#17
- Breaking update to /api/system_status/soe endpoint that now provides the 95% scaled values. This was important to make sure the Power Flow animation matches the Tesla App. The /soe shortcut URL will continue to provide actual battery level (unscaled). See Issue jasonacox/Powerwall-Dashboard#37
- Bug fix to remove scrollbars from web view (see jasonacox#15 and jasonacox/Powerwall-Dashboard#29) thanks to @danisla.
-
Added ability to change the style of the power flow animation background color:
clear(default),black,white,grafanagray, anddakboardblack. Set usingPW_STYLEenvironment variable:export PW_STYLE="clear"
-
Added ability to proxy Powerwall web interface for power flow animation (by @danisla). #14
-
Added optional HTTPS support for iframe compatibility via
PW_HTTPSenvironment variable:# Turn on experimental HTTPS mode export PW_PORT="8676" export PW_PASSWORD="password" export PW_EMAIL="name@example.com" export PW_HOST="10.0.1.73" export PW_TIMEZONE="America/Los_Angeles" export PW_CACHE_EXPIRE="5" export PW_DEBUG="no" export PW_HTTPS="yes" python3 server.py
- Removed memory leak debug function.
- Bug Fix - ThreadingHTTPServer daemon_threads related memory leak fix. #13
- Proxy server memory metrics added to /stats response.
- Cleaned up /freq macro to better handle vitals response with missing ISLAND or METER metrics.
- Backup Switch: Added frequency, current and voltage for Backup Switch device.
- Bug Fix: Debug logging continued even when disable.
- Force exit added for faster termination instead of waiting on connections to drain.
- Added /pod to provide battery state information (e.g. ActiveHeating, ChargeComplete, PermanentlyFaulted) with boolean values as integers (1/0).
- Added /version to provide Powerwall TEG Firmware Version in string and integer value calculated from the semantic version (e.g. 21.1.1 = 210101).
- Added /alerts to provide list of alerts across devices.
- Added /freq to provide Frequency, Current and Voltage data for Home, Grid, Powerwall.
- Added /temps (raw) and /temps/pw (aliased) to provide temperature data for Powerwalls.
- Added /help to provide link to this page.
- Bug fix in NoneType for error counter.
- Added support for allow list of Powerwall API calls.
- Added multi-threading to HTTP handling using python ThreadingHTTPServer library.



