{"id":50745659,"url":"https://github.com/johnbr/ha-tesla-fleet-telemetry","last_synced_at":"2026-06-10T20:30:58.169Z","repository":{"id":359622134,"uuid":"1232428769","full_name":"johnbr/ha-tesla-fleet-telemetry","owner":"johnbr","description":"Home Assistant all in one integration using Tesla Fleet Telemetry","archived":false,"fork":false,"pushed_at":"2026-05-22T19:01:24.000Z","size":91,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T20:57:38.386Z","etag":null,"topics":["hacs","hacs-integration","homeassistant"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnbr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T23:32:01.000Z","updated_at":"2026-05-22T17:05:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/johnbr/ha-tesla-fleet-telemetry","commit_stats":null,"previous_names":["johnbr/ha-tesla-fleet-telemetry"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/johnbr/ha-tesla-fleet-telemetry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbr%2Fha-tesla-fleet-telemetry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbr%2Fha-tesla-fleet-telemetry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbr%2Fha-tesla-fleet-telemetry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbr%2Fha-tesla-fleet-telemetry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnbr","download_url":"https://codeload.github.com/johnbr/ha-tesla-fleet-telemetry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbr%2Fha-tesla-fleet-telemetry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34170162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacs","hacs-integration","homeassistant"],"created_at":"2026-06-10T20:30:57.664Z","updated_at":"2026-06-10T20:30:58.164Z","avatar_url":"https://github.com/johnbr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tesla Fleet Telemetry for Home Assistant\n\nA custom Home Assistant integration that consumes Tesla's\n[Fleet Telemetry](https://developer.tesla.com/docs/fleet-api/fleet-telemetry)\npush stream — an mTLS WebSocket carrying Protobuf-in-FlatBuffers frames — and\nsurfaces the vehicle's live state as Home Assistant entities.\n\nUnlike a polled integration, the vehicle *pushes* updates: location and speed\narrive every few seconds while the car is awake, and discrete events (doors,\nlocks, charging state) arrive the moment they change.\n\n\u003e **This is an advanced integration.** Tesla delivers Fleet Telemetry only to\n\u003e a publicly reachable endpoint that terminates mutual TLS. You must run a\n\u003e reverse proxy (nginx is assumed throughout this document) and hold a Tesla\n\u003e developer *partner* account. If you only want polled climate/charging/door\n\u003e data with no infrastructure to manage, use the official\n\u003e [`tesla_fleet`](https://www.home-assistant.io/integrations/tesla_fleet/)\n\u003e integration instead.\n\nThis integration **complements** `tesla_fleet`: run both side by side and the\ntelemetry entities give you a real-time mirror of the polled ones. It does not\nsend commands to the vehicle — it is read-only.\n\n## Entities\n\nOne Home Assistant **device per vehicle**, carrying ~52 entities. Add the\nintegration once per VIN to track multiple cars.\n\n| Platform | Count | Examples |\n| --- | --- | --- |\n| `device_tracker` | 2 | Location, Route (active nav destination) |\n| `sensor` | 33 | Speed, State of charge, Charging state, Inside temperature, Odometer, Tire pressure ×4 |\n| `binary_sensor` | 17 | Doors ×6, Windows ×4, Lock, Charging, Climate, Sentry armed, User present |\n\n\u003cdetails\u003e\n\u003csummary\u003eFull entity list\u003c/summary\u003e\n\n**Device trackers** — Location, Route\n\n**Sensors** — Speed, Distance to arrival, Time to arrival, Traffic delay,\nOdometer, Gear, Battery level, State of charge, Battery range, Rated range,\nCharging state, Charge rate, AC charging power, DC charging power,\nAC charge energy added, DC charge energy added, Charger current,\nCharger voltage, Fast charger type, Charging cable, Charge limit,\nTime to full charge, Inside temperature, Outside temperature,\nClimate left setpoint, Climate right setpoint, Tire pressure (front left,\nfront right, rear left, rear right), Software version,\nSoftware update download, Software update install\n\n**Binary sensors** — Front/rear driver/passenger doors, Frunk, Trunk,\nFront/rear driver/passenger windows, Lock, Charge port door, Charge cable,\nCharging, Climate, Sentry armed, User present\n\n\u003c/details\u003e\n\nEntity IDs follow the vehicle's name, e.g. `sensor.\u003cvehicle\u003e_speed`,\n`device_tracker.\u003cvehicle\u003e_location`.\n\n## How it works\n\n```\n┌──────────┐  mTLS WSS   ┌────────┐  HTTP (X-Tesla-* headers)  ┌────────────────┐\n│  Tesla   │ ──────────► │ nginx  │ ─────────────────────────► │ Home Assistant │\n│ Vehicle  │             │ (mTLS  │                            │ /api/tesla_    │\n│ (Hermes) │             │  term) │                            │ telemetry/ws   │\n└──────────┘             └────────┘                            └────────────────┘\n```\n\n* **No sidecar service.** nginx terminates mTLS, then forwards the WebSocket\n  upgrade to Home Assistant's own HTTP server. The integration registers a\n  view at `/api/tesla_telemetry/ws`.\n* **OAuth via `application_credentials`.** Home Assistant Core owns the Tesla\n  OAuth token lifecycle. Each integration instance gets its own grant — no\n  refresh-token contention with `tesla_fleet`.\n* **`Tesla.SS256` JWT signing.** Tesla's `fleet_telemetry_config_jws` endpoint\n  requires a JWT signed with RFC 8235 Schnorr over P-256. The signer is\n  implemented in `crypto.py`.\n* **FlatBuffers + Protobuf decoding.** Tesla wraps Protobuf payloads in a\n  FlatBuffers envelope; the generated bindings are vendored under `proto/`.\n\n## Requirements\n\n* Home Assistant **2024.12** or later.\n* A **Tesla developer account** with a registered *partner application*\n  ([developer.tesla.com](https://developer.tesla.com/)). North America\n  accounts are supported today; EU/CN are not yet wired into the config flow.\n* An **EC P-256 (secp256r1) partner key pair**, with the public key hosted at\n  `https://\u003cpartner-domain\u003e/.well-known/appspecific/com.tesla.3p.public-key.pem`.\n* A **publicly reachable reverse proxy** (nginx assumed) that:\n  * presents a valid TLS server certificate,\n  * terminates mutual TLS, verifying the vehicle's client certificate against\n    Tesla's fleet CA,\n  * proxies the WebSocket upgrade to Home Assistant,\n  * injects the `X-Tesla-Proxy-Secret` and `X-Tesla-Verified-Vin` headers.\n* Python packages `cryptography`, `protobuf`, and `flatbuffers` — declared in\n  `manifest.json` and installed automatically by Home Assistant.\n\n## Setup\n\n### 1. Tesla developer / partner application\n\n1. Create an application at [developer.tesla.com](https://developer.tesla.com/).\n   Note the **client ID** and **client secret**.\n2. Add `https://my.home-assistant.io/redirect/oauth` to the application's\n   **Allowed Redirect URIs** (Home Assistant's OAuth flow uses it).\n3. Request the scopes `openid`, `offline_access`, and `vehicle_device_data`.\n4. Generate the partner key pair and host its public half:\n   ```sh\n   openssl ecparam -genkey -name prime256v1 -noout -out partner.key\n   openssl ec -in partner.key -pubout -out public-key.pem\n   ```\n   Publish `public-key.pem` at\n   `https://\u003cpartner-domain\u003e/.well-known/appspecific/com.tesla.3p.public-key.pem`.\n   Keep `partner.key` — you paste it into Home Assistant later.\n\n### 2. nginx reverse proxy\n\nnginx terminates mutual TLS and forwards the WebSocket to Home Assistant.\nDownload Tesla's fleet CA (`config/files/prod_ca.crt` from\n[`teslamotors/fleet-telemetry`](https://github.com/teslamotors/fleet-telemetry))\nand use it as the client-certificate trust anchor.\n\n```nginx\nserver {\n    listen 443 ssl;\n    http2 on;\n    server_name tesla-telemetry.example.com;\n\n    # Server certificate presented to the vehicle. Its chain must be\n    # anchored in the CA bundle pushed as fleet_telemetry_config.ca — the\n    # integration's default bundle covers Let's Encrypt and Sectigo/ZeroSSL.\n    ssl_certificate     /etc/letsencrypt/live/tesla-telemetry.example.com/fullchain.pem;\n    ssl_certificate_key /etc/letsencrypt/live/tesla-telemetry.example.com/privkey.pem;\n\n    # Mutual TLS: require and verify the vehicle's client certificate\n    # against Tesla's fleet CA.\n    ssl_client_certificate /etc/nginx/tesla/prod_ca.crt;\n    ssl_verify_client on;\n    ssl_verify_depth 2;\n\n    location /api/tesla_telemetry/ws {\n        proxy_pass http://127.0.0.1:8123/api/tesla_telemetry/ws;\n        proxy_http_version 1.1;\n\n        # WebSocket upgrade.\n        proxy_set_header Upgrade    $http_upgrade;\n        proxy_set_header Connection \"upgrade\";\n        proxy_set_header Host       $host;\n\n        # Trusted only because ssl_verify_client succeeded above.\n        proxy_set_header X-Tesla-Proxy-Secret  \"REPLACE-WITH-YOUR-PROXY-SECRET\";\n        proxy_set_header X-Tesla-Verified-Vin  $ssl_client_s_dn;\n\n        # Telemetry streams are long-lived.\n        proxy_read_timeout 1h;\n        proxy_send_timeout 1h;\n    }\n}\n```\n\nThe proxy secret is any shared string; the integration generates one for you\nin the config flow, and you paste that same value into the `proxy_set_header`\nline above.\n\n### 3. Install the integration\n\nUntil this repository is published in the default HACS store, add it as a\ncustom repository:\n\n1. HACS → ⋯ → **Custom repositories** → add\n   `https://github.com/johnbr/ha-tesla-fleet-telemetry` as type *Integration*.\n2. Install **Tesla Fleet Telemetry**.\n3. Restart Home Assistant.\n\n(Manual install: copy `custom_components/tesla_telemetry` into your Home\nAssistant `config/custom_components/` directory and restart.)\n\n### 4. Configure in Home Assistant\n\n1. **Settings → Devices \u0026 Services → Application Credentials** — add the Tesla\n   **client ID** and **client secret** from step 1.\n2. **Settings → Devices \u0026 Services → Add Integration → Tesla Fleet Telemetry.**\n3. Complete the Tesla OAuth login, then pick the **VIN** to track.\n4. On the **endpoint** step, enter:\n   * the public **hostname** and **port** nginx listens on,\n   * the **partner domain** hosting your `.well-known` public key,\n   * the **proxy secret** (used in the nginx config above),\n   * the **partner private key** (`partner.key` contents from step 1).\n\n### 5. Bootstrap and verify\n\n1. Run the **`tesla_telemetry.bootstrap`** service once. It registers your\n   partner domain with Tesla and pushes the initial telemetry configuration.\n2. Run **`tesla_telemetry.get_telemetry_config`** and confirm `synced: true`\n   in the response. Tesla's `synced` flag can lag several minutes behind a\n   successful push.\n3. Wake the vehicle (open the Tesla app) and watch the nginx access log for\n   the telemetry vhost — a `Hermes/...` user agent connecting is the sign the\n   car has picked up the configuration. Entities begin updating shortly after.\n\n## Multiple vehicles\n\nAdd the integration again for each additional VIN. The endpoint settings\n(hostname, proxy secret, partner key) are deployment-wide, so the endpoint\nstep is pre-filled from your first vehicle — just confirm it. Each VIN becomes\nits own Home Assistant device with its own entities. Service calls take an\n`entry_id` to select the vehicle when more than one is configured.\n\n## Services\n\n| Service | Purpose |\n| --- | --- |\n| `tesla_telemetry.bootstrap` | One-time onboarding: register the partner domain and push the initial config. |\n| `tesla_telemetry.resync_telemetry_config` | Re-push the config. Runs automatically (the config's `exp` is ~30 days); rarely needed by hand. |\n| `tesla_telemetry.get_telemetry_config` | Fetch Tesla's current config for the VIN — check `synced`. |\n| `tesla_telemetry.dump_public_key` | Emit the partner public key PEM, ready to host at `.well-known`. |\n| `tesla_telemetry.set_interval_preset` | Switch streaming intervals between `default` and `high_rate` (~1 s location/speed). |\n\nThe telemetry configuration expires on Tesla's side after roughly 30 days. The\nintegration checks daily and re-pushes automatically when the last sync is\nmore than 7 days old, so no manual upkeep is required.\n\n## Troubleshooting\n\n* **`synced: false` for a long time.** Tesla's flag lags reality. If the nginx\n  access log shows a `Hermes/...` connection, the car has the config.\n* **TLS handshake failures in the nginx error log.** The vehicle is rejecting\n  nginx's server certificate. Make sure the certificate chain is anchored in\n  the CA bundle pushed as `fleet_telemetry_config.ca` — pass a `ca_pem`\n  override to `bootstrap`/`resync_telemetry_config` if you use a CA outside\n  the default bundle.\n* **nginx connects but no entities update.** Check the `X-Tesla-Proxy-Secret`\n  header in the nginx config matches the proxy secret stored in the config\n  entry, and that `X-Tesla-Verified-Vin` carries the certificate subject.\n* Enable debug logging with:\n  ```yaml\n  logger:\n    logs:\n      custom_components.tesla_telemetry: debug\n  ```\n\n## License\n\n[MIT](LICENSE).\n\n## Disclaimer\n\nThis integration is not affiliated with, endorsed by, or sponsored by Tesla,\nInc. \"Tesla\" is a trademark of Tesla, Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnbr%2Fha-tesla-fleet-telemetry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnbr%2Fha-tesla-fleet-telemetry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnbr%2Fha-tesla-fleet-telemetry/lists"}