The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Tesla-API-0.01
River stage one • 1 direct dependent • 1 total dependent
/ Tesla::API

NAME

Tesla::API - Interface to Tesla's API

Coverage Status

SYNOPSIS

    use Tesla::API;

    my $tesla = Tesla::API->new;

    my $vehicles = $tesla->my_vehicles;

    my $vehicle_name = $tesla->vehicle_name;

    my @endpoint_names = keys %{ $tesla->endpoints };

    # Using the internal api() until the complete interface
    # of this distribution is done

    my $endpoint_name = 'VEHICLE_DATA';

    my $car_data = $tesla->api($endpoint_name, $tesla->vehicle_id);

DESCRIPTION

This distribution provides access to the Tesla API.

WARNING: This is an initial, beta release. Barely any functionality has been implemented, and the authentication mechanism needs a lot of polishing.

It's currently in its infancy, so the interface may^H^H^Hwill change. Although there are very few public access methods available yet, all current and future ones behave the exact same way, by using the object's api() method with an endpoint name.

Some endpoints require an ID sent in, so it must be provided for those calls as well.

NOTE: The 'wake' function has not yet been fully impemented, so if a Tesla API call times out, its likely you'll have to use the official Tesla App to wake the car up.

METHODS

new(%params)

Instantiates and returns a new Tesla::API object.

NOTE: When instantiating an object and you haven't previously authenticated, a URL will be displayed on the console for you to navigate to. You will then be redirected to Tesla's login page where you will authenticate. You will be redirected again to a "Page Not Found" page, in which you must copy the URL from the address bar and paste it back into the console.

We then internally generate an access token for you, store it in a tesla_cache.json file in your home directory, and use it on all subsequent accesses.

NOTE: If you do not have a Tesla account, you can still instantiate a Tesla::API object by supplying the unauthenticated => 1 parameter to new().

Parameters:

All parameters are to be sent in the form of a hash.

    unauthenticated

Optional, Bool: Set to true to bypass the access token generation.

Default: False.

    vehicle_id

Optional, Integer: If sent in, we'll use this ID for all calls to endpoints that require one.

If not sent in, we'll check how many vehicles you own under your account, and if there's only one, we'll use that ID instead.

If you have more than one Tesla vehicle registered and you don't supply this parameter, you will have to supply the ID to each method call that requires it, or set it in vehicle_id($id) after instantiation.

Default: undef

api($endpoint, $id)

Responsible for disseminating the endpoints and retrieving data through the Tesla API.

Parameters:

    $endpoint

Mandatory, String: A valid Tesla API endpoint name. The entire list can be found in the t/test_data/endpoints.json file for the time being.

    $id

Optional, Integer: Some endpoints require an ID sent in (eg. vehicle ID, powerwall ID etc).

Return: Hash or array reference, depending on the endpoint.

data

Returns a hash reference of the data we've collected for you and stashed within the object. This does not reflect the entire object.

endpoints

Returns a hash reference of hash references. Each key is the name of the endpoint, and its value contains data on how we process the call to Tesla.

Example (snipped for brevity):

    {
        MEDIA_VOLUME_DOWN => {
            TYPE => 'POST',
            URI => 'api/1/vehicles/{vehicle_id}/command/media_volume_down'
            AUTH => $VAR1->{'UPGRADES_CREATE_OFFLINE_ORDER'}{'AUTH'},
        },
        VEHICLE_DATA => {
            TYPE => 'GET',
            URI => 'api/1/vehicles/{vehicle_id}/vehicle_data',
            AUTH => $VAR1->{'UPGRADES_CREATE_OFFLINE_ORDER'}{'AUTH'}
        },
    }

Bracketed names in the URI (eg: {vehicle_id}) are variable placeholders. It will be replaced with the ID sent in to the various method or api() call.

To get a list of endpoint names:

    my @endpoint_names = keys %{ $tesla->endpoints };

mech

Returns the WWW::Mechanze object we've instantiated internally.

my_vehicle_id($id)

Sets/gets your primary vehicle ID. If set, we will use this in all API calls that require it.

Parameters:

    $id

Optional, Integer: The vehicle ID you want to use in all API calls that require one, as opposed to sending it into every separate call.

If you only have a single Tesla vehicle registered under your account, we will set my_vehicle_id() to that ID when you instantiate the object.

You can also have this auto-populated in new() by sending it in with the vehicle_id => $id parameter.

my_vehicle_name

Returns the name you associated with your vehicle under your Tesla account.

"my_vehicle_id($id)" must have already been set.

my_vehicles

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 => 'Model S',
    }

vehicle_data($id)

Returns a hash reference containing state data of a vehicle.

croak()s if an ID isn't sent in and we can't sort one out automatically.

wake($id)

NOT YET IMPLEMENTED FULLY.

EXAMPLE USAGE

    use Data::Dumper;
    use Tesla::API;
    use feature 'say';

    my $tesla = Tesla::API->new;

    say $tesla->my_vehicle_name;

    print Dumper $tesla->vehicle_data;

Output (massively and significantly snipped for brevity):

    Dream machine

    $VAR1 = {
        'vehicle_config' => {
            'car_type' => 'modelx',
            'rear_seat_type' => 7,
            'rear_drive_unit' => 'Small',
            'wheel_type' => 'Turbine22Dark',
            'timestamp' => '1647461524710',
            'rear_seat_heaters' => 3,
            'trim_badging' => '100d',
            'headlamp_type' => 'Led',
            'driver_assist' => 'TeslaAP3',
        },
        'id_s' => 'XXXXXXXXXXXXXXXXX',
        'vehicle_id' => 'XXXXXXXXXX',
        'charge_state' => {
            'usable_battery_level' => 69,
            'battery_range' => '189.58',
            'charge_limit_soc_std' => 90,
            'charge_amps' => 48,
            'charge_limit_soc' => 90,
            'battery_level' => 69,
        },
        'vin' => 'XXXXXXXX',
        'in_service' => $VAR1->{'vehicle_config'}{'use_range_badging'},
        'user_id' => 'XXXXXX',
        'id' => 'XXXXXXXXXXXXX',
        'drive_state' => {
            'shift_state' => 'P',
            'heading' => 92,
            'longitude' => '-XXX.XXXXXX',
            'latitude' => 'XX.XXXXXX',
            'power' => 0,
            'speed' => undef,
        },
        'api_version' => 34,
        'display_name' => 'Dream machine',
        'state' => 'online',
        'access_type' => 'OWNER',
        'option_codes' => 'AD15,MDL3,PBSB,RENA,BT37,ID3W,RF3G,S3PB,DRLH,DV2W,W39B,APF0,COUS,BC3B,CH07,PC30,FC3P,FG31,GLFR,HL31,HM31,IL31,LTPB,MR31,FM3B,RS3H,SA3P,STCP,SC04,SU3C,T3CA,TW00,TM00,UT3P,WR00,AU3P,APH3,AF00,ZCST,MI00,CDM0',
        'vehicle_state' => {
            'valet_mode' => $VAR1->{'vehicle_config'}{'use_range_badging'},
            'vehicle_name' => 'Dream machine',
            'sentry_mode_available' => $VAR1->{'vehicle_config'}{'plg'},
            'sentry_mode' => $VAR1->{'vehicle_config'}{'use_range_badging'},
            'car_version' => '2022.4.5.4 abcfac6bfcdc',
            'homelink_device_count' => 3,
            'is_user_present' => $VAR1->{'vehicle_config'}{'use_range_badging'},
            'odometer' => 'XXXXXXX.233656',
            'media_state' => {
                'remote_control_enabled' => $VAR1->{'vehicle_config'}{'plg'}
            },
        },
        'autopark_style' => 'dead_man',
        'software_update' => {
            'expected_duration_sec' => 2700,
            'version' => ' ',
            'status' => '',
            'download_perc' => 0,
            'install_perc' => 1
        },
        'speed_limit_mode' => {
            'max_limit_mph' => 90,
            'min_limit_mph' => '50',
            'active' => $VAR1->{'vehicle_config'}{'use_range_badging'},
            'current_limit_mph' => '80.029031',
            'pin_code_set' => $VAR1->{'vehicle_config'}{'plg'}
        },
        'climate_state' => {
               'passenger_temp_setting' => '20.5',
               'driver_temp_setting' => '20.5',
               'side_mirror_heaters' => $VAR1->{'vehicle_config'}{'use_range_badging'},
               'is_climate_on' => $VAR1->{'vehicle_config'}{'use_range_badging'},
               'fan_status' => 0,
               'seat_heater_third_row_right' => 0,
               'seat_heater_right' => 0,
               'is_front_defroster_on' => $VAR1->{'vehicle_config'}{'use_range_badging'},
               'battery_heater' => $VAR1->{'vehicle_config'}{'use_range_badging'},
               'is_rear_defroster_on' => $VAR1->{'vehicle_config'}{'use_range_badging'},
        },
        'gui_settings' => {
              'gui_temperature_units' => 'C',
              'gui_charge_rate_units' => 'km/hr',
              'gui_24_hour_time' => $VAR1->{'vehicle_config'}{'use_range_badging'},
              'gui_range_display' => 'Ideal',
              'show_range_units' => $VAR1->{'vehicle_config'}{'plg'},
              'gui_distance_units' => 'km/hr',
              'timestamp' => '1647461524710'
        }
    };

AUTHOR

Steve Bertrand, <steveb at cpan.org>

LICENSE AND COPYRIGHT

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