Add detailed documentation for Tesla Fleet API

README.md

@@ -1,21 +1,70 @@
-# Tesla Fleet Api
-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.
+# Tesla Fleet API
 
-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)
+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.
 
-**Documentation is currently outdated for V1.0.X**
+## Features
 
-## TeslaFleetApi
-This is the base class, however can also be used directly if you have a valid user access_token.
+- Fleet API for vehicles
+- Fleet API for energy sites
+- Fleet API with signed vehicle commands
+- Bluetooth for vehicles
+- Teslemetry integration
+- Tessie integration
 
+## Installation
+
+You can install the library using pip:
+
+```bash
+pip install tesla-fleet-api
 ```
+
+## Usage
+
+### Authentication
+
+The `TeslaFleetOAuth` class provides methods that help with authenticating to the Tesla Fleet API. Here's a basic example:
+
+```python
 import asyncio
 import aiohttp
+from tesla_fleet_api import TeslaFleetOAuth
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        oauth = TeslaFleetOAuth(
+            session=session,
+            client_id="<client_id>",
+            client_secret="<client_secret>",
+            redirect_uri="<redirect_uri>",
+        )
+
+        # Get the login URL and navigate the user to it
+        login_url = oauth.get_login_url(scopes=["openid", "email", "offline_access"])
+        print(f"Please go to {login_url} and authorize access.")
+
+        # After the user authorizes access, they will be redirected to the redirect_uri with a code
+        code = input("Enter the code you received: ")
+
+        # Exchange the code for a refresh token
+        await oauth.get_refresh_token(code)
+        print(f"Access token: {oauth.access_token}")
+        print(f"Refresh token: {oauth.refresh_token}")
+        # Dont forget to store the refresh token so you can use it again later
+
+asyncio.run(main())
+```
+
+### Fleet API for Vehicles
 
+The `TeslaFleetApi` class provides methods to interact with the Fleet API for vehicles. Here's a basic example:
+
+```python
+import asyncio
+import aiohttp
 from tesla_fleet_api import TeslaFleetApi
 from tesla_fleet_api.exceptions import TeslaFleetError
 
-
 async def main():
     async with aiohttp.ClientSession() as session:
         api = TeslaFleetApi(
@@ -25,64 +74,108 @@ async def main():
         )
 
         try:
-            data = await api.vehicle.list()
+            data = await api.vehicles.list()
             print(data)
         except TeslaFleetError as e:
             print(e)
 
 asyncio.run(main())
 ```
 
-## TeslaFleetOAuth
-This extends TeslaFleetApi to support OAuth, and requires a client_id, and either a refresh_token or initial authentication code.
+For more detailed examples, see [Fleet API for Vehicles](docs/fleet_api_vehicles.md).
 
-```
-from tesla_fleet_api import TeslaFleetOAuth
+### Fleet API for Energy Sites
+
+The `EnergySites` class provides methods to interact with the Fleet API for energy sites. Here's a basic example:
+
+```python
+import asyncio
+import aiohttp
+from tesla_fleet_api import TeslaFleetApi
 from tesla_fleet_api.exceptions import TeslaFleetError
-import json
 
 async def main():
-    with open("auth.json", "r") as f:
-        auth = json.load(f)
     async with aiohttp.ClientSession() as session:
-        api = TeslaFleetOAuth(
-            session,
-            client_id=<client_id>,
-            access_token=auth["access_token"],
-            refresh_token=auth["refresh_token"],
-            expires=auth["expires"],
+        api = TeslaFleetApi(
+            access_token="<access_token>",
+            session=session,
             region="na",
         )
+
         try:
-            data = await api.vehicle.list()
-            print(data)
+            energy_sites = await api.energySites.list()
+            print(energy_sites)
         except TeslaFleetError as e:
             print(e)
 
-    with open("auth.json", "w") as f:
-        json.dump(
-            {
-                "access_token": api.access_token,
-                "refresh_token": api.refresh_token,
-                "expires": api.expires,
-            },
-            f,
+asyncio.run(main())
+```
+
+For more detailed examples, see [Fleet API for Energy Sites](docs/fleet_api_energy_sites.md).
+
+### Fleet API with Signed Vehicle Commands
+
+The `VehicleSigned` class provides methods to interact with the Fleet API using signed vehicle commands. Here's a basic example:
+
+```python
+import asyncio
+import aiohttp
+from tesla_fleet_api import TeslaFleetApi
+from tesla_fleet_api.tesla.vehicle.signed import VehicleSigned
+from tesla_fleet_api.exceptions import TeslaFleetError
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        api = TeslaFleetApi(
+            access_token="<access_token>",
+            session=session,
+            region="na",
         )
 
+        try:
+            vehicle = VehicleSigned(api, "<vin>")
+            await vehicle.handshake()
+            data = await vehicle.wake_up()
+            print(data)
+        except TeslaFleetError as e:
+            print(e)
+
 asyncio.run(main())
 ```
 
-## Teslemetry
-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.
+For more detailed examples, see [Fleet API with Signed Vehicle Commands](docs/fleet_api_signed_commands.md).
 
+### Bluetooth for Vehicles
+
+The `TeslaBluetooth` class provides methods to interact with Tesla vehicles using Bluetooth. Here's a basic example:
+
+```python
+import asyncio
+from bleak import BleakScanner
+from tesla_fleet_api import TeslaBluetooth
+
+async def main():
+    scanner = BleakScanner()
+    devices = await scanner.discover()
+    for device in devices:
+        if TeslaBluetooth().valid_name(device.name):
+            print(f"Found Tesla vehicle: {device.name}")
+
+asyncio.run(main())
 ```
+
+For more detailed examples, see [Bluetooth for Vehicles](docs/bluetooth_vehicles.md).
+
+### Teslemetry
+
+The `Teslemetry` class provides methods to interact with the Teslemetry service. Here's a basic example:
+
+```python
 import asyncio
 import aiohttp
-
 from tesla_fleet_api import Teslemetry
 from tesla_fleet_api.exceptions import TeslaFleetError
 
-
 async def main():
     async with aiohttp.ClientSession() as session:
         api = Teslemetry(
@@ -91,25 +184,26 @@ async def main():
         )
 
         try:
-            data = await api.vehicle.list()
+            data = await api.vehicles.list()
             print(data)
         except TeslaFleetError as e:
             print(e)
 
 asyncio.run(main())
 ```
 
-## Tessie
-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).
+For more detailed examples, see [Teslemetry](docs/teslemetry.md).
 
-```
+### Tessie
+
+The `Tessie` class provides methods to interact with the Tessie service. Here's a basic example:
+
+```python
 import asyncio
 import aiohttp
-
 from tesla_fleet_api import Tessie
 from tesla_fleet_api.exceptions import TeslaFleetError
 
-
 async def main():
     async with aiohttp.ClientSession() as session:
         api = Tessie(
@@ -118,10 +212,12 @@ async def main():
         )
 
         try:
-            data = await api.vehicle.list()
+            data = await api.vehicles.list()
             print(data)
         except TeslaFleetError as e:
             print(e)
 
 asyncio.run(main())
 ```
+
+For more detailed examples, see [Tessie](docs/tessie.md).

docs/bluetooth_vehicles.md

@@ -0,0 +1,98 @@
+# Bluetooth for Vehicles
+
+This document provides detailed examples for using Bluetooth for vehicles.
+
+## Initialize TeslaBluetooth
+
+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:
+
+```python
+import asyncio
+from bleak import BleakScanner
+from tesla_fleet_api import TeslaBluetooth
+
+async def main():
+    scanner = BleakScanner()
+    devices = await scanner.discover()
+    for device in devices:
+        if TeslaBluetooth().valid_name(device.name):
+            print(f"Found Tesla vehicle: {device.name}")
+
+asyncio.run(main())
+```
+
+## Create VehicleBluetooth Instance
+
+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:
+
+```python
+import asyncio
+from tesla_fleet_api import TeslaBluetooth
+
+async def main():
+    tesla_bluetooth = TeslaBluetooth()
+    tesla_bluetooth.get_private_key("path/to/private_key.pem")
+    vehicle = tesla_bluetooth.vehicles.create("<vin>")
+    vehicle.find_vehicle()
+    print(f"Created VehicleBluetooth instance for VIN: {vehicle.vin}")
+
+asyncio.run(main())
+```
+
+## Pair Vehicle
+
+You can pair a `VehicleBluetooth` instance using the `pair` method. Here's a basic example to pair a `VehicleBluetooth` instance:
+
+```python
+import asyncio
+from tesla_fleet_api import TeslaBluetooth
+
+async def main():
+    tesla_bluetooth = TeslaBluetooth()
+    device = await tesla_bluetooth.find_vehicle()
+    private_key = tesla_bluetooth.get_private_key("path/to/private_key.pem")
+    vehicle = tesla_bluetooth.vehicles.create("<vin>")
+    await vehicle.pair()
+    print(f"Paired with VehicleBluetooth instance for VIN: {vehicle.vin}")
+
+asyncio.run(main())
+```
+
+## Wake Up Vehicle
+
+You can wake up a `VehicleBluetooth` instance using the `wake_up` method. Here's a basic example to wake up a `VehicleBluetooth` instance:
+
+```python
+import asyncio
+from tesla_fleet_api import TeslaBluetooth
+
+async def main():
+    tesla_bluetooth = TeslaBluetooth()
+    device = await tesla_bluetooth.find_vehicle()
+    private_key = tesla_bluetooth.get_private_key("path/to/private_key.pem")
+    vehicle = tesla_bluetooth.vehicles.create("<vin>")
+    await vehicle.wake_up()
+    print(f"Woke up VehicleBluetooth instance for VIN: {vehicle.vin}")
+
+asyncio.run(main())
+```
+
+## Get Vehicle Data
+
+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:
+
+```python
+import asyncio
+from tesla_fleet_api import TeslaBluetooth, BluetoothVehicleData
+
+async def main():
+    tesla_bluetooth = TeslaBluetooth()
+    device = await tesla_bluetooth.find_vehicle()
+    private_key = tesla_bluetooth.get_private_key("path/to/private_key.pem")
+    vehicle = tesla_bluetooth.vehicles.create("<vin>")
+    data = await vehicle.vehicle_data([BluetoothVehicleData.CHARGE_STATE, BluetoothVehicleData.CLIMATE_STATE])
+    print(f"Vehicle data for VIN: {vehicle.vin}")
+    print(data)
+
+asyncio.run(main())
+```