Skip to content

Commit f7811fb

Browse files
Bre77Bre77
authored
Merge pull request #18 from Teslemetry/Bre77/add-documentation
Add detailed documentation for Tesla Fleet API
2 parents 30d2788 + 73d0bd8 commit f7811fb

File tree

7 files changed

+1383
-42
lines changed

7 files changed

+1383
-42
lines changed

‎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: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Bluetooth for Vehicles
2+
3+
This document provides detailed examples for using Bluetooth for vehicles.
4+
5+
## Initialize TeslaBluetooth
6+
7+
The `TeslaBluetooth` class provides methods to interact with Tesla vehicles using Bluetooth. Here's a basic example to initialize the `TeslaBluetooth` class and discover nearby Tesla vehicles:
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+
## Create VehicleBluetooth Instance
25+
26+
You can create a `VehicleBluetooth` instance using the `TeslaBluetooth` class. Here's a basic example to create a `VehicleBluetooth` instance and set the private key from a file:
27+
28+
```python
29+
import asyncio
30+
from tesla_fleet_api import TeslaBluetooth
31+
32+
async def main():
33+
tesla_bluetooth = TeslaBluetooth()
34+
tesla_bluetooth.get_private_key("path/to/private_key.pem")
35+
vehicle = tesla_bluetooth.vehicles.create("<vin>")
36+
vehicle.find_vehicle()
37+
print(f"Created VehicleBluetooth instance for VIN: {vehicle.vin}")
38+
39+
asyncio.run(main())
40+
```
41+
42+
## Pair Vehicle
43+
44+
You can pair a `VehicleBluetooth` instance using the `pair` method. Here's a basic example to pair a `VehicleBluetooth` instance:
45+
46+
```python
47+
import asyncio
48+
from tesla_fleet_api import TeslaBluetooth
49+
50+
async def main():
51+
tesla_bluetooth = TeslaBluetooth()
52+
device = await tesla_bluetooth.find_vehicle()
53+
private_key = tesla_bluetooth.get_private_key("path/to/private_key.pem")
54+
vehicle = tesla_bluetooth.vehicles.create("<vin>")
55+
await vehicle.pair()
56+
print(f"Paired with VehicleBluetooth instance for VIN: {vehicle.vin}")
57+
58+
asyncio.run(main())
59+
```
60+
61+
## Wake Up Vehicle
62+
63+
You can wake up a `VehicleBluetooth` instance using the `wake_up` method. Here's a basic example to wake up a `VehicleBluetooth` instance:
64+
65+
```python
66+
import asyncio
67+
from tesla_fleet_api import TeslaBluetooth
68+
69+
async def main():
70+
tesla_bluetooth = TeslaBluetooth()
71+
device = await tesla_bluetooth.find_vehicle()
72+
private_key = tesla_bluetooth.get_private_key("path/to/private_key.pem")
73+
vehicle = tesla_bluetooth.vehicles.create("<vin>")
74+
await vehicle.wake_up()
75+
print(f"Woke up VehicleBluetooth instance for VIN: {vehicle.vin}")
76+
77+
asyncio.run(main())
78+
```
79+
80+
## Get Vehicle Data
81+
82+
You can get data from a `VehicleBluetooth` instance using the `vehicle_data` method. Here's a basic example to get data from a `VehicleBluetooth` instance:
83+
84+
```python
85+
import asyncio
86+
from tesla_fleet_api import TeslaBluetooth, BluetoothVehicleData
87+
88+
async def main():
89+
tesla_bluetooth = TeslaBluetooth()
90+
device = await tesla_bluetooth.find_vehicle()
91+
private_key = tesla_bluetooth.get_private_key("path/to/private_key.pem")
92+
vehicle = tesla_bluetooth.vehicles.create("<vin>")
93+
data = await vehicle.vehicle_data([BluetoothVehicleData.CHARGE_STATE, BluetoothVehicleData.CLIMATE_STATE])
94+
print(f"Vehicle data for VIN: {vehicle.vin}")
95+
print(data)
96+
97+
asyncio.run(main())
98+
```

0 commit comments

Comments
 (0)