vehicle command
v0.2.1
テスラ車は、エンドツーエンドのコマンド認証を提供するプロトコルをサポートするようになりました。この Golang パッケージは、新しいプロトコルを使用して、空調や充電などの車両機能を制御します。
含まれているツールには、REST API 呼び出しを新しい車両コマンド プロトコルに変換する HTTP プロキシ サーバーがあります。
開発者の中には、Tesla の Owner API に精通している人もいるかもしれません。車両がエンドツーエンドのコマンド認証を要求し始めると、オーナー API は機能しなくなります。あなたがこれらの開発者のいずれかである場合は、プロキシ サーバーをセットアップするか、このライブラリを直接使用するようにアプリケーションをリファクタリングできます。 2021 年より前のモデル S および X 車両は、この新しいプロトコルをサポートしていません。フリート API はこれらの車両に対して引き続き機能します。
コマンド認証は 2 つのステップで行われます。
したがって、車両にコマンドを送信するには、サードパーティ アプリケーションがユーザーから有効な OAuth トークンを取得する必要があり、ユーザーはアプリケーションの公開キーを車両に登録する必要があります。
Tesla の Web サイトには、OAuth トークンを取得する手順が記載されています。この README には、秘密キーを生成し、ユーザーを公開キーの登録フローに誘導する手順が記載されています。このリポジトリ内のツールは、OAuth トークンと秘密キーを使用して車両にコマンドを送信できます。
たとえば、リポジトリにはコマンドライン インターフェイスが含まれています。
tesla-control -ble -key-file private_key.pem lockREST API プロキシ サーバー (起動時に秘密キーが提供され、クライアントから送信された OAuth トークンを使用します):
curl --cacert cert.pem
--header 'Content-Type: application/json'
--header "Authorization: Bearer $TESLA_AUTH_TOKEN"
--data '{}'
"https://localhost:4443/api/1/vehicles/$VIN/command/door_lock"
要件：
インストール手順:
go get ./...go build ./...go install ./...最後のコマンドは、次のユーティリティをインストールします。
これらのツールを実行するには、Docker イメージを使用できます。このイメージではデフォルトで HTTP プロキシが実行されますが、 --entrypointフラグにより使用されるツールが変更されます。
Docker ハブからイメージを実行します。
docker pull tesla/vehicle-command:latest
docker run tesla/vehicle-command:latest --help
# running a different tool
docker run --entrypoint tesla-control tesla/vehicle-command:latest --helpdocker-compose.yml ファイルの例も提供されています。
docker compose upコマンドライン フラグの代わりに、次の環境変数を使用できます。
TESLA_KEY_NAME 、システム キーリング内のコマンド認証秘密キーのエントリ名を導出するために使用されます。TESLA_TOKEN_NAME 、システム キーリング内の OAuth トークンのエントリ名を導出するために使用されます。TESLA_KEYRING_TYPE 、OS のデフォルトのシステム キーリング タイプをオーバーライドして使用されます。 tesla-keygen -hを実行して、 -keyring-typeフラグのドキュメントにリストされているサポートされている値を確認します。各オプションの詳細については、キーリングのドキュメントを参照してください。TESLA_VIN車両識別番号を指定します。 VIN は、車両の UI の [コントロール] > [ソフトウェア] で確認できます。 (名前にもかかわらず、VIN には文字と数字の両方が含まれます)。TESLA_CACHE_FILEセッション情報をキャッシュするファイルを指定します。キャッシュを使用すると、プログラムは車両へのハンドシェイク メッセージの送信をスキップできます。これにより、再起動後に車両に再接続するときにクライアントが行うフリート API 呼び出しの数と待ち時間の両方が減少します。これは、呼び出しごとに再起動するtesla-control使用する場合に特に役立ちます。TESLA_HTTP_PROXY_TLS_CERT HTTP プロキシの TLS 証明書ファイルを指定します。TESLA_HTTP_PROXY_TLS_KEY HTTP プロキシの TLS キー ファイルを指定します。TESLA_HTTP_PROXY_HOST HTTP プロキシのホストを指定します。TESLA_HTTP_PROXY_PORT HTTP プロキシのポートを指定します。TESLA_HTTP_PROXY_TIMEOUT Tesla サーバーに接続するときに使用する HTTP プロキシのタイムアウトを指定します。TESLA_VERBOSE詳細ログを有効にします。 tesla-controlおよびtesla-http-proxyによってサポートされます。例えば：
export TESLA_KEY_NAME= $( whoami )
export TESLA_TOKEN_NAME= $( whoami )
export TESLA_CACHE_FILE= ~ /.tesla-cache.jsonこの時点で、コマンド ライン ツールを使用して、BLE 経由で個人車両にコマンドを送信する準備が整いました。あるいは、以下を読み続けて、REST API を使用してインターネット経由でコマンドを送信できるアプリケーションを構築する方法を学習してください。
このセクションでは、クライアントが REST API を使用して車両コマンドを送信できるようにする HTTP プロキシを設定および使用する方法について説明します。
上で説明したように、HTTP プロキシは、Tesla (OAuth トークンを使用) と個々の車両 (秘密キーを使用) の両方で認証する必要があります。
Tesla のサーバーは、車両にコマンドを転送する前に、クライアントに OAuth アクセス トークンを提供することを要求します。車両の所有者から OAuth トークンを取得する必要があります。開発者アカウントの登録と OAuth トークンの取得の手順については、Tesla の Web サイトを参照してください。
クライアントが有効なトークンを持っている場合でも、車両はクライアントの秘密キーによって許可されたコマンドのみを受け入れます。
このリポジトリに含まれるtesla-keygenユーティリティは、秘密鍵を生成し、それをシステム キーリングに保存し、対応する公開鍵を出力します。
export TESLA_KEY_NAME=$(whoami)
tesla-keygen create > public_key.pem
システム キーリングは、OS に依存する認証情報ストレージをシステム キーリングとして使用します。たとえば、macOS では、デフォルトでログイン キーチェーンが使用されます。その他のオプションについては、 tesla-keygen -hを実行します。
tesla-keygenコマンドを再実行すると、秘密鍵を上書きせずに同じ公開鍵が出力されます。 -fを使用して、ユーティリティに既存の公開キーを強制的に上書きさせることができます。
車両は公開鍵を使用してコマンドを検証します。ユーザーがアプリケーションから送信されたコマンドを受け入れる前に、公開キーをユーザーの車両に登録する必要があります。
オーナーの観点から見た登録プロセスは次のとおりです。
このプロセスが機能するには、アプリケーションを識別するドメイン名を登録する必要があります。 Tesla アプリは、リクエストを承認するかどうかをユーザーに尋ねるときにこのドメイン名をユーザーに表示し、車両はロック画面のキーの横にドメイン名を表示します。
指示に従って公開キーとドメインを登録します。これらの手順で参照される公開キーは、上記の例ではpublic_key.pemファイルです。
公開キーが正常に登録されたら、車両所有者にhttps://tesla.com/_ak/<your_domain_name>へのリンクを提供します。たとえば、 example.comを登録した場合は、 https://tesla.com/_ak/example.comへのリンクを提供します。残りの部分は、公式の Tesla iPhone または Android モバイル アプリ (バージョン 4.27.3 以降) で処理されます。複数の Tesla 製品をお持ちのお客様は、リンクをクリックするか QR コードをスキャンする前に、目的の車両を選択する必要があります。
HTTP プロキシには TLS サーバー証明書が必要です。テストと開発の目的で、OpenSSL を使用して自己署名されたローカルホスト サーバー証明書を作成できます。
mkdir config
openssl req -x509 -nodes -newkey ec
-pkeyopt ec_paramgen_curve:secp521r1
-pkeyopt ec_param_enc:named_curve
-subj '/CN=localhost'
-keyout config/tls-key.pem -out config/tls-cert.pem -sha256 -days 3650
-addext "extendedKeyUsage = serverAuth"
-addext "keyUsage = digitalSignature, keyCertSign, keyAgreement"
このコマンドは、暗号化されていない秘密キーconfig/tls-key.pemを作成します。
プロキシ サーバーは、次のコマンドを使用して実行できます。
tesla-http-proxy -tls-key config/tls-key.pem -cert config/tls-cert.pem -key-file config/fleet-key.pem -port 4443Docker を使用して実行することもできます。
# option 1: using docker run
docker pull tesla/vehicle-command:latest
docker run -v ./config:/config -p 127.0.0.1:4443:4443 tesla/vehicle-command:latest -tls-key /config/tls-key.pem -cert /config/tls-cert.pem -key-file /config/fleet-key.pem -host 0.0.0.0 -port 4443
# option 2: using docker compose
docker compose up注:運用環境では、 -port 4443省略し、標準ポート 443 でリッスンすることをお勧めします。
このセクションでは、クライアントがcurl使用してサーバーにアクセスする方法を説明します。クライアントは OAuth トークンを取得する責任があります。上記の説明に従って OAuth トークンを取得します。
エンドツーエンド認証をサポートしないエンドポイントは、Tesla の REST API にプロキシされます。
export TESLA_AUTH_TOKEN= < access-token >
export VIN= < vin >
curl --cacert cert.pem
--header " Authorization: Bearer $TESLA_AUTH_TOKEN "
" https://localhost:4443/api/1/vehicles/ $VIN /vehicle_data "
| jq -r .エンドツーエンド認証をサポートするエンドポイントは、セッション状態と再試行を処理するプロキシによってインターセプトされ、書き換えられます。 cert.pemクライアントにコピーした後、クライアントから次のコマンドを実行すると、プロキシがflash_lightsコマンドを車両に送信します。
export TESLA_AUTH_TOKEN= < access-token >
export VIN= < vin >
curl --cacert cert.pem
--header ' Content-Type: application/json '
--header " Authorization: Bearer $TESLA_AUTH_TOKEN "
--data ' {} '
" https://localhost:4443/api/1/vehicles/ $VIN /command/flash_lights " $TESLA_AUTH_TOKEN取得するフロー:
システム内のコマンドの流れは次のとおりです。
HTTP プロキシは、Tesla Fleet API 車両コマンド エンドポイントを実装します。
オーナー API 用に作成されたレガシー クライアントは、URL パスを構築するときに車両のオーナー API ID を使用している可能性があります。プロキシ サーバーでは、クライアントが代わりに VIN を直接使用する必要があります。
pkg.go.dev でパッケージのドキュメントを読むことができます。
このリポジトリはgo modサポートし、Go バージョンのセマンティクスに従います。 v0.xx リリースでは API の安定性が保証されないことに注意してください。
