Connect Your Coding (API) Skill with Your Tesla Model 3/S/X – How to Access Your Car in Your Computer

对于一个IT从业人员来说,能够通过自己的电脑来操控自己的车辆,是一件让人兴奋的事情。从此,车打破了100多年来机械产品的古板印象,摇身一变成为了充满活力的电子产品。也许这正是Tesla这类新型电动车最让人着迷的地方 – Software Define Anything,软件定义一切。

虽然特斯拉官方的API接口的说明文档,但是在Github上已经有人通过反向工程,整理并发布了一整套非官方API文档。注意只是文档是非官方的,其中描述的所有API都是特斯拉自己在iOS平台和安卓平台的官方App中使用的接口,因此这一整套API的安全性,稳定性都是可以信任的。实际上目前市面上可以看到的其它非官方用以操控Tesla车辆的应用程序,应该使用的都是这套API。

首先看一下特斯拉官方的App,在这个App里面我们可以做到如下各种操作:

IMG 4773

  • 获取车辆各种信息:包括剩余电量在内的各种车辆状态以及当前停车位置
  • 唤醒车辆
  • 启动车辆
  • 打开和关闭车内空调
  • 打开和关闭坐骑加热
  • 打开前后行李厢
  • 打开和关闭车门
  • 打开和关闭车窗
  • 让车辆鸣笛
  • 让车辆闪烁车灯
  • 打开和关闭哨兵模式

这些在官方App里面可以实现的功能,通过API也都可以通过自己写代码来实现,既然支持写代码,那么就进一步更可以做到各种智能场景,比如在iPhone手机里通过“捷径”功能,编写定时程序,让车辆在每天出门上班前的10分钟自动将车内空调打开。有了API就拥有了无穷的想象空间。

那么如何使用API来操控你的Tesla车辆,本文做简单介绍。我的车辆是Tesla Model 3,然而这套API也同样适用于Model S/X/Y,或者是Roadster,甚至是还未发售的Cybertruck。

准备条件

  1. 仔细阅读API文档,文档链接在这里
  2. 为了测试API,要从头开始写代码有些麻烦,因此我使用了Setapp订阅里包含的软件Paw,可以直接调用和测试API。同样功能的软件还有Postman

第一步:生成Token

整套API使用的是OAuth 2.0的鉴权协议,因此在第一步我们需要先生成可以用于之后调用API接口的Token,为了生成这个Token,需要提供在Tesla官网上注册的用户邮箱和密码,每个Tesla车主在购车前一定是需要在官方注册的,因此生成的Token也是每位车主独有的。注意,这个Token不要告诉任何其他人,否则别人就可以远程操控你的车辆了。当然,生成的Token是有失效期的,也可以手动失效。因此也无需担心安全性问题。

我们在Paw中创建一个Request,调用类型选择“POST”,调用的API地址是:https://owner-api.teslamotors.com/oauth/token?grant_type=password
当在Paw的地址栏中输入带?的URL时,Paw会自动将问号后的内容转换成URL Params部分的键值对。
在调用的Headers部分要填入:Content-Type: application/json,其中Content-Type是Header Name,而application/json是Header Value,如果不填入,在调用的时候会报错,而无法获得正确Token。
在调用的Body部分要填入API需要的入参,在文档中都有明确描述,分别是:

  • grant_type,这是一个固定值,就是文本password;
  • client_id,这是API提供者提供的id,也是一个固定值,是81527cff06843c8634fdc09e8ac0abefb46ac849f38fe1e431c2ef2106796384;
  • client_secret,这是API提供者提供的密钥,也是一个固定值,是c7257eb71a564034f9419ee651c7d0e5f7aa6bfbd18bafb5c5c033b093bb2fa3;
  • email是上面说的Tesla官网的帐号邮箱;
  • password是上面说的Tesla官网帐号的密码。

最终整个调用在Paw中的显示如下图:
UntitledImage

可以看到这里已经成功执行了,在右侧的结果栏中已经返回了access_token,整个返回结果的JSON格式如下:

{
  "access_token": "abc123",
  "token_type": "bearer",
  "expires_in": 3888000,
  "refresh_token": "cba321",
  "created_at": 1538359034
}

Token的失效时间是45天,在失效时间内可以反复使用该Token,来进行其它的API调用。再次强调,不要将这个Token告诉别人。

第二步:获取帐号下的车辆信息

所有在这个帐号下购买的车辆都可以列出来,包括只是订购了还没有交车的车辆。我们要通过这一步获取到车辆ID,这个ID是后续要操控的车辆的标识码。

在Paw中创建一个新的Request,调用类型选择“GET”,调用的API地址是:https://owner-api.teslamotors.com/api/1/vehicles
在调用的Header部分要填入上一步获得的Token信息,键值对的表示就是:Authorization: Bearer {access_token}。
在本文的后续的步骤中也都需要提供Token,后续不再赘述。

这里需要额外注意的是:Bearer是文本,必须要写在Token前面;Token前后不要用引号括起来,否则执行调用的时候会返回报错error=”invalid_token”。

最终整个调用在Paw中的显示如下图:
UntitledImage

后续步骤中我们要使用的车辆ID是返回值中的id,而不是vehicle_id,这是需要注意的。

第三步:开始操纵车辆吧

实际上在进行完前面两步之后,剩下的就是研究API文档,探索这套API里给我们提供了哪些功能,让我们能够怎样地远程操控车辆。

唤醒车辆

后续的一些操作在执行前,必须要先唤醒车辆。否则当车辆处于休眠状态下,API调用会返回”error”:”vehicle unavailable”的报错。

在Paw中创建一个新的Request,调用类型选择“POST”,调用的API地址是:https://owner-api.teslamotors.com/api/1/vehicles/{id}/wake_up
这里的{id}就是步骤二中获取到的车辆ID。

唤醒调用成功之后,大约需要等待1-2秒钟的时间,车辆才会被真正唤醒。因此如果自己写整段代码,那么需要在wake_up调用成功以后,等待2秒钟,再调用后续的API。
唤醒调用成功以后的返回跟列出车辆信息的返回差不多。
UntitledImage

获取车辆数据

这是对于特定车辆获取更全面的数据,返回的数据比前面的列出车辆信息要多很多,包括涵盖了当前充电状态,空调状态,座椅状态,车辆配置等等各个方面的一百多项数据。

在Paw中创建一个新的Request,调用类型选择“GET”,调用的API地址是:https://owner-api.teslamotors.com/api/1/vehicles/{id}/vehicle_data
这里的{id}同样是步骤二中获取到的车辆ID。后续也不再赘述。

调用成功后返回的数据比较硬核,有兴趣的同学可以逐项阅读,以更了解自己购买的车辆。
UntitledImage

获取车辆当前位置附近的充电站信息

该调用返回的结果,跟在车内点击地图上的充电站图标之后显示出来的列表是一致的。只是目前看该调用只会返回Tesla的超充站和目的地充电站的位置,第三方合作充电站似乎并没有返回。

调用类型选择“GET”,调用的API地址是:https://owner-api.teslamotors.com/api/1/vehicles/{id}/nearby_charging_sites

返回结果中,type:destination表示是目的地充电站,type:supercharger表示是特斯拉超级充电站。在我所在的城市,名古屋只有一家超充站,远远没有中国国内普及。
UntitledImage

启动车内空调

调用类型选择“POST”,调用的API地址是:https://owner-api.teslamotors.com/api/1/vehicles/{id}/command/auto_conditioning_start

调用成功以后,返回结果”result”:true。

UntitledImage

远程调用这个请求,可能感受不到车辆的变化,那么可以打开Tesla官方App,进入到温度界面,调用成功之后,稍等2秒就可以看到这个界面自动变成了空调开启的样子。
IMG 4775

如果在调用时候,车门没有锁好,那么会返回报错:{“response”:{“reason”:”door_open”,”result”:false}},这跟在Tesla官方App中尝试启动空调获得的报错信息是一致的。
IMG 4774

总结

能够使用API来操纵车辆是让人激动的事情,这让Tesla在极客们的手里可能会爆发出各种奇葩而又颇具想象力的玩点。仔细阅读整份文档吧,去探索和体验更多编程操控车辆的乐趣。比如,将API和iOS捷径功能相结合的尝试可以参看这篇文章-【使用篇】利用iOS捷径全面控制你的特斯拉

最后,如果因为我的文章,你决定购买一辆Tesla来玩玩,那么非常欢迎使用我的推荐链接。ts.la/rakueki64678,这样你和我都能获得1500公里的免费超冲额度。

Have a good day!