tesla-powerwall 0.3.1

API for Tesla Powerwall

Python Tesla Powerwall API

Python Tesla Powerwall API for consuming a local endpoint. The API is by no means complete and mainly features methods which are considered to be of common use. If you feel like methods should be included you are welcome to open an Issue or create a Pull Request.

Note: This is not an official API provided by Tesla and as such might fail at any time.

Powerwall Software versions from 1.45.0 to 1.49.0 are supported, but others will probably work too.

For more information about versioning see API versioning.

Table of Contents

• Installation
• Usage
  • Setup
  • Authentication
  • General
    • API versioning
    • Errors
    • Response
  • Battery level
  • Powerwall Status
  • Sitemaster
  • Siteinfo
  • Meters
    • Aggregates
    • Current power supply/draw
    • Energy exported/imported
  • Device Type
  • Grid Status
  • Operation mode
  • Powerwalls Serial Numbers
  • VIN

Installation

$ pip install tesla_powerwall

Usage

Setup

from tesla_powerwall import Powerwall

powerwall = Powerwall("<ip of your Powerwall>")
#=> <Powerwall ...>

powerwall = Powerwall(
    endpoint="<ip of your powerwall>",
    timeout=10,
    http_sesion=None,
    verify_ssl=False,
    disable_insecure_warning=True,
    pin_version=None
)
#=> <Powerwall ...>

Note: By default the API client does not verify the SSL certificate of the Powerwall. If you want to verify the SSL certificate you can set verify_ssl to True. The API client suppresses warnings about an inseucre request (because we aren't verifing the certificate). If you want to enable those warnings you can set disable_insecure_warning to False.

Authentication

Logging in is not required for most methods. When a method requires you to log in an AccessDeniedError is thrown.

To login you can either use login or login_as. login logs you in as User.CUSTOMER whereas with login_as you can choose a different user:

from tesla_powerwall import User

# Login as customer
powerwall.login("<email>", "<password>")
#=> <LoginResponse ...>

# Login with different user
powerwall.login_as(User.INSTALLER, "<email>", "<password>")
#=> <LoginResponse ...>

# Check if we are logged in 
powerwall.is_authenticated()
#=> True

# Logout
powerwall.logout()

General

The API object directly maps the REST endpoints with a python method in the form of <verb>_<path>. So if you need the raw json responses you can use the API object. It can be either created manually or retrived from an existing Powerwall:

from tesla_powerwall import API

# Manually create API object
api = API('https://<ip>/')
# Perform get on 'system_status/soe'
api.get_system_status_soe()
#=> {'percentage': 97.59281925744594}


# From existing powerwall
api = powerwall.get_api()
api.get_system_status_soe()

The Powerwall objet provides a wrapper around the API and exposes common methods.

API versioning

The powerwall API is inconsistent across different versions. This is why some versions may return different responses. If no version is specified the newest version is assumed.

If you are sure which version your powerwall has you can pin the Powerwall object to a version:

from tesla_powerwall import Version
# Pin powerwall object
powerwall = Powerwall("<powerwall-ip>", pin_version="1.46.0")

# You can also pin a version after the powerwall object was created
powerwall.pin_version("1.46.0")

Otherwise you can let the API try to detect the version and pin it. This method should be prefered over the manual detection and pinning of the version:

powerwall.detect_and_pin_version()

Errors

As the powerwall REST API varies widley between version and country it may happen that an attribute may not be included in your response. If that is the case a MissingAttributeError will be thrown indicating what attribute wasn't available.

Response

Responses are usally wrapped inside a Response object to provide convenience methods. An Example is the Meter class which is a sublass of Response. Each Response object includes the response member which consists of the plain json response.

from helpers import assert_attribute

status = powerwall.get_status()
#=> <PowerwallStatus ...>

status.version
# is the same as
assert_attribute(status.response, "version")
# or
status.assert_attribute("version)

Battery level

Get charge in percent:

powerwall.get_charge()
#=> 97.59281925744594

Powerwall Status

status = powerwall.get_status()
#=> <PowerwallStatus ...>
status.version
#=> '1.49.0'
status.up_time_seconds
#=> datetime.timedelta(days=13, seconds=63287, microseconds=146455)
status.start_time
#=> datetime.datetime(2020, 9, 23, 23, 31, 16, tzinfo=datetime.timezone(datetime.timedelta(seconds=28800)))
status.device_type
#=> DeviceType.GW2

Sitemaster

sm = powerwall.sitemaster 
#=> <SiteMaster ...>
sm.status 
#=> StatusUp
sm.running
#=> true
sm.connected_to_tesla
#=> true

Siteinfo

info = powerwall.get_site_info()
#=> <SiteInfo ...>
info.site_name
#=> 'Tesla Home'
info.country
#=> 'Germany'
info.nominal_system_energy
#=> 13.5
info.timezone
#=> 'Europe/Berlin'

Meters

Aggregates

from tesla_powerwall import MeterType

meters = powerwall.get_meters()
#=> <MetersAggregates ...>
meters.solar
#=> <Meter ...>

meters.get_meter(MeterType.SOLAR)
#=> <Meter ...>

Available meters are: solar, site, load and battery

Current power supply/draw

Meter provides different methods for checking current power supply/draw:

meters = powerwall.get_meters()
meters.solar.get_power()
#=> 0.4 (in kWh)
meters.solar.instant_power
#=> 409.941801071167 (in watts)
meters.solar.is_drawing_from()
#=> True
meters.load.is_sending_to()
#=> True
meters.battery.is_active()
#=> False

# Different precision settings might return different results
meters.battery.is_active(precision=5)
#=> True

Note: For MeterType.LOAD is_drawing_from always returns False because it cannot be drawn from load.

Meter.get_power is just a convenience method which is equivalent to:

from tesla_powerwall.helpers import convert_to_kw

convert_to_kw(meters.solar.instant_power, precision=1)

Energy exported/imported

Get energy exported/imported in watts with energy_exported and energy_imported. For the values in kWh use get_energy_exported and get_energy_imported:

meters.battery.energy_exported
#=> 6394100
meters.battery.get_energy_exported()
#=> 6394.1
meters.battery.energy_imported
#=> 7576570
meters.battery.get_energy_imported()
#=> 7576.6

Device Type

powerwall.get_devie_type()
#=> <DeviceType.GW1: 'hec'>

Grid Status

Get current grid status.

powerwall.get_grid_status()
#=> <GridStatus.Connected: 'SystemGridConnected'>
powerwall.get_grid_services_active()
#=> False

Operation mode

powerwall.get_operation_mode()
#=> <OperationMode.SELF_CONSUMPTION: ...>
powerwall.get_backup_reserved_percentage()
#=> 5.000019999999999

Powerwalls Serial Numbers

serials = powerwall.get_serial_numbers()
#=> ["...", "...", ...]

VIN

vin = powerwall.get_vin()