How to Configure TeslaMate Polling Intervals: Environment Variable Guide

TeslaMate configures polling intervals through environment variables that override default values defined in the Vehicle state machine, allowing runtime customization of how frequently the Tesla API is queried during different vehicle states.

The teslamate-org/teslamate repository implements a sophisticated state-machine architecture in lib/teslamate/vehicles/vehicle.ex to manage vehicle data synchronization. Rather than using hard-coded timers, the application derives polling cadences from configurable environment variables, enabling operators to balance API usage against data freshness based on their specific deployment needs.

How Polling Intervals Work in TeslaMate

TeslaMate uses a GenStateMachine to handle vehicle state transitions, where each state (asleep, driving, charging, online) maintains its own polling frequency. The system calculates these intervals at runtime using a helper function that checks for environment variable overrides before falling back to safe defaults.

This design prevents excessive API calls during inactive periods while ensuring high-frequency updates during critical states like driving or charging.

Default Polling Intervals and Environment Variables

The Vehicle module defines six distinct polling modes, each mapped to a specific environment variable and default value. The core logic resides in the interval/2 helper function at lines 55-61 of lib/teslamate/vehicles/vehicle.ex:

@asleep_interval 30

def interval(env_var, default) do
  System.get_env(env_var)
  |> case do
       nil -> default
       interval -> String.to_integer(interval) |> max(default)
     end
end

This function ensures that user-defined values never fall below the default minimums, preventing accidental API rate limit violations.

Specific interval getters expose the following configurations:

• asleep_interval/0: Controlled by POLLING_ASLEEP_INTERVAL, defaults to 30 seconds
• driving_interval/0: Controlled by POLLING_DRIVING_INTERVAL, defaults to 2.5 seconds
• default_interval/0: Controlled by POLLING_DEFAULT_INTERVAL, defaults to 15 seconds
• online_interval/0: Controlled by POLLING_ONLINE_INTERVAL, defaults to 60 seconds
• charging_interval/0: Controlled by POLLING_CHARGING_INTERVAL, defaults to 5 seconds
• minimum_interval/0: Controlled by POLLING_MINIMUM_INTERVAL, defaults to 0 seconds

Complete documentation for these variables appears in website/docs/configuration/environment_variables.md.

Scheduling Mechanism in the State Machine

Once calculated, intervals feed into the schedule_fetch/3 function (lines 70-77), which translates time values into Erlang timer specifications using the fetch_timeout/2 macro:

defp schedule_fetch(_n, _unit, %Data{import?: true}), do: {:state_timeout, 0, :fetch}
defp schedule_fetch(n, unit, _), do: {:state_timeout, fetch_timeout(n, unit), :fetch}

The state machine invokes these schedules during state transitions. For example, when transitioning to the asleep state, the code calls asleep_interval() and passes the result to schedule_fetch/2:

{:next_state, {:asleep, asleep_interval()},
 %Data{...},
 [{:reply, from, :ok}, broadcast_summary(), schedule_fetch(@asleep_interval, data)]}

This pattern repeats for driving, charging, and online states throughout the module, ensuring each state maintains its distinct polling cadence.

Practical Configuration Examples

Docker Compose Override

To increase the driving poll rate to 5 seconds, modify your docker-compose.yml:

services:
  teslamate:
    image: teslamate/teslamate:latest
    environment:
      - POLLING_DRIVING_INTERVAL=5
      - POLLING_CHARGING_INTERVAL=10

Programmatic Access

Inspect current intervals from within the application:

# Returns the effective driving interval in seconds

current_interval = TeslaMate.Vehicles.Vehicle.driving_interval()
IO.puts("Driving poll interval: #{current_interval}s")

Manual State Timeout Trigger

For debugging or forced updates, manually trigger a fetch using the computed timeout:

pid = TeslaMate.Vehicles.Vehicle.whereis(car.id)
interval = TeslaMate.Vehicles.Vehicle.online_interval()
send(pid, {:state_timeout, :fetch, interval})

Summary

• TeslaMate uses environment variables (e.g., POLLING_DRIVING_INTERVAL) to configure polling intervals without requiring code changes or restarts.
• The interval/2 helper in lib/teslamate/vehicles/vehicle.ex enforces minimum values to prevent API abuse.
• Six distinct modes exist: asleep, driving, default, online, charging, and minimum, each with specific defaults optimized for Tesla API rate limits.
• The GenStateMachine applies these intervals via schedule_fetch/3 during state transitions to maintain appropriate data freshness per vehicle state.

Frequently Asked Questions

What is the default polling interval when my Tesla is driving?

The default driving polling interval is 2.5 seconds, defined by the driving_interval/0 function in lib/teslamate/vehicles/vehicle.ex. You can override this by setting the POLLING_DRIVING_INTERVAL environment variable to any integer value in seconds.

How do I reduce API calls when the vehicle is parked and online?

Set the POLLING_ONLINE_INTERVAL environment variable to increase the delay between status checks. The default is 60 seconds, but you can extend this to 300 seconds (5 minutes) or higher to reduce API usage while the vehicle remains stationary but awake.

What happens if I set a polling interval lower than the default minimum?

The interval/2 function uses the max/2 operator to compare your environment variable value against the hard-coded default. If you specify a value lower than the default (e.g., setting POLLING_ASLEEP_INTERVAL=5 when the default is 30), TeslaMate will use the default value instead, protecting you from accidental API rate limiting.

Where are the polling intervals documented in the TeslaMate source code?

Default values and environment variable mappings reside in lib/teslamate/vehicles/vehicle.ex at lines 55-61. User-facing documentation appears in website/docs/configuration/environment_variables.md, which provides comprehensive tables explaining each variable's purpose and acceptable values.

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