Skip to content

Commit 666abe4

Browse files
Bre77Bre77
committed
Add detailed documentation for Tesla Fleet API
--- For more details, open the [Copilot Workspace session](https://copilot-workspace.githubnext.com/Teslemetry/python-tesla-fleet-api?shareId=XXXX-XXXX-XXXX-XXXX).
1 parent 30d2788 commit 666abe4

7 files changed

Lines changed: 1377 additions & 42 deletions

File tree

‎README.md‎

Lines changed: 138 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,70 @@
1-
# Tesla Fleet Api
2-
Python library for Tesla Fleet API and Tesla Command Protocol, including signed commands and encrypted local Bluetooth (BLE). Also provides interfaces for Teslemetry and Tessie.
1+
# Tesla Fleet API
32

4-
Based on [Tesla Developer documentation](https://developer.tesla.com/docs/fleet-api) and [Tesla Command Protocol](https://github.com/teslamotors/vehicle-command/blob/main/pkg/protocol/protocol.md)
3+
Tesla Fleet API is a Python library that provides an interface to interact with Tesla's Fleet API, including signed commands and encrypted local Bluetooth (BLE) communication. It also supports interactions with Teslemetry and Tessie services.
54

6-
**Documentation is currently outdated for V1.0.X**
5+
## Features
76

8-
## TeslaFleetApi
9-
This is the base class, however can also be used directly if you have a valid user access_token.
7+
- Fleet API for vehicles
8+
- Fleet API for energy sites
9+
- Fleet API with signed vehicle commands
10+
- Bluetooth for vehicles
11+
- Teslemetry integration
12+
- Tessie integration
1013

14+
## Installation
15+
16+
You can install the library using pip:
17+
18+
```bash
19+
pip install tesla-fleet-api
1120
```
21+
22+
## Usage
23+
24+
### Authentication
25+
26+
The `TeslaFleetOAuth` class provides methods that help with authenticating to the Tesla Fleet API. Here's a basic example:
27+
28+
```python
1229
import asyncio
1330
import aiohttp
31+
from tesla_fleet_api import TeslaFleetOAuth
32+
33+
async def main():
34+
async with aiohttp.ClientSession() as session:
35+
oauth = TeslaFleetOAuth(
36+
session=session,
37+
client_id="<client_id>",
38+
client_secret="<client_secret>",
39+
redirect_uri="<redirect_uri>",
40+
)
41+
42+
# Get the login URL and navigate the user to it
43+
login_url = oauth.get_login_url(scopes=["openid", "email", "offline_access"])
44+
print(f"Please go to {login_url} and authorize access.")
45+
46+
# After the user authorizes access, they will be redirected to the redirect_uri with a code
47+
code = input("Enter the code you received: ")
48+
49+
# Exchange the code for a refresh token
50+
await oauth.get_refresh_token(code)
51+
print(f"Access token: {oauth.access_token}")
52+
print(f"Refresh token: {oauth.refresh_token}")
53+
# Dont forget to store the refresh token so you can use it again later
54+
55+
asyncio.run(main())
56+
```
57+
58+
### Fleet API for Vehicles
1459

60+
The `TeslaFleetApi` class provides methods to interact with the Fleet API for vehicles. Here's a basic example:
61+
62+
```python
63+
import asyncio
64+
import aiohttp
1565
from tesla_fleet_api import TeslaFleetApi
1666
from tesla_fleet_api.exceptions import TeslaFleetError
1767

18-
1968
async def main():
2069
async with aiohttp.ClientSession() as session:
2170
api = TeslaFleetApi(
@@ -25,64 +74,108 @@ async def main():
2574
)
2675

2776
try:
28-
data = await api.vehicle.list()
77+
data = await api.vehicles.list()
2978
print(data)
3079
except TeslaFleetError as e:
3180
print(e)
3281

3382
asyncio.run(main())
3483
```
3584

36-
## TeslaFleetOAuth
37-
This extends TeslaFleetApi to support OAuth, and requires a client_id, and either a refresh_token or initial authentication code.
85+
For more detailed examples, see [Fleet API for Vehicles](docs/fleet_api_vehicles.md).
3886

39-
```
40-
from tesla_fleet_api import TeslaFleetOAuth
87+
### Fleet API for Energy Sites
88+
89+
The `EnergySites` class provides methods to interact with the Fleet API for energy sites. Here's a basic example:
90+
91+
```python
92+
import asyncio
93+
import aiohttp
94+
from tesla_fleet_api import TeslaFleetApi
4195
from tesla_fleet_api.exceptions import TeslaFleetError
42-
import json
4396

4497
async def main():
45-
with open("auth.json", "r") as f:
46-
auth = json.load(f)
4798
async with aiohttp.ClientSession() as session:
48-
api = TeslaFleetOAuth(
49-
session,
50-
client_id=<client_id>,
51-
access_token=auth["access_token"],
52-
refresh_token=auth["refresh_token"],
53-
expires=auth["expires"],
99+
api = TeslaFleetApi(
100+
access_token="<access_token>",
101+
session=session,
54102
region="na",
55103
)
104+
56105
try:
57-
data = await api.vehicle.list()
58-
print(data)
106+
energy_sites = await api.energySites.list()
107+
print(energy_sites)
59108
except TeslaFleetError as e:
60109
print(e)
61110

62-
with open("auth.json", "w") as f:
63-
json.dump(
64-
{
65-
"access_token": api.access_token,
66-
"refresh_token": api.refresh_token,
67-
"expires": api.expires,
68-
},
69-
f,
111+
asyncio.run(main())
112+
```
113+
114+
For more detailed examples, see [Fleet API for Energy Sites](docs/fleet_api_energy_sites.md).
115+
116+
### Fleet API with Signed Vehicle Commands
117+
118+
The `VehicleSigned` class provides methods to interact with the Fleet API using signed vehicle commands. Here's a basic example:
119+
120+
```python
121+
import asyncio
122+
import aiohttp
123+
from tesla_fleet_api import TeslaFleetApi
124+
from tesla_fleet_api.tesla.vehicle.signed import VehicleSigned
125+
from tesla_fleet_api.exceptions import TeslaFleetError
126+
127+
async def main():
128+
async with aiohttp.ClientSession() as session:
129+
api = TeslaFleetApi(
130+
access_token="<access_token>",
131+
session=session,
132+
region="na",
70133
)
71134

135+
try:
136+
vehicle = VehicleSigned(api, "<vin>")
137+
await vehicle.handshake()
138+
data = await vehicle.wake_up()
139+
print(data)
140+
except TeslaFleetError as e:
141+
print(e)
142+
72143
asyncio.run(main())
73144
```
74145

75-
## Teslemetry
76-
This extends TeslaFleetApi to send requests through Teslemetry, which manages all aspects of Tesla OAuth. This class only requires an access_token from the Teslemetry console.
146+
For more detailed examples, see [Fleet API with Signed Vehicle Commands](docs/fleet_api_signed_commands.md).
77147

148+
### Bluetooth for Vehicles
149+
150+
The `TeslaBluetooth` class provides methods to interact with Tesla vehicles using Bluetooth. Here's a basic example:
151+
152+
```python
153+
import asyncio
154+
from bleak import BleakScanner
155+
from tesla_fleet_api import TeslaBluetooth
156+
157+
async def main():
158+
scanner = BleakScanner()
159+
devices = await scanner.discover()
160+
for device in devices:
161+
if TeslaBluetooth().valid_name(device.name):
162+
print(f"Found Tesla vehicle: {device.name}")
163+
164+
asyncio.run(main())
78165
```
166+
167+
For more detailed examples, see [Bluetooth for Vehicles](docs/bluetooth_vehicles.md).
168+
169+
### Teslemetry
170+
171+
The `Teslemetry` class provides methods to interact with the Teslemetry service. Here's a basic example:
172+
173+
```python
79174
import asyncio
80175
import aiohttp
81-
82176
from tesla_fleet_api import Teslemetry
83177
from tesla_fleet_api.exceptions import TeslaFleetError
84178

85-
86179
async def main():
87180
async with aiohttp.ClientSession() as session:
88181
api = Teslemetry(
@@ -91,25 +184,26 @@ async def main():
91184
)
92185

93186
try:
94-
data = await api.vehicle.list()
187+
data = await api.vehicles.list()
95188
print(data)
96189
except TeslaFleetError as e:
97190
print(e)
98191

99192
asyncio.run(main())
100193
```
101194

102-
## Tessie
103-
This extends TeslaFleetApi to send requests through Tessie, which manages all aspects of Tesla OAuth. This class only requires an access_token from [Tessie](https://dash.tessie.com/settings/api).
195+
For more detailed examples, see [Teslemetry](docs/teslemetry.md).
104196

105-
```
197+
### Tessie
198+
199+
The `Tessie` class provides methods to interact with the Tessie service. Here's a basic example:
200+
201+
```python
106202
import asyncio
107203
import aiohttp
108-
109204
from tesla_fleet_api import Tessie
110205
from tesla_fleet_api.exceptions import TeslaFleetError
111206

112-
113207
async def main():
114208
async with aiohttp.ClientSession() as session:
115209
api = Tessie(
@@ -118,10 +212,12 @@ async def main():
118212
)
119213

120214
try:
121-
data = await api.vehicle.list()
215+
data = await api.vehicles.list()
122216
print(data)
123217
except TeslaFleetError as e:
124218
print(e)
125219

126220
asyncio.run(main())
127221
```
222+
223+
For more detailed examples, see [Tessie](docs/tessie.md).

‎docs/bluetooth_vehicles.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Detailed Examples for Using Bluetooth for Vehicles
2+
3+
This document provides detailed examples for using the `TeslaBluetooth` class to interact with Tesla vehicles using Bluetooth.
4+
5+
## Example 1: Discovering Tesla Vehicles
6+
7+
The following example demonstrates how to discover Tesla vehicles using Bluetooth:
8+
9+
```python
10+
import asyncio
11+
from bleak import BleakScanner
12+
from tesla_fleet_api import TeslaBluetooth
13+
14+
async def main():
15+
scanner = BleakScanner()
16+
devices = await scanner.discover()
17+
for device in devices:
18+
if TeslaBluetooth().valid_name(device.name):
19+
print(f"Found Tesla vehicle: {device.name}")
20+
21+
asyncio.run(main())
22+
```
23+
24+
## Example 2: Querying Display Name
25+
26+
The following example demonstrates how to query the display name of a Tesla vehicle using Bluetooth:
27+
28+
```python
29+
import asyncio
30+
from bleak import BleakScanner
31+
from tesla_fleet_api import TeslaBluetooth
32+
33+
async def main():
34+
scanner = BleakScanner()
35+
devices = await scanner.discover()
36+
for device in devices:
37+
if TeslaBluetooth().valid_name(device.name):
38+
print(f"Found Tesla vehicle: {device.name}")
39+
name = await TeslaBluetooth().query_display_name(device)
40+
print(f"Display name: {name}")
41+
42+
asyncio.run(main())
43+
```
44+
45+
## Example 3: Connecting to a Tesla Vehicle
46+
47+
The following example demonstrates how to connect to a Tesla vehicle using Bluetooth:
48+
49+
```python
50+
import asyncio
51+
from bleak import BleakScanner
52+
from tesla_fleet_api import TeslaBluetooth
53+
54+
async def main():
55+
scanner = BleakScanner()
56+
devices = await scanner.discover()
57+
for device in devices:
58+
if TeslaBluetooth().valid_name(device.name):
59+
print(f"Found Tesla vehicle: {device.name}")
60+
async with TeslaBluetooth() as bluetooth:
61+
await bluetooth.connect(device)
62+
print("Connected to Tesla vehicle")
63+
64+
asyncio.run(main())
65+
```
66+
67+
## Example 4: Querying Vehicle Data
68+
69+
The following example demonstrates how to query vehicle data from a Tesla vehicle using Bluetooth:
70+
71+
```python
72+
import asyncio
73+
from bleak import BleakScanner
74+
from tesla_fleet_api import TeslaBluetooth, BluetoothVehicleData
75+
76+
async def main():
77+
scanner = BleakScanner()
78+
devices = await scanner.discover()
79+
for device in devices:
80+
if TeslaBluetooth().valid_name(device.name):
81+
print(f"Found Tesla vehicle: {device.name}")
82+
async with TeslaBluetooth() as bluetooth:
83+
await bluetooth.connect(device)
84+
data = await bluetooth.vehicle_data([
85+
BluetoothVehicleData.CHARGE_STATE,
86+
BluetoothVehicleData.CLIMATE_STATE,
87+
BluetoothVehicleData.DRIVE_STATE,
88+
])
89+
print(f"Vehicle data: {data}")
90+
91+
asyncio.run(main())
92+
```

0 commit comments

Comments
 (0)