Skip to content

badolgm/raceTelemetryAi

BranchesTags

Repository files navigation

Hack the Track — Unleash the Data. Engineer Victory.

Hackathon 2025: Race Telemetry AI Coach

Proyecto base y documentación para analizar telemetría de competición (GR Cup / SRO) y visualizar insights por sectores de pista, con IA orientada a coaching en tiempo real y post‑sesión.

Índice

Banners rápidos (sitios oficiales)

Hackathon 2025 SRO America GT World Challenge America GR Cup TGRNA

Barber Motorsports Park Circuit of The Americas Indianapolis Motor Speedway Road America Sebring Raceway Sonoma Raceway VIR

MoTeC AIM Technologies Bosch Motorsport CAN bus

Nota: Algunos circuitos no publican mapas de pista "oficiales" de libre acceso; se incluyen páginas oficiales de mapas del recinto o configuraciones. Donde exista un PDF oficial, se enlaza.

Descripción general

Este repositorio acompaña la aplicación web "Race Telemetry AI Coach" (Vite) y la documentación técnica del proyecto. El objetivo es procesar telemetría (velocidad, RPM, frenos, aceleraciones, dirección, GPS, lapdist) y ofrecer:

  • Segmentación por sectores S1.a/S1.b ... S3.b, coherente con los "análisis por secciones" del hackathon.
  • Mapas de riesgo por sector y recomendaciones de conducción.
  • Gráficas de vueltas, tiempos y eventos (frenada, aceleración, cambios de marcha).
  • Integración con IA para estimar oportunidades de mejora y detectar anomalías de sensores (ECU/VBOX).

IA y entrenamiento

  • Entrenamiento offline sobre datasets locales (∼20GB) produce artefactos ligeros por pista (ej.: public/DataFiles/models/riskModel.json, trackModels.json).
  • El runtime aplica esos artefactos: pesos y umbrales por componente, normalizaciones y longitudes por pista.
  • Integración generativa opcional: si defines VITE_API_KEY, el servicio Gemini puede generar recomendaciones textuales; si no, se usa el motor de riesgo heurístico con calibración.

Modo IA (Gemini) y seguridad

  • Activación desde la UI:
    • En el Dashboard, barra superior, botón Configurar IA.
    • Pega tu clave en Clave Gemini y pulsa Guardar.
    • Indicador cambia a Gemini listo.
  • Verificación en el asistente:
    • Pulsa Analizar vuelta. Si la IA está activa, aparece el badge Fuente IA: Gemini; si no, Fuente IA: Motor de Riesgo.
  • Referencias de código:
    • Controles de UI: components/Header.tsx:126-147.
    • Detección de clave y fallback: services/geminiService.ts:4-18 y components/AIAssistant.tsx:31-36.
    • Badge de fuente: components/AIAssistant.tsx:59-63.
  • Seguridad:
    • La clave pegada en la UI se guarda en localStorage del navegador y NO se sube a GitHub.
    • Alternativa: definir VITE_API_KEY en el entorno del sistema o del proveedor de despliegue.
    • No incluyas la clave en archivos versionados.

Entrenamiento offline y artefactos

  • Objetivo: evitar procesar ∼20GB en tiempo real y reducir falsos positivos. Se procesan offline y se exportan artefactos por pista.
  • Artefactos soportados por la app:
    • public/DataFiles/models/riskModel.json: pesos (tire/engine/brake) y umbrales (engineHigh/engineCritical/tireWearHigh/fuel*) por pista.
    • public/DataFiles/models/trackModels.json: normalizaciones (máximos realistas de speed/rpm/brake/steer), sectorización y longitud de vuelta.
  • Carga y uso en runtime:
    • Loader de modelos: services/modelLoader.ts:65-92.
    • Motor de riesgo que aplica pesos/umbrales: services/riskEngine.ts:86-95,167-182.
    • Precarga al cambiar de pista: components/Dashboard.tsx:23-28.
  • Cómo verificar que se aplican:
    • Modifica riskModel.json para tu pista (ej. Barber) y recarga: el panel del asistente mostrará los nuevos pesos/umbrales y cambiarán las alertas.
    • Panel informativo del asistente: components/AIAssistant.tsx:66-70.

Uso por fuente: Demo, CSV y WebSocket

  • Selección de fuente en el Header: components/Header.tsx:75-84.
  • Demo:
    • Fuente demo usa datos simulados coherentes para mostrar UI y alertas.
  • CSV (Barber incluido):
    • Coloca tu CSV y mapping:
      • public/DataFiles/barber/R1_barber_telemetry_data.csv
      • public/DataFiles/barber/mapping.json
    • Adaptador CSV: services/telemetryAdapter.ts:95-190.
    • Conversión de unidades y mapeo de columnas: services/telemetryAdapter.ts:62-79,222-233.
  • WebSocket (tiempo real desde logger/ECU):
    • Adaptador WS: services/telemetryAdapter.ts:235-260.
    • Conecta tu logger que emita frames con el contrato TelemetryDataPoint.

Instalación y despliegue (PC, tablet, vehículo)

  • Desarrollo local:
    • npm install
    • npm run dev y abrir http://localhost:5173/.
  • Build de producción y vista previa:
    • npm run build
    • npm run preview (servidor estático de prueba).
  • Tablet del piloto (PWA/browser):
    • Servir el dist/ en un servidor accesible vía Wi‑Fi del paddock/coche.
    • Abrir en Chrome/Safari y usar “Agregar a pantalla de inicio” (PWA) para acceso rápido.
    • Fuente ws si conectas al logger en el vehículo; csv para reproducir sesiones.
  • Sin “ejecutable” nativo:
    • Esta app es web. No incluye .exe/.apk por defecto.
    • Opciones futuras: empaquetar con Electron/Tauri o usar un contenedor con nginx para servir dist/ en dispositivos embebidos.
  • Claves y seguridad:
    • Usa Configurar IA en la UI o variables de entorno del proveedor. Evita subir claves a Git.

Demostración en video (YouTube)

  • Objetivo: mostrar telemetría en vivo/reproducida, alertas de riesgo, análisis del asistente y la activación de Gemini.
  • Guion sugerido:
    1. Inicio: Dashboard, explicar selector de fuente (demo/csv/ws) y selector de pista.
    2. CSV Barber: seleccionar Source: csv y pista Barber. Verás gauges, mapa y barra de progreso moviéndose.
    3. Artefactos offline: mostrar panel del asistente con Modelo de riesgo cargado para Barber (pesos/umbrales activos).
    4. IA: pulsar Configurar IA, pegar clave de https://aistudio.google.com/apikey, guardar. Pulsar Analizar vuelta y mostrar el badge Fuente IA: Gemini y las recomendaciones textuales.
    5. Alertas: provocar o explicar alertas visuales (motor/neumáticos/frenos/combustible) en VisualAlerts.
    6. Cierre: cambiar a otra pista con artefactos distintos (cota) y repetir análisis para comparar.
  • Enlace del video:
    • Pega tu URL aquí cuando esté publicado: https://youtu.be/TU_ENLACE_DEMO
    • También puedes añadirlo al banner superior o a la sección “Descripción general”.

Preguntas frecuentes (FAQ)

  • ¿Qué clave debo usar y dónde la obtengo?
    • Es la API key de Gemini. Obténla en https://aistudio.google.com/apikey.
  • ¿Se sube la clave a GitHub si la pego en la UI?
    • No. Se guarda en localStorage del navegador y no forma parte del repo. En producción usa variables de entorno (VITE_API_KEY).
  • ¿Cómo borro la clave?
    • Dashboard → Configurar IA → vacía Clave Gemini → Guardar; o localStorage.removeItem('gemini_api_key') en consola.
  • ¿Cómo preparo riskModel.json para una pista nueva?
    • Crea una entrada con weights y thresholds calibrados, por ejemplo: 
      {
  "mi_pista": {
    "weights": { "tire": 0.50, "engine": 0.28, "brake": 0.22 },
    "thresholds": {
      "overallHigh": 0.65,
      "engineHigh": 105,
      "engineCritical": 110,
      "tireWearHigh": 0.92,
      "tireWearMedium": 0.76,
      "fuelCriticalPct": 0.07,
      "fuelHighPct": 0.12
    }
  }
}
    • La app aplicará estos valores en services/riskEngine.ts:86-95,167-182.
  • ¿Cómo uso CSV vs. WebSocket?
    • CSV: coloca public/DataFiles/<pista>/*.csv y mapping.json. El adaptador está en services/telemetryAdapter.ts:95-190.
    • WebSocket: conecta tu logger que emita frames con el contrato TelemetryDataPoint (services/telemetryAdapter.ts:235-260).
  • ¿Hay ejecutable (.exe/.apk)?
    • No incluido por defecto. Esta app es web (Vite/React). Puedes empaquetar con Electron/Tauri o servir dist/ con nginx.
  • ¿Cómo usar sin internet en el vehículo?
    • Sirve dist/ en un hotspot local (paddock/vehículo). Abre en la tablet (Chrome/Safari) y usa “Agregar a pantalla de inicio”. Fuente ws para tiempo real.
  • ¿Compatibilidad de dispositivos?
    • Navegadores modernos (Chrome 116+, Safari 16+, Edge). Pantallas 10–13" recomendadas para cockpit; modo high/ultra contraste en exteriores.

Documento técnico (MASTERDOC)

Revisa el documento técnico completo en raceTelemetryAi/MASTERDOC.md, con diagramas UML, diseño de BD, flujos de datos y fórmulas del motor de riesgos.

Pistas y mapas

Si necesitas track maps vectoriales, consulta también las secciones de "Créditos y referencias" al final.

Fuentes de datos

Proveedores de telemetría

Cómo correr localmente

Requisitos:

  • Node.js >= 18
  • npm o pnpm

Pasos:

  1. Instala dependencias: npm install
  2. Arranca desarrollo: npm run dev
  3. Abre http://localhost:5173/ en el navegador.

Estructura de datos sugerida (sirviendo estáticos desde public/DataFiles/):

public/DataFiles/
  barber/
    R1_barber_telemetry_data.csv
    mapping.json
  cota/
    ...
  models/
    riskModel.json
    trackModels.json
  config/
    calibration.json
    trackPaths.json

Notas:

  • Los CSV pesados se colocan localmente en public/DataFiles/<pista>/ y no se versionan.
  • Los artefactos de modelos (models/*.json) y configuración (config/*.json) sí deben existir para que la app cargue normalizaciones y umbrales.

Exportar a PDF

  • Opción 1: Extensión "Markdown PDF" de tu IDE.
  • Opción 2: pandoc (Windows):
    • Instala pandoc.
    • pandoc README.md -o README.pdf
    • pandoc MASTERDOC.md -o MASTERDOC.pdf

GitHub del autor

  • Autor: Bernardo Adolfo Gómez Montoya — https://github.com/badolgm.
  • Comandos básicos (PowerShell):
    • git init
    • git add .
    • git commit -m "docs: README y MASTERDOC iniciales"
    • git branch -M main
    • git remote add origin https://github.com/TU_USUARIO/NOMBRE_REPO.git
    • git push -u origin main

Licencia

Este proyecto se publica bajo licencia MIT. Consulta raceTelemetryAi/LICENSE.

Créditos y referencias

About

Coach de Telemetría de Carreras con IA. Este dashboard analiza datos de carrera simulados usando la API de Google Gemini para ofrecer a los pilotos consejos prácticos y feedback detallado sobre su rendimiento. Creado con React, TypeScript y Tailwind CSS.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

2 tags

Packages

 
 
 

Contributors

Languages

Generated from google-gemini/aistudio-repository-template