# TeslaMate MQTT Topics and Data Structure: Complete Reference Guide

> Explore TeslaMate MQTT topics and data structure for real-time vehicle telemetry. Understand published data under teslamate/cars/$car_id/ and access comprehensive integration guides.

- Repository: [TeslaMate/teslamate](https://github.com/teslamate-org/teslamate)
- Tags: api-reference
- Published: 2026-06-23

---

**TeslaMate publishes real-time vehicle telemetry under the namespace `teslamate/cars/$car_id/` as scalar values (strings, numbers, booleans) or JSON objects, with the MQTT client implementation located in [`lib/teslamate/mqtt.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/mqtt.ex) and comprehensive documentation available in the project's MQTT integration guide.**

TeslaMate, the open-source Tesla data logger written in Elixir, exposes vehicle data through a comprehensive MQTT interface. Understanding the TeslaMate MQTT topics and their data structure is essential for building custom dashboards, home automation integrations, or third-party applications. The MQTT publisher runs as a supervised process defined in [`lib/teslamate/mqtt.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/mqtt.ex), forwarding live telemetry whenever the application receives updates from the Tesla API.

## Topic Namespace and Structure

All TeslaMate MQTT topics follow the hierarchical pattern `teslamate/cars/$car_id/<attribute>`, where `$car_id` represents the numeric vehicle identifier (typically starting at 1). The publisher writes to these topics immediately upon receiving new data from the Tesla API or internal logger.

### Scalar vs. JSON Payloads

Most topics publish **scalar values**—plain JSON-encoded strings, numbers, or booleans without wrapping objects. However, two specific topics deviate from this pattern:

- **`location`**: Publishes a JSON object containing latitude and longitude
- **`active_route`**: Publishes a JSON object with navigation details including destination, ETA, and energy predictions

## Identity and Vehicle Metadata

Static vehicle attributes are published under the root namespace:

- `teslamate/cars/$car_id/display_name`: Vehicle name (e.g., `"Blue Thunder"`)
- `teslamate/cars/$car_id/state`: Current status (e.g., `"asleep"`, `"online"`)
- `teslamate/cars/$car_id/version`: Firmware version (e.g., `"2019.32.12.2"`)
- `teslamate/cars/$car_id/update_available`: Boolean flag for pending updates
- `teslamate/cars/$car_id/update_version`: Target version string
- `teslamate/cars/$car_id/model`: Model identifier (e.g., `"3"`)
- `teslamate/cars/$car_id/trim_badging`: Trim specification (e.g., `"P100D"`)
- `teslamate/cars/$car_id/exterior_color`: Color code (e.g., `"DeepBlue"`)
- `teslamate/cars/$car_id/wheel_type`: Wheel specification (e.g., `"Pinwheel18"`)
- `teslamate/cars/$car_id/spoiler_type`: Spoiler configuration (e.g., `"None"`)

## Location and Navigation

Geographic data uses structured JSON payloads rather than scalar values.

### Location Topic

The `teslamate/cars/$car_id/location` topic carries a JSON object:

```json
{ "latitude": 35.278131, "longitude": 29.744801 }

```

### Active Route Topic

The `teslamate/cars/$car_id/active_route` topic provides navigation data:

```json
{
  "destination": "Home",
  "energy_at_arrival": 73,
  "miles_to_arrival": 6.485299,
  "minutes_to_arrival": 23.466667,
  "location": { "latitude": 35.278131, "longitude": 29.744801 },
  "error": null
}

```

If no route is active, the payload returns `{ "error": "No active route available" }`.

## Battery and Charging Metrics

Power management data includes percentages and range estimates:

- `teslamate/cars/$car_id/battery_level`: Integer percentage (e.g., `88`)
- `teslamate/cars/$car_id/usable_battery_level`: Adjusted percentage accounting for cold weather (e.g., `85`)
- `teslamate/cars/$car_id/est_battery_range_km`: Estimated range in kilometers (e.g., `372.5`)
- `teslamate/cars/$car_id/rated_battery_range_km`: Rated range (e.g., `401.63`)
- `teslamate/cars/$car_id/ideal_battery_range_km`: Ideal range (e.g., `335.79`)

Charging-specific topics include:

- `teslamate/cars/$car_id/charging_state`: Status string (e.g., `"Charging"`, `"Complete"`)
- `teslamate/cars/$car_id/charge_energy_added`: Energy in kWh (e.g., `5.06`)
- `teslamate/cars/$car_id/charge_limit_soc`: Target percentage (e.g., `90`)
- `teslamate/cars/$car_id/plugged_in`: Boolean connection status
- `teslamate/cars/$car_id/charge_port_door_open`: Boolean charger door status

Charger electrical metrics:

- `teslamate/cars/$car_id/charger_actual_current`: Amperage (e.g., `2.05`)
- `teslamate/cars/$car_id/charger_phases`: Integer count (e.g., `3`)
- `teslamate/cars/$car_id/charger_power`: Kilowatts (e.g., `48.9`)
- `teslamate/cars/$car_id/charger_voltage`: Volts (e.g., `240`)
- `teslamate/cars/$car_id/charge_current_request`: Requested amperage (e.g., `40`)
- `teslamate/cars/$car_id/charge_current_request_max`: Maximum allowed (e.g., `40`)

## Driving State and Telemetry

Real-time motion data includes:

- `teslamate/cars/$car_id/shift_state`: Gear position (`"D"`, `"N"`, `"R"`, `"P"`)
- `teslamate/cars/$car_id/power`: Instantaneous power in watts (e.g., `-9`)
- `teslamate/cars/$car_id/speed`: Speed in km/h (e.g., `12`)
- `teslamate/cars/$car_id/heading`: Direction in degrees (e.g., `340`)
- `teslamate/cars/$car_id/elevation`: Altitude in meters (e.g., `70`)

## Climate and Environment

Climate control status publishes as:

- `teslamate/cars/$car_id/is_climate_on`: Boolean operational state
- `teslamate/cars/$car_id/inside_temp`: Interior temperature in Celsius (e.g., `20.8`)
- `teslamate/cars/$car_id/outside_temp`: Exterior temperature in Celsius (e.g., `18.4`)
- `teslamate/cars/$car_id/is_preconditioning`: Boolean cabin preparation status

## Security and Access

Door and lock status uses boolean values:

- `teslamate/cars/$car_id/locked`: Central lock state
- `teslamate/cars/$car_id/doors_open`: Aggregate door status
- `teslamate/cars/$car_id/driver_front_door_open`: Individual door states (`driver_front`, `driver_rear`, `passenger_front`, `passenger_rear`, `trunk`, `frunk`)

## Tire Pressure Monitoring (TPMS)

Tire data includes pressure and warning flags for each wheel:

- `teslamate/cars/$car_id/tpms_pressure_fl`: Front-left pressure in BAR (e.g., `2.9`)
- `teslamate/cars/$car_id/tpms_pressure_fr`: Front-right pressure
- `teslamate/cars/$car_id/tpms_pressure_rl`: Rear-left pressure
- `teslamate/cars/$car_id/tpms_pressure_rr`: Rear-right pressure
- `teslamate/cars/$car_id/tpms_soft_warning_fl`: Boolean warning flags for each tire

## Geofence Detection

The `teslamate/cars/$car_id/geofence` topic publishes the name of the geofence currently containing the vehicle (e.g., `"🏡 Home"`), or null if outside defined boundaries.

## Subscribing to TeslaMate MQTT Topics

Implementing MQTT consumers requires connecting to the same broker configured in TeslaMate.

### Elixir Client Example

Using the Tortoise311 library as implemented in the TeslaMate ecosystem:

```elixir

# Subscribe to battery level updates for car #1

Tortoise311.subscribe(
  client_id: "my_dashboard",
  topics: [{"teslamate/cars/1/battery_level", 0}]
)

# Handle incoming messages

def handle_info({Tortoise311, _client_id, {:publish, %{topic: topic, payload: payload}}}, state) do
  case topic do
    "teslamate/cars/1/battery_level" ->
      battery = String.to_integer(payload)
      IO.puts("Battery level: #{battery}%")
    _ -> 
      :ok
  end
  {:noreply, state}
end

```

### Python Navigation Parser

Processing the JSON `active_route` payload:

```python
import json
import paho.mqtt.client as mqtt

def on_message(client, userdata, msg):
    if msg.topic == "teslamate/cars/1/active_route":
        data = json.loads(msg.payload.decode())
        if data.get("error"):
            print("No active route available")
        else:
            print(f"Destination: {data['destination']}")
            print(f"ETA: {data['minutes_to_arrival']:.1f} minutes")
            print(f"Energy at arrival: {data['energy_at_arrival']}%")

client = mqtt.Client()
client.on_message = on_message
client.connect("mqtt-broker.local", 1883, 60)
client.subscribe("teslamate/cars/1/active_route")
client.loop_forever()

```

### Command Line Publishing

Testing through command line using `mosquitto_pub`:

```bash
mosquitto_pub -h mqtt-broker.local -t teslamate/cars/1/is_climate_on -m true

```

## Implementation Details

The MQTT integration is defined in three key locations within the repository:

- **[`lib/teslamate/mqtt.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/mqtt.ex)**: Contains the supervisor implementation that establishes the MQTT connection and manages the publisher process lifecycle
- **[`website/docs/integrations/mqtt.md`](https://github.com/teslamate-org/teslamate/blob/main/website/docs/integrations/mqtt.md)**: Comprehensive documentation of all available topics and expected payload formats
- **[`test/support/mocks/mqtt_publisher.ex`](https://github.com/teslamate-org/teslamate/blob/main/test/support/mocks/mqtt_publisher.ex)**: Test double used to verify publishing behavior without external network calls

## Summary

- TeslaMate organizes all vehicle telemetry under the `teslamate/cars/$car_id/` namespace, where `$car_id` represents the vehicle's numeric identifier
- Most topics publish scalar values (strings, numbers, booleans), while `location` and `active_route` transmit structured JSON objects
- Data updates occur immediately upon receiving new information from the Tesla API or internal logging systems
- The MQTT client implementation resides in [`lib/teslamate/mqtt.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/mqtt.ex) as part of the Erlang/Elixir supervision tree
- Complete topic documentation is available in [`website/docs/integrations/mqtt.md`](https://github.com/teslamate-org/teslamate/blob/main/website/docs/integrations/mqtt.md)

## Frequently Asked Questions

### What is the format of TeslaMate's location topic?

The `teslamate/cars/$car_id/location` topic publishes a JSON object containing `latitude` and `longitude` as floating-point numbers, such as `{"latitude": 35.278131, "longitude": 29.744801}`, rather than individual scalar topics for each coordinate.

### How do I determine if my Tesla is actively charging via MQTT?

Monitor the `teslamate/cars/$car_id/charging_state` topic for values like `"Charging"` or `"Complete"`, and verify the `teslamate/cars/$car_id/plugged_in` boolean returns `true`. Real-time charging metrics including power (kW), voltage, and amperage are available under the `charger_*` prefixed topics.

### Can I receive navigation data through TeslaMate's MQTT interface?

Yes, the `teslamate/cars/$car_id/active_route` topic provides JSON-formatted navigation data including destination name, minutes to arrival, miles remaining, and predicted energy percentage at arrival. If no route is active, the payload returns an error field indicating `"No active route available"`.

### Where is the MQTT configuration handled in the TeslaMate source code?

The MQTT client connection and publisher process are configured in [`lib/teslamate/mqtt.ex`](https://github.com/teslamate-org/teslamate/blob/main/lib/teslamate/mqtt.ex), which implements the GenServer supervision tree. Connection parameters are typically configured through environment variables, while the complete topic specification is documented in [`website/docs/integrations/mqtt.md`](https://github.com/teslamate-org/teslamate/blob/main/website/docs/integrations/mqtt.md).