Unofficial documentation of the Tesla Model S REST API | Hacker News Reader

Unofficial documentation of the Tesla Model S REST API

github.com

181 pointstimdorr99 comments

Docs are here: http://docs.timdorr.apiary.io/

This was discovered via the Android app in particular: https://play.google.com/store/apps/details?id=com.teslamotor...

I did some sniffing on the traffic, which is SSL encrypted, but luckily it's pretty easy to install your own CA in Android 4.1+.

They have both a Rails app and a nodejs server. The nodejs server is for live streaming car location and driving metrics. I haven't gotten that documented yet (but I'm accepting pull requests!), but some people have already been making use of it: http://www.teslamotorsclub.com/showthread.php/13410-Model-S-...

One guy already has his Model S tweeting: https://twitter.com/pureamps

Re:tweeting model s. Who would have thought that Knight Rider's Kit would be so into social networking?

Thanks for this awesome work ;)

If I had a Model S, I'd write a BlackBerry 10 app using this. Kudos to you for this work!

And it looks like someone did it!

http://appworld.blackberry.com/webstore/content/23977878/?co...

I love Tesla, and the Model S seems great, but having a rails app server on my luxury car seems capricious.

How does it get updated? An attacker can at least unlock the doors or drain the battery (lights & HVAC control), and possibly it is an entry point for something much worse (unlocking & starting, or disabling controls while enroute). Is this a major security flaw or am I just spreading FUD?

It doesn't have a rails server on the car. The car communicates to Teslas datacenter, which is where the Rails servers are. You then query the API by querying the datacenter.

Cool, that feels a lot better.

I certainly hope the engineers their are staying on top of the recent deluge of Rails patches. Tesla's database has a huge amount of private data; mostly containing information about rich and influential people. A black hat could undoubtedly profit by tracking people and correlating their location to affairs/secret business meetings/etc.

According to Elon Musk, it only sends data if you explicitly enable it.

I'd just like to add that they enabled it by default for cars they lend to media outlets for reviews after the Top Gun thing. Some people in the other thread were freaking out about how much Tesla knows about your car but a regular customer can just opt out.

I think you meant "Top Gear". ;)

Using GET to trigger horn honking... Not sure I'd consider that good REST practices.

(At least honking the horn doesn't incur permanent state change; unlocking the doors is obviously not safe.)

Edit: idempotency vs safety... I knew I was being stupid.

Just think of what a single index crawler could do to this car!

Unlocking doors absolutely is idempotent. What different state would you see if you issue Unlock once or a thousand times?

Solenoid melted?

Thinking like an embedded systems engineer (I am) instead of a mathematician (I'm not), I would have a sensor to know the state of the lock and only whack the unlock solenoid if the lock has been discovered to be closed.

Always treat mechanical devices in a non-deterministic fashion.

As a software developer I'd always try to unlock it. The user probably has a reason for pressing the button. Maybe your "is the door locked" sensor is broken? If you're afraid of overheating it wait a bit after the second try before enabling it again.

You might be surprised by the semantics assigned to double clicking the button by some manufacturers. On some BMWs (mine included) locking it twice DISABLES the alarm. It's intended for ferries / low-loader recovery etc. but if you don't know it...

VWs can do a thing where the windows open if you hold the lock key down - fortunately this can be turned off in the cars configuration settings for people who live in rainy countries!

Just to be precise, the windows open when holding the unlock button, and close when holding the lock button.

The lock button on a BMW is completely driven through the CPU. When you lock the car with the remote, the lock buttons inside the car AND THE DOOR HANDLES do nothing. Anti-theft measure I suppose.

Salesmen have to remind every new customer about this, since sooner or later someone locks themself or someone else in the car and the remote has walked away...

The user manually requesting an unlock is one thing. He's the software running the lock. I'm talking more about an automatic unlock request from high-level software control.

There are techniques to monitor the health of the switch and know when the sensor is failing/has failed. THEN you can whack the solenoid to your heart's content if you believe the sensor is damaged. But if you have a working sensor, there's no need to overstress the solenoid and mechanical linkage.

Funny that you say this, my Honda Civic always attempts to unlock regardless of lock state. I guess they don't really trust the lock sensor.

I'm not saying this is how every car is or should be designed, especially a Civic. You're also in the vicinity of the car - either you're sitting inside it or you're using the keyfob within visual distance.

But if you're locking/unlocking your car over the internet with this funky API and want to be sure it's locked, how do you do it? You don't hit the solenoid 20 times and say "well, good enough".

> non-deterministic fashion.

Wait, perhaps I am understanding it wrong, but if I were to consider a lock sensor as non-deterministic, wouldn't that imply that I always have to send the unlock signal, regardless of lock state, because you don't trust the sensor?

You consider the mechanical state of the lock mechanism to be non-deterministic. The sensor has no state, it's an observer.

You do not trust that because your boolean in RAM says "locked" that the door is locked.

Now whether you trust the sensor to be functional or not is another story.

Tip - the human in or near the car reacting to the first opening...

The 'unlock' operation, at least on most central locking systems I've used, is the perfect example of an idempotent unary operation.

It doesn't matter how many times you apply the 'unlock' operation, it has the same effect as applying it once[1]. However, the 'unlock' operation is not safe[2].

[1]: http://en.wikipedia.org/wiki/Idempotence

[2]: http://www.packetizer.com/ws/rest.html

Yeah, I considered not carrying the wireless-entry key for my car, because if I lost that key, it would be easy for a thief to walk through the parking lot, pushing the button until they found my car.

Ultimately, I decided that I'm unlikely to lose the key. But I don't like the idea that someone could still scan the parking lot, unlocking cars by radio.

Opening up more data/control wirelessly isn't necessarily a good thing. You CERTAINLY don't want someone to be able to make your car segfault while you're driving down the highway.

>You CERTAINLY don't want someone to be able to make your car segfault while you're driving down the highway.

That could make for a great scene in some futuristic hacker movie.

On a more serious note, there are many possible solutions to the problem of losing a wireless car entry key. Off the top of my head:

1) Have the user tap out a simple rhythm with the button to unlock the car. Downsides: kind of involved and the rhythm would have to be long to be secure.

2) Put a fingerprint scanner on the key. The one in my laptop is a tiny self-contained module, so I expect it to be possible to fit one inside a wireless car key. Downsides: the scanner can break; can't use in gloves.

3) Have the cars mesh network to detect the "trawling for the right car with a key" behavior. Downsides: complexity; the thief could exploit this to lock you out of your own car.

4) Make the key a wristwatch or a wristband. I think this is the best cheap solution. Downsides: might disagree with your fashion sense.

What's wrong with putting the second auth method (fingerprint, passcode, whatever) on the car itself? Likely much more durable and keeps the key itself simple.

"Person of Interest" had it...

Keyless entry has been around for a long time and I have not heard of this scenario actually occurring (no doubt it has, but it's certainly not common enough to worry about).

I have visions of a rube-goldberg style contraption, starting with the car horn activating, scaring a flock of pigeons, knocking over a set of bowling pins, bumping into a lit candle and tipping it under a rope, burning through and releasing a piano on some poor sap's head. No side effects, indeed :)

Or, on the other hand, it's a zen koan. If a car honks in a parking garage and no-one is there to hear it, has it even made a sound?

Unlocking door is idempotent, but it is not safe (has side effect), and thus, according to the HTTP standard, GET should not be used for it.

Does Tesla describe it as a RESTful API, though? By the looks of things, the author has discovered it and decided to call it RESTful himself, even though it's just an HTTP API.

A RESTful API is more than just using GET to access resources.

Agree, there is a long way from HTTP API to REST API and this one is definitely missing key REST features.

True. It's not truely RESTful, just REST-ish. But if you wanted to wrap this in an HTTParty or RestClient library, that would still work.

I agree. This interface is not RESTful, and that's good, because it's not a good fit for REST. I may be wrong, but it seems REST is best suited for accessing and creating resources. And it seems you would have to do a lot of conceptual mashing to represent all this API needs to do as resources. I am happy to be corrected.

For more topics along these lines, look into Resource-oriented Architecture (ROA) [1]. Many REST tutorials and classes are often further labeled as Service-oriented, which is really untrue. This is also why many existing SOAs are unfit for a RESTful transformation. Truly RESTful API's deal with resources, not services/business processes.

[1] http://en.wikipedia.org/wiki/Resource-oriented_architecture

What "conceptual mashing" is required? Your resources are things like locks, batteries and thermostats. It seems pretty straightforward to me.

You may have a point that I didn't consider. So if we wanted to unlock the car, would we perhaps post new a version of the lock resource (in json, xml, or whatever serialization format the system uses), representing its new state, to the uri representing it?

Exampe: POST {"state": "unlocked} to http://doors/front-left/lock

I realize I don't understand this, so your comment, and any further points you have, are sincerely appreciated.

Exactly. (except you would probably want to PUT the state instead of POST, since it's an idempotent operation)

You would GET the lock to see if it's locked, GET the battery to read its charging state.

You could PUT to the battery (or to some more abstract, finer-grained resources) to set the charge mode and turn charging on and off. The HVAC and thermostat would work the same way.

The only tricky stuff is "flash lights" and "honk horn"; they're inherently commands, so you might as well implement them in the RPC style that Tesla has used. They can't benefit from anything REST has to offer anyways.

Thank you. That is very helpful. But what about if it was necessary to have one command that changed the state of more than one resource?

And as you say, since certain aspects of the API (like honk horn) are unfit for REST, does it make sense to have the other parts of the API in REST? And then you've have two API's at once?

> But what about if it was necessary to have one command that changed the state of more than one resource?

Then you need to have another resource that encompasses the aspects that need to be changed. Sometimes resources have to be somewhat abstract.

> since certain aspects of the API (like honk horn) are unfit for REST, does it make sense to have the other parts of the API in REST?

If the application benefits from the constraints that REST provides then why wouldn't it make sense? It's still one API, "honk" and "flash" don't need to be walled off from the other elements of the API in any way.

Beau, everyone certainly agrees with you. This same comment appears any time someone mentions REST. The phrase has indeed been repurposed to describe HTTP APIs, generally, despite the hard work of Fielding to give REST a proper meaning.

It would be better if people just said "HTTP" when they mean "REST," but that's a long shot.

Hope this is secured against cross car request forgery.

My first thought was "Holy Shit! Cookie only authentication and you can unlock the doors, among other things!"

It's absolutely vulnerable to XSRF with cookie only authentication. This is a huge security issue.

What I would like to see is USB plug in every car, which provides diagnostic and maintenance data according to a standardized format. This should be available to the owner and to any shop they authorize to work on the car.

There's actually this sort of thing in the car via the touchscreen. If you hold down on the "T" at the top center of the screen, it will prompt for an access PIN and behind there is all the diagnostics you could dream of. Unfortunately, that's all hidden from the consumer for now :/

what's a valid PIN?

Only the technicians know, and they're not allowed to tell customers.

500 tries on average and I'll have it anyway ;-)

Crap. It's a password not a PIN. Much harder to get with brut force.

The OBD2 standard does this today. Not pretty, but works well enough. I always check my fault codes before going to the mechanic.

>which provides diagnostic and maintenance data according to a standardized format.

Except the values you get won't make any sense outside of your particular model. Its like reading SMART data from a hard drive. Okay, you can generate this csv and have all this data, but without the manufacturer telling what thresholds matter (and these are arguable), its kinda meaningless. SMART was supposed to predict failures and do all sorts of things, but its kind useless in practice. I think most controllers just stupidly rely on bad blocks appearing than trying to interpret the tea leaves of SMART data.

With OBD systems, all this information is internal and we get a fault code when we pass a certain threshold. I think this makes it a lot easier for mechanics and lay people to work with. Data addicts, of course, will never be satisfied unless they can pull every bit out of the system, but that may not be practical or useful. I could see a hybrid system where a car has the old fashioned OBD2 protocol and something else for nerds to download.

> but without the manufacturer telling what thresholds matter (and these are arguable), its kinda meaningless

I know exactly what you mean. Through random forum postings I found which index my SSD uses for "wear level", only nobody knows what the units are or what they mean.

Getting at that level of data would be possible if you could access the CAN bus. It's part of the OBD-II standard, but most manufacturers don't forward the CAN bus data to that specific connector hidden under your steering column. However, a few do, and there are other connections in other locations for the other makes.

You can access the CAN bus pretty cheaply (there are several cards available around $200 with linux drivers, maybe cheaper if you're willing to do more than plug it in and turn on wireshark). That said, the last time I worked on ECMs, the messages were not standardized at all. You needed a spec to define what variations of ECMs were available as well as what the individual values would mean. I feel like GM was standardizing this more than others in an effort to consolidate ECMs they were shipping (runtime config via "calibrations" I believe), and all manufacturers might be using standardized parts now, but you'll still need to know not only the message inventory for your vehicle, but you'll want to know whatever diagnostic protocol that your manufacturer uses to sit on top of CAN. Keyword Protocol 2000 was used by DaimlerChrysler was used when I was still in the business and GMLAN was used by GM for these purposes.

The Goodthopter [1], an offshoot of Travis Goodspeed's 'GoodFET' project, allows CAN access for about $35 all in. It's basically a MSP430 + a CAN controller.

Even 'simple' CAN protocols, like J1939 used in trucks/agri/marine, are purposely non-standard. It's rather annoying.

I'm curious as to what systems will emerge from Mercedes/VW/BMW (and I guess Google) as more high speed sources like LiDAR, active dampening, etc become the norm. The current BMW 5/7 series and Mercedes' S-class already have separate CAN-like systems for high speed buses.

[1] http://goodfet.sourceforge.net/hardware/goodthopter11/

Check out OpenXC project lead by Ford http://openxcplatform.com/.

Also, check out OBDII protocol each car after 1996 implements it up to a certain weight. This is the data available: http://en.wikipedia.org/wiki/OBD-II_PIDs.

Basically there is a way to gather fuel usage, fuel levels, speed, Mass Air Flow Rate, rpm, etc etc. Adding accelerometer and GPS to the mix pretty much gives you a decent start to the vehicle analytics platform.

On heavy vehicles or if you want more data on light duty, tapping into CAN is the only way, but that can get very manufacturer specific...

I was actually working on a project based on OpenXC but the license[1] is pretty restrictive. License aside, it's really easy to use and implement.

[1] http://openxcplatform.com/agreement.html

Yes, I noticed this too. It really hard to invest time with such a restrictive license. Do you know by any chance if Odometer value is a real odometer or distance since MIL or something else. Odometer is not a standard PID and I was curious to see if Ford opened that up.

OpenXC had a really easy to way to get odometer readings, otherwise according to [1] "For a Ford vehicle, the odometer can be read via a mode $22 PID of $6180 for km clusters, and $6182 for mph clusters.". [2] Also talks a bit about reading Odometer. Shame there isn't a standard for reading it.

[1] http://www.mp3car.com/engine-management-obd-ii-engine-diagno...

[2] http://www.canbushack.com/blog/index.php?title=oh-no-odomete...

There's smartphone apps that take advantage of OBD-II, e.g. -

https://play.google.com/store/apps/details?id=org.prowl.torq...

https://itunes.apple.com/ie/app/dashcommand-obd-ii-gauge-das...

http://www.devtoaster.com/products/rev/

Some of these are massively overpriced, but they are useful looking.

If I had a bit of cash I'd consider putting a 7" Android tablet into the dash (you'd need a double DIN slot) and install the torque app, with a custom moulded surround to make it look stock. Live engine data to satisfy your inner nerd!

Wow,the price is really steep, but I also could not find info on the hardware they use to interface with OBDII for Dashcommand. I think there is most likely additional cost for a wifi enable d device that plugs in to OBDII and forwards this data to the mobile app.

Another nerdier but cheaper route is to use Arduino with ELM interpreter: http://www.cs.purdue.edu/homes/millerrv/Ryan_Miller/Projects...

Great link thanks.

Head over to Amazon, buy a bluetooth OBD2 dongle. Plug it into the port in your car, typically under the steering wheel. Load up the Torque app on your smartphone. You now have real-time direct access to all the diagnostics, fault codes, and can clear your own Check Engine light. With the app you can create your own dashboards of gauges, monitor all your car's sensors while driving, and log everything for export.

Really? That's actually amazing! Thanks for mentioning it, I'm going to look into this.

Don't buy a cheapo Chinese ODB2 adapter because it won't work with the 1 Mbps bus on the Tesla. I tried already.

Wow, finally a way for us nerds to interact with our cars, besides of hunting undocumented CAN bus commands via OBD2!

Would also be nice if we had publicicly available IVI computers with proper car APIs to tinker and play with. Any ideas if there are other available than upcoming Tizen IVI reference hardware (which is not yet available for 2.0 afaik)?

It has an active 3G connection at all times and can be queried for its GPS position ? Damn, future is both exciting (tech wise) and scary (privacy wise).

Now that I think about it I'm sure it's not the only car with this, but I didn't realize before

This is really actively used in fleet management domain today. Mostly for utilization analytics, fuel usage, idling detection, driver behavior etc. It is amazing how many efficiencies can be found in the data...

I believe this tracking has to be turned on by the user.

I use this every night from a python script to force the charge to start after the electricity becomes cheaper. So far it is fast and reliable.

Neat! Couple of nits, though, if anyone from Tesla is reading:

- Wish it used OAuth or some other revocable token mechanism. What if I lose my device? Sell the car? Get a divorce? etc..

- GET for things that change state? Looks like these are all idempotent, so they should be PUT.

- Versioning might be nice. :)

Still, progress! Clean API over HTTP that returns easy-to-parse JSON for a car = win.

Coming soon to the HN front page: RoadRage.js

This would make an interesting music instrument. I hope someone writes something that makes it MIDI-compatible.

I hate to think what would happen if tesla's user database was hacked. Not that that's a reason not to have a REST API of course, I hope to see a lot of car-app innovation come from this!

Do the cars have an onboard wifi for the server-client communication? Is this API also open to the Internet over the car's cellular connection? (if there is one of course)

It's over 3G for now. There is wifi hardware in the car, but they haven't built out an interface for it yet.

All Model S's come with 3 months of cell service and they will be offering data plans shortly. It's running on AT&T, so we should be able to add it to Mobile Share plans (which I plan to do).

Is the SIM soldered? Or can you drop a T-Mobile SIM card in?

/T-Mobile user

I looked around and didn't see a SIM slot. Tesla hasn't disclosed the carrier in use either.

They did however say that you'll be able to tether a phone with a data connection to the car via USB to avoid paying a subscription for the car.

I don't mind paying the subscription; I just hate AT&T with the passion of ten fiery hells.

It is weird that you connect to the API through http and send user and password in plain text.

It's https, actually.

http://www.youtube.com/watch?feature=player_detailpage&v...

Lovely

/vehicles/{id}/command/door_unlock

Exactly what I was thinking... one vulnerability in their stack and every car is pwned.

Fingerprint the requestor by IP; what's that? You're making more than 1 request per second to more than more vehicle ID and you're not a trusted partner? BAN LIST

Meh, you've had these for years. I'd put it at even money that some RF protocol stacks on recent vehicles are vulnerable to exploitation and connected to one of the CAN buses on the vehicle so you can pivot to a more critical system. Hurray for drive by exploits (literally).

I'm honestly surprised that criminal organizations haven't paid/coerced engineers working how to steal certain cars using a remote control, because I'm pretty certain that with some effort, it's possible.

This is when software bugs start affecting physical (costly) things.

Hello XSRF! Cookie only authentication? Seriously?

This is only accessed directly via library, so CSRF isn't a factor. Also, everything is happening over SSL.

SSL wouldn't save you, but if you never get the magic cookie into a browser then you're safe from XSRF.

This is great! Can't wait until they add steering, gas, and brake to the API.

Not a new thing - Tesla not the first automotive to do this.

wow....they are using GETs for everything ! :)

Reply on news.ycombinator.com