proxy

pyPowerwall Proxy Server

This pyPowerwall Caching Proxy handles authentication to the Powerwall Gateway and will proxy API calls to /api/meters/aggregates (power metrics), /api/system_status/soe (battery level), and many others (see HELP for full list). With the instructions below, you can containerize this proxy and run it as an endpoint for tools like telegraf to pull metrics without needing to authenticate.

Cache: Because pyPowerwall is designed to cache the auth and high frequency API calls and use HTTP persistent connections. This will help reduce the load on the Gateway and prevent crash/restart issues that can happen if too many session are created on the Gateway. Logic in pypowerwall will also activate cooldown modes if the Gateway responds with errors indicating overload.

Local or Cloud: The proxy uses the built in abstraction of pypowerwall to operate in two modes: local mode and cloud mode. Local mode will connect directly with your Powerwall's Tesla Energy Gateway (TEG) to pull realtime data. Cloud mode will connect to the Tesla cloud APIs to pull realtime data. Cloud mode has lower fidelity than local mode and does not include some data points available on the the local API.

Control Mode: An optional mode allows the proxy to send control commands to set backup reserve percentage and mode of the Powerwall. This requires that you set and use the PW_CONTROL_SECRET environmental variable. For safety reasons, this mode is disabled by default and should be used with caution.

Quick Start

1. Run the Docker Container to listen on port 8675. Update the -e values for your Powerwall (see Environmental Settings for options):

   docker run \
       -d \
       -p 8675:8675 \
       -e PW_PORT='8675' \
       -e PW_PASSWORD='password' \
       -e PW_EMAIL='email@example.com' \
       -e PW_HOST='IP_of_Powerwall_Gateway' \
       -e PW_TIMEZONE='America/Los_Angeles' \
       -e TZ='America/Los_Angeles' \
       -e PW_CACHE_EXPIRE='5' \
       -e PW_DEBUG='no' \
       -e PW_HTTPS='no' \
       -e PW_STYLE='clear' \
       --name pypowerwall \
       --restart unless-stopped \
       jasonacox/pypowerwall
   
   # Cloud Mode Setup - Optional
   docker exec -it pypowerwall python3 -m pypowerwall setup -email=email@example.com
   docker restart pypowerwall

2. Test the Proxy

   # Get Powerwall Data
   curl -i http://localhost:8675/soe
   curl -i http://localhost:8675/aggregates
   curl -i http://localhost:8675/vitals
   curl -i http://localhost:8675/strings
   
   # Get Proxy Stats
   curl -i http://localhost:8675/stats
   
   # Clear Proxy Stats
   curl -i http://localhost:8675/stats/clear

Build Your Own

This folder contains the server.py script that runs a simple python based webserver that makes the pyPowerwall API calls.

The Dockerfile here will allow you to containerize the proxy server for clean installation and running.

1. Build the Docker Container

   # Build for local architecture  
   docker build -t pypowerwall:latest .
   
   # Build for all architectures - requires Docker experimental 
   docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t pypowerwall:latest . 
   

2. Setup the Docker Container to listen on port 8675.

   docker run \
       -d \
       -p 8675:8675 \
       --name pypowerwall \
       --restart unless-stopped \
       pypowerwall

3. Test the Proxy

   curl -i http://localhost:8675/soe
   curl -i http://localhost:8675/aggregates

   Browse to http://localhost:8675/ to see Powerwall web interface.

Power Flow Animation - Passthrough

The Proxy will pass authenticated calls through to the Powerwall Web Interface allowing the display of the Power Flow Animation:

This is available by directly accessing the proxy endpoint, https://localhost:8675 (replace localhost with the address of host running pyPowerwall Proxy). You can embed this animation within an iFrame. See web/example.html.

Browser Cache Control

By default resources sent for the power flow animation passthrough are not cached by the browser. This includes fairly large CSS, JavaScript and Image PNG files which are downloaded every time the browser reloads the animation. Performance can be improved by directing the web browser to cache these resources locally - only reloading if the data in the cache is old, a period known as max-age.

You can control this with an optional environment variable PW_BROWSER_CACHE which takes a value in seconds. For example,

• PW_BROWSER_CACHE=86400 - set max-age to 24 hours.

If PW_BROWSER_CACHE is not set, or set to zero, then no caching takes place. If you need to force a reload of the browser cache before max-age then most browsers will do this if you hold down the shift key while reloading the page.

HTTPS Support (Experimental)

The Proxy now supports https protocol using the optional environmental variable PW_HTTPS. This is useful for placing data in secured iFrame, including the power flow animation available via the Powerwall portal (https://localhost:8675/).

There are three settings for PW_HTTPS:

• PW_HTTPS='no' - This is default - run in HTTP mode only.
• PW_HTTPS='http' - Run in HTTP mode but simulate HTTPS when behind https proxy.
• PW_HTTPS='yes' - Run in HTTPS mode using self-signed certificate.

Troubleshooting Help

If you see python errors, make sure you entered your credentials correctly in docker run.

# See the logs
docker logs pypowerwall

# Stop the server
docker stop pypowerwall

# Start the server
docker start pypowerwall

Content does not render in iFrame or prompts you for a login:

• Browser may be set to never accept third party cookies. The web app requires cookies and in an iFrame it will look like a third party, see here).
• iFrame doesn't render. Make sure the browser is not running in incognito mode. Try other browsers.

API Help

Documentation for using the API is located in HELP.md.

Environmental Settings

The pyPowerwall Proxy will react to the following environmental variables with (defaults):

Powerwall Settings

• PW_PASSWORD - Powerwall customer password ("password") [required]
• PW_EMAIL - Powerwall customer email ("email@example.com") [required for cloudmode]
• PW_HOST - Powerwall hostname or IP address ("hostname") [required for local mode]
• PW_TIMEZONE - Local timezone ("America/Los_Angeles") [optional]

Proxy Settings

• PW_BIND_ADDRESS - IP address ("") - Required
• PW_PORT - TCP port ("8675")
• PW_DEBUG - Turn on debug logging ("no")
• PW_CACHE_EXPIRE - Time to cache responses from Powerwall in sec ("5")
• PW_BROWSER_CACHE - Sets Cache-Control for browser in sec ("0" = no-cache)
• PW_TIMEOUT - Timeout waiting for Powerwall to respond in sec ("10")
• PW_POOL_MAXSIZE - Concurrent connections to Powerwall ("15")
• PW_HTTPS - Set https mode - see HTTPS section above ("no")
• PW_STYLE - Background color style for iframe animation ("clear") - options:
  • clear (uses transparent)
  • black or dakboard (uses #000 )
  • white (uses #ffffff )
  • grafana (uses #161719 )
  • grafana-dark (uses #111217 )
• PW_AUTH_PATH - Location (path) for authentication and cache files ("")
• PW_AUTH_MODE - Use cookie (default) or token for authentication
• PW_CACHE_FILE - Proxy cache file path, with override PW_AUTH_PATH if provided (".powerwall")
• PW_SITEID - For cloud mode, if you have multiple sites configured, use this site ID ("")
• PW_CONTROL_SECRET - If provided, will activate the Powerwall control commands to adjust Powerwall backup reserve level and mode (disabled by default)

Control Mode

If the PW_CONTROL_SECRET environmental variable is set, the proxy will attempt to connect ot the cloud in addition to local mode setup (if you are using local mode). The PW_EMAIL must match your Tesla account and you need to run cloud setup before using this mode.

WARNING: Activating control mode means that the proxy can make changes to your system. This will be available to anyone who can access the proxy. For safety reasons, this mode is disabled by default and should be used with caution.

# Run Proxy 
docker run \
    -d \
    -p 8675:8675 \
    -e PW_PORT='8675' \
    -e PW_PASSWORD='password' \
    -e PW_EMAIL='email@example.com' \
    -e PW_HOST='IP_of_Powerwall_Gateway' \
    -e PW_TIMEZONE='America/Los_Angeles' \
    -e TZ='America/Los_Angeles' \
    -e PW_CONTROL_SECRET='YourSecretToken' \
    --name pypowerwall \
    --restart unless-stopped \
    jasonacox/pypowerwall

# Setup Cloud
docker exec -it pypowerwall python3 -m pypowerwall setup -email=email@example.com
docker restart pypowerwall

APIs

• Use GET method to read and POST to set.
• Mode: /control/mode value=$MODE token=$PW_CONTROL_SECRET
• Reserve: /control/reserve value=$RESERVE token=$PW_CONTROL_SECRET

Examples

export MODE=self_consumption
export RESERVE=20
export PW_CONTROL_SECRET=mySecretKey

# Set Mode
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

## Release Notes

Release notes are in the [RELEASE.md](https://github.com/jasonacox/pypowerwall/blob/main/proxy/RELEASE.md) file.