Tesla Bluetooth Low Energy (BLE) API Documentation

[LexNastin]

Hey, I recently reverse engineered Tesla's BLE protocol which is used by (model 3 + y) keyfobs, the phone key, tire pressure sensors, and possibly more! I had a very fun time reverse engineering the Android app, and figuring out how cryptography even works; yes there's good cryptography involved!

Anyways after lots and lots and lots of hours of research... I finally found a way to extract Tesla's VCSEC (Vehicle Controller Secondary) protobuf. VCSEC is responsible for unlocking the car from the keyfob and the phone key. After extracting that I began experimenting a lot, until I got the cryptography and everything else just right!

After lots of documentation, I have made this website so that you too can use it in your own apps and products to control certain aspects of the car! You can find it at teslabtapi.lexnastin.com! Make sure to read the getting started section completely as it contains all the required info that you need to get started with the BLE API.

Thanks!

 

[Sean1]

Thank you for all your work. Quick question... Do you know what devices or power lines "wake up" when phone BT is within range?

 

[LexNastin]

No device wakes up the car automatically, the car wakes up when you pull on a handle whether there is a phone nearly or not it will wake up the car, or when you press unlock in the notification, or in the app when your phone is connected directly to the car (by the way the car's Bluetooth that you connect to for audio is a different type of Bluetooth and doesn't have to be connected for your phone and car to communicate). Also just opening the app will wake up the car, but that's part of the web (REST) API.

Thanks for reading btw!

 

[LexNastin]

Thank you for all your work. Quick question... Do you know what devices or power lines "wake up" when phone BT is within range?

(forgot to press reply, idk if that matters)

 

[Sean1]

(forgot to press reply, idk if that matters)

???

 

[LexNastin]

???

Nevermind that post

 

[pllopia]

Did you publish an app that opens the frunk via widget/shortcut using this api?

 

[LexNastin]

No, I'm developing a small app but it's only for personal purposes.

 

[Sean1]

No device wakes up the car automatically, the car wakes up when you pull on a handle whether there is a phone nearly or not it will wake up the car, or when you press unlock in the notification, or in the app when your phone is connected directly to the car (by the way the car's Bluetooth that you connect to for audio is a different type of Bluetooth and doesn't have to be connected for your phone and car to communicate). Also just opening the app will wake up the car, but that's part of the web (REST) API.

Thanks for reading btw!

I'm trying to find a power source that comes on when the phone is within range. Any ideas?

 

[LexNastin]

So, nothing ever turns on unless one of the following happens:

• The user opens the app
• The car is interacted with (the user pressing any button in the notification, pulling a handle, or pressing the trunk button)
• Sentry mode has been left on (the car never goes asleep/turns off in that case)
• The REST API sends a "wake up" request

Otherwise, the car never turns anything on. So there isn't any power source turned on when the phone is in range. Hope this answered your question!

 

[kishorekumaru]

Thank for your work @ArchGryphon been looking for the service and characteristic doc. Do you have any plans to update the doc for iOS?

​

 

[LexNastin]

It works for absolutely anything that has at least half decent Bluetooth LE support, so iOS is fully supported.

In a certain part of the guide I say to identify yourself as an Android device. I don't know if it matters whether u say Android or anything else, but identifying yourself as Android should work on any OS.

I have a friend who managed to get something working on the iOS side of things, and another one did it on Windows, so just give it a go!

Thanks for reading BTW!

(also, the website is currently down... sorry for that, you can visit it at teslabtapi/start.md at main · ArchGryphon9362/teslabtapi whenever it's down)

 

[LexNastin]

Update!

List of changes:

• Found out and documented how to find vehicle's BLE name!
• Created examples for every section in getting started
• Extracted the new VCSEC protobuf (not currently documented, but published in the first warning of the getting started page)
• Slight visual changes to the documentation

 

[Lyth]

This is hugely interesting.
I don’t have the car yet(few more weeks. Fingers crossed)

I assume you have to go through the normal Bluetooth pairing process.

Can you use LightBlue/Bluetooth explorer to send messages to the car/explore the services and characteristics?


On a side note would love a bit more technical detail on how you reverse engineered it all.

 

[LexNastin]

No, there is no actual pairing process as this is just BLE, for which no pairing is needed at all, you just literally connect and you can communicate right away.

Anyways, I never used LightBlue or Bluetooth explorer, but if you are able to send raw bytes to any characteristic over it, then yes. That's how I did it during reverse engineering, I used Serial Bluetooth Terminal for that, it's on Android.

For the more technical side of how I did it. It wasn't too hard but did take some time and failed attempts before getting to that point: I used JadX to decompile Tesla's mobile app. I then found a VCSEC file which had a thing called a Proto descriptor. It appeared to have all the original data of what looked like it could unlock the car and stuff. So after like 2 weeks of researching, I found multiple tools that could help me extract it, which I am still confused on how to use, but oh well, their app changed that anyways (see below). After extracting the protobuf, I then looked at the main Bluetooth communication class to see what encryption it uses, what it does when, etc., after some deobfuscation, I just documented it.

For later versions of the app which were properly made in Kotlin, that VCSEC file was separated into many classes each representing a message, but they all have headers and stuff describing them, so I made a Python script to extract them into a whole .proto file!

 

[LexNastin]

Ok, so, took a quick look at LightBlue, and it seems that yes, it will be possible to test using it!

 

[EddyM2]

Oooo this is very interesting! I've just recently got myself an Android Wear OS smartwatch and have been experimenting with building an app to communicate with Bluetooth LE devices from it. I don't actually have a Tesla but I've had a few ideas and have been wondering what might be possible to do with them via Bluetooth LE, so what you've done here answers a lot of my questions about that! Hopefully I might get a chance to experiment with one at some point and see what I can do

One thing I'm still wondering, does the car send out Bluetooth LE advertising messages (which would allow a device to tell when it's near the car)? Or do you have to already know the Bluetooth address of the car you want to connect to, and just keep trying to connect to it on the assumption it's nearby?

 

[LexNastin]

Oooo this is very interesting! I've just recently got myself an Android Wear OS smartwatch and have been experimenting with building an app to communicate with Bluetooth LE devices from it. I don't actually have a Tesla but I've had a few ideas and have been wondering what might be possible to do with them via Bluetooth LE, so what you've done here answers a lot of my questions about that! Hopefully I might get a chance to experiment with one at some point and see what I can do

One thing I'm still wondering, does the car send out Bluetooth LE advertising messages (which would allow a device to tell when it's near the car)? Or do you have to already know the Bluetooth address of the car you want to connect to, and just keep trying to connect to it on the assumption it's nearby?

I don't really know, buy I do know that as scan would show the car, so I'd assume it'a advertising. Also, you can find out it's name before connecting to it, it's in the getting started page of the docu.

 

[Lyth]

No, there is no actual pairing process as this is just BLE, for which no pairing is needed at all, you just literally connect and you can communicate right away.

Anyways, I never used LightBlue or Bluetooth explorer, but if you are able to send raw bytes to any characteristic over it, then yes. That's how I did it during reverse engineering, I used Serial Bluetooth Terminal for that, it's on Android.

For the more technical side of how I did it. It wasn't too hard but did take some time and failed attempts before getting to that point: I used JadX to decompile Tesla's mobile app. I then found a VCSEC file which had a thing called a Proto descriptor. It appeared to have all the original data of what looked like it could unlock the car and stuff. So after like 2 weeks of researching, I found multiple tools that could help me extract it, which I am still confused on how to use, but oh well, their app changed that anyways (see below). After extracting the protobuf, I then looked at the main Bluetooth communication class to see what encryption it uses, what it does when, etc., after some deobfuscation, I just documented it.

For later versions of the app which were properly made in Kotlin, that VCSEC file was separated into many classes each representing a message, but they all have headers and stuff describing them, so I made a Python script to extract them into a whole .proto file!

Thanks for all your hard work!

The closest to "Reverse engineering" Ive done(aside from websites and API calls) is running the apple private frameworks through a shell application lol.

Anyway, have to test with lightblue.. I have an ESP32 in the garage somewhere(gotta find it).

But I'd love to make a low privilege/"kids key" where they can get entry to the car without necessarily having the privileges to drive the car.
Looking at the message types it definitely looks possible.

Cant wait, 2 more weeks assuming the delivery dates are accurate!

 

[LexNastin]

YES! I wanted to do that too at some point, also, if u wanna, take a look at the secondsToBeActive field, as I haven't found out what it does yet (I assume it autodeletes the key or something), here it is: PermissionChange | Tesla BluetoothLE API (Unofficial)... would be nice