TeslaMate MQTT Topics and Data Structure: Complete Reference Guide

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 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, 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:

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

Active Route Topic

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

{
  "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:

# 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:

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:

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: Contains the supervisor implementation that establishes the MQTT connection and manages the publisher process lifecycle
• website/docs/integrations/mqtt.md: Comprehensive documentation of all available topics and expected payload formats
• 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 as part of the Erlang/Elixir supervision tree
• Complete topic documentation is available in 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}