TeslaMate

TeslaMate is a self‑hosted telemetry platform that ingests, persists, and visualizes data from Tesla vehicles. Built in Elixir, it leverages the BEAM VM’s concurrency model to handle continuous streams of JSON payloads from Tesla’s vehicle APIs. Incoming telemetry is parsed into a PostgreSQL schema that captures every millisecond of drive data, charge sessions, and state changes. The application exposes a minimal REST interface for status checks while broadcasting real‑time updates to an embedded MQTT broker, enabling seamless integration with home automation stacks such as Home Assistant or Node‑RED. A dedicated Grafana dashboard package ships with the repo, providing out‑of‑the‑box visual analytics for battery health, energy consumption, and driving patterns.

Architecture & Technical Stack

• Language & Runtime: Elixir (Erlang/BEAM) – chosen for fault‑tolerant, lightweight processes that can maintain long‑lived TCP connections to Tesla’s HTTPS endpoints without blocking.
• Data Store: PostgreSQL – a relational backend that stores time‑series data in normalized tables (drives, charges, states). Indexing on timestamps and vehicle IDs ensures sub‑second query latency for Grafana panels.
• Message Bus: MQTT broker (Eclipse Mosquitto) bundled as a Docker service – publishes every telemetry event under topics like teslamate/vehicle/<id>/state. This decouples the data layer from consumer applications.
• Visualization: Grafana dashboards are pre‑configured to query PostgreSQL directly. The dashboards use advanced panels (heatmaps, time series, world maps) to surface insights such as projected range or charge cost.
• Containerization: Docker Compose files expose services (teslamate, postgres, mosquitto) with volume mounts for persistent data. The Docker images are built on Alpine Linux, keeping the footprint under 200 MB.

Core Capabilities & APIs

• High‑precision logging: Every 5 seconds of drive data (speed, odometer, temperature) is stored with millisecond timestamps. This granularity supports detailed energy‑usage analysis.
• Vehicle discovery & multi‑account support: The OAuth flow retrieves all vehicles linked to an account; each vehicle is assigned a unique numeric ID used throughout the system.
• MQTT topic schema: teslamate/vehicle/<id>/state, .../charge_state, .../climate_status – each topic publishes a JSON payload that can be subscribed to by any MQTT client.
• REST endpoints: /api/v1/vehicles returns a list of registered vehicles; /api/v1/drives?vehicle_id=… supports filtered queries. These endpoints are protected via API tokens configured in the .env file.
• Import utilities: CSV importers for TeslaFi and tesla‑apiscraper data allow migration from legacy logs without manual re‑entry.

Deployment & Infrastructure

TeslaMate’s Docker Compose stack is designed for single‑host deployments but scales horizontally by replicating the teslamate service behind a reverse proxy and sharing a common PostgreSQL instance. The PostgreSQL database can be backed up with standard pg_dump or managed via Kubernetes StatefulSets. Because the application uses stateless HTTP connections to Tesla’s API, it can run behind NAT or on a Raspberry Pi with modest CPU and RAM (≥ 1 GB). The embedded Mosquitto broker can be replaced with an external broker if required, simply by updating the MQTT endpoint in the config.

Integration & Extensibility

The MQTT interface is the primary hook for extensibility. Developers can write Node‑RED flows, Home Assistant automations, or custom Go services that react to state changes. The REST API can be consumed by external dashboards or analytics pipelines (e.g., Prometheus exporters). A small plugin system exists in the form of Grafana dashboard JSON that can be forked and customized. For more advanced use cases, the source code exposes a TeslaMate.Repo module that can be imported into other Elixir projects, allowing direct access to the telemetry tables.

Developer Experience

Configuration is driven by environment variables (TESLAMATE_DB_URL, TELEMETRY_INTERVAL, etc.), making the stack trivial to adjust in CI/CD pipelines. The documentation site at docs.teslamate.org provides comprehensive guides, API references, and migration steps. The community is active on GitHub Discussions and Discord; contributors frequently add new metrics or fix edge‑case bugs. The open‑source license (MIT) removes any licensing friction, and the project's adherence to OpenSSF Best Practices signals a commitment to security.

Use Cases

• Home automation: Publish real‑time battery level and charging status to Home Assistant, triggering smart plugs or notifications.
• Energy cost tracking: Integrate TeslaMate’s charge cost calculations with an electricity pricing API to optimize charging times.
• Fleet analytics: Deploy a single instance for multiple Tesla vehicles, aggregating mileage and efficiency metrics across a small company fleet.
• Data science experiments: Export drive logs to CSV or directly query PostgreSQL for machine‑learning models that predict range degradation.

Advantages Over Alternatives

TeslaMate’s combination of high‑resolution logging, native MQTT publishing, and pre‑built Grafana dashboards gives developers a turnkey analytics platform without reinventing data ingestion. Its Elixir core ensures robust handling of long‑running connections, while the open‑source license and minimal dependencies keep operational overhead low. Compared to commercial services that require cloud accounts or proprietary APIs