vehicle command
v0.2.1
Les véhicules Tesla prennent désormais en charge un protocole qui fournit une authentification des commandes de bout en bout. Ce package Golang utilise le nouveau protocole pour contrôler les fonctions du véhicule, telles que la climatisation et la recharge.
Parmi les outils inclus se trouve un serveur proxy HTTP qui convertit les appels de l'API REST vers le nouveau protocole de commande de véhicule.
Certains développeurs connaissent peut-être l'API Owner de Tesla. L'API du propriétaire cessera de fonctionner à mesure que les véhicules commenceront à exiger une authentification des commandes de bout en bout. Si vous faites partie de ces développeurs, vous pouvez configurer le serveur proxy ou refactoriser votre application pour utiliser directement cette bibliothèque. Les véhicules Model S et X antérieurs à 2021 ne prennent pas en charge ce nouveau protocole. Fleet API continuera à travailler sur ces véhicules.
L'authentification des commandes s'effectue en deux étapes :
Ainsi, pour envoyer une commande à un véhicule, une application tierce doit obtenir un jeton OAuth valide de l'utilisateur, et l'utilisateur doit inscrire la clé publique de l'application dans le véhicule.
Le site Web de Tesla contient des instructions pour obtenir des jetons OAuth. Ce README contient des instructions pour générer des clés privées et diriger l'utilisateur vers le flux d'inscription de clé publique. Les outils de ce référentiel peuvent utiliser le jeton OAuth et la clé privée pour envoyer des commandes aux véhicules.
Par exemple, le référentiel comprend une interface de ligne de commande :
tesla-control -ble -key-file private_key.pem lockEt un serveur proxy API REST (qui est fourni avec une clé privée au lancement et utilise les tokens OAuth envoyés par les clients) :
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"
Exigences:
Étapes d'installation :
go get ./...go build ./...go install ./...La commande finale installe les utilitaires suivants :
Une image Docker est disponible pour exécuter ces outils. L'image exécute par défaut le proxy HTTP, mais l'indicateur --entrypoint modifie l'outil à utiliser.
Exécutez l'image depuis le hub 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 --helpUn exemple de fichier docker-compose.yml est également fourni.
docker compose upLes variables d'environnement suivantes peuvent être utilisées à la place des indicateurs de ligne de commande.
TESLA_KEY_NAME utilisé pour dériver le nom d'entrée de votre clé privée d'authentification de commande dans votre trousseau de clés système.TESLA_TOKEN_NAME utilisé pour dériver le nom d'entrée de votre jeton OAuth dans votre trousseau de clés système.TESLA_KEYRING_TYPE remplace le type de trousseau de clés système par défaut pour votre système d'exploitation. Exécutez tesla-keygen -h pour voir les valeurs prises en charge répertoriées dans la documentation de l'indicateur -keyring-type . Consultez la documentation du porte-clés pour plus de détails sur chaque option.TESLA_VIN spécifie un numéro d'identification du véhicule. Vous pouvez trouver votre VIN sous Contrôles > Logiciel dans l'interface utilisateur de votre véhicule. (Malgré leur nom, les VIN contiennent à la fois des lettres et des chiffres).TESLA_CACHE_FILE spécifie un fichier qui met en cache les informations de session. Le cache permet aux programmes d'ignorer l'envoi de messages de poignée de main à un véhicule. Cela réduit à la fois la latence et le nombre d'appels API de flotte qu'un client effectue lors de la reconnexion à un véhicule après le redémarrage. Ceci est particulièrement utile lors de l'utilisation tesla-control , qui redémarre à chaque appel.TESLA_HTTP_PROXY_TLS_CERT spécifie un fichier de certificat TLS pour le proxy HTTP.TESLA_HTTP_PROXY_TLS_KEY spécifie un fichier de clé TLS pour le proxy HTTP.TESLA_HTTP_PROXY_HOST spécifie l'hôte du proxy HTTP.TESLA_HTTP_PROXY_PORT spécifie le port du proxy HTTP.TESLA_HTTP_PROXY_TIMEOUT spécifie le délai d'expiration que le proxy HTTP doit utiliser lors de la contact avec les serveurs Tesla.TESLA_VERBOSE active la journalisation détaillée. Pris en charge par tesla-control et tesla-http-proxy .Par exemple:
export TESLA_KEY_NAME= $( whoami )
export TESLA_TOKEN_NAME= $( whoami )
export TESLA_CACHE_FILE= ~ /.tesla-cache.jsonÀ ce stade, vous êtes prêt à utiliser l'outil de ligne de commande pour commencer à envoyer des commandes à votre véhicule personnel via BLE ! Vous pouvez également continuer à lire ci-dessous pour savoir comment créer une application capable d'envoyer des commandes sur Internet à l'aide d'une API REST.
Cette section décrit comment configurer et utiliser le proxy HTTP, qui permet aux clients d'envoyer des commandes de véhicule à l'aide d'une API REST.
Comme indiqué ci-dessus, votre proxy HTTP devra s'authentifier à la fois auprès de Tesla (à l'aide de jetons OAuth) et auprès de véhicules individuels (à l'aide d'une clé privée).
Les serveurs de Tesla exigent que votre client fournisse un jeton d'accès OAuth avant de transmettre des commandes à un véhicule. Vous devez obtenir le jeton OAuth auprès du propriétaire du véhicule. Consultez le site Web de Tesla pour obtenir des instructions sur l'enregistrement d'un compte de développeur et l'obtention de jetons OAuth.
Même si votre client dispose d'un token valide, le véhicule n'accepte que les commandes autorisées par la clé privée de votre client.
L'utilitaire tesla-keygen inclus dans ce référentiel génère une clé privée, la stocke dans le trousseau de clés de votre système et imprime la clé publique correspondante :
export TESLA_KEY_NAME=$(whoami)
tesla-keygen create > public_key.pem
Le trousseau système utilise le stockage des informations d'identification dépendant du système d'exploitation comme trousseau système. Sur macOS, par exemple, il utilise par défaut votre trousseau de connexion. Exécutez tesla-keygen -h pour plus d'options.
La réexécution de la commande tesla-keygen imprimera la même clé publique sans écraser la clé privée. Vous pouvez forcer l'utilitaire à écraser une clé publique existante avec -f .
Les véhicules vérifient les commandes à l'aide de clés publiques. Votre clé publique doit être inscrite sur les véhicules de vos utilisateurs avant qu'ils acceptent les commandes envoyées par votre application.
Voici le processus d'inscription du point de vue du propriétaire :
Pour que ce processus fonctionne, vous devez enregistrer un nom de domaine qui identifie votre application. L'application Tesla affichera ce nom de domaine à l'utilisateur lorsqu'elle lui demandera s'il souhaite approuver votre demande, et le véhicule affichera le nom de domaine à côté de la clé dans l'écran Serrures.
Suivez les instructions pour enregistrer votre clé publique et votre domaine. La clé publique mentionnée dans ces instructions est le fichier public_key.pem dans l'exemple ci-dessus.
Une fois votre clé publique enregistrée avec succès, fournissez aux propriétaires de véhicules un lien vers https://tesla.com/_ak/<your_domain_name> . Par exemple, si vous avez enregistré example.com , fournissez un lien vers https://tesla.com/_ak/example.com . L'application mobile officielle Tesla pour iPhone ou Android (version 4.27.3 ou supérieure) s'occupera du reste. Les clients possédant plusieurs produits Tesla doivent sélectionner le véhicule souhaité avant de cliquer sur le lien ou de scanner le code QR.
Le proxy HTTP nécessite un certificat de serveur TLS. À des fins de test et de développement, vous pouvez créer un certificat de serveur localhost auto-signé à l'aide d'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"
Cette commande crée une clé privée non chiffrée, config/tls-key.pem .
Le serveur proxy peut être exécuté à l'aide de la commande suivante :
tesla-http-proxy -tls-key config/tls-key.pem -cert config/tls-cert.pem -key-file config/fleet-key.pem -port 4443Il peut également être exécuté à l'aide de Docker :
# 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 Remarque : En production, vous souhaiterez probablement omettre le -port 4443 et écouter sur le port standard 443.
Cette section illustre comment les clients peuvent accéder au serveur à l'aide de curl . Les clients sont responsables de l'obtention des jetons OAuth. Obtenez un jeton OAuth comme décrit ci-dessus.
Les points de terminaison qui ne prennent pas en charge l'authentification de bout en bout sont transmis par proxy à l'API REST de Tesla :
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 . Les points de terminaison prenant en charge l'authentification de bout en bout sont interceptés et réécrits par le proxy, qui gère l'état de la session et les tentatives. Après avoir copié cert.pem sur votre client, l'exécution de la commande suivante à partir d'un client entraînera l'envoi par le proxy d'une commande flash_lights au véhicule :
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 " Le flux pour obtenir $TESLA_AUTH_TOKEN :
Flux d'une commande à travers le système :
Le proxy HTTP implémente les points de terminaison de commande de véhicule de l'API Tesla Fleet.
Les anciens clients écrits pour l'API Owner peuvent utiliser l'ID API Owner d'un véhicule lors de la création de chemins d'URL. Le serveur proxy exige que les clients utilisent directement le VIN.
Vous pouvez lire la documentation du package sur pkg.go.dev.
Ce référentiel prend en charge go mod et suit la sémantique de la version Go. Notez que les versions v0.xx ne garantissent pas la stabilité de l'API.
