tesla_api 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 18033816ec5eb77b7103295925eecef144e0c601
-  data.tar.gz: 372b7eccdcba14d8c7be82a45d3df1719f3c7ec5
+SHA256:
+  metadata.gz: 402e885d5f181024647338d54848e77f71a7fce7b2a3d4d308708366bb809d6a
+  data.tar.gz: 859d52863c8e0c58ee761edab3c418df031e96bec3fa1ce9d095bd2304bdf555
 SHA512:
-  metadata.gz: a38e04aa77bf22edc412f1d3af818b7a2f4c79255ce909e96a282808ca9441a71d42d51bc47760696b0783365fb89a4f186eb150fddec8afe2b075eb57da2af6
-  data.tar.gz: aaceed89e6cc188b2dfcf8a51c07bb3bf5158f4c86f62a978c2b20c78d94dfeae6e4d114d9ffb52a1dc1d9d1d9fe3b91863a837e6db59cd954aaf28245ad592d
+  metadata.gz: a64a3a8e93bdd1aecfb9274020a322482f96a83e1154a57db5f60cd415c79164f934c896e520fa2c234d145d12e42bcdfce3d48d2f6298e649db82cad1e190a8
+  data.tar.gz: 0b1e192d37378e004415108e44387aec166106d7616fa0b576c15d9475c83438b1445b164a88980331a5e7cfa30936ce7964775086b093b6f5a9979969e66e59

data/.gitbook.yml

@@ -0,0 +1,4 @@
+root: ./docs/
+structure:
+  readme: README.md
+  summary: SUMMARY.md

data/.travis.yml

@@ -1,9 +1,8 @@
 language: ruby
 rvm:
-  - 1.9.3
-  - 2.0.0
-  - 2.2.2
-  - 2.3.0
+  - 2.3
+  - 2.4
+  - 2.5
 env:
   global:
     - TESLA_EMAIL=elon.musk@teslamotors.com

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Tim Dorr
+Copyright (c) 2014-Present Tim Dorr
 
 MIT License
 

data/README.md

@@ -1,12 +1,16 @@
+Need a Tesla to develop with? Use [my referral link](http://ts.la/timothy8449) to get a $100 Supercharging credit.
+
 # Tesla JSON API
 
 [View Documentation](http://docs.timdorr.apiary.io/)
 
 This is unofficial documentation of the Tesla JSON API used by the iOS and Android apps.
 The API provides functionality to monitor and control the Model S (and future Tesla vehicles) remotely.
-The project provides both a documention of the API and a Ruby library to for accessing it.
+The project provides both a documention of the API and a Ruby library for accessing it.
+
+> If any folks at Tesla are reading this, I'd love to help coordinate a developer program for your APIs. If there's any way I can be helpful, please feel free to get in contact. Also, I'd love to be in the beta firmware program :wink:
 
-## Ruby Gem [![Gem Version](https://img.shields.io/gem/v/tesla_api.svg)](http://rubygems.org/gems/tesla_api) [![Build Status](https://img.shields.io/travis/timdorr/model-s-api/master.svg)](https://travis-ci.org/timdorr/model-s-api) [![Coverage Status](https://img.shields.io/coveralls/timdorr/model-s-api.svg)](https://coveralls.io/r/timdorr/model-s-api?branch=master)
+## Ruby Gem [![Gem Version](https://img.shields.io/gem/v/tesla_api.svg)](http://rubygems.org/gems/tesla_api) [![Build Status](https://img.shields.io/travis/timdorr/tesla-api/master.svg)](https://travis-ci.org/timdorr/tesla-api)
 
 This gem provides a basic wrapper around the API to easily query and command the car remotely. 
 It also provides access to the streaming API and a means to process data coming from it.
@@ -48,5 +52,5 @@ puts "Your Model S is #{charge_state["charging_state"]} " +
 
 ## Copyright
 
-Ruby portions are Copyright (c) 2014 Tim Dorr. Released under the terms of the
+Ruby portions are Copyright (c) 2014-Present Tim Dorr. Released under the terms of the
 MIT license. See LICENSE for details.

data/Rakefile

@@ -7,7 +7,33 @@ end
 
 desc "Open an irb session preloaded with this library"
 task :console do
-  sh "irb -rubygems -I lib -r tesla_api.rb -rdotenv"
+  # Load all gems
+  require 'rubygems'
+  require 'bundler/setup'
+  Bundler.require(:default)
+
+  # Load the envs
+  require 'dotenv'
+  Dotenv.load!
+
+  # Set up a global client
+  def client
+    @client ||= begin
+        client = TeslaApi::Client.new(ENV['TESLA_EMAIL'])
+        client.login!(ENV['TESLA_PASS'])
+        client
+    end
+  end
+
+  # Load IRB
+  require 'irb'
+  require 'irb/completion'
+
+  IRB.conf[:PROMPT_MODE] = :SIMPLE
+  IRB.conf[:AUTO_INDENT] = true
+
+  ARGV.clear
+  IRB.start
 end
 
 task default: :spec

data/apiary.apib

@@ -2,6 +2,11 @@ FORMAT: 1A
 HOST: https://owner-api.teslamotors.com
 
 # Tesla Model S JSON API
+
+# ⚠️ ⚠️ ⚠️ ⚠️
+# This site has moved! [https://tesla-api.timdorr.com/](https://tesla-api.timdorr.com/)
+# ⚠️ ⚠️ ⚠️ ⚠️
+
 This is unofficial documentation of the Tesla Model S JSON API used by the iOS and Android apps. It features functionality to monitor and control the Model S remotely.
 
 # Group Authentication
@@ -15,9 +20,9 @@ Returns a `access_token` which is passed along as a header with all future reque
 
 You must provide the `Authorization: Bearer {access_token}` header in all other requests.
 
-The current client ID and secret are [available here](http://pastebin.com/fX6ejAHd)
+The current client ID and secret are [available here](http://pastebin.com/YiLPDggh)
 
-+ Parameters
++ Attributes
     + grant_type: `password` (string) - The type of oAuth grant. Always "password"
     + client_id: `abc` (string) - The oAuth client ID
     + client_secret: `123` (string) - The oAuth client secret
@@ -30,7 +35,9 @@ The current client ID and secret are [available here](http://pastebin.com/fX6ejA
             {
               "access_token": "abc123",
               "token_type": "bearer",
-              "expires_in": 7776000
+              "expires_in": 7776000,
+              "created_at": 1457385291,
+              "refresh_token" : "cba321"
             }
 
 # Group Vehicles
@@ -329,7 +336,7 @@ Resets the PIN set for valet mode, if set.
             }
 
 ## Open Charge Port [POST /api/1/vehicles/{vehicle_id}/command/charge_port_door_open]
-Opens the charge port. Does not close the charge port (for now...)
+Opens the charge port. Does not close the charge port (for now...). This endpoint also unlocks the charge port if it's locked.
 
 + Request
     + Headers
@@ -559,7 +566,7 @@ Lock the car's doors.
               }
             }
 
-## Set Temperature [POST /api/1/vehicles/{vehicle_id}/command/set_temps?driver_temp={driver_degC}&passenger_temp={pass_degC}]
+## Set Temperature [POST /api/1/vehicles/{vehicle_id}/command/set_temps?driver_temp={driver_temp}&passenger_temp={passenger_temp}]
 Set the temperature target for the HVAC system.
 
 + Request
@@ -570,8 +577,8 @@ Set the temperature target for the HVAC system.
 + Parameters
 
     + vehicle_id: `1` (number) - The id of the Vehicle.
-    + driver_degC: `23.7` (number) - The desired temperature on the driver's side in celcius.
-    + pass_degC: `18.1` (number) - The desired temperature on the passenger's side in celcius.
+    + driver_temp: `23.7` (number) - The desired temperature on the driver's side in celcius.
+    + passenger_temp: `18.1` (number) - The desired temperature on the passenger's side in celcius.
 
 + Response 200 (application/json)
 
@@ -584,8 +591,8 @@ Set the temperature target for the HVAC system.
               }
             }
 
-## Start Air Condition [POST /api/1/vehicles/{vehicle_id}/command/auto_conditioning_start]
-Start the HVAC system. Will cool or heat automatically, depending on set temperature.
+## Start HVAC System [POST /api/1/vehicles/{vehicle_id}/command/auto_conditioning_start]
+Start the climate control system. Will cool or heat automatically, depending on set temperature.
 
 + Request
     + Headers
@@ -607,8 +614,8 @@ Start the HVAC system. Will cool or heat automatically, depending on set tempera
               }
             }
 
-## Stop Air Condition [POST /api/1/vehicles/{vehicle_id}/command/auto_conditioning_stop]
-Stop the HVAC system.
+## Stop HVAC System  [POST /api/1/vehicles/{vehicle_id}/command/auto_conditioning_stop]
+Stop the climate control system.
 
 + Request
     + Headers
@@ -687,7 +694,7 @@ Start the car for keyless driving. Must start driving within 2 minutes of issuin
             }
 
 ## Open Trunk/Frunk [POST /api/1/vehicles/{vehicle_id}/command/trunk_open]
-Open the trunk or frunk. Currently inoperable.
+Open the trunk or frunk. Call the endpoint again to close (this only works on rear powered trunks)
 
 + Request
     + Headers
@@ -697,7 +704,7 @@ Open the trunk or frunk. Currently inoperable.
 + Parameters
 
     + vehicle_id: `1` (number) - The id of the Vehicle.
-    + which_trunk: `rear` (string) - The trunk to open. `rear` is the only one known currently.
+    + which_trunk: `rear` (string) - The trunk to open. `rear` and `front` are the only options
 
 + Response 200 (application/json)
 
@@ -708,4 +715,4 @@ Open the trunk or frunk. Currently inoperable.
                 "result": true,
                 "reason": ""
               }
-            }
+            }

data/docs/README.md

@@ -0,0 +1,26 @@
+# Introduction
+
+This is unofficial documentation of the Tesla JSON API used by their iOS and Android apps. It features functionality to monitor and control their vehicle (Model S, Model X, and Model 3) and power (Powerwall) products. We currently have documentation for their vehicles, but always accept [pull requests](https://github.com/timdorr/tesla-api/pulls) for improvements and additions.
+
+## Before You Begin
+
+The base URI for all requests is `https://owner-api.teslamotors.com/` (except for the Streaming and Autopark APIs)
+
+_All requests require a_ `User-Agent` _header with any value provided._ For Tesla's sake, it's recommended you identify your application in some way using this header.
+
+## API Organization
+
+The API for vehicles is organized into 3 primary surfaces:
+
+### State and commands
+
+Gives point-in-time data about the state of the vehicle and basic controls over certain functions of the vehicle. The state and command APIs loosely adhere to the REST standard, but differ in some crucial ways. As a result, you may not be able to use it with many REST tools and libraries out of the box.
+
+### Streaming telemetry
+
+Streams in data about the car's telemetry at up to half second increments. The underlying protocol is simply a streaming HTTP API that provides JSON objects at regular intervals.
+
+### Autopark ("Summon")
+
+A streaming command mode to control the automatic parking of HW1 (Autopilot v1) and HW2/HW2.5 (Autopilot v2) cars. This API uses a standard WebSocket that exchanges JSON objects to convey state information and issue commands during the Autopark session.
+

data/docs/SUMMARY.md

@@ -0,0 +1,39 @@
+# Table of contents
+
+* [Introduction](README.md)
+
+## API Basics
+
+* [Authentication](api-basics/authentication.md)
+* [Vehicles](api-basics/vehicles.md)
+
+## Vehicle
+
+* [State](vehicle/state/README.md)
+  * [Data](vehicle/state/data.md)
+  * [Charge State](vehicle/state/chargestate.md)
+  * [Climate State](vehicle/state/climatestate.md)
+  * [Drive State](vehicle/state/drivestate.md)
+  * [GUI Settings](vehicle/state/guisettings.md)
+  * [Vehicle State](vehicle/state/vehiclestate.md)
+  * [Mobile Enabled](vehicle/state/mobileenabled.md)
+* [Commands](vehicle/commands/README.md)
+  * [Wake](vehicle/commands/wake.md)
+  * [Alerts](vehicle/commands/alerts.md)
+  * [Doors](vehicle/commands/doors.md)
+  * [Frunk/Trunk](vehicle/commands/trunk.md)
+  * [Sunroof](vehicle/commands/sunroof.md)
+  * [Charging](vehicle/commands/charging.md)
+  * [Climate](vehicle/commands/climate.md)
+  * [Media](vehicle/commands/media.md)
+  * [Navigation](vehicle/commands/nagivation.md)
+  * [Remote Start](vehicle/commands/remotestart.md)
+  * [Software Updates](vehicle/commands/softwareupdate.md)
+  * [Speed Limit](vehicle/commands/speedlimit.md)
+  * [Valet Mode](vehicle/commands/valet.md)
+  * [Calendar](vehicle/commands/calendar.md)
+
+* [Streaming](vehicle/streaming.md)
+* [Autopark/Summon](vehicle/autopark.md)
+* [Option Codes](vehicle/optioncodes.md)
+

data/docs/api-basics/authentication.md

@@ -0,0 +1,40 @@
+---
+description: The authentication process for the Tesla API
+---
+
+# Authentication
+
+The authentication process is via [an OAuth 2.0 Password Grant](https://oauth.net/2/grant-types/password/) with the same credentials used for tesla.com and the mobile apps.
+
+The current client ID and secret are [available here](https://pastebin.com/pS7Z6yyP).
+
+You will get back an `access_token` which is treated as [an OAuth 2.0 Bearer Token](https://oauth.net/2/bearer-tokens/). This token is passed along in an `Authorization` header with all future requests:
+
+```http
+Authorization: Bearer {access_token}
+```
+
+## POST `/oauth/token`
+
+### Request parameters
+
+| Field | Type | Example | Description |
+| :--- | :--- | :--- | :--- |
+| `grant_type` | String, required | `password` | The type of OAuth grant. Always "password" |
+| `client_id` | String, required | `abc` | The OAuth client ID |
+| `client_secret` | String, required | `123` | The OAuth client secret |
+| `email` | String, required | `elon@teslamotors.com` | The email for the authenticating Tesla account |
+| `password` | String, required | `edisonsux` | The password for the authenticating Tesla account |
+
+### Response
+
+```json
+{
+  "access_token":"abc123",
+  "token_type":"bearer",
+  "expires_in": 3888000,
+  "refresh_token":"cba321",
+  "created_at": 1538359034
+}
+```
+

data/docs/api-basics/vehicles.md

@@ -0,0 +1,77 @@
+---
+description: Endpoints for getting an account's vehicles
+---
+
+# Vehicles
+
+A logged in user can have multiple vehicles under their account (congrats on being rich!). This resource is primarily responsible for listing the vehicles and the basic details about them.
+
+#### `vehicle_id` vs `id`
+
+One potentially confusing part of Tesla's API is the switching use of the `id` and `vehicle_id` of the car. The `id` field is an identifier for the car on the owner-api endpoint. The `vehicle_id` field is for identifying the car across different endpoints, such as the streaming or Autopark APIs.
+
+For the state and command APIs, you should be using the `id` field. If your JSON parser doesn't support large numbers (>32 bit), then you can use the `id_s` field for a string version of the ID.
+
+## GET `/api/1/vehicles`
+
+Retrieve a list of your owned vehicles (includes vehicles not yet shipped!)
+
+### Request parameters
+
+### Response
+
+```json
+{
+  "response": [
+    {
+      "id": 12345678901234567,
+      "vehicle_id": 1234567890,
+      "vin": "5YJSA11111111111",
+      "display_name": "Nikola 2.0",
+      "option_codes": "MDLS,RENA,AF02,APF1,APH2,APPB,AU01,BC0R,BP00,BR00,BS00,CDM0,CH05,PBCW,CW00,DCF0,DRLH,DSH7,DV4W,FG02,FR04,HP00,IDBA,IX01,LP01,ME02,MI01,PF01,PI01,PK00,PS01,PX00,PX4D,QTVB,RFP2,SC01,SP00,SR01,SU01,TM00,TP03,TR00,UTAB,WTAS,X001,X003,X007,X011,X013,X021,X024,X027,X028,X031,X037,X040,X044,YFFC,COUS",
+      "color": null,
+      "tokens": ["abcdef1234567890", "1234567890abcdef"],
+      "state": "online",
+      "in_service": false,
+      "id_s": "12345678901234567",
+      "calendar_enabled": true,
+      "backseat_token": null,
+      "backseat_token_updated_at": null
+    }
+  ],
+  "count": 1
+}
+```
+
+## GET `/api/1/vehicles/{id}`
+
+These resources are read-only and determine the state of the vehicle's various sub-systems.
+
+### URL parameters
+
+| Field | Example | Description |
+| :--- | :--- | :--- |
+| `id` | `12345678901234567` | The `id` of the car. (Not the `vehicle_id`!) |
+
+### Response
+
+```json
+{
+  "response": {
+    "id": 12345678901234567,
+    "vehicle_id": 1234567890,
+    "vin": "5YJSA11111111111",
+    "display_name": "Nikola 2.0",
+    "option_codes": "MDLS,RENA,AF02,APF1,APH2,APPB,AU01,BC0R,BP00,BR00,BS00,CDM0,CH05,PBCW,CW00,DCF0,DRLH,DSH7,DV4W,FG02,FR04,HP00,IDBA,IX01,LP01,ME02,MI01,PF01,PI01,PK00,PS01,PX00,PX4D,QTVB,RFP2,SC01,SP00,SR01,SU01,TM00,TP03,TR00,UTAB,WTAS,X001,X003,X007,X011,X013,X021,X024,X027,X028,X031,X037,X040,X044,YFFC,COUS",
+    "color": null,
+    "tokens": ["abcdef1234567890", "1234567890abcdef"],
+    "state": "online",
+    "in_service": false,
+    "id_s": "12345678901234567",
+    "calendar_enabled": true,
+    "backseat_token": null,
+    "backseat_token_updated_at": null
+  }
+}
+```
+

data/docs/vehicle/autopark.md

@@ -0,0 +1,4 @@
+# Autopark/Summon
+
+
+

data/docs/vehicle/commands/README.md

@@ -0,0 +1,22 @@
+---
+description: These endpoints issue various commands to the car.
+---
+
+# Commands
+
+These commands alter the vehicles state and return a boolean `result` to indicate success.
+
+{% page-ref page="wake.md" %}
+{% page-ref page="alerts.md" %}
+{% page-ref page="doors.md" %}
+{% page-ref page="trunk.md" %}
+{% page-ref page="sunroof.md" %}
+{% page-ref page="charging.md" %}
+{% page-ref page="climate.md" %}
+{% page-ref page="media.md" %}
+{% page-ref page="nagivation.md" %}
+{% page-ref page="remotestart.md" %}
+{% page-ref page="softwareupdate.md" %}
+{% page-ref page="speedlimit.md" %}
+{% page-ref page="valet.md" %}
+{% page-ref page="calendar.md" %}

data/docs/vehicle/commands/alerts.md

@@ -0,0 +1,5 @@
+# Alerts
+
+Controls for honking the horn and flashing the lights.
+
+## POST `/api/1/vehicles/{id}/command/honk_horn`

data/docs/vehicle/commands/calendar.md

@@ -0,0 +1,3 @@
+# Calendar
+
+

data/docs/vehicle/commands/charging.md

@@ -0,0 +1,3 @@
+# Charging
+
+

data/docs/vehicle/commands/climate.md

@@ -0,0 +1,3 @@
+# Climate
+
+