DOCSEARCHbyAlgolia
Submit Docs

pyPowerwall

repository·main·Indexed 42 days ago

https://github.com/jasonacox/pypowerwall

A Python library and caching proxy server for interfacing with Tesla Energy Gateways (Powerwall, Powerwall+, and Powerwall 3). It allows users to monitor and control energy data via local or cloud-based APIs, providing methods to retrieve device vitals and solar panel string data, as well as a CLI tool to scan networks for gateways.

Tokens
41K
Snippets
102
Records
185
Agent score
53%

What's inside pyPowerwall

  1. Overview of pyPowerwall

    main

    pyPowerwall is a Python module designed to interface with Tesla Energy Gateways to monitor and control Powerwall and solar power data. It supports Powerwall, Powerwall 2, Powerwall+, and Powerwall 3 systems.

    Key features include:

    • Multiple Access Modes: Supports Local Gateway APIs, official Tesla FleetAPI, unofficial Tesla Owners API, and v1r LAN TEDAPI (specifically for Powerwall 3).
    • Efficiency: Caches authentication headers and API responses to reduce load on the Gateway and cloud services. It also re-uses HTTP connections for faster response times.
    • Solar Data: Provides solar string data for Powerwall+ and Powerwall 3 systems.
    • Core Interface: Uses a single Powerwall class and simple functions to fetch energy data and poll endpoints.

  2. Overview of pyPowerwall Proxy capabilities

    main

    The pyPowerwall Proxy serves three primary functions for developers aggregating Powerwall data:

    1. Authentication & Caching: Provides authentication management and payload caching to optimize data retrieval.
    2. Aggregated Data APIs: Exposes specialized APIs that transform complex Powerwall data into simplified JSON outputs for easier processing.
    3. Pass-through APIs: Provides several read-only pass-through endpoints that allow direct calls to the underlying Powerwall API.

    For setup instructions, refer to the main README. For a complete list of available endpoints and how to use them, see the API documentation.

  3. Overview of TeslaPy

    main

    TeslaPy is a Python API designed to monitor and control Tesla products remotely. It is built based on unofficial documentation of the Tesla Motors Owner API.

    Note for users of pypowerwall: This project currently uses a local copy of TeslaPy (version 2.9.1) to ensure compatibility and stability while waiting for the upstream version to be published to PyPI.

  4. Overview of pyPowerwall Proxy Server

    main

    The pyPowerwall Proxy Server is a caching proxy that handles authentication to the Powerwall Gateway and proxies API calls (such as /api/meters/aggregates and /api/system_status/soe). It is designed to reduce load on the Gateway and prevent crashes by caching authentication and using HTTP persistent connections.

    Note: This proxy is in maintenance mode. New features are being developed in pypowerwall-server. Use this proxy if you need a drop-in replacement for existing deployments or critical security fixes.

  5. PyPowerwall Proxy Server API Overview

    main

    The PyPowerwall Proxy Server provides a RESTful HTTP API to access Tesla Powerwall metrics (site, battery, solar, vitals, alerts) and control features. It supports local gateway and cloud modes (FleetAPI/Owners Cloud).

    Base URL Configuration:

    • Default: http://<host>:8675/
    • If using a reverse proxy, set the PROXY_BASE_URL environment variable.

    Security Note: Control operations are DISABLED by default. To enable them, you must set the PW_CONTROL_SECRET environment variable to any non-empty value.

    http://localhost:8675/

  6. Use related pyPowerwall tools

    main

    The following tools are built on top of or complement pyPowerwall:

    • Powerwall Proxy: A caching proxy for handling authentication and making read-only API calls to /api/meters/aggregates (power metrics) and /api/system_status/soe (battery level). It is ideal for metrics gathering tools like Telegraf to reduce load on the Gateway and prevent session-related crashes.
    • Powerwall Simulator: A simulator used to mimic Tesla Powerwall Gateway responses for testing purposes.
    • Powerwall Dashboard: A monitoring dashboard implementation using Grafana, InfluxDB, Telegraf, and pyPowerwall.

  7. PyPowerwall Server Performance Characteristics

    main

    The PyPowerwall Server is designed for high performance and low latency:

    • Response Times: Sub-50ms for cached endpoints.
    • Concurrency: Capable of handling 1000+ concurrent connections.
    • Memory Usage: Approximately 100MB base, plus an additional 20MB per gateway managed.
    • WebSockets: Supports hundreds of simultaneous real-time connections.

  8. Details for specific Powerwall devices

    main

    Detailed breakdown of specific device components and their roles within the Tesla Energy ecosystem:

    STSTSM (Tesla Energy System)

    • ECU Type: 207
    • Role: Primary control unit for Tesla Energy Systems.
    • Associated Hardware: Tesla Gateway 1, Tesla Gateway 2, or Tesla Backup Switch.

    TETHC (Tesla Energy Total Home Controller)

    • ECU Type: 224
    • Role: Controller for Powerwall 2, Powerwall 2.1, and Powerwall + systems.

    TEPOD (Tesla Energy Powerwall)

    • ECU Type: 226
    • Role: The Powerwall battery system; a component of TETHC.

    TEPINV (Tesla Energy Powerwall Inverter)

    • ECU Type: 253
    • Role: The inverter for battery energy storage/release; a component of TETHC.

    TESYNC (Tesla Energy Synchronizer)

    • ECU Type: 259
    • Role: Monitors grid voltage and frequency to manage the transition to backup mode; a component of TETHC.

    TEMSA (Tesla Backup Switch)

    • ECU Type: 300
    • Role: Simplifies installation by plugging into the meter socket panel and controlling the connection to the grid via a contactor.

    PVAC (Photovoltaic AC - Solar Inverter)

    • ECU Type: 296
    • Role: Solar inverter; a component of TETHC.

    PVS (Photovoltaic Strings)

    • ECU Type: 297
    • Role: Terminates Photovoltaic DC power strings; a component of PVAC.

    NEURIO (Wireless Revenue Grade Solar Meter)

    • Role: A third-party (Generac) meter with Tesla proprietary firmware used to report solar production; a component of STSTSM.

    TESLA (Internal Device Attributes)

    • Role: Describes attributes of inverters, meters, and other components; a component of STSTSM.

  9. How PyPowerwall Server handles Authentication and Control

    main

    The server distinguishes between TEDAPI (Local) for monitoring and Cloud (Control) for managing settings. This separation allows for high-performance local monitoring without internet dependency, while still enabling remote control via Tesla's Cloud API.

    TEDAPI (Local Monitoring)

    • Purpose: Fast data reads (metrics, power flow, etc.).
    • Requirements: host (gateway IP) and gw_pwd (gateway password).
    • Benefit: Low latency, works on local network without internet.

    Cloud (Control Operations)

    • Purpose: Changing settings like battery reserve or operating mode.
    • Requirements: email and authpath (directory containing .pypowerwall.auth and .pypowerwall.site tokens).
    • Setup: Requires running python3 -m pypowerwall setup to generate tokens.

    Security for Control

    By default, the server is read-only. To enable control, you must set CONTROL_ENABLED=true and provide a CONTROL_TOKEN. All control operations then require this token in the Authorization header.

  10. Manage grid islanding (WARNING)

    main

    ⚠️ WARNING

    Methods go_off_grid(confirm) and reconnect_grid() physically operate your home's grid contactor.

    • go_off_grid(confirm=True): Disconnects from the grid (opens contactor). Requires confirm=True.
    • reconnect_grid(): Reconnects to the grid (closes contactor).

    Risks:

    • Going off-grid causes a brief transition (~30s solar dropout).
    • If the battery depletes while islanded, your home loses power.
    • Do not automate these commands without understanding failure modes. Test only when someone is present and verify grid status after execution.

  11. How pypowerwall architecture and backends work

    main

    pypowerwall uses a modular architecture where the main Powerwall class acts as a high-level interface that automatically selects the appropriate backend based on your configuration.

    Supported Backends

    • TEDAPI: Tesla Energy Device API. Best for Powerwall 3 or recent Powerwall 2+ firmware (23.44.0+). Uses local gateway communication via protobuf. Supports vitals streaming and offline operation.
    • Local: Legacy local API. Best for older firmware/systems. Uses cookie/bearer authentication via the local gateway.
    • Cloud: Tesla Cloud API. Best for remote access over the internet. Uses Tesla account authentication.
    • FleetAPI: Tesla Fleet API. Best for third-party integrations. Uses OAuth tokens and vehicle integration.

    Backend Selection Logic

    The Powerwall class selects the backend in this priority order:

    1. If fleetapi=True $\rightarrow$ FleetAPI
    2. Else if cloudmode=True $\rightarrow$ Cloud
    3. Else if gw_pwd is provided $\rightarrow$ Test TEDAPI connection. If successful, use TEDAPI; otherwise, fallback to Local.
    4. Else $\rightarrow$ Local

  12. Understand the pypowerwall architecture and connection modes

    main

    pypowerwall provides a unified API for Tesla Powerwall energy gateways by using the local gateway's /api/... URI namespace as a universal internal interface. The Powerwall facade class handles mode selection and validation, delegating actual communication to a backend client (self.client) that implements the PyPowerwallBase contract.

    Connection Modes

    ModeBackend ClassTransport / Description
    localPyPowerwallLocalGateway REST (https://<host>/api/...) using cookie or bearer auth.
    hybridPyPowerwallLocalUses REST for most data and TEDAPI for vitals (requires host, password, and gw_pwd).
    tedapi (full)PyPowerwallTEDAPIProtobuf communication directly to 192.168.91.1.
    v1rPyPowerwallTEDAPIRSA-4096-signed transport for Powerwall 3 wired LAN access (requires rsa_key_path).
    cloudPyPowerwallCloudTesla Owner API via bundled teslapy.
    fleetapiPyPowerwallFleetAPITesla FleetAPI via OAuth.

    Mode Resolution Logic

    1. Initialization: Powerwall.__init__ determines the initial mode. If auto_select=True, it prefers local (if host is set), then fleetapi (if .pypowerwall.fleetapi exists), then cloud (if .pypowerwall.auth exists).
    2. Connection: Powerwall.connect(retry) attempts the selected mode. If it fails, it degrades circularly: local $\rightarrow$ fleetapi $\rightarrow$ cloud $\rightarrow$ local. If retry_modes=True is set, it will sleep 30s after each cycle and retry indefinitely.