An unofficial NodeJS library that encapsulates the Tesla RESTful API. This library currently supports all existing Tesla vehicles.
First, it is important to acknowledge that there are already several very good Javascript libraries available for the Tesla. So why create another one? Rather than contribute to or modify one or more of the existing libraries, this library was created for two main reasons:
- The anticipated need for a few small but important features that existing libraries did not provide
- I was looking for a personal opportunity to learn more about the Tesla REST API, NodeJS, Express and Git/GitHub
With the introduction of the new OAuth-based owner API, one of the features I wanted was the ability to make API callswithout having to login each time a new process was invoked. Many existing libraries require a login transaction with each initiation of the library. With the TeslaJS library, once an auth token is retrieved it can be cached and used to make other Tesla REST API calls. For certain use cases, notably server logging of multiple vehicles, this can be important for moderating load on the Tesla login servers.
This is also important if you want to use the library to do server-based data logging. It is generally safer to store an OAuth token on the server rather than logon credentials. If the server is compromised only the OAuth token is at risk and all existing tokens can be invalidated by changing the password on the account.
Another feature that I wanted was API stateless-ness (achieved via an options parameter to API calls) so that it was possible to use the library to make multiple overlapping async calls for different vehicles for data-logging.
We've recently added auto-generated documentation via jsdocs. See the DOCS for a mostly complete reference. Please let us know if you see something missing and we'll continue to expand.
This project has a few principles that have and will continue to guide its development.
- Dependency lean. Try to keep the required dependencies to a minimum.
- Comprehensive. Attempt to expose the full Tesla REST API surface area.
- Simple. Using the library should be simple and straightforward following common conventions.
- Server friendly. Provide for use based on auth tokens and avoid requiring access to passwords.
Contributions are welcome, particularly bug fixes and enhancements! Refer to our Contribution Guidelines for details.
Please note that Project owners reserve the right to accept or reject any PR for any reason.
Before contributing or participating in the TeslaJS community please be sure to familiarize yourself with our project code of conduct. These guidelines are intended to govern interactions with and within the TeslaJS community.
You can read the complete history of changes in the CHANGELOG.
Here are some of the more recent features and fixes:
- In 2.1.33 fixed
homelinksample cmd line parms #84 - In 2.1.34 merged PR #85 to add vehicleConfig()
- In 2.1.35 added
vehicleConfigsample - In 2.1.36 fixed #44 sunroof control and
sunroofsample
- The homelink API appears to require Autopilot hardware. Can someone with AP test and report back?
- Calendar support not yet functional. If someone can share the JSON for a valid calendar request that would help!
The Tesla REST API encapusulated by this library was documented through the collaboration of many Tesla owners. Please thank and support them for their efforts! The current REST API documentation can be found at:
http://docs.timdorr.apiary.io/
Note that timdorr has announced plans to migrate the documentation to a new location. This reference will be updated in the future once that migration is complete.
You may use this library with the understanding that doing so is AT YOUR OWN RISK. No warranty, express or implied, is made with regards to the fitness or safety of this code for any purpose. If you use this library to query or change settings of your vehicle you understand that it is possible to make changes that could inadvertently lower the security of your vehicle, or cause damage, through actions including but not limited to:
- Unlocking the vehicle
- Remotely starting the vehicle
- Opening the sunroof
- Opening the frunk or trunk
- Lowering the battery charge level
- Impacting the long-term health of your battery
Please be careful not to use this code in a way that loads the Tesla servers with too many with requests. Calling the Tesla REST APIs at a very high frequency will stress the Tesla servers and could get your IP or favorite cloud service blocked by Tesla. Or in the worst case it could cause Tesla to revoke the key that enables access via this and many other libraries.
In order to use the library and/or samples you must first download and install NodeJS.
An installable TeslaJS module for npm is now available.
To download and install the library and all of its dependencies to a local
project directory use the following:
npm install teslajs
If you are building an npm package that depends upon this library then you will want to use the --save parameter in order to update the package.json file for your package as follows:
npm install teslajs --save
If you prefer to download and install the library globally for all future node projects you may use:
npm install -g teslajs
You may also install directly from the GitHub source. Either download and unzip the source, or clone the repository.
Remember, whether you install via ZIP source or Git clone you must install the dependencies before using TeslaJS.
To install dependencies via npm, from the root level of the library directory type:
npm install
This library and its accomanying samples are under active development. New features, samples and bug fixes are being added regularly. To ensure that you have the very latest version of TeslaJS and it's dependencies be sure to update frequently.
To do so, from your project directory type:
npm update
As you can see below, it is very simple to login and acquire an OAuth token.
var tjs = require('TeslaJS');
var username = "<your MyTesla email>";
var password = "<your MyTesla password>";
tjs.login(username, password, function(err, result) {
if (result.error) {
console.log(JSON.stringify(result.error));
process.exit(1);
}
var token = JSON.stringify(result.authToken);
if (token)
console.log("Login Succesful!");
});Note: Currently the only way to invalidate an issued token is to change your MyTesla account password. Therefore, you must take care to properly secure tokens. Do not share them over an unsecure connection, or store them on a public machine.
With the OAuth token from a successful login() call you can query the
vehicles for the account:
var options = { authToken: result.authToken };
tjs.vehicles(options, function (err, vehicle) {
console.log("Vehicle " + vehicle.vin + " is: " + vehicle.state);
});Or using the new Async Promise-based calls:
tjs.vehiclesAsync(options).done(function(vehicle) {
console.log("Vehicle " + vehicle.vin + " is: " + vehicle.state);
});Adding the vehicle ID from a successful vehicles() call to options you can
make other Tesla REST calls:
tjs.chargeState(options, function (err, chargeState) {
console.log("Current charge level: " + chargeState.battery_level + '%');
});And using the new Async Promise-based calls:
tjs.chargeStateAsync(options).done(function(chargeState) {
console.log("Current charge level: " + chargeState.battery_level + '%');
});Or using the new vehicleData API call:
tjs.vehicleData(options).done(function(vehicleData) {
var chargeState = vehicleData.charge_state;
console.log("Current charge level: " + chargeState.battery_level + '%');
});The TeslaJS library exports a number of methods and constants. The library also responds to some environment variables.
Environment Variables
| ENV variable | Description |
|---|---|
| TESLAJS_LOG | if set defines the value of the default logging level |
| TESLAJS_SERVER | if set defines the URI for the Tesla servers (e.g. set to http://127.0.0.1:3000) |
| TESLAJS_STREAMING | if set defines the URI for the Tesla streaming servers (e.g. set to http://127.0.0.1:3000) |
General API calls
| Function | Description |
|---|---|
| getLogLevel() | gets the level of debug logging |
| setLogLevel() | sets the level of debug logging |
| getVin() | return the VIN from the vehicle object |
| getShortVin() | return short form VIN from the vehicle object |
| getPortalBaseURI() | gets the server URI |
| setPortalBaseURI() | sets the server for testing, pass null to reset |
| login() | authenticate with Tesla servers and retrieve the OAuth token |
| loginAsync() | same as above but returns a Promise |
| logout() | delete the current OAuth token |
| logoutAsync() | same as above but returns a Promise |
| vehicles() | retrieve list of vehicles and return requested vehicle option data |
| vehicle() | same as above |
| vehiclesAsync() | same as above but returns a Promise |
| vehicleAsync() | same as above |
| allVehicles() | return information and option data for all vehicles |
| allVehiclesAsync() | same as above but returns a Promise |
| getModel(vehicle) | returns the Tesla model as a string from vehicle object |
| getPaintColor(vehicle) | returns the paint color as a string from vehicle object |
NodeJS Callback (nodeback) style API calls for a given vehicle id
| Function | Description |
|---|---|
| chargeState() | retrieve the charge_state data |
| chargeStandard() | set the charge limit to 90% |
| chargeMaxRange() | sets the charge limit to 100% |
| climateState() | retrieve the climate_state data |
| climateStart() | turn on the HVAC system |
| climateStop() | turn off the HVAC system |
| closeChargePort() | close the charge port on appropriately equipped vehicles |
| doorLock() | locks the doors |
| doorUnlock() | unlocks the doors |
| driveState() | retrieve the drive_state data |
| flashLights() | flashes the headlights |
| guiSettings() | retrieves the GUI settings |
| homelink() | Triggers homelink from the vehicle |
| honkHorn() | honks the horn |
| mobileEnabled() | returns whether mobile access is enabled |
| startCharge() | initiates a charging session |
| stopCharge() | terminates a charging session |
| openChargePort() | opens the charge port, or releases the latch if the charge port is open, a cable is plugged in, and charging is stopped |
| openTrunk() | open the trunk or frunk |
| refreshToken() | retrieve new OAuth token from refresh token |
| remoteStart() | enables remote starting of the car |
| resetValetPin() | reset the valet pin |
| setChargeLimit() | sets the charge limit to a specific amount |
| setTemps() | set driver/passenger temp set points (in Deg.C) |
| setValetMode() | set/reset valet mode |
| startStreaming() | initiate a streaming data session |
| sunRoofControl() | put the sunroof into a specific state |
| sunRoofMove() | open the sunroof to a specific percent |
| vehicleData() | retrieve all vehicle state data in a single call |
| vehicleConfig() | retrieve the vehicle_config data |
| vehicleState() | retrieve the vehicle_state data |
| wakeUp() | attempt to wake a sleeping vehicle |
Promise based API calls for a given vehicle id
| Function | Description |
|---|---|
| chargeStateAsync() | retrieve the charge_state data |
| chargeStandardAsync() | set the charge limit to 90% |
| chargeMaxRangeAsync() | sets the charge limit to 100% |
| climateStateAsync() | retrieve the climate_state data |
| climateStartAsync() | turn on the HVAC system |
| climateStopAsync() | turn off the HVAC system |
| closeChargePortAsync() | close the charge port on appropriately equipped vehicles |
| doorLockAsync() | locks the doors |
| doorUnlockAsync() | unlocks the doors |
| driveStateAsync() | retrieve the drive_state data |
| flashLightsAsync() | flashes the headlights |
| guiSettingsAsync() | retrieves the GUI settings |
| homelinkAsync() | Triggers homelink from the vehicle |
| honkHornAsync() | honks the horn |
| mobileEnabledAsync() | returns whether mobile access is enabled |
| startChargeAsync() | initiates a charging session |
| stopChargeAsync() | terminates a charging session |
| openChargePortAsync() | opens the charge port, or releases the latch if the charge port is open, a cable is plugged in, and charging is stopped |
| openTrunkAsync() | open the trunk or frunk |
| refreshTokenAsync() | retrieve new OAuth token from refresh token |
| remoteStartAsync() | enables remote starting of the car |
| resetValetPinAsync() | reset the valet pin |
| setChargeLimitAsync() | sets the charge limit to a specific amount |
| setTempsAsync() | set driver/passenger temp set points (in Deg.C) |
| setValetModeAsync() | set/reset valet mode |
| startStreamingAsync() | initiate a streaming data session |
| sunRoofControlAsync() | put the sunroof into a specific state |
| sunRoofMoveAsync() | open the sunroof to a specific percent |
| vehicleDataAsync() | retrieve all vehicle state data in a single call |
| vehicleConfigAsync() | retrieve the vehicle_config data |
| vehicleStateAsync() | retrieve the vehicle_state data |
| wakeUpAsync() | attempt to wake a sleeping vehicle |
Library exported constants
| Constant | Description |
|---|---|
| streamingPortal | the URI for the streaming API portal |
| portal | the base URI for the OAuth-based API portal |
| API_LOG_ALWAYS | log this message always |
| API_CALL_LEVEL | log all API calls |
| API_RETURN_LEVEL | log all API calls and completions |
| API_REQUEST_LEVEL | log all API requests |
| API_RESPONSE_LEVEL | log all API responses |
| API_BODY_LEVEL | log calls and completions as well as the body of POST commands |
| API_LOG_ALL | the highest level of logging |
| CHARGE_STORAGE | charge to 50% |
| CHARGE_STANDARD | charge to 90% |
| CHARGE_RANGE | charge to 100%. Tesla recommends against frequent usage! |
| MAX_TEMP | maximum temperature for climate system |
| MIN_TEMP | minimum temperature for climate system |
| SUNROOF_CLOSED | closes the sunroof |
| SUNROOF_VENT | open the sunroof to the vent position |
| streamingColumns | an array of the available streaming columns |
Most of the APIs take both an options parameter and an optional callback function. The options parameter must always contain a property called authToken that contains the OAuth token returned from a successfull login(). For all APIs that act on a specific vehicle the options parameter must also contain a vehicleID member that contains the long vehicle ID value returned from a successful call to vehicles().
By default the vehicles() API returns information on the first vehicle returned. By providing a carIndex member in the options parameter information on a specific vehicle can be queried.
A number of samples are provided in the Examples directory. These demonstrate some basic usage scenarios for the library. To use the samples first:
cd Examples
After running the login sample an auth token will be cached locally.
If you prefer to avoid keeping an auth token on your machine, provide login
credentials on the command line for each sample. This will perform a login
request and keep the token only for the duration of the sample. The
difference lies in whether you are more comfortable with the security of a
file associated with an account in your file system vs. the visibility of
your login credentials in the process table for the lifetime of the sample.
| Sample | Description |
|---|---|
| login | Login and acquire an OAuth token. Cached to the local directory |
| logout | Delete the locally cached OAuth token if present |
| climate | Display the current state of the HVAC system |
| climateStart | Turn on the HVAC system |
| climateStop | Turn off the HVAC system |
| flashLights | Flash the headlights |
| geoloc | Display the current GPS location of the vehicle |
| guiSettings | Display the current unit format settings |
| homelink | Trigger homelink (note appears to require AP hardware) |
| honkHorn | Honk the horn |
| lock | Lock the car doors |
| mobileEnabled | Display whether remote access is enabled |
| odometer | Displays the current odometer value |
| openChargePort | Opens the charge port, or releases the latch if the charge port is open, a cable is plugged in, and charging is stopped |
| resetValetPin | Resets the valet mode pin |
| remoteStart | Enables driving without the key fob present |
| setChargeLimit | Set the battery charge limit to the given value |
| setTemps | Set the driver and passenger temperatures to the given value |
| simpleStreaming | Demonstrates basic use of the streaming API |
| soc | Displays the current battery State of Charge (SOC) for the vehicle |
| startCharge | Initiate a charging session |
| stopCharge | Terminate a charging session |
| sunroof | Control the sunroof. Be careful! |
| unlock | Unlock the car doors |
| valet | Enable or disable valet mode |
| vehicle | Retrieve and display information on the current vehicle state |
| vehicleConfig | Retrieve and display information on the current vehicle configuration |
| wakeup | Send a wakeup command to the vehicle |
This sample demonstrates the basic login process which returns the OAuth token required for other API calls. The sample writes out a file called .token which stores the OAuth token. Other samples will use this cached token if present to avoid the need to enter the username and password and login via the Tesla servers.
If you prefer not to have your OAuth token stored locally do not run this sample. Instead you may run the samples and provide the username and password each time on the command line.
Usage:
node login.js [options] username password
Options:
-h, --help output usage information
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample deletes the locally cached .token file if present.
Usage:
node logout.js
This sample retrieves and displays the climate_state data on the HVAC system of the vehicle.
Usage:
node climate.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample demonstrates turning on the HVAC system of the vehicle.
Usage:
node climateStart.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample demonstrates turning off the HVAC system of the vehicle.
Usage:
node climateStop.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample demonstrates flashing the headlights of the vehicle.
Usage:
node flashLights.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample retrieves and displays information on the location and driving state of the car using the drive_state query.
Usage:
node geoloc.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-g, --geocode geocode (reverse geocode to nearest address)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample retrieves and displays the current display formats for the user interface.
Usage:
node guiSettings.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample demonstrates triggering homelink via the vehicle.
Note: This feature appears to be tied to the presence of Autopilot hardware and software. Looking for validation on both AP and pre-AP vehicles.
Usage:
node homelink.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample demonstrates honking the horn of the vehicle.
Usage:
node honkHorn.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample demonstrates locking the doors of the vehicle.
Usage:
node lock.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample retrieves and displays whether mobile access is enabled.
Usage:
node mobileEnabled.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample retrieves and displays the current vehicle odometer value.
Usage:
node odometer.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample sends the command to open the charge port, or to release the latch if the charge port is open, a cable is plugged in, and charging is stopped.
Usage:
node openChargePort.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample enables remotely starting the vehicle without a key fob present. Note that the password parameter is required in this sample.
Usage:
node remoteStart.js [options] password
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample attempts to reset the current valet pin.
Usage:
node resetValetPin.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample sets the current battery charge limit to the given value.
Usage:
node setChargeLimit.js [options] number|standard|storage|range
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample sets the driver and passenger temperature to the given value.
Usage:
node setTemps.js [options] temperature
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample demonstrates basic use of the streaming API to retrieve real-time vehicle data.
Usage:
node simpleStreaming.js [options] username
Options:
-h, --help output usage information
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample retrieves the charge_state information and displays the charge limit, the current vehicle charge level, and the ideal, rated and projected range.
Usage:
node soc.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample demonstrates how to initiate a charging session.
Usage:
node startCharge.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample demonstrates how to terminate a charging session.
Usage:
node stopCharge.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample demonstrates controlling the panoramic sunroof if present.
Usage:
node sunroof.js [options] close|vent
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample demonstrates unlocking the doors of the vehicle.
Usage:
node unlock.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample retrives and displays several elements of data returned from the vehicle_state REST API.
Usage:
node vehicle.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample retrives and displays several elements of data returned from the vehicle_config REST API.
Usage:
node vehicleConfig.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample enables or disables valet mode.
Usage:
node valet.js [options] ON|OFF pincode
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)
This sample sends a wakeup signal to wake a vehicle in sleep mode.
Usage:
node wakeup.js [options]
Options:
-h, --help output usage information
-u, --username [string] username (needed only if token not cached)
-p, --password [string] password (needed only if token not cached)
-i, --index <n> vehicle index (first car by default)
-U, --uri [string] URI of test server (e.g. http://127.0.0.1:3000)