0
# TeslaPy
1

2
A Python implementation based on unofficial documentation of the client side interface to the Tesla Motors Owner API, which provides functionality to monitor and control Tesla products remotely including vehicles, Powerwall batteries, and solar panels.
3

4
## Package Information
5

6
- **Package Name**: TeslaPy
7
- **Language**: Python
8
- **Installation**: `pip install teslapy 'urllib3<2'`
9

10
## Core Imports
11

12
```python
13
import teslapy
14
```
15

16
## Basic Usage
17

18
```python
19
import teslapy
20

21
# Create Tesla session with your email
22
with teslapy.Tesla('elon@tesla.com') as tesla:
23
    # Get list of vehicles
24
    vehicles = tesla.vehicle_list()
25
    
26
    # Wake up the first vehicle
27
    vehicles[0].sync_wake_up()
28
    
29
    # Send a command (open front trunk)
30
    vehicles[0].command('ACTUATE_TRUNK', which_trunk='front')
31
    
32
    # Get vehicle data
33
    vehicles[0].get_vehicle_data()
34
    print(vehicles[0]['vehicle_state']['car_version'])
35
```
36

37
## Architecture
38

39
TeslaPy follows a hierarchical object model that mirrors Tesla's product ecosystem:
40

41
- **Tesla Session**: Main authentication and API session manager extending OAuth2Session
42
- **Vehicle Objects**: Individual Tesla vehicles with control and monitoring capabilities
43
- **Product Objects**: Base class for energy products (Powerwall, solar panels)
44
- **Battery Objects**: Powerwall energy storage systems extending Product
45
- **SolarPanel Objects**: Solar panel installations extending Product
46

47
The library implements Tesla's OAuth 2 Single Sign-On service with automatic token refresh, provides both synchronous API calls and streaming capabilities for real-time data, and includes comprehensive error handling with custom exception classes.
48

49
## Capabilities
50

51
### Authentication and Session Management
52

53
Core authentication functionality using Tesla's OAuth 2 SSO service with support for multiple authentication methods, token caching, and automatic refresh capabilities.
54

55
```python { .api }
56
class Tesla(OAuth2Session):
57
    def __init__(self, email, verify=True, proxy=None, retry=0, timeout=10, 
58
                 user_agent=None, authenticator=None, cache_file='cache.json', 
59
                 cache_loader=None, cache_dumper=None, sso_base_url=None, 
60
                 code_verifier=None, app_user_agent=None, **kwargs): ...
61
    
62
    def fetch_token(self, token_url='oauth2/v3/token', **kwargs): ...
63
    def refresh_token(self, token_url='oauth2/v3/token', **kwargs): ...
64
    def logout(self, sign_out=False): ...
65
```
66

67
[Authentication](./authentication.md)
68

69
### Vehicle Control and Monitoring
70

71
Comprehensive vehicle control functionality including wake-up, status monitoring, climate control, charging management, location tracking, and command execution.
72

73
```python { .api }
74
class Vehicle(JsonDict):
75
    def sync_wake_up(self, timeout=60, interval=2, backoff=1.15): ...
76
    def get_vehicle_data(self, endpoints='location_data;charge_state;climate_state;vehicle_state;gui_settings;vehicle_config'): ...
77
    def command(self, name, **kwargs): ...
78
    def stream(self, callback=None, retry=0, indefinitely=False, **kwargs): ...
79
```
80

81
[Vehicle Control](./vehicle-control.md)
82

83
### Energy Product Management
84

85
Management functionality for Tesla energy products including Powerwall batteries and solar panel installations with status monitoring, configuration, and control capabilities.
86

87
```python { .api }
88
class Battery(Product):
89
    def set_operation(self, mode): ...
90
    def set_backup_reserve_percent(self, percent): ...
91
    def get_tariff(self): ...
92
    def set_tariff(self, tariff_data): ...
93

94
class SolarPanel(Product):
95
    def get_site_data(self): ...
96
```
97

98
[Energy Products](./energy-products.md)
99

100
### Data Processing and Utilities
101

102
Utility functions for data processing, unit conversion, VIN decoding, option code lookup, and error handling with custom exception classes.
103

104
```python { .api }
105
class JsonDict(dict):
106
    def __str__(self): ...
107

108
class VehicleError(Exception): ...
109
class ProductError(Exception): ...
110

111
def decode_vin(self): ...
112
def decode_option(cls, code): ...
113
```
114

115
[Utilities](./utilities.md)
116

117
## Types
118

119
```python { .api }
120
class Tesla(OAuth2Session):
121
    """Main session manager for Tesla Motors Owner API"""
122

123
class Vehicle(JsonDict):
124
    """Vehicle class with dictionary access and API request support"""
125

126
class Product(JsonDict):
127
    """Base product class for energy products"""
128

129
class Battery(Product):
130
    """Powerwall battery class"""
131

132
class SolarPanel(Product):
133
    """Solar panel class"""
134

135
class JsonDict(dict):
136
    """Pretty printing dictionary with JSON string representation"""
137

138
class VehicleError(Exception):
139
    """Vehicle-specific exception class"""
140

141
class ProductError(Exception):
142
    """Product-specific exception class"""
143
```