Tesla::Vehicle - Access information and command Tesla automobiles via the API
use Tesla::Vehicle; my $car = Tesla::Vehicle->new; $car->wake if ! $car->online; if ($car->locked) { $car->doors_unlock; $car->climate_on; if ($car->temperature_outside < 0) { # Freezing! $car->climate_defrost_max; } } printf( "%s is at %d%% charge, is moving %d MPH and is using %.2f kWh per mile\n", $car->name, $car->battery_level, $car->speed, $car->power ); my $physical_address_hashref = $car->address;
This distribution provides methods for accessing and updating aspects of your Tesla vehicle. Not all attributes available through Tesla's API have methods listed here yet, but more will be added as time goes on.
To access attributes that we don't have methods for, see the "AGGREGATE DATA METHODS" section, pull that data, then extract out the info you want. If we don't have an aggregate data method for something you want yet, see Tesla::API to be able to get this yourself.
As always, requests for updates to my software is encouraged. Please just open an issue.
The parent module Tesla::API that we inherit the Tesla API access code from has a complex caching mechanism in place that you ought to know about. Please do read through the Tesla API Caching documentation.
Instantiates and returns a new Tesla::Vehicle object. We subclass Tesla::API so there are several things inherited.
Parameters:
All parameters are sent in as a hash. See the documentation for Tesla::API for further parameters that can be sent into this method.
id
Optional, Integer: The ID of the vehicle you want to associate this object with. Most methods require this to be set. You can send it in after instantiation by using the id() method. If you don't know what the ID is, you can instantiate the object, and dump the returned hashref from a call to list().
id()
list()
As a last case resort, we will try to figure out the ID by ourselves. If we can't, and no ID has been set, methods that require an ID will croak().
croak()
auto_wake
Optional, Bool: If set, we will automatically wake up your vehicle on calls that require the car to be in an online state to retrieve data (via a call to wake()). If not set and the car is asleep, we will print a warning and exit. You can set this after instantiation by a call to auto_wake().
wake()
auto_wake()
Default: False.
api_cache_time
Optional, Integer: The number of seconds to cache data returned from Tesla's API.
Default: 2
warn
Enables or disables the warnings that we receive from Tesla if there's a failure to execute one of the "COMMAND METHODS".
If enabled, we print these warnings to STDOUT.
STDOUT
Optional, Bool: True (1) to enable, false (0) to disable the warnings.
1
0
Default: True
Informs this software if we should automatically wake a vehicle for calls that require it online, and the vehicle is currently offline.
Send in a true value to allow us to do this.
Default: False
$bool
Sets/gets your primary vehicle ID. If set, we will use this in all API calls that require it.
$id
Optional, Integer: The vehicle ID you want to use in all API calls that require one. This can be set as a parameter in new(). If you attempt an API call that requires and ID and one isn't set, we croak().
new()
If you only have a single Tesla vehicle registered under your account, we will set id() to that ID when you instantiate the object.
You can also have this auto-populated in new() by sending it in with the id => $id parameter.
id => $id
If you don't know the ID of the vehicle you want to use, make a call to list(), and it will return a hash reference where each key is a vehice ID, and the value is the name you've assigned your vehicle.
Returns the name you associated with your vehicle under your Tesla account.
NOTE:"id($id)" must have already been set, either through the id() method, or in new().
Returns a hash reference of your listed vehicles. The key is the vehicle ID, and the value is the name you've assigned to that vehicle.
Example:
{ 1234567891011 => "Dream machine", 1234567891012 => "Steve's Model S", }
Returns a bool whether your vehicle is in service mode or not.
NOTE: The Tesla API, since 2019, has been returning wrong information about vehicle option codes, so do not trust them. For my Model X, I'm getting returned option codes for a Model 3. Several people I've spoken to about the issue see the same thing for their Model S.
Returns a hash reference of the options available on your vehicle. The key is the option code, and the value is the option description.
{ 'APH3' => 'Autopilot 2.5 Hardware', 'RENA' => 'Region: North America', 'MR31' => 'Uplevel Mirrors', 'GLFR' => 'Final Assembly Fremont', }
Returns an integer of Tesla's representation of the vehicle identification of your vehicle. This is not the same as the ID you use to access the API.
Returns an alpha-numeric string that contains the actual Vehicle Identification Number of your vehicle. This value is located on a stamped plate on the driver's side bottom on the outside of your windshield.
Alongside "latitude" and "longitude", we provide a convenience method to return human readable address location data for your vehicle.
Takes no parameters. If the "latitude" and "longitude" information for the vehicle is available, we will return a hash reference containing the street address information of the vehicle.
The return hash reference may have additional keys depending on the specific location.
Example return:
{ 'state' => 'British Columbia', 'city' => 'Kelowna', 'road' => 'Old Vernon Road', 'postcode' => 'V1X 7T8', 'village' => 'Ellison', 'country' => 'Canada', 'ISO3166-2-lvl4' => 'CA-BC', 'leisure' => 'Ellison Dog Park', 'country_code' => 'ca', 'county' => 'Regional District of Central Okanagan' }
All command methods return a true value (1)if the operation was successful, and a false value (0) if the command failed.
We will also print to STDOUT the reason for the failure if one occurred. This warning includes the message we received from Tesla.
You can disable these warnings from being displayed by sending in a false value to warn(), or instantiate the object with new(warn = 0)>.
warn()
new(warn =
Example warning:
$vehicle->media_volume_up; # Output Couldn't turn volume up: 'user_not_present'
Toggles the HVAC Bio Weapon mode on or off.
Returns true on success, false on failure.
Turns the climate system on to whatever settings they last had.
Returns true on success.
Follow up with a call to is_climate_on() to verify.
is_climate_on()
Turns the climate system off.
Returns true if the call was successful, false otherwise.
Locks the car doors. Returns true on success.
Follow up with a call to locked() to verify.
locked()
Unlocks the car doors. Returns true on success.
Honks the horn once. Returns true on success.
Flashes the exterior lights of the vehicle.
Play/Pause the currently loaded audio in the vehicle.
NOTE: Most often reason for fail is "User Not Present".
Skips to the next audio track.
Skips to the previous audio track.
Turns down the audio volume by one notch.
Turns up the audio volume by one notch.
Sets the limit in percent the battery can be charged to.
Returns true if the operation was successful, and false if not.
Follow up with a call to battery_level().
battery_level()
Opens or closes the rear trunk.
You must give time for the trunk to shut before checking its status with the trunk_rear() call.
trunk_rear()
You must give time for the trunk to shut before checking its status with the trunk_front() call.
trunk_front()
Attempt to wake the vehicle up from sleep mode. Most method calls against this object require the vehicle to be awake.
We don't return anything; the vehicle will be woken up, or it won't and your next method call will fail.
By default, this software does not wake up the car automatically, it just croaks if the car isn't awake and you attempt something it can't do while sleeping.
croak
Set auto_wake => 1 in new() or auto_wake(1) to allow us to automatically wake the vehicle up.
auto_wake => 1
auto_wake(1)
These methods aggregate all attributes of the vehicle that relate to a specific aspect of the vehicle. Methods that allow access to individual attributes of these larger aggregates are listed below. For example, charge_state() will return the battery_level attribute, but so will battery_level(). By using the aggregate method, you'll have to fish that attribute out yourself.
charge_state()
battery_level
Returns a hash reference containing all available API data that Tesla provides for your vehicles.
croak()s if you haven't specified a vehicle ID through new() or id(), and we weren't able to figure one out automatically.
This data will be retained and re-used for a period of two (2) seconds to reduce API calls through the Tesla API. This timing can be overridden in the new() method by specifying the refresh => $seconds parameter, or by a call to the object's delay($seconds) method.
2
refresh => $seconds
delay($seconds)
Return: Hash reference. Contains every attribute Tesla has available through their API for their vehicles.
The data accessor methods listed below use this data, simply selecting out individual parts of it.
Returns an important list of information about your vehicle, and Tesla's API access.
The most important piece of information is the vehicle's state, which shows whether the car is online or not. Other information includes in_service, vin, the display_name etc.
state
in_service
vin
display_name
Return: Hash reference.
Returns the vehicle_state section of Tesla's vehicle data. This includes things like whether the car is locked, whether there is media playing, the odometer reading, whether sentry mode is enabled or not etc.
vehicle_state
Returns information regarding battery and charging information of your vehicle.
Returns information regarding the climate state of the vehicle.
Returns the information about the operation of the vehicle.
Returns attributes related to the actual configuration of your vehicle.
Returns a string of the state of the dashcam (eg. "Recording").
Returns true if the doors are locked, false if not.
Returns true if the vehicle is online and ready to communicate, and false if
Returns the number of miles the vehicle is traveled since new, as a floating point number.
Returns a bool indicating whether the vehicle is in sentry mode or not.
Returns a bool whether the vehicle is in "Santa" mode or not.
Returns true if the front trunk (ie. Frunk) is open, and false if it's closed.
Returns true if the rear trunk is open, and false if it's closed.
Returns a bool indicating whether someone with a valid FOB key is in proximity of the vehicle.
Retrieves information regarding the actual operation and location of the vehicle.
Returns a single alpha character representing the gear the vehicle is in.
One of P for parked, N for Neutral, D for Drive and R for reverse.
P
N
D
R
This value is very often retured as undefined by Tesla, so a custom value of U is returned if the Tesla API doesn't return a valid value after API_RETRIES attempts to get one.
U
API_RETRIES
Returns an integer that is the timestamp that the GPS data was last refreshed from the vehicle.
Returns an integer between 0 and 360 which is the current compass heading of the vehicle.
360
Returns a signed float of the current Latitude of the vehicle.
Returns a signed float of the current Longitude of the vehicle.
Returns a signed float that contains the current kWh (Kilowatt-hours) per mile the car is currently consuming in its operation.
A negative value indicates that either the car is plugged in and charging, or that the regenerative brakes are engaged and are replenishing the battery (eg. the car is going downhill and the car is decelerating).
Returns a float of the vehicle's speed in MPH.
Returns an integer of the percent that the battery is charged to.
Returns a float indicating how many Amps the vehicle is set to draw through the current charger connection.
Returns a float indicating how many Amps are actually being drawn through the charger.
Returns an integer stating what percentage of battery level you've indicated the charging will be cut off at.
"soc" stands for "State of Charge"
Returns an integer stating Tesla's default charge_limit_soc is set to.
Returns an integer stating what the minimum number you can set as the Charge Limit SOC (charge_limit_soc).
charge_limit_soc
Returns an integer stating what the maximum number you can set as the Charge Limit SOC (charge_limit_soc).
Returns a string containing the color of the vehicle's charge port (eg. "Green Flashing" etc).
Returns a float containing the actual Voltage level that the charger is connected through.
Returns a hash reference of arrays. The keys are super_chargers and destination_chargers. Under each key is an array of charging station details, each in a hash reference. The hash references are sorted in the array as closest first, farthest last. All stations with no available stalls have been removed. Each station has the following properties:
super_chargers
destination_chargers
{ total_stalls => 8, site_closed => $VAR1->{'super_chargers'}[0]{'site_closed'}, location => { long => '-119.429277', lat => '49.885799' }, name => 'Kelowna, BC', type => 'supercharger', distance_miles => '26.259798', available_stalls => 4 }
Returns a string that identifies the state of the vehicle's charger. Eg. "Disconnected", "Connected" etc.
Returns an integer containing the estimated number of minutes to fully charge the batteries, taking into consideration voltage level, Amps requested and drawn etc.
Yes, this is truly a thing. At least my Tesla vehicle has a mode that seals the vehicle from all outside air, and puts positive pressure inside the cabin to ensure that no contaminents can enter the vehicle.
This method returns a bool to indicate whether this mode is enabled or not.
Is the front windshield defroster on or not
Is the rear window defroster on or not.
Returns an integer that represents the climate fan speed.
Is the battery warmer on or not.
Is the driver's seat warmer on.
Is the passenger's seat warmer on.
Is the wing mirror heater on.
Is the steering wheel warmer on or not
Is the windshield wiper warmer on.
Is the climate system currently active.
Is the air conditioning unit active.
The current temperature inside of the vehicle cabin.
The temperature outside of the vehicle.
What the driver's side temperature setting is set to.
What the passenger's side temperature setting is set to.
Steve Bertrand, <steveb at cpan.org>
<steveb at cpan.org>
Copyright 2022 Steve Bertrand.
This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:
http://www.perlfoundation.org/artistic_license_2_0
To install Tesla::Vehicle, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Tesla::Vehicle
CPAN shell
perl -MCPAN -e shell install Tesla::Vehicle
For more information on module installation, please visit the detailed CPAN module installation guide.