Some of the information in this page relates only to version 1.5.0 or higher of the tesla_custom integration.

---

How polling works

Remember that there are two components involved here, both with their different timers.

• The Home Assistant Integration (this repo). Here we have a static timer (not configurable) that will run an "update" every 10 seconds.
• This "update" is done towards teslajsonpy, which is the component that is talking with Teslas APIs to update the data.

Whenever teslajsonpy receives an update()-request from Home Assistant it will scan Teslas servers for a list of cars if has been more then 60 seconds since the last time the list was retrieved. The list will show which cars are awake, and which ones are sleeping.

For each car that is online (e.g. "awake") it will then check another timer, the polling_interval - which is configureable and defaults to 660 seconds. If the car's status was updated at least polling_interval seconds ago, teslajsonpy will do another API request to Tesla to fetch the full status information about that car and then update Home Assistant.

It the car is currently in drive (or reverse), polling_interval is internally and temporarily adjusted to every 60 seconds if it is configured to be more than 60 seconds to ensure location updates, speed etc. are updated within a reasonable timeframe. If polling_interval is configured less then 60 seconds then it will use polling_interval.

No polling is done if it is detected that the car is in service mode.

So to sum it up. A list of all cars is fetched from Tesla every 60 seconds, but no polling is done on a specific car unless the car is online (awake), not in service AND the previous poll was at least polling_interval seconds ago.

The polling switch

In the integration, there is a Polling Switch for each car. If this switch is set to "off", no polling of that car is done. This switch can be turned off if you want to make sure the integration will not touch a car, e.g. if you are going to be parked for a long time and want to preserve as much energy as possible.

Some examples

All the examples assume that the car is parked, awake and not in service.

Polling interval is set to 660 seconds (default)

• Every minute, Teslas servers are scanned to check the online status of all cars.
• If any cars are online (awake) we check what time we last did a full poll of that car.
• If this was at least polling_interval (default 660) seconds ago, we will do a new, full poll of the car.

This will update the car status (locks, charge status etc) of all online (awake) cars every 11 minutes. Sleeping cars are never polled, and driving cars are polled every 60 seconds (not configureable) or polling_interval depending which one is smallest but not more often than every 10 seconds.

Polling slips

Sometimes, a poll will slip. This can be due to issues with the Tesla API, but it can also happen because Home Assistant timers are not run with millisecond precision, and that the polling takes a variable amount of time. This means that occasionally you have to wait an extra 10 seconds before the check if 11 minutes (660 seconds) has passed.

E.g. The first full poll happens at 12:00:00, but it takes a little while to complete, so "Last poll timestamp" is set to 12:00:01. Then a scan is done every 10 seconds. This scan is run 12:00:10, 12:00:20, 12:00:30 etc. All the way to 12:11:00. However, since 12:11:00 is still NOT MORE than 11 minutes after 12:00:01, it will not do another full poll until after the scan at 12:11:10.

As long as the car is still awake at 12:11:10, another full poll of the car is done, and Home Assistant is updated again. Setting polling_interval to a value a bit lower than how often you want the car to be updated will prevent this.

E.g. to ensure the polling happens and thus Home Assistant is updated every 11 minutes set the polling_interval to 655 instead. Now when the update runs at 12:11:00 it will be more than 655 seconds and a full poll will be done.

Polling interval is set to 60 seconds

• Every minute, Teslas servers are scanned to check the online status of all cars. This list is cached and used in the next step.
• If any cars are online (awake) we check what time we last did a full poll of that car.
• If this was at least 60 seconds ago (polling_interval), we will do another full poll of the car.

Due to the problem with polling slips described above, this means that a car might be polled (and Home Assistant updated) only every 1 minute and 10 seconds when polling interval is set to 60 seconds.

Polling interval is set to 5 seconds

• Every minute, Teslas servers are scanned to check the online status of all cars. This list is cached and used in the next step.
• If any cars are online (awake) we check what time we last did a full poll of that car.
• If this was at least than 5 seconds ago (which it always is, because we only check every 10 seconds), we will do another full poll of the car.

So this ensures that Home Assistant always have the latest (no more than 10 seconds old) data, as long as the car is online (awake).

The data will never be updated more frequently than every 10 seconds, as that is the set interval that the Home Assistant integration uses between each "update"-request it sends to teslajsonpy. This can not be overridden.

Changing the polling interval

There is an integration polling_interval that is common for all cars, adjusting this polling_interval will affect how often all cars are polled. There is also a polling_interval per car that can be set. If the polling_interval for a car is set then that polling interval will be used instead of the polling_interval for the integration. If you set a low polling interval, you can use the Polling Switch for each car to disable/enable polling of that particular car.

The polling_interval is set as part of the configuration of this integration.

The polling_interval can be temporarily changed using the tesla_custom.polling_interval service. To change the integration polling_interval:

service: tesla_custom.polling_interval
data:
  scan_interval: 120

Internally, Home Assistant calls this "scan_interval", hence the slightly confusing name of the parameter.

To change the polling_interval for a specific car:

service: tesla_custom.polling_interval
data:
  vin: 5YJSA11111111111
  scan_interval: 120

To remove the polling_interval for a specific car so that it will use the integration polling_interval again provide -1 as the scan_interval value:

service: tesla_custom.polling_interval
data:
  vin: 5YJSA11111111111
  scan_interval: -1

This allows you to dynamically adjust the polling_interval based on criteria such as the battery SOC, where the car is parked etc. to ensure you get the most updated information when you need it, while at the same time making sure that the car can enter sleep mode when you need to preserve energy.

For example, you have 2 cars (car A and car B) and the polling_interval is set to default which is 660. At this time polling happens every 660 seconds unless the car is driving in which case it happens every 60 seconds.

1. Call service tesla_custom.polling_interval with scan_interval = 330. Now both cars will be polled every 330 seconds. If one of the cars is driving then it will be polled every 60 seconds, the car that is not driving will still be polled every 330 seconds.
2. Call service tesla_custom.polling_interval with vin for car A and scan_interval = 30. Now car A will be polled every 30 seconds irrespective if it is driving or not, car B will still be polled every 330 seconds unless it is driving.
3. Call service tesla_custom.polling_interval with scan_interval = 180. This will not change anything for car A, car B will now be polled every 180 seconds unless it is driving.
4. Call service tesla_custom.polling_interval with vin for car B and scan_interval = 5. No change for car A, car B will now be polled every 10 seconds which is the minimum due to the static, not configurable timer.
5. Call service tesla_custom.polling_interval with vin for car A and scan_interval = -1. No change for car B, car A is set back to use the integration polling_interval which was set to 180 (see point 3).
6. Call service tesla_custom.polling_interval with vin for car B and scan_interval = -1. No change for car A, car B is set back to use the integration polling_interval which was set to 180 (see point 3).

Note that changing the polling_interval using the service call wil not modify the value set in the configuration of the integration. So after a restart of Home Assistant, polling_interval is set back to the configured value, not the last value set by the service call. To ensure the least chance of keeping the car awake unintentionally, we strongly suggest setting the polling_interval to a reasonably high value (or leaving it as default) in the configuration, and lowering it using the service call only when needed. That way, e.g. a restart of Home Assistant will not suddenly drain your battery while parked somewhere remote.

Sleeping and waking up

With newer software releases, the car tries very hard to go to sleep. So even if you do a full poll every minute (e.g set polling_interval to < 60 seconds), the car will usually go to sleep after being parked for a short while. When a car is woken up, either using the app, an API-call, or physcally by opening a door etc. it will usually go back to sleep after 10-15 minutes, even if you keep on polling it.

However, there have been reports that polling keeps the car awake, so be careful, especially when parked without a charger connected, as the car will use significantly more energy when it is awake than when it sleeps.

But if you want to keep track of, e.g., SOC on a regular interval, you need to make sure the car is awake, and wake the car up if it goes to sleep. This can be done using an automation that triggers when the "Online Binary Sensor" turns off to send an API-request to wake it up again. But be aware that this will drain your battery.

Also, it might be tempting to adjust the polling_interval to ensure that the data is refreshed more often than every 11 minutes. But keep an eye on the car status to make sure it is allowed to sleep if you lower that interval.

Polling Policy

The Polling Policy controls how aggressively we will poll the full status of a car. While the polling is normally done every polling_interval seconds, it is also dependent on other factors.

This integration will never touch a sleeping car. So as long as the car is sleeping, polling is skipped no matter what Polling Policy is set to.

If the car is in Drive (or Reverse) it will be polled at least every 60 seconds, or polling_interval if it is set to less than 60 seconds no matter what you set Polling Policy to.

If the car is in service, it will not be polled, no matter what Polling Policy you chose.

Polling Policy: Normal (default)

With Polling Policy set to "normal" it will poll the car every polling_interval seconds as long as the following criteria is met:

• The car is awake

And either

• Sentry mode is on or ...
• HVAC is on or ...
• The car was parked less than 10 minutes ago or ...
• The car is actively charging

If none of the above 4 criteria are met, this policy will throttle polling of the car back to minimum 660 seconds (non configurable), or to polling_interval if it is more than 660 seconds, after the car has been parked for more than 10 minutes. This is done to try to ensure that the car is allowed to sleep.

Polling Policy: Connected

With Polling Policy set to "connected" it will poll the car every polling_interval seconds as long as the following criteria is met:

• The car is awake

And either

• Sentry mode is on or ...
• HVAC is on or ...
• The car was parked or was woken up less than 10 minutes ago or ...
• The car is connected to a charger (even if it is not actively charging)

This will allow you to get more recent data from your car for e.g. statistical purposes as long as a charger is connected. It will also keep polling the car every polling_interval seconds for 10 minutes after you park or after the car is woken up. This is to ensure that you get refreshed data if the car is woken up because someone opens a door or unlocks the car without starting it.

Since this might keep the car awake and use more energy than allowing the car to sleep, a real cost might be incurred as the car will need to charge more, and more often.

If the car has been parked for more than 10 minutes, and is not connected to a charger, the same throttle as for the normal policy will be set.

Polling Policy: Always

With Polling Policy set to "always" it will poll the car every polling_interval seconds as long as the following criteria is met:

• The car is awake

There are no checks here to see if the car has been parked for a long time or if a charger is connected. So this setting can potentially keep the car awake forever.

Using this setting might have a huge impact on your "vampire drain" and is not recommended unless you have a specific reason.

Potential Battery impacts

Here are some things to consider and understand when implementing the Tesla component and its potential effect on your car's battery.

• The default polling_interval is 660 seconds. Polling a car too frequently can keep the car awake and drain the battery. Different firmware versions and measurements of Tesla cars shows that it can take from 11 to 15 minutes for sleep mode to occur. There is no official information on sleep mode timings so your mileage may vary and you should experiment with different polling intervals for an optimal experience.
• The car will, however, be woken up when a command is actively sent to the car, such as door unlock or turning on the HVAC. It will then also fetch updated information while the car is awake based on the polling_interval and Polling Policy.
• The car can intentionally be woken up to fetch recent information by sending a harmless command, for example, a lock command or a WAKE_UP API-call. This can be used in an automation to, for example, ensure that updated information is available every morning. (Note that the command must be valid for that specific car model. So locking the frunk of a Model 3 will not wake up that car).
• You can also toggle the polling switch on/off to disable polling of the vehicle completely via automations or the Lovelace UI.