vehicle command
v0.2.1
Tesla-Fahrzeuge unterstützen jetzt ein Protokoll, das eine durchgängige Befehlsauthentifizierung ermöglicht. Dieses Golang-Paket nutzt das neue Protokoll zur Steuerung von Fahrzeugfunktionen wie Klimatisierung und Laden.
Zu den enthaltenen Tools gehört ein HTTP-Proxy-Server, der REST-API-Aufrufe in das neue Fahrzeugbefehlsprotokoll umwandelt.
Einige Entwickler sind möglicherweise mit der Owner API von Tesla vertraut. Die Besitzer-API funktioniert nicht mehr, wenn für Fahrzeuge eine End-to-End-Befehlsauthentifizierung erforderlich ist. Wenn Sie einer dieser Entwickler sind, können Sie den Proxyserver einrichten oder Ihre Anwendung umgestalten, um diese Bibliothek direkt zu verwenden. Fahrzeuge der Modelle S und X vor 2021 unterstützen dieses neue Protokoll nicht. Die Flotten-API wird bei diesen Fahrzeugen weiterhin funktionieren.
Die Befehlsauthentifizierung erfolgt in zwei Schritten:
Um also einen Befehl an ein Fahrzeug zu senden, muss eine Drittanbieteranwendung ein gültiges OAuth-Token vom Benutzer erhalten und der Benutzer muss den öffentlichen Schlüssel der Anwendung im Fahrzeug registrieren.
Auf der Website von Tesla finden Sie Anweisungen zum Erhalten von OAuth-Tokens. Diese README-Datei enthält Anweisungen zum Generieren privater Schlüssel und zum Weiterleiten des Benutzers an den Registrierungsablauf für öffentliche Schlüssel. Die Tools in diesem Repository können das OAuth-Token und den privaten Schlüssel verwenden, um Befehle an Fahrzeuge zu senden.
Das Repository umfasst beispielsweise eine Befehlszeilenschnittstelle:
tesla-control -ble -key-file private_key.pem lockUnd ein REST-API-Proxyserver (der beim Start mit einem privaten Schlüssel versehen wird und von Clients gesendete OAuth-Token verwendet):
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"
Anforderungen:
Installationsschritte:
go get ./...go build ./...go install ./...Der letzte Befehl installiert die folgenden Dienstprogramme:
Für die Ausführung dieser Tools steht ein Docker-Image zur Verfügung. Das Image führt standardmäßig den HTTP-Proxy aus, aber das Flag --entrypoint ändert das zu verwendende Tool.
Führen Sie das Image vom Docker-Hub aus:
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 --helpEine Beispieldatei „docker-compose.yml“ wird ebenfalls bereitgestellt.
docker compose upDie folgenden Umgebungsvariablen können anstelle von Befehlszeilenflags verwendet werden.
TESLA_KEY_NAME wird verwendet, um den Eintragsnamen für Ihren privaten Befehlsauthentifizierungsschlüssel in Ihrem Systemschlüsselbund abzuleiten.TESLA_TOKEN_NAME wird verwendet, um den Eintragsnamen für Ihr OAuth-Token in Ihrem Systemschlüsselbund abzuleiten.TESLA_KEYRING_TYPE überschreibt den standardmäßigen Systemschlüsselringtyp für Ihr Betriebssystem. Führen Sie tesla-keygen -h aus, um die unterstützten Werte anzuzeigen, die in der Dokumentation zum Flag -keyring-type aufgeführt sind. Einzelheiten zu den einzelnen Optionen finden Sie in der Dokumentation zum Schlüsselbund.TESLA_VIN gibt eine Fahrzeugidentifikationsnummer an. Sie finden Ihre VIN unter „Steuerung“ > „Software“ in der Benutzeroberfläche Ihres Fahrzeugs. (Trotz des Namens enthalten Fahrgestellnummern sowohl Buchstaben als auch Zahlen).TESLA_CACHE_FILE gibt eine Datei an, die Sitzungsinformationen zwischenspeichert. Der Cache ermöglicht es Programmen, das Senden von Handshake-Nachrichten an ein Fahrzeug zu überspringen. Dies reduziert sowohl die Latenz als auch die Anzahl der Flotten-API-Aufrufe, die ein Client durchführt, wenn er nach dem Neustart erneut eine Verbindung zu einem Fahrzeug herstellt. Dies ist besonders hilfreich, wenn Sie tesla-control verwenden, das bei jedem Aufruf neu startet.TESLA_HTTP_PROXY_TLS_CERT gibt eine TLS-Zertifikatdatei für den HTTP-Proxy an.TESLA_HTTP_PROXY_TLS_KEY gibt eine TLS-Schlüsseldatei für den HTTP-Proxy an.TESLA_HTTP_PROXY_HOST gibt den Host für den HTTP-Proxy an.TESLA_HTTP_PROXY_PORT gibt den Port für den HTTP-Proxy an.TESLA_HTTP_PROXY_TIMEOUT gibt das Zeitlimit an, das der HTTP-Proxy bei der Kontaktaufnahme mit Tesla-Servern verwenden soll.TESLA_VERBOSE ermöglicht die ausführliche Protokollierung. Unterstützt von tesla-control und tesla-http-proxy .Zum Beispiel:
export TESLA_KEY_NAME= $( whoami )
export TESLA_TOKEN_NAME= $( whoami )
export TESLA_CACHE_FILE= ~ /.tesla-cache.jsonAn diesem Punkt können Sie das Befehlszeilentool verwenden, um über BLE Befehle an Ihr persönliches Fahrzeug zu senden! Alternativ können Sie weiter unten lesen, um zu erfahren, wie Sie eine Anwendung erstellen, die mithilfe einer REST-API Befehle über das Internet senden kann.
In diesem Abschnitt wird beschrieben, wie Sie den HTTP-Proxy einrichten und verwenden, der es Clients ermöglicht, Fahrzeugbefehle über eine REST-API zu senden.
Wie oben erläutert, muss sich Ihr HTTP-Proxy sowohl bei Tesla (mithilfe von OAuth-Tokens) als auch bei einzelnen Fahrzeugen (mithilfe eines privaten Schlüssels) authentifizieren.
Die Server von Tesla verlangen von Ihrem Client die Bereitstellung eines OAuth-Zugriffstokens, bevor Befehle an ein Fahrzeug weitergeleitet werden. Sie müssen das OAuth-Token vom Fahrzeughalter erhalten. Anweisungen zum Registrieren eines Entwicklerkontos und zum Erhalten von OAuth-Tokens finden Sie auf der Website von Tesla.
Selbst wenn Ihr Kunde über einen gültigen Token verfügt, akzeptiert das Fahrzeug nur Befehle, die durch den privaten Schlüssel Ihres Kunden autorisiert sind.
Das in diesem Repository enthaltene Dienstprogramm tesla-keygen generiert einen privaten Schlüssel, speichert ihn in Ihrem Systemschlüsselbund und druckt den entsprechenden öffentlichen Schlüssel aus:
export TESLA_KEY_NAME=$(whoami)
tesla-keygen create > public_key.pem
Der Systemschlüsselbund verwendet Ihren betriebssystemabhängigen Anmeldeinformationsspeicher als Systemschlüsselbund. Unter macOS wird beispielsweise standardmäßig Ihr Login-Schlüsselbund verwendet. Führen Sie tesla-keygen -h aus, um weitere Optionen zu erhalten.
Durch erneutes Ausführen des Befehls tesla-keygen wird derselbe öffentliche Schlüssel ausgedruckt, ohne den privaten Schlüssel zu überschreiben. Sie können das Dienstprogramm dazu zwingen, einen vorhandenen öffentlichen Schlüssel mit -f zu überschreiben.
Fahrzeuge verifizieren Befehle mithilfe öffentlicher Schlüssel. Ihr öffentlicher Schlüssel muss in den Fahrzeugen Ihrer Benutzer registriert werden, bevor diese von Ihrer Anwendung gesendete Befehle akzeptieren.
Hier ist der Registrierungsprozess aus Sicht des Eigentümers:
Damit dieser Vorgang funktioniert, müssen Sie einen Domänennamen registrieren, der Ihre Anwendung identifiziert. Die Tesla-App zeigt dem Benutzer diesen Domänennamen an, wenn er fragt, ob er Ihre Anfrage genehmigen möchte, und das Fahrzeug zeigt den Domänennamen neben dem Schlüssel auf dem Sperrbildschirm an.
Befolgen Sie die Anweisungen, um Ihren öffentlichen Schlüssel und Ihre Domäne zu registrieren. Der öffentliche Schlüssel, auf den sich diese Anweisungen beziehen, ist im obigen Beispiel die Datei public_key.pem .
Sobald Ihr öffentlicher Schlüssel erfolgreich registriert wurde, stellen Sie den Fahrzeugbesitzern einen Link zu https://tesla.com/_ak/<your_domain_name> zur Verfügung. Wenn Sie beispielsweise example.com registriert haben, geben Sie einen Link zu https://tesla.com/_ak/example.com an. Den Rest erledigt die offizielle iPhone- oder Android-App von Tesla (Version 4.27.3 oder höher). Kunden mit mehr als einem Tesla-Produkt müssen das gewünschte Fahrzeug auswählen, bevor sie auf den Link klicken oder den QR-Code scannen.
Der HTTP-Proxy erfordert ein TLS-Serverzertifikat. Zu Test- und Entwicklungszwecken können Sie mit OpenSSL ein selbstsigniertes Localhost-Serverzertifikat erstellen:
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"
Dieser Befehl erstellt einen unverschlüsselten privaten Schlüssel, config/tls-key.pem .
Der Proxyserver kann mit dem folgenden Befehl ausgeführt werden:
tesla-http-proxy -tls-key config/tls-key.pem -cert config/tls-cert.pem -key-file config/fleet-key.pem -port 4443Es kann auch mit Docker ausgeführt werden:
# 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 Hinweis: In der Produktion möchten Sie wahrscheinlich den -port 4443 weglassen und den Standard-Port 443 abhören.
In diesem Abschnitt wird veranschaulicht, wie Clients mithilfe von curl auf den Server zugreifen können. Kunden sind für den Erhalt von OAuth-Tokens verantwortlich. Besorgen Sie sich wie oben beschrieben ein OAuth-Token.
Endpunkte, die keine End-to-End-Authentifizierung unterstützen, werden per Proxy an die REST-API von Tesla weitergeleitet:
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 . Endpunkte, die eine End-to-End-Authentifizierung unterstützen, werden vom Proxy abgefangen und neu geschrieben, der den Sitzungsstatus und Wiederholungsversuche verwaltet. Nachdem Sie cert.pem auf Ihren Client kopiert haben, führt die Ausführung des folgenden Befehls von einem Client dazu, dass der Proxy einen flash_lights -Befehl an das Fahrzeug sendet:
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 " Der Ablauf zum Erhalten von $TESLA_AUTH_TOKEN :
Der Ablauf eines Befehls durch das System:
Der HTTP-Proxy implementiert die Fahrzeugbefehlsendpunkte der Tesla Fleet API.
Ältere Clients, die für die Eigentümer-API geschrieben wurden, verwenden beim Erstellen von URL-Pfaden möglicherweise die Eigentümer-API-ID eines Fahrzeugs. Der Proxyserver erfordert stattdessen, dass Clients die VIN direkt verwenden.
Sie können die Paketdokumentation auf pkg.go.dev lesen.
Dieses Repository unterstützt go mod und folgt der Semantik der Go-Version. Beachten Sie, dass Versionen v0.xx keine API-Stabilität garantieren.
