pypowerwall 0.1.1

Python module to access Tesla Energy Gateway for Powerwall and solar power data

pyPowerwall

Python module to interface with Tesla Energy Gateways for Powerwall and solar power data.

Description

This python module can be used to monitor and control Tesla Energy Gateway Powerwalls. It uses a single class (Powerwall) and simple functions to fetch energy data and poll API endpoints on the Gateway.

pyPowerwall will cache the authentication headers and API call responses to help reduce the number of calls made to the Gateway (useful if you are polling the Powerwall frequently for trending data).

• Works with Tesla Energy Gateways - Powerwall+
• Simple access through easy to use functions using customer credentials
• Will cache authentication to reduce load on Powerwall Gateway
• Will cache responses for 5s to limit number of calls to Powerwall Gateway

NOTE: This module requires that you (or your installer) have set up customer credentials on your Powerwall Gateway.

Setup

You can clone this repo or install the package with pip. Once installed, pyPowerwall can scan your local network to find th IP address of your Tesla Powerwall Gateway.

Note: pyPowerwall requires these packages (via pip): requests and protobuf.

# Install pyPowerwall
python -m pip install pypowerwall

# Scan Network for Powerwalls
python -m pypowerwall scan

Programming with pyPowerwall

After importing pypowerwall, you simply create a handle for your Powerwall device and call function to poll data. Here is an example:

    import pypowerwall

    # Optional: Turn on Debug Mode
    # pypowerwall.set_debug(True)

    # Credentials for your Powerwall - Customer Login Data
    password='password'
    email='[e-mail]'
    host = "10.0.1.123"               # Address of your Powerwall Gateway
    timezone = "America/Los_Angeles"  # Your local timezone

    # Connect to Powerwall
    pw = pypowerwall.Powerwall(host,password,email,timezone)

    # Some System Info
    print("Site Name: %s - Firmware: %s - DIN: %s" % (pw.site_name(), pw.version(), pw.din()))
    print("System Uptime: %s\n" % pw.uptime())

    # Pull Sensor Power Data
    grid = pw.grid()
    solar = pw.solar()
    battery = pw.battery()
    home = pw.home()

    # Display Data
    print("Battery power level: %0.0f%%" % pw.level())
    print("Combined power metrics: %r" % pw.power())
    print("")

    # Display Power in kW
    print("Grid Power: %0.2fkW" % (float(grid)/1000.0))
    print("Solar Power: %0.2fkW" % (float(solar)/1000.0))
    print("Battery Power: %0.2fkW" % (float(battery)/1000.0))
    print("Home Power: %0.2fkW" % (float(home)/1000.0))
    print("")

    # Raw JSON Payload Examples
    print("Grid raw: %r\n" % pw.grid(verbose=True))
    print("Solar raw: %r\n" % pw.solar(verbose=True))

    # Display Vitals
    print("Vitals: %r\n" % pw.vitals())

    # Display String Data
    print("String Data: %r\n" % pw.strings())

pyPowerwall Module Class and Functions

 set_debug(True, color=True)

 Classes
    Powerwall(host, password, email, timezone)

 Functions 
    poll(api, json)         # Fetch data from Powerwall API URI (return JSON if True)
    level()                 # Fetch battery power level percentage
    power()                 # Fetch power data returned as dictionary
    site(verbose)           # Fetch site sensor data (W or raw JSON if verbose=True)
    solar(verbose):         # Fetch solar sensor data (W or raw JSON if verbose=True)
    battery(verbose):       # Fetch battery sensor data (W or raw JSON if verbose=True)
    load(verbose)           # Fetch load sensor data (W or raw JSON if verbose=True)
    grid()                  # Alias for site()
    home()                  # Alias for load()
    vitals(json)            # Fetch raw Powerwall vitals
    strings(json, verbose)  # Fetch solar panel string data
    din()                   # Display DIN
    uptime()                # Display uptime - string hms format
    version()               # Display system version
    status(param)           # Display status (JSON) or individual param
    site_name()             # Display site name

 Variables
    pwcacheexpire = 5       # Set API cache timeout in seconds
    timeout = 10            # Timeout for HTTPS calls in seconds

Tools

The following are some useful tools based on pypowerwall:

• Powerwall Proxy - Use this caching proxy to handle authentication to the Powerwall Gateway and make basic read-only API calls to /api/meters/aggregates (power metrics) and /api/system_status/soe (battery level). This is handy proxy with metrics gathering tools like telegraf to pull metrics without needing to authenticate. Because pyPowerwall is designed to cache the auth and high frequency API calls, this will reduce the load on the Gateway and prevent crash/restart issues that can happen if too many session are created on the Gateway.

• Powerwall Simulator - A Powerwall simulator to mimic the responses from the Tesla Powerwall Gateway. This is useful for testing purposes.

Powerwall API Listing

The following APIs are a result of help from other projects as well as my own investigation.

• /api/login/Basic - Used to establish authentication

• /api/logout - End Session

• /api/system_status/soe - Battery percentage (JSON with float 0-100) Example:

  {"percentage":40.96227949234631}
  

• /api/meters/aggregates - Site, Load, Solar and Battery (JSON) Example:

  {
     "site": {
        "last_communication_time": "2021-11-22T22:15:06.590577619-07:00",
        "instant_power": -23,
        "instant_reactive_power": -116,
        "instant_apparent_power": 118.25819210524064,
        "frequency": 0,
        "energy_exported": 3826.313294918422,
        "energy_imported": 1302981.2128324094,
        "instant_average_voltage": 209.59546822390985,
        "instant_average_current": 5.4655000000000005,
        "i_a_current": 0,
        "i_b_current": 0,
        "i_c_current": 0,
        "last_phase_voltage_communication_time": "0001-01-01T00:00:00Z",
        "last_phase_power_communication_time": "0001-01-01T00:00:00Z",
        "timeout": 1500000000,
        "num_meters_aggregated": 1,
        "instant_total_current": 5.4655000000000005
     },
     "battery": {
        "last_communication_time": "2021-11-22T22:15:06.590178016-07:00",
        "instant_power": 1200,
        "instant_reactive_power": 0,
        "instant_apparent_power": 1200,
        "frequency": 59.997,
        "energy_exported": 635740,
        "energy_imported": 730610,
        "instant_average_voltage": 242.15000000000003,
        "instant_average_current": -28.6,
        "i_a_current": 0,
        "i_b_current": 0,
        "i_c_current": 0,
        "last_phase_voltage_communication_time": "0001-01-01T00:00:00Z",
        "last_phase_power_communication_time": "0001-01-01T00:00:00Z",
        "timeout": 1500000000,
        "num_meters_aggregated": 2,
        "instant_total_current": -28.6
     },
     "load": {
        "last_communication_time": "2021-11-22T22:15:06.590178016-07:00",
        "instant_power": 1182.5,
        "instant_reactive_power": -130.5,
        "instant_apparent_power": 1189.6791584288599,
        "frequency": 0,
        "energy_exported": 0,
        "energy_imported": 2445454.899537491,
        "instant_average_voltage": 209.59546822390985,
        "instant_average_current": 5.641820455472543,
        "i_a_current": 0,
        "i_b_current": 0,
        "i_c_current": 0,
        "last_phase_voltage_communication_time": "0001-01-01T00:00:00Z",
        "last_phase_power_communication_time": "0001-01-01T00:00:00Z",
        "timeout": 1500000000,
        "instant_total_current": 5.641820455472543
     },
     "solar": {
        "last_communication_time": "2021-11-22T22:15:06.594908129-07:00",
        "instant_power": 10,
        "instant_reactive_power": 0,
        "instant_apparent_power": 10,
        "frequency": 59.988,
        "energy_exported": 1241170,
        "energy_imported": 0,
        "instant_average_voltage": 241.60000000000002,
        "instant_average_current": 0.04132231404958678,
        "i_a_current": 0,
        "i_b_current": 0,
        "i_c_current": 0,
        "last_phase_voltage_communication_time": "0001-01-01T00:00:00Z",
        "last_phase_power_communication_time": "0001-01-01T00:00:00Z",
        "timeout": 1000000000,
        "num_meters_aggregated": 1,
        "instant_total_current": 0.04132231404958678
     }
  }
  

• /api/site_info/site_name

• /api/sitemaster

• /api/status

• /api/powerwalls

• /api/devices/vitals - System Summary: Inverter, Powerwalls, Site (protobuf payload)

// Strings Example:  pw.strings(True)
{
    "A": {
        "Connected": true,
        "Current": 1.81,
        "Power": 422.0,
        "State": "PV_Active",
        "Voltage": 230.0
    },
    "B": {
        "Connected": false,
        "Current": 0.0,
        "Power": 0.0,
        "State": "PV_Active",
        "Voltage": -2.5
    },
    "C": {
        "Connected": true,
        "Current": 4.47,
        "Power": 892.0,
        "State": "PV_Active",
        "Voltage": 202.4
    },
    "D": {
        "Connected": true,
        "Current": 4.44,
        "Power": 889.0,
        "State": "PV_Active_Parallel",
        "Voltage": 202.10000000000002
    }
}

Credits and References

• Tesla Powerwall 2 – Local Gateway API documentation – https://github.com/vloschiavo/powerwall2
• Python Tesla Powerwall API – https://github.com/jrester/tesla_powerwall
• TESLA PowerWall 2 Security Shenanigans – https://github.com/hackerschoice/thc-tesla-powerwall2-hack
• Powerwall Monitoring – https://github.com/mihailescu2m/powerwall_monitor
• Protocol Buffers (protobuf) Basics - https://developers.google.com/protocol-buffers/docs/pythontutorial
• Tesla (tesla.proto) Research and Credit to @brianhealey