vehicle command
v0.2.1
Os veículos Tesla agora suportam um protocolo que fornece autenticação de comando ponta a ponta. Este pacote Golang utiliza o novo protocolo para controlar funções do veículo, como controle climático e carregamento.
Entre as ferramentas incluídas está um servidor proxy HTTP que converte chamadas da API REST para o novo protocolo de comando de veículo.
Alguns desenvolvedores podem estar familiarizados com a API Owner da Tesla. A API do proprietário deixará de funcionar à medida que os veículos começarem a exigir autenticação de comando de ponta a ponta. Se você for um desses desenvolvedores, poderá configurar o servidor proxy ou refatorar seu aplicativo para usar esta biblioteca diretamente. Os veículos Modelo S e X anteriores a 2021 não suportam este novo protocolo. A Fleet API continuará funcionando nesses veículos.
A autenticação de comando ocorre em duas etapas:
Portanto, para enviar um comando a um veículo, uma aplicação de terceiros deve obter um token OAuth válido do usuário, e o usuário deve cadastrar a chave pública da aplicação no veículo.
O site da Tesla contém instruções para obter tokens OAuth. Este README contém instruções para gerar chaves privadas e direcionar o usuário ao fluxo de inscrição de chave pública. As ferramentas deste repositório podem usar o token OAuth e a chave privada para enviar comandos aos veículos.
Por exemplo, o repositório inclui uma interface de linha de comando:
tesla-control -ble -key-file private_key.pem lockE um servidor proxy REST API (que é fornecido com uma chave privada na inicialização e usa tokens OAuth enviados pelos 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:
Etapas de instalação:
go get ./...go build ./...go install ./...O comando final instala os seguintes utilitários:
Uma imagem Docker está disponível para executar essas ferramentas. O padrão da imagem é executar o proxy HTTP, mas o sinalizador --entrypoint altera a ferramenta a ser usada.
Execute a imagem do 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 --helpUm exemplo de arquivo docker-compose.yml também é fornecido.
docker compose upAs variáveis de ambiente a seguir podem ser usadas no lugar dos sinalizadores de linha de comando.
TESLA_KEY_NAME usado para derivar o nome da entrada para sua chave privada de autenticação de comando no chaveiro do sistema.TESLA_TOKEN_NAME usado para derivar o nome da entrada do seu token OAuth no chaveiro do sistema.TESLA_KEYRING_TYPE usado substitui o tipo de chaveiro do sistema padrão para o seu sistema operacional. Execute tesla-keygen -h para ver os valores suportados listados na documentação do sinalizador -keyring-type . Consulte a documentação do chaveiro para obter detalhes sobre cada opção.TESLA_VIN especifica um número de identificação do veículo. Você pode encontrar seu VIN em Controles > Software na interface do usuário do seu veículo. (Apesar do nome, os VINs contêm letras e números).TESLA_CACHE_FILE especifica um arquivo que armazena informações da sessão em cache. O cache permite que os programas ignorem o envio de mensagens de handshake para um veículo. Isso reduz a latência e o número de chamadas da Fleet API que um cliente faz ao se reconectar a um veículo após a reinicialização. Isto é particularmente útil ao usar tesla-control , que reinicia a cada invocação.TESLA_HTTP_PROXY_TLS_CERT especifica um arquivo de certificado TLS para o proxy HTTP.TESLA_HTTP_PROXY_TLS_KEY especifica um arquivo de chave TLS para o proxy HTTP.TESLA_HTTP_PROXY_HOST especifica o host do proxy HTTP.TESLA_HTTP_PROXY_PORT especifica a porta do proxy HTTP.TESLA_HTTP_PROXY_TIMEOUT especifica o tempo limite para o proxy HTTP usar ao entrar em contato com servidores Tesla.TESLA_VERBOSE ativa o registro detalhado. Suportado por tesla-control e tesla-http-proxy .Por exemplo:
export TESLA_KEY_NAME= $( whoami )
export TESLA_TOKEN_NAME= $( whoami )
export TESLA_CACHE_FILE= ~ /.tesla-cache.jsonNeste ponto, você está pronto para usar a ferramenta de linha de comando para começar a enviar comandos para seu veículo pessoal via BLE! Alternativamente, continue lendo abaixo para aprender como construir um aplicativo que pode enviar comandos pela Internet usando uma API REST.
Esta seção descreve como configurar e usar o proxy HTTP, que permite aos clientes enviar comandos de veículos usando uma API REST.
Conforme discutido acima, seu proxy HTTP precisará ser autenticado tanto com Tesla (usando tokens OAuth) quanto com veículos individuais (usando uma chave privada).
Os servidores da Tesla exigem que seu cliente forneça um token de acesso OAuth antes de encaminhar comandos para um veículo. Você deve obter o token OAuth do proprietário do veículo. Consulte o site da Tesla para obter instruções sobre como registrar uma conta de desenvolvedor e obter tokens OAuth.
Mesmo que o seu cliente possua um token válido, o veículo só aceita comandos autorizados pela chave privada do seu cliente.
O utilitário tesla-keygen incluído neste repositório gera uma chave privada, armazena-a no chaveiro do sistema e imprime a chave pública correspondente:
export TESLA_KEY_NAME=$(whoami)
tesla-keygen create > public_key.pem
O chaveiro do sistema usa o armazenamento de credenciais dependente do sistema operacional como o chaveiro do sistema. No macOS, por exemplo, o padrão é usar suas chaves de login. Execute tesla-keygen -h para mais opções.
A nova execução do comando tesla-keygen imprimirá a mesma chave pública sem substituir a chave privada. Você pode forçar o utilitário a substituir uma chave pública existente com -f .
Os veículos verificam os comandos usando chaves públicas. Sua chave pública deve estar cadastrada nos veículos de seus usuários antes que eles aceitem comandos enviados por seu aplicativo.
Aqui está o processo de inscrição da perspectiva do proprietário:
Para que esse processo funcione, você deve registrar um nome de domínio que identifique sua aplicação. A aplicação Tesla apresentará este nome de domínio ao utilizador quando lhe perguntar se pretende aprovar o seu pedido, e o veículo apresentará o nome de domínio junto à chave no ecrã Bloqueios.
Siga as instruções para registrar sua chave pública e domínio. A chave pública referida nessas instruções é o arquivo public_key.pem no exemplo acima.
Depois que sua chave pública for registrada com sucesso, forneça aos proprietários do veículo um link para https://tesla.com/_ak/<your_domain_name> . Por exemplo, se você registrou example.com , forneça um link para https://tesla.com/_ak/example.com . O aplicativo móvel oficial Tesla para iPhone ou Android (versão 4.27.3 ou superior) cuidará do resto. Clientes com mais de um produto Tesla devem selecionar o veículo desejado antes de clicar no link ou escanear o código QR.
O proxy HTTP requer um certificado de servidor TLS. Para fins de teste e desenvolvimento, você pode criar um certificado de servidor localhost autoassinado usando 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 cria uma chave privada não criptografada, config/tls-key.pem .
O servidor proxy pode ser executado usando o seguinte comando:
tesla-http-proxy -tls-key config/tls-key.pem -cert config/tls-cert.pem -key-file config/fleet-key.pem -port 4443Também pode ser executado 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 Observação: na produção, você provavelmente desejará omitir -port 4443 e escutar na porta padrão 443.
Esta seção ilustra como os clientes podem acessar o servidor usando curl . Os clientes são responsáveis pela obtenção de tokens OAuth. Obtenha um token OAuth conforme descrito acima.
Endpoints que não suportam autenticação ponta a ponta são proxy para a API REST da 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 . Os endpoints que oferecem suporte à autenticação ponta a ponta são interceptados e reescritos pelo proxy, que trata do estado da sessão e das novas tentativas. Depois de copiar cert.pem para seu cliente, executar o seguinte comando de um cliente fará com que o proxy envie um comando flash_lights para o veí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 " O fluxo para obter $TESLA_AUTH_TOKEN :
O fluxo de um comando através do sistema:
O proxy HTTP implementa os pontos finais de comando do veículo Tesla Fleet API.
Os clientes legados escritos para a API do proprietário podem usar o ID da API do proprietário de um veículo ao construir caminhos de URL. O servidor proxy exige que os clientes usem o VIN diretamente.
Você pode ler a documentação do pacote em pkg.go.dev.
Este repositório suporta go mod e segue a semântica da versão Go. Observe que as versões v0.xx não garantem a estabilidade da API.
