DOCSEARCHbyAlgolia
Submit Docs

Tesla Fleet Telemetry

repository·main·Indexed 21 days ago

https://github.com/teslamotors/fleet-telemetry

A server reference implementation for receiving and storing telemetry data from Tesla vehicles via WebSocket connections. It enables secure ingestion of vehicle signals and connectivity states, with support for dispatching data to backends including Kafka, Kinesis, Redis, Google Pub/Sub, ZMQ, and MQTT. The system supports reliable acknowledgments, Prometheus/StatsD metrics, and provides a reference implementation for fleet operators to manage vehicle data streams.

Tokens
7.2K
Snippets
23
Records
37
Agent score
74%

What's inside fleet-telemetry

  1. Detect vehicle connectivity changes

    main

    You can use Fleet Telemetry connectivity events as a proxy to determine when a vehicle is online. When configured correctly, the Fleet Telemetry connectivity state should match the actual vehicle connectivity state with 99%+ accuracy.

    To enable these events, add the connectivity key to the records object in your server_config.json file, specifying the dispatcher to use.

    "records": {
    "connectivity": [
        "kafka"
      ]
}

  2. Supported Dispatchers for vehicle data

    main

    Dispatchers process vehicle data upon arrival. Supported types include:

    • Kafka (Preferred): Requires topics for _V, _connectivity, and _alerts. Uses a configurable namespace prefix (default: tesla).
    • Kinesis: Uses standard AWS environment variables and config files. Stream names default to {namespace}_{topic_name} (e.g., tesla_V). Can be overridden via KINESIS_STREAM_{TOPIC} env vars.
    • Google Pub/Sub: Requires GOOGLE_APPLICATION_CREDENTIALS. The server attempts to create missing topics on startup.
    • Redis: Publishes to Redis Pub/Sub channels.
      • If subscriber_set_prefix is set, it uses a per-VIN sorted set: <prefix>_<namespace>_<topic>_{vin}.
      • If publish_vin_topics is enabled, it also publishes to <namespace>_<topic>_{vin}.
      • Note: Either subscriber_set_prefix or publish_vin_topics must be configured for the server to start.
    • ZMQ: Configured via the JSON config file.
    • MQTT: Configured via the JSON config file.
    • Logger: A simple STDOUT logger that serializes protobufs to JSON.

  3. Track incoming signals and usage metrics

    main

    If metrics are enabled, you can track the count of incoming signals to monitor service usage or approximate billing.

    • Default behavior: Signals are tracked per record_type using the prefixes V and alerts.
    • VIN-specific tracking: To track metrics for a specific subset of vehicles, add vins_signal_tracking_enabled to your configuration file.

  4. Reliable acknowledgment and data integrity

    main

    The producer supports reliable acknowledgment for specified transaction types.

    Critical Behavior: If any related MQTT publish operations within a transaction fail, the entire packet from the vehicle will not be acknowledged. This mechanism prevents partial updates and ensures data integrity by allowing the system to retry the complete set of data if any part of the publishing process fails.

  5. Understand the MQTT topic structure

    main

    The MQTT datastore uses a hierarchical topic structure based on a <topic_base> and the vehicle's <VIN>. This allows subscribers to filter data by type (metrics, alerts, errors, or connectivity) or by specific vehicle.

    Topic Patterns:

    • Metrics: <topic_base>/<VIN>/v/<field_name>
    • Alerts (current state): <topic_base>/<VIN>/alerts/<alert_name>/current
    • Alerts (history): <topic_base>/<VIN>/alerts/<alert_name>/history
    • Errors: <topic_base>/<VIN>/errors/<error_name>
    • Connectivity: <topic_base>/<VIN>/connectivity

  8. List unapproved licenses

    main

    To identify licenses that have not been approved in the project's decisions file, run license_finder pointing to the existing decisions configuration:

    license_finder --decisions-file=doc/license_decisions.yml

    license_finder --decisions-file=doc/license_decisions.yml

  9. Install Fleet Telemetry on Kubernetes

    main

    The recommended way to deploy Fleet Telemetry is using Kubernetes with Helm Charts. A reference Helm chart is available in the teslamotors/helm-charts repository.

    Manual Deployment Requirements:

    • Assign a Fully Qualified Domain Name (FQDN).
    • Architecture recommendation: Firewall/Loadbalancer -> Fleet Telemetry -> Kafka.
    • Ensure mTLS connections are terminated on the Fleet Telemetry service.
    • If running manually (non-Kubernetes), use the binary with the -config flag: ./fleet-telemetry -config=/etc/fleet-telemetry/config.json.
    # Example Kubernetes Deployment snippet
apiVersion: apps/v1
kind: Deployment
metadata:
  name: fleet-telemetry
spec:
  replicas: 1
  selector:
    matchLabels:
      app: fleet-telemetry
  template:
    metadata:
      labels:
        app: fleet-telemetry
    spec:
      containers:
      - name: fleet-telemetry
        image: tesla/fleet-telemetry:<tag>
        command: ["/fleet-telemetry", "-config=/etc/fleet-telemetry/config.json"]
        ports:
        - containerPort: 443
---
apiVersion: v1
kind: Service
metadata:
  name: fleet-telemetry
spec:
  selector:
    app: fleet-telemetry
  ports:
  - protocol: TCP
    port: 443
    targetPort: 443
  type: LoadBalancer

  10. Recompile Protobuf messages

    main

    Data is encapsulated in protobuf messages. To recompile them, follow these steps:

    1. Install protoc (version 4.25.1 recommended).
    2. Install the Go plugin: go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28.
    3. Run the generation command via make.
    make generate-protos

  12. Setup Tesla Fleet Telemetry service

    main

    To set up a Fleet Telemetry server, follow these high-level steps:

    1. Create a Developer Application: Use developer.tesla.com. For most use cases, select "Authorization Code and Machine-to-Machine".
    2. Generate EC Keys: Create a private key using the secp256r1 curve and derive the public key.
    3. Host Public Key: Place the public key at https://<application-domain>/.well-known/appspecific/com.tesla.3p.public-key.pem.
    4. Authentication: Generate a Partner Authentication Token and register your application via the Fleet API register endpoint.
    5. Server Configuration: Configure the fleet-telemetry server (see installation steps).
    6. Validate Configuration: Use the check_server_cert.sh tool to validate your server's TLS configuration.
    7. Vehicle Pairing: Pair the application's virtual key to the vehicle(s).
    8. Command Proxy: Configure and run the vehicle-command proxy using your application's private key.
    9. Vehicle Configuration: Use the fleet_telemetry_config endpoint to configure vehicles. Wait for synced to be true before expecting data streams.
    # Generate EC private key
openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem

# Derive public key
openssl ec -in private-key.pem -pubout -out public-key.pem