From a2bc719ef11c2e7f8eba11f047c0a8c0549adad9 Mon Sep 17 00:00:00 2001 From: Julien Date: Wed, 19 Jun 2024 09:29:09 +0200 Subject: [PATCH 1/8] Update docs --- website/docs/guides/api.md | 76 ++++++++++++++++++++++++++++++++++++++ website/sidebars.js | 2 +- 2 files changed, 77 insertions(+), 1 deletion(-) create mode 100644 website/docs/guides/api.md diff --git a/website/docs/guides/api.md b/website/docs/guides/api.md new file mode 100644 index 0000000000..2930e4f050 --- /dev/null +++ b/website/docs/guides/api.md @@ -0,0 +1,76 @@ +--- +title: Using the new Tesla Fleet API and Telemetry streaming +--- + +## Why Tesla Fleet and Telemetry should be needed? + +By default, TeslaMate uses the _unofficial_ Owner API and streaming. + +Tesla now provides official APIs: the Fleet API and the Telemetry API, which replace the Owner API and streaming respectively. + +If the Owner API stops working, the Fleet API will become the only alternative. + +## Impact/limitations of new endpoints + +### Tesla Fleet API + +The [Fleet API](https://developer.tesla.com/docs/fleet-api) is similar to the Owner API but more comprehensive. However, retrieving vehicle information (`vehicle_data`) is limited to 300 hits per day. The limits on the Owner API were historically much higher. + +### Tesla Telemetry + +The [Tesla Telemetry](https://github.com/teslamotors/fleet-telemetry) differs from the "Owner" streaming. By default, metrics are sent to message queues instead of a websocket as streaming did. Historical streaming could send events every second, whereas Telemetry will only send information every minute at the minimum. + +### How to use Tesla APIs? + +To use the official Tesla APIs, you need to create a [Tesla developer account](https://developer.tesla.com/), register an application, and follow a process that requires advanced skills and specific hosting. + +To easily access these APIs, you can use a third-party provider. + +## Guide for third-party + +Environment variables allow changing the API and streaming endpoints. + +You must obtain the `URL` to use for your third-party API calls and the `TOKEN` that serves to identify your calls. + +### [MyTeslaMate](https://www.myteslamate.com) (free) + +Simply log in with your Tesla account and then check the fleet page to get the environment variables to use. + +You must use your `TOKEN` instead of _`xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx`_ + +```yml +# API Fleet +- TOKEN=?token=xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx +- TESLA_API_HOST=https://api.myteslamate.com +- TESLA_AUTH_HOST=https://api.myteslamate.com +- TESLA_AUTH_PATH=/api/oauth2/v3 +``` + +MyTeslaMate also provides streaming by [reproducing the old streaming from the data sent by Telemetry](https://github.com/MyTeslaMate/websocket). + +You need to use dedicated environment variables : + +```yml +# Streaming from Telemetry +- TESLA_WSS_HOST=wss://streaming.myteslamate.com +- TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true +- TESLA_WSS_USE_VIN=true +``` + +### Teslemetry ($) + +You must use your `TOKEN` instead of _`xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx`_ and add the following environment variables. + +_No streaming given, you must disable the streaming in Teslamate settings._ + +```yml +# API Fleet +- TOKEN=?token=xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx +- TESLA_API_HOST=https://api.teslemetry.com +- TESLA_AUTH_HOST=https://api.teslemetry.com +- TESLA_AUTH_PATH=/api/oauth2/v3 +``` + +## Guide for Tesla API + +_TODO_ \ No newline at end of file diff --git a/website/sidebars.js b/website/sidebars.js index 76aade76ef..f5959572af 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -19,7 +19,7 @@ module.exports = { { type: "category", label: "Guides", - items: ["guides/traefik", "guides/apache", "guides/unix_domain_sockets"], + items: ["guides/traefik", "guides/apache", "guides/unix_domain_sockets", "guides/api"], }, { type: "category", From 83f2797e75c44041e689bc80ec830ccc1a425af0 Mon Sep 17 00:00:00 2001 From: Julien Date: Wed, 19 Jun 2024 09:34:45 +0200 Subject: [PATCH 2/8] Update for streaming --- website/docs/guides/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/guides/api.md b/website/docs/guides/api.md index 2930e4f050..3bc1c78a59 100644 --- a/website/docs/guides/api.md +++ b/website/docs/guides/api.md @@ -34,7 +34,7 @@ You must obtain the `URL` to use for your third-party API calls and the `TOKEN` ### [MyTeslaMate](https://www.myteslamate.com) (free) -Simply log in with your Tesla account and then check the fleet page to get the environment variables to use. +Simply log in with your Tesla account and go to the [MyTeslamate Fleet](https://app.myteslamate.com/fleet) page to get your `TOKEN`. You must use your `TOKEN` instead of _`xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx`_ @@ -48,7 +48,7 @@ You must use your `TOKEN` instead of _`xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx`_ MyTeslaMate also provides streaming by [reproducing the old streaming from the data sent by Telemetry](https://github.com/MyTeslaMate/websocket). -You need to use dedicated environment variables : +You need to "_Pair your vehicle(s)_" on the [MyTeslamate Fleet](https://app.myteslamate.com/fleet) page and then use dedicated environment variables : ```yml # Streaming from Telemetry From 81db679f48a00c9a093d598725e80b2bb57f13f2 Mon Sep 17 00:00:00 2001 From: Julien Date: Wed, 19 Jun 2024 14:20:29 +0200 Subject: [PATCH 3/8] Update guides and add a reference in the project page --- website/docs/guides/api.md | 87 ++++++++++++++++++++++++++++---------- website/docs/projects.md | 12 +++++- 2 files changed, 76 insertions(+), 23 deletions(-) diff --git a/website/docs/guides/api.md b/website/docs/guides/api.md index 3bc1c78a59..8fcc16d278 100644 --- a/website/docs/guides/api.md +++ b/website/docs/guides/api.md @@ -1,40 +1,46 @@ --- -title: Using the new Tesla Fleet API and Telemetry streaming +title: Using the Official Tesla Fleet API and Telemetry Streaming --- -## Why Tesla Fleet and Telemetry should be needed? +## Why Tesla Fleet and Telemetry are Needed -By default, TeslaMate uses the _unofficial_ Owner API and streaming. +By default, TeslaMate uses the _unofficial_ Owner API and streaming. Tesla now provides official APIs: the Fleet API and the Telemetry API, which replace the Owner API and streaming respectively. -If the Owner API stops working, the Fleet API will become the only alternative. +**Migration to the new API depends on your Tesla account type:** -## Impact/limitations of new endpoints +1. **_Tesla Business Fleet users:_** the Owner API is [being shut down](https://developer.tesla.com/docs/fleet-api#2024-03-26-shutting-down-legacy-vehicle-api-endpoints) for Tesla Business Fleet users. This is done gradually and an error message means that they must now use the official API. + +1. **_Individual users:_** the Owner API is currently still accessible. Even if it seems to incorporate new limitations similar to those present on the official API. + +**Resume: if you are a Tesla Business Fleet user, you should migrate to the official API ASAP!** The official Tesla API will only become mandatory when the Owner API shuts down for all users. + +## Impact/Limitations of New Endpoints ### Tesla Fleet API The [Fleet API](https://developer.tesla.com/docs/fleet-api) is similar to the Owner API but more comprehensive. However, retrieving vehicle information (`vehicle_data`) is limited to 300 hits per day. The limits on the Owner API were historically much higher. -### Tesla Telemetry +### Tesla Fleet Telemetry -The [Tesla Telemetry](https://github.com/teslamotors/fleet-telemetry) differs from the "Owner" streaming. By default, metrics are sent to message queues instead of a websocket as streaming did. Historical streaming could send events every second, whereas Telemetry will only send information every minute at the minimum. +The [Tesla Fleet Telemetry](https://github.com/teslamotors/fleet-telemetry) differs from the "Owner" streaming. By default, metrics are sent to message queues instead of a websocket as streaming did. Historical streaming could send events every second, whereas Fleet Telemetry will only send information every minute at the minimum. -### How to use Tesla APIs? +### How to Use Tesla APIs -To use the official Tesla APIs, you need to create a [Tesla developer account](https://developer.tesla.com/), register an application, and follow a process that requires advanced skills and specific hosting. +The process to use the official Tesla APIs is complex. -To easily access these APIs, you can use a third-party provider. +You can use a third-party provider to easily access these APIs. -## Guide for third-party +## Guide for Third-Party Providers Environment variables allow changing the API and streaming endpoints. You must obtain the `URL` to use for your third-party API calls and the `TOKEN` that serves to identify your calls. ### [MyTeslaMate](https://www.myteslamate.com) (free) - -Simply log in with your Tesla account and go to the [MyTeslamate Fleet](https://app.myteslamate.com/fleet) page to get your `TOKEN`. +#### MyTeslaMate Fleet API +Log in the [MyTeslaMate](https://app.myteslamate.com) website **with your Tesla account** and go to the [MyTeslaMate Fleet](https://app.myteslamate.com/fleet) page to get your `TOKEN`. You must use your `TOKEN` instead of _`xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx`_ @@ -46,22 +52,22 @@ You must use your `TOKEN` instead of _`xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx`_ - TESLA_AUTH_PATH=/api/oauth2/v3 ``` -MyTeslaMate also provides streaming by [reproducing the old streaming from the data sent by Telemetry](https://github.com/MyTeslaMate/websocket). +#### MyTeslaMate Streaming +MyTeslaMate also provides streaming by [reproducing the old streaming from the data sent by Fleet Telemetry](https://github.com/MyTeslaMate/websocket). -You need to "_Pair your vehicle(s)_" on the [MyTeslamate Fleet](https://app.myteslamate.com/fleet) page and then use dedicated environment variables : +You need to "_Pair your vehicle(s)_" on the [fleet](https://app.myteslamate.com/fleet) page and then use the following dedicated environment variables: ```yml -# Streaming from Telemetry +# Streaming from Fleet Telemetry - TESLA_WSS_HOST=wss://streaming.myteslamate.com - TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true - TESLA_WSS_USE_VIN=true ``` -### Teslemetry ($) - -You must use your `TOKEN` instead of _`xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx`_ and add the following environment variables. +### [Teslemetry](https://teslemetry.com/pricing) (paid) -_No streaming given, you must disable the streaming in Teslamate settings._ +#### Teslemetry Fleet API +Log in the [Teslemetry website](https://teslemetry.com) and create your `TOKEN`. Use this `TOKEN` instead of _`xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx`_ and add the following environment variables. ```yml # API Fleet @@ -71,6 +77,43 @@ _No streaming given, you must disable the streaming in Teslamate settings._ - TESLA_AUTH_PATH=/api/oauth2/v3 ``` -## Guide for Tesla API +#### Streaming +**_Important: no streaming provided by Teslemetry, you MUST disable manually the streaming in Teslamate settings._** -_TODO_ \ No newline at end of file +## Guide for official Tesla API + +_This solution requires advanced skills._ + +### Tesla Fleet API +You can follow the official [Setup documentation](https://developer.tesla.com/docs/fleet-api#setup): +1. Set up a third-party account at [developer.tesla.com](https://developer.tesla.com) +1. Complete registration of an account: you need to share your public key on a public domain (eg: _api.mydomain.com_) +1. Request authorization permissions from a customer: _the generation of tokens usable in Teslamate no longer requires a third-party application as with the Owner API_ +4. Send drivers a "Pairing request" to be able to use your own [Tesla Vehicle Command Protocol http proxy to send commands](https://github.com/teslamotors/vehicle-command?tab=readme-ov-file#using-the-http-proxy). +This proxy must be accessible from your Teslamate instance. You need to host this http proxy on the same domain +1. Add the following environment variable with your own domain : +```yml +# API Fleet +- TESLA_API_HOST=https://api.mydomain.com +``` + +_Authentication endpoint remains unchanged. Teslamate will take care of the tokens renewal as usual._ + +### Tesla Streaming + +**_Important: if you don't setup the streaming, you MUST disable manually the streaming in Teslamate settings._** + +To get your own streaming server, you can follow these steps: +1. Setup a [Tesla Fleet Telemetry](https://github.com/teslamotors/fleet-telemetry) instance on a public domain (eg: _telemetry.mydomain.com_) +1. Add a [Google pubsub dispatcher](https://github.com/teslamotors/fleet-telemetry?tab=readme-ov-file#backendsdispatchers) to your own GCP PubSub. +1. Setup a [Streaming Server from Fleet Telemetry Events](https://github.com/MyTeslaMate/websocket) on a public domain (eg: _streaming.mydomain.com_) +1. Manually create a subscription to the `telemetry_V` PubSub with: + - Delivery type: Push + - Endpoint URL: https://streaming.mydomain.com +1. Update your environment variables: + +```yml +- TESLA_WSS_HOST=wss://streaming.mydomain.com +- TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true +- TESLA_WSS_USE_VIN=true +``` \ No newline at end of file diff --git a/website/docs/projects.md b/website/docs/projects.md index 446275f6d8..ae64d5c3aa 100644 --- a/website/docs/projects.md +++ b/website/docs/projects.md @@ -79,4 +79,14 @@ LINK: [https://github.com/brchri/tesla-geogdo](https://github.com/brchri/tesla-g Raspberry Pi project that installs along Tesla's standard USB drive, sends video alerts in real-time & backs up all footage, now comes pre-installed with TeslaMate. -LINK: [https://www.teslarpi.com) +LINK: [https://www.teslarpi.com](https://www.teslarpi.com) + +## [MyTeslaMate](https://www.myteslamate.com) + +For those who do not wish to install their own instance, MyTeslaMate provides a managed instance of TeslaMate ready to use in one minute, with a security overlay (Authelia), 30-day backups, and the possibility of importing a backup to migrate easily. + +For all [TeslaMate](https://www.myteslamate.com) users, MyTeslaMate also provides for free a [Fleet API](https://app.myteslamate.com/fleet) endpoint and a streaming server based on Tesla Telemetry events. + +LINK: [MyTeslaMate Website](https://www.myteslamate.com) + +LINK: [Follow this guide](/docs/guides/api#myteslamate-fleet-api) to use official Tesla APIs on your Teslamate. From 07ab0fdbf36ef709334d504fa7e32c6b2301dc96 Mon Sep 17 00:00:00 2001 From: Julien Date: Wed, 19 Jun 2024 15:22:21 +0200 Subject: [PATCH 4/8] Update for readability --- website/docs/guides/api.md | 64 ++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 34 deletions(-) diff --git a/website/docs/guides/api.md b/website/docs/guides/api.md index 8fcc16d278..3d5f72dcab 100644 --- a/website/docs/guides/api.md +++ b/website/docs/guides/api.md @@ -10,7 +10,7 @@ Tesla now provides official APIs: the Fleet API and the Telemetry API, which rep **Migration to the new API depends on your Tesla account type:** -1. **_Tesla Business Fleet users:_** the Owner API is [being shut down](https://developer.tesla.com/docs/fleet-api#2024-03-26-shutting-down-legacy-vehicle-api-endpoints) for Tesla Business Fleet users. This is done gradually and an error message means that they must now use the official API. +1. **_[Tesla Business Fleet users](https://www.tesla.com/fleet):_** the Owner API is [being shut down](https://developer.tesla.com/docs/fleet-api#2024-03-26-shutting-down-legacy-vehicle-api-endpoints). Fleet vehicles are upgraded gradually and an error message means that they must now use the official API. 1. **_Individual users:_** the Owner API is currently still accessible. Even if it seems to incorporate new limitations similar to those present on the official API. @@ -29,24 +29,21 @@ The [Tesla Fleet Telemetry](https://github.com/teslamotors/fleet-telemetry) diff ### How to Use Tesla APIs The process to use the official Tesla APIs is complex. - You can use a third-party provider to easily access these APIs. ## Guide for Third-Party Providers Environment variables allow changing the API and streaming endpoints. - You must obtain the `URL` to use for your third-party API calls and the `TOKEN` that serves to identify your calls. ### [MyTeslaMate](https://www.myteslamate.com) (free) #### MyTeslaMate Fleet API -Log in the [MyTeslaMate](https://app.myteslamate.com) website **with your Tesla account** and go to the [MyTeslaMate Fleet](https://app.myteslamate.com/fleet) page to get your `TOKEN`. - -You must use your `TOKEN` instead of _`xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx`_ +1. Log in the [MyTeslaMate](https://app.myteslamate.com) website **with your Tesla account** and go to the [MyTeslaMate Fleet](https://app.myteslamate.com/fleet) page to get your `TOKEN`. +1. Add the following environment variables (using your `TOKEN` instead of _`xxxx-xxxx-xxxx-xxxx`_): ```yml # API Fleet -- TOKEN=?token=xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx +- TOKEN=?token=xxxx-xxxx-xxxx-xxxx - TESLA_API_HOST=https://api.myteslamate.com - TESLA_AUTH_HOST=https://api.myteslamate.com - TESLA_AUTH_PATH=/api/oauth2/v3 @@ -55,27 +52,27 @@ You must use your `TOKEN` instead of _`xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx`_ #### MyTeslaMate Streaming MyTeslaMate also provides streaming by [reproducing the old streaming from the data sent by Fleet Telemetry](https://github.com/MyTeslaMate/websocket). -You need to "_Pair your vehicle(s)_" on the [fleet](https://app.myteslamate.com/fleet) page and then use the following dedicated environment variables: - -```yml -# Streaming from Fleet Telemetry -- TESLA_WSS_HOST=wss://streaming.myteslamate.com -- TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true -- TESLA_WSS_USE_VIN=true -``` +1. You need to "_Pair your vehicle(s)_" on the [fleet](https://app.myteslamate.com/fleet) page +1. Use the following dedicated environment variables: + ```yml + - TESLA_WSS_HOST=wss://streaming.myteslamate.com + - TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true + - TESLA_WSS_USE_VIN=true + ``` +1. Restart your instance ### [Teslemetry](https://teslemetry.com/pricing) (paid) #### Teslemetry Fleet API -Log in the [Teslemetry website](https://teslemetry.com) and create your `TOKEN`. Use this `TOKEN` instead of _`xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx`_ and add the following environment variables. - -```yml -# API Fleet -- TOKEN=?token=xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx -- TESLA_API_HOST=https://api.teslemetry.com -- TESLA_AUTH_HOST=https://api.teslemetry.com -- TESLA_AUTH_PATH=/api/oauth2/v3 -``` +1. Log in the [Teslemetry website](https://teslemetry.com) and create your `TOKEN`. +1. Use this `TOKEN` instead of _`xxxx-xxxx-xxxx-xxxx`_ and add the following environment variables: + ```yml + - TOKEN=?token=xxxx-xxxx-xxxx-xxxx + - TESLA_API_HOST=https://api.teslemetry.com + - TESLA_AUTH_HOST=https://api.teslemetry.com + - TESLA_AUTH_PATH=/api/oauth2/v3 + ``` +1. Restart your instance #### Streaming **_Important: no streaming provided by Teslemetry, you MUST disable manually the streaming in Teslamate settings._** @@ -101,19 +98,18 @@ _Authentication endpoint remains unchanged. Teslamate will take care of the toke ### Tesla Streaming -**_Important: if you don't setup the streaming, you MUST disable manually the streaming in Teslamate settings._** +**_Important: if you don't setup your own streaming, you MUST disable manually the streaming in Teslamate settings._** -To get your own streaming server, you can follow these steps: +To setup your own streaming server, you can follow these steps: 1. Setup a [Tesla Fleet Telemetry](https://github.com/teslamotors/fleet-telemetry) instance on a public domain (eg: _telemetry.mydomain.com_) 1. Add a [Google pubsub dispatcher](https://github.com/teslamotors/fleet-telemetry?tab=readme-ov-file#backendsdispatchers) to your own GCP PubSub. -1. Setup a [Streaming Server from Fleet Telemetry Events](https://github.com/MyTeslaMate/websocket) on a public domain (eg: _streaming.mydomain.com_) -1. Manually create a subscription to the `telemetry_V` PubSub with: +1. Setup a [MyTeslaMate Streaming Server from Fleet Telemetry Events](https://github.com/MyTeslaMate/websocket) on a public domain (eg: _streaming.mydomain.com_) +1. Manually create a subscription to the `telemetry_V` created in PubSub by the Tesla Telemetry with: - Delivery type: Push - Endpoint URL: https://streaming.mydomain.com 1. Update your environment variables: - -```yml -- TESLA_WSS_HOST=wss://streaming.mydomain.com -- TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true -- TESLA_WSS_USE_VIN=true -``` \ No newline at end of file + ```yml + - TESLA_WSS_HOST=wss://streaming.mydomain.com + - TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true + - TESLA_WSS_USE_VIN=true + ``` From 3258e53124da89265bcfa4980177ccce3c9b0bd4 Mon Sep 17 00:00:00 2001 From: Julien Date: Wed, 19 Jun 2024 15:41:35 +0200 Subject: [PATCH 5/8] readability --- website/docs/guides/api.md | 64 ++++++++++++++++++++++++++------------ 1 file changed, 44 insertions(+), 20 deletions(-) diff --git a/website/docs/guides/api.md b/website/docs/guides/api.md index 3d5f72dcab..3f33c8ba7a 100644 --- a/website/docs/guides/api.md +++ b/website/docs/guides/api.md @@ -2,7 +2,28 @@ title: Using the Official Tesla Fleet API and Telemetry Streaming --- -## Why Tesla Fleet and Telemetry are Needed +## Table of Contents + +- [Official Tesla APIs](#official-tesla-apis) + - [Why Tesla Fleet and Telemetry are Needed](#why-tesla-fleet-and-telemetry-are-needed) + - [Impacts/Limitations of New Endpoints](#impactslimitations-of-new-endpoints) + - [Tesla Fleet API: no impact](#tesla-fleet-api-no-impact) + - [Tesla Fleet Telemetry: non compatible by default](#tesla-fleet-telemetry-non-compatible-by-default) + - [How to Use Tesla APIs](#how-to-use-tesla-apis) +- [Guide for Third-Party Providers](#guide-for-third-party-providers) + - [MyTeslaMate (free)](#myteslamate-free) + - [MyTeslaMate Fleet API](#myteslamate-fleet-api) + - [MyTeslaMate Streaming](#myteslamate-streaming) + - [Teslemetry (paid)](#teslemetry-paid) + - [Teslemetry Fleet API](#teslemetry-fleet-api) + - [Teslemetry Streaming](#teslemetry-streaming) +- [Guide for Official Tesla API](#guide-for-official-tesla-api) + - [Requirements](#requirements) + - [Tesla Fleet API](#tesla-fleet-api) + - [Streaming via Tesla Telemetry](#streaming-via-tesla-telemetry) + +## Official Tesla APIs +### Why Tesla Fleet and Telemetry are Needed By default, TeslaMate uses the _unofficial_ Owner API and streaming. @@ -16,28 +37,28 @@ Tesla now provides official APIs: the Fleet API and the Telemetry API, which rep **Resume: if you are a Tesla Business Fleet user, you should migrate to the official API ASAP!** The official Tesla API will only become mandatory when the Owner API shuts down for all users. -## Impact/Limitations of New Endpoints +### Impacts/Limitations of New Endpoints -### Tesla Fleet API +#### Tesla Fleet API: no impact -The [Fleet API](https://developer.tesla.com/docs/fleet-api) is similar to the Owner API but more comprehensive. However, retrieving vehicle information (`vehicle_data`) is limited to 300 hits per day. The limits on the Owner API were historically much higher. +The [Fleet API](https://developer.tesla.com/docs/fleet-api) is similar to the Owner API but more comprehensive. However, retrieving vehicle information (`vehicle_data`) or sending commands is limited. The limits on the Owner API were historically much higher. It is likely that [these limits](https://developer.tesla.com/docs/fleet-api#membership-levels) will also be applied soon to the API Owner. -### Tesla Fleet Telemetry +#### Tesla Fleet Telemetry: non compatible by default The [Tesla Fleet Telemetry](https://github.com/teslamotors/fleet-telemetry) differs from the "Owner" streaming. By default, metrics are sent to message queues instead of a websocket as streaming did. Historical streaming could send events every second, whereas Fleet Telemetry will only send information every minute at the minimum. -### How to Use Tesla APIs +#### How to Use Tesla APIs -The process to use the official Tesla APIs is complex. -You can use a third-party provider to easily access these APIs. +The setup to use the official Tesla APIs ([described below](#tesla-fleet-api)) is complex. +You can use a [third-party providers](#guide-for-third-party-providers) to easily access these APIs. -## Guide for Third-Party Providers +### Guide for Third-Party Providers Environment variables allow changing the API and streaming endpoints. -You must obtain the `URL` to use for your third-party API calls and the `TOKEN` that serves to identify your calls. +You must use the `URL` and the `TOKEN` given by the third party API provider. -### [MyTeslaMate](https://www.myteslamate.com) (free) -#### MyTeslaMate Fleet API +#### [MyTeslaMate](https://www.myteslamate.com) (free) +##### MyTeslaMate Fleet API 1. Log in the [MyTeslaMate](https://app.myteslamate.com) website **with your Tesla account** and go to the [MyTeslaMate Fleet](https://app.myteslamate.com/fleet) page to get your `TOKEN`. 1. Add the following environment variables (using your `TOKEN` instead of _`xxxx-xxxx-xxxx-xxxx`_): @@ -49,7 +70,7 @@ You must obtain the `URL` to use for your third-party API calls and the `TOKEN` - TESLA_AUTH_PATH=/api/oauth2/v3 ``` -#### MyTeslaMate Streaming +##### MyTeslaMate Streaming MyTeslaMate also provides streaming by [reproducing the old streaming from the data sent by Fleet Telemetry](https://github.com/MyTeslaMate/websocket). 1. You need to "_Pair your vehicle(s)_" on the [fleet](https://app.myteslamate.com/fleet) page @@ -61,9 +82,9 @@ MyTeslaMate also provides streaming by [reproducing the old streaming from the d ``` 1. Restart your instance -### [Teslemetry](https://teslemetry.com/pricing) (paid) +#### [Teslemetry](https://teslemetry.com/pricing) (paid) -#### Teslemetry Fleet API +##### Teslemetry Fleet API 1. Log in the [Teslemetry website](https://teslemetry.com) and create your `TOKEN`. 1. Use this `TOKEN` instead of _`xxxx-xxxx-xxxx-xxxx`_ and add the following environment variables: ```yml @@ -74,14 +95,16 @@ MyTeslaMate also provides streaming by [reproducing the old streaming from the d ``` 1. Restart your instance -#### Streaming +##### Teslemetry Streaming **_Important: no streaming provided by Teslemetry, you MUST disable manually the streaming in Teslamate settings._** -## Guide for official Tesla API +### Guide for official Tesla API -_This solution requires advanced skills._ -### Tesla Fleet API +#### Requirements +- A dedicated public hosting +- Advanced IT skills +#### Tesla Fleet API You can follow the official [Setup documentation](https://developer.tesla.com/docs/fleet-api#setup): 1. Set up a third-party account at [developer.tesla.com](https://developer.tesla.com) 1. Complete registration of an account: you need to share your public key on a public domain (eg: _api.mydomain.com_) @@ -96,7 +119,7 @@ This proxy must be accessible from your Teslamate instance. You need to host thi _Authentication endpoint remains unchanged. Teslamate will take care of the tokens renewal as usual._ -### Tesla Streaming +#### Streaming via Tesla Telemetry **_Important: if you don't setup your own streaming, you MUST disable manually the streaming in Teslamate settings._** @@ -113,3 +136,4 @@ To setup your own streaming server, you can follow these steps: - TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true - TESLA_WSS_USE_VIN=true ``` +1. Restart your instance \ No newline at end of file From 1b2c601bc865ca15da5c4205cad77ea6ddbb06f1 Mon Sep 17 00:00:00 2001 From: Julien Date: Wed, 19 Jun 2024 15:50:03 +0200 Subject: [PATCH 6/8] format --- website/docs/guides/api.md | 103 +++++++++++++++++-------------------- 1 file changed, 47 insertions(+), 56 deletions(-) diff --git a/website/docs/guides/api.md b/website/docs/guides/api.md index 3f33c8ba7a..26c81f92e6 100644 --- a/website/docs/guides/api.md +++ b/website/docs/guides/api.md @@ -2,27 +2,8 @@ title: Using the Official Tesla Fleet API and Telemetry Streaming --- -## Table of Contents - -- [Official Tesla APIs](#official-tesla-apis) - - [Why Tesla Fleet and Telemetry are Needed](#why-tesla-fleet-and-telemetry-are-needed) - - [Impacts/Limitations of New Endpoints](#impactslimitations-of-new-endpoints) - - [Tesla Fleet API: no impact](#tesla-fleet-api-no-impact) - - [Tesla Fleet Telemetry: non compatible by default](#tesla-fleet-telemetry-non-compatible-by-default) - - [How to Use Tesla APIs](#how-to-use-tesla-apis) -- [Guide for Third-Party Providers](#guide-for-third-party-providers) - - [MyTeslaMate (free)](#myteslamate-free) - - [MyTeslaMate Fleet API](#myteslamate-fleet-api) - - [MyTeslaMate Streaming](#myteslamate-streaming) - - [Teslemetry (paid)](#teslemetry-paid) - - [Teslemetry Fleet API](#teslemetry-fleet-api) - - [Teslemetry Streaming](#teslemetry-streaming) -- [Guide for Official Tesla API](#guide-for-official-tesla-api) - - [Requirements](#requirements) - - [Tesla Fleet API](#tesla-fleet-api) - - [Streaming via Tesla Telemetry](#streaming-via-tesla-telemetry) - ## Official Tesla APIs + ### Why Tesla Fleet and Telemetry are Needed By default, TeslaMate uses the _unofficial_ Owner API and streaming. @@ -52,14 +33,16 @@ The [Tesla Fleet Telemetry](https://github.com/teslamotors/fleet-telemetry) diff The setup to use the official Tesla APIs ([described below](#tesla-fleet-api)) is complex. You can use a [third-party providers](#guide-for-third-party-providers) to easily access these APIs. -### Guide for Third-Party Providers +## Guide for Third-Party Providers Environment variables allow changing the API and streaming endpoints. You must use the `URL` and the `TOKEN` given by the third party API provider. -#### [MyTeslaMate](https://www.myteslamate.com) (free) -##### MyTeslaMate Fleet API -1. Log in the [MyTeslaMate](https://app.myteslamate.com) website **with your Tesla account** and go to the [MyTeslaMate Fleet](https://app.myteslamate.com/fleet) page to get your `TOKEN`. +### [MyTeslaMate](https://www.myteslamate.com) (free) + +#### MyTeslaMate Fleet API + +1. Log in the [MyTeslaMate](https://app.myteslamate.com) website **with your Tesla account** and go to the [MyTeslaMate Fleet](https://app.myteslamate.com/fleet) page to get your `TOKEN`. 1. Add the following environment variables (using your `TOKEN` instead of _`xxxx-xxxx-xxxx-xxxx`_): ```yml @@ -70,48 +53,55 @@ You must use the `URL` and the `TOKEN` given by the third party API provider. - TESLA_AUTH_PATH=/api/oauth2/v3 ``` -##### MyTeslaMate Streaming -MyTeslaMate also provides streaming by [reproducing the old streaming from the data sent by Fleet Telemetry](https://github.com/MyTeslaMate/websocket). +#### MyTeslaMate Streaming + +MyTeslaMate also provides streaming by [reproducing the old streaming from the data sent by Fleet Telemetry](https://github.com/MyTeslaMate/websocket). 1. You need to "_Pair your vehicle(s)_" on the [fleet](https://app.myteslamate.com/fleet) page 1. Use the following dedicated environment variables: - ```yml - - TESLA_WSS_HOST=wss://streaming.myteslamate.com - - TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true - - TESLA_WSS_USE_VIN=true - ``` -1. Restart your instance + ```yml + - TESLA_WSS_HOST=wss://streaming.myteslamate.com + - TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true + - TESLA_WSS_USE_VIN=true + ``` +1. Restart your instance + +### [Teslemetry](https://teslemetry.com/pricing) (paid) -#### [Teslemetry](https://teslemetry.com/pricing) (paid) +#### Teslemetry Fleet API -##### Teslemetry Fleet API -1. Log in the [Teslemetry website](https://teslemetry.com) and create your `TOKEN`. +1. Log in the [Teslemetry website](https://teslemetry.com) and create your `TOKEN`. 1. Use this `TOKEN` instead of _`xxxx-xxxx-xxxx-xxxx`_ and add the following environment variables: - ```yml - - TOKEN=?token=xxxx-xxxx-xxxx-xxxx - - TESLA_API_HOST=https://api.teslemetry.com - - TESLA_AUTH_HOST=https://api.teslemetry.com - - TESLA_AUTH_PATH=/api/oauth2/v3 - ``` + ```yml + - TOKEN=?token=xxxx-xxxx-xxxx-xxxx + - TESLA_API_HOST=https://api.teslemetry.com + - TESLA_AUTH_HOST=https://api.teslemetry.com + - TESLA_AUTH_PATH=/api/oauth2/v3 + ``` 1. Restart your instance -##### Teslemetry Streaming +#### Teslemetry Streaming + **_Important: no streaming provided by Teslemetry, you MUST disable manually the streaming in Teslamate settings._** -### Guide for official Tesla API +## Guide for official Tesla API +### Requirements -#### Requirements - A dedicated public hosting - Advanced IT skills -#### Tesla Fleet API + +### Tesla Fleet API + You can follow the official [Setup documentation](https://developer.tesla.com/docs/fleet-api#setup): + 1. Set up a third-party account at [developer.tesla.com](https://developer.tesla.com) 1. Complete registration of an account: you need to share your public key on a public domain (eg: _api.mydomain.com_) 1. Request authorization permissions from a customer: _the generation of tokens usable in Teslamate no longer requires a third-party application as with the Owner API_ -4. Send drivers a "Pairing request" to be able to use your own [Tesla Vehicle Command Protocol http proxy to send commands](https://github.com/teslamotors/vehicle-command?tab=readme-ov-file#using-the-http-proxy). -This proxy must be accessible from your Teslamate instance. You need to host this http proxy on the same domain +1. Send drivers a "Pairing request" to be able to use your own [Tesla Vehicle Command Protocol http proxy to send commands](https://github.com/teslamotors/vehicle-command?tab=readme-ov-file#using-the-http-proxy). + This proxy must be accessible from your Teslamate instance. You need to host this http proxy on the same domain 1. Add the following environment variable with your own domain : + ```yml # API Fleet - TESLA_API_HOST=https://api.mydomain.com @@ -119,21 +109,22 @@ This proxy must be accessible from your Teslamate instance. You need to host thi _Authentication endpoint remains unchanged. Teslamate will take care of the tokens renewal as usual._ -#### Streaming via Tesla Telemetry +### Streaming via Tesla Telemetry **_Important: if you don't setup your own streaming, you MUST disable manually the streaming in Teslamate settings._** To setup your own streaming server, you can follow these steps: + 1. Setup a [Tesla Fleet Telemetry](https://github.com/teslamotors/fleet-telemetry) instance on a public domain (eg: _telemetry.mydomain.com_) 1. Add a [Google pubsub dispatcher](https://github.com/teslamotors/fleet-telemetry?tab=readme-ov-file#backendsdispatchers) to your own GCP PubSub. 1. Setup a [MyTeslaMate Streaming Server from Fleet Telemetry Events](https://github.com/MyTeslaMate/websocket) on a public domain (eg: _streaming.mydomain.com_) 1. Manually create a subscription to the `telemetry_V` created in PubSub by the Tesla Telemetry with: - - Delivery type: Push - - Endpoint URL: https://streaming.mydomain.com + - Delivery type: Push + - Endpoint URL: https://streaming.mydomain.com 1. Update your environment variables: - ```yml - - TESLA_WSS_HOST=wss://streaming.mydomain.com - - TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true - - TESLA_WSS_USE_VIN=true - ``` -1. Restart your instance \ No newline at end of file + ```yml + - TESLA_WSS_HOST=wss://streaming.mydomain.com + - TESLA_WSS_TLS_ACCEPT_INVALID_CERTS=true + - TESLA_WSS_USE_VIN=true + ``` +1. Restart your instance From 14b78c4972f23fd1b6bc0dff95a560d223ae69e4 Mon Sep 17 00:00:00 2001 From: Julien Date: Wed, 19 Jun 2024 15:59:00 +0200 Subject: [PATCH 7/8] update fleet api price --- website/docs/guides/api.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/website/docs/guides/api.md b/website/docs/guides/api.md index 26c81f92e6..a29f4d6228 100644 --- a/website/docs/guides/api.md +++ b/website/docs/guides/api.md @@ -84,12 +84,13 @@ MyTeslaMate also provides streaming by [reproducing the old streaming from the d **_Important: no streaming provided by Teslemetry, you MUST disable manually the streaming in Teslamate settings._** -## Guide for official Tesla API +## Guide to using the official Tesla API directly (free) ### Requirements -- A dedicated public hosting - Advanced IT skills +- A dedicated public hosting +- A [free Tesla Fleet API plan](https://developer.tesla.com/docs/fleet-api#membership-levels) ### Tesla Fleet API From 0cbc80aeaf6ae9bcb0542a6eae636ea5bba12a82 Mon Sep 17 00:00:00 2001 From: Julien Date: Fri, 21 Jun 2024 01:50:20 +0200 Subject: [PATCH 8/8] Update direct Tesla API part --- website/docs/guides/api.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/website/docs/guides/api.md b/website/docs/guides/api.md index a29f4d6228..ab03a49fdd 100644 --- a/website/docs/guides/api.md +++ b/website/docs/guides/api.md @@ -94,21 +94,24 @@ MyTeslaMate also provides streaming by [reproducing the old streaming from the d ### Tesla Fleet API -You can follow the official [Setup documentation](https://developer.tesla.com/docs/fleet-api#setup): - -1. Set up a third-party account at [developer.tesla.com](https://developer.tesla.com) -1. Complete registration of an account: you need to share your public key on a public domain (eg: _api.mydomain.com_) -1. Request authorization permissions from a customer: _the generation of tokens usable in Teslamate no longer requires a third-party application as with the Owner API_ -1. Send drivers a "Pairing request" to be able to use your own [Tesla Vehicle Command Protocol http proxy to send commands](https://github.com/teslamotors/vehicle-command?tab=readme-ov-file#using-the-http-proxy). - This proxy must be accessible from your Teslamate instance. You need to host this http proxy on the same domain +1. Set up a third-party account at [developer.tesla.com](https://developer.tesla.com) as described on the [Tesla docs](https://developer.tesla.com/docs/fleet-api#setup) 1. Add the following environment variable with your own domain : + 1. Use [the correct region](https://developer.tesla.com/docs/fleet-api#endpoints-and-regional-requirements) in the `TESLA_API_HOST` field: + - North America, Asia-Pacific (excluding China): https://fleet-api.prd.na.vn.cloud.tesla.com + - Europe, Middle East, Africa: https://fleet-api.prd.eu.vn.cloud.tesla.com + - China: https://fleet-api.prd.cn.vn.cloud.tesla.cn + 1. Update the `TESLA_AUTH_CLIENT_ID` with the client ID of your Tesla application. + ```yml + # API Fleet + - TESLA_API_HOST=https://fleet-api.prd.eu.vn.cloud.tesla.com + - TESLA_AUTH_HOST=https://auth.tesla.com + - TESLA_AUTH_PATH=/oauth2/v3 + - TESLA_AUTH_CLIENT_ID=xxxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx + ``` +1. (Optional) If you want to send commands or use Tesla Telemetry: + 1. Send drivers a "Pairing request" to be able to use your own [Tesla Vehicle Command Protocol http proxy to send commands](https://github.com/teslamotors/vehicle-command?tab=readme-ov-file#using-the-http-proxy) + 1. Send test commands or setup Telemetry to [stream it to your Teslamate](#streaming-via-tesla-telemetry) -```yml -# API Fleet -- TESLA_API_HOST=https://api.mydomain.com -``` - -_Authentication endpoint remains unchanged. Teslamate will take care of the tokens renewal as usual._ ### Streaming via Tesla Telemetry