vehicle command
v0.2.1
Los vehículos Tesla ahora admiten un protocolo que proporciona autenticación de comandos de un extremo a otro. Este paquete Golang utiliza el nuevo protocolo para controlar las funciones del vehículo, como el control del clima y la carga.
Entre las herramientas incluidas se encuentra un servidor proxy HTTP que convierte las llamadas API REST al nuevo protocolo de comando de vehículo.
Es posible que algunos desarrolladores estén familiarizados con la API de propietario de Tesla. La API del propietario dejará de funcionar a medida que los vehículos comiencen a requerir autenticación de comando de un extremo a otro. Si es uno de estos desarrolladores, puede configurar el servidor proxy o refactorizar su aplicación para usar esta biblioteca directamente. Los vehículos Model S y X anteriores a 2021 no son compatibles con este nuevo protocolo. Fleet API seguirá funcionando en estos vehículos.
La autenticación de comandos se realiza en dos pasos:
Entonces, para enviar un comando a un vehículo, una aplicación de terceros debe obtener un token OAuth válido del usuario, y el usuario debe registrar la clave pública de la aplicación en el vehículo.
El sitio web de Tesla tiene instrucciones para obtener tokens OAuth. Este README tiene instrucciones para generar claves privadas y dirigir al usuario al flujo de inscripción de clave pública. Las herramientas de este repositorio pueden utilizar el token OAuth y la clave privada para enviar comandos a los vehículos.
Por ejemplo, el repositorio incluye una interfaz de línea de comandos:
tesla-control -ble -key-file private_key.pem lockY un servidor proxy REST API (que recibe una clave privada en el lanzamiento y utiliza tokens OAuth enviados por los clientes):
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"
Requisitos:
Pasos de instalación:
go get ./...go build ./...go install ./...El comando final instala las siguientes utilidades:
Hay una imagen de Docker disponible para ejecutar estas herramientas. De forma predeterminada, la imagen ejecuta el proxy HTTP, pero el indicador --entrypoint cambia la herramienta que se utilizará.
Ejecute la imagen desde Docker Hub:
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 --helpTambién se proporciona un archivo docker-compose.yml de ejemplo.
docker compose upSe pueden utilizar las siguientes variables de entorno en lugar de indicadores de línea de comandos.
TESLA_KEY_NAME se utiliza para derivar el nombre de entrada de su clave privada de autenticación de comando en el conjunto de claves de su sistema.TESLA_TOKEN_NAME se utiliza para derivar el nombre de entrada de su token OAuth en el conjunto de claves de su sistema.TESLA_KEYRING_TYPE se utiliza para anular el tipo de conjunto de claves del sistema predeterminado para su sistema operativo. Ejecute tesla-keygen -h para ver los valores admitidos enumerados en la documentación del indicador -keyring-type . Consulte la documentación del llavero para obtener detalles sobre cada opción.TESLA_VIN especifica un número de identificación del vehículo. Puede encontrar su VIN en Controles > Software en la interfaz de usuario de su vehículo. (A pesar del nombre, los VIN contienen letras y números).TESLA_CACHE_FILE especifica un archivo que almacena en caché la información de la sesión. El caché permite que los programas omitan el envío de mensajes de protocolo de enlace a un vehículo. Esto reduce tanto la latencia como la cantidad de llamadas a Fleet API que realiza un cliente cuando se vuelve a conectar a un vehículo después de reiniciar. Esto es particularmente útil cuando se usa tesla-control , que se reinicia en cada invocación.TESLA_HTTP_PROXY_TLS_CERT especifica un archivo de certificado TLS para el proxy HTTP.TESLA_HTTP_PROXY_TLS_KEY especifica un archivo de clave TLS para el proxy HTTP.TESLA_HTTP_PROXY_HOST especifica el host para el proxy HTTP.TESLA_HTTP_PROXY_PORT especifica el puerto para el proxy HTTP.TESLA_HTTP_PROXY_TIMEOUT especifica el tiempo de espera que debe utilizar el proxy HTTP al contactar con los servidores de Tesla.TESLA_VERBOSE habilita el registro detallado. Compatible con tesla-control y tesla-http-proxy .Por ejemplo:
export TESLA_KEY_NAME= $( whoami )
export TESLA_TOKEN_NAME= $( whoami )
export TESLA_CACHE_FILE= ~ /.tesla-cache.jsonEn este punto, está listo para usar la herramienta de línea de comandos para comenzar a enviar comandos a su vehículo personal a través de BLE. Alternativamente, continúe leyendo a continuación para aprender cómo crear una aplicación que pueda enviar comandos a través de Internet utilizando una API REST.
Esta sección describe cómo configurar y usar el proxy HTTP, que permite a los clientes enviar comandos del vehículo usando una API REST.
Como se mencionó anteriormente, su proxy HTTP deberá autenticarse tanto con Tesla (usando tokens OAuth) como con vehículos individuales (usando una clave privada).
Los servidores de Tesla requieren que su cliente proporcione un token de acceso OAuth antes de reenviar comandos a un vehículo. Debes obtener el token OAuth del propietario del vehículo. Consulte el sitio web de Tesla para obtener instrucciones sobre cómo registrar una cuenta de desarrollador y obtener tokens OAuth.
Incluso si su cliente tiene un token válido, el vehículo solo acepta comandos autorizados por la clave privada de su cliente.
La utilidad tesla-keygen incluida en este repositorio genera una clave privada, la almacena en el conjunto de claves de su sistema e imprime la clave pública correspondiente:
export TESLA_KEY_NAME=$(whoami)
tesla-keygen create > public_key.pem
El conjunto de claves del sistema utiliza el almacenamiento de credenciales dependiente del sistema operativo como conjunto de claves del sistema. En macOS, por ejemplo, de forma predeterminada se utiliza su llavero de inicio de sesión. Ejecute tesla-keygen -h para obtener más opciones.
Al volver a ejecutar el comando tesla-keygen se imprimirá la misma clave pública sin sobrescribir la clave privada. Puede forzar a la utilidad a sobrescribir una clave pública existente con -f .
Los vehículos verifican comandos utilizando claves públicas. Su clave pública debe estar registrada en los vehículos de sus usuarios antes de que acepten los comandos enviados por su aplicación.
Aquí está el proceso de inscripción desde la perspectiva del propietario:
Para que este proceso funcione, debe registrar un nombre de dominio que identifique su aplicación. La aplicación Tesla mostrará este nombre de dominio al usuario cuando le pregunte si desea aprobar su solicitud, y el vehículo mostrará el nombre de dominio junto a la llave en la pantalla Bloqueos.
Siga las instrucciones para registrar su clave pública y dominio. La clave pública a la que se hace referencia en esas instrucciones es el archivo public_key.pem en el ejemplo anterior.
Una vez que su clave pública se haya registrado correctamente, proporcione a los propietarios de vehículos un enlace a https://tesla.com/_ak/<your_domain_name> . Por ejemplo, si registró example.com , proporcione un enlace a https://tesla.com/_ak/example.com . La aplicación móvil oficial de Tesla para iPhone o Android (versión 4.27.3 o superior) se encargará del resto. Los clientes con más de un producto Tesla deben seleccionar el vehículo deseado antes de hacer clic en el enlace o escanear el código QR.
El proxy HTTP requiere un certificado de servidor TLS. Para fines de prueba y desarrollo, puede crear un certificado de servidor localhost autofirmado utilizando 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"
Este comando crea una clave privada no cifrada, config/tls-key.pem .
El servidor proxy se puede ejecutar usando el siguiente comando:
tesla-http-proxy -tls-key config/tls-key.pem -cert config/tls-cert.pem -key-file config/fleet-key.pem -port 4443También se puede ejecutar usando 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 Nota: En producción, probablemente querrás omitir el -port 4443 y escuchar en el puerto estándar 443.
Esta sección ilustra cómo los clientes pueden llegar al servidor usando curl . Los clientes son responsables de obtener tokens OAuth. Obtenga un token de OAuth como se describe arriba.
Los puntos finales que no admiten la autenticación de un extremo a otro se envían mediante proxy a la 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 . Los puntos finales que admiten la autenticación de un extremo a otro son interceptados y reescritos por el proxy, que maneja el estado de la sesión y los reintentos. Después de copiar cert.pem a su cliente, ejecutar el siguiente comando desde un cliente hará que el proxy envíe un comando flash_lights al vehículo:
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 " El flujo para obtener $TESLA_AUTH_TOKEN :
El flujo de un comando a través del sistema:
El proxy HTTP implementa los puntos finales de comando de vehículos Tesla Fleet API.
Los clientes heredados escritos para Owner API pueden estar usando el ID de Owner API de un vehículo al crear rutas URL. En su lugar, el servidor proxy requiere que los clientes utilicen el VIN directamente.
Puede leer la documentación del paquete en pkg.go.dev.
Este repositorio admite go mod y sigue la semántica de la versión Go. Tenga en cuenta que las versiones v0.xx no garantizan la estabilidad de la API.
