obd2_gauge/README.md

# Cluster Digital OBD-II ESP32 CYD (Ford Ka Endura 1.3)

Instrumento digital automotriz de alta precisión basado en la placa **ESP32 CYD (ESP32-2432S028)** con pantalla táctil resistiva TFT de 2.8" (320x240). Se comunica de forma inalámbrica vía Bluetooth SPP con un escáner **ELM327 v1.5** conectado al puerto OBD-II del vehículo.

El sistema fue diseñado y calibrado a medida para el motor **Ford Ka Endura-E 1.3** (y es compatible con instalaciones de GNC).

---

## Características Principales

### 1. Cuadrante de 4 Instrumentos Simultáneos
* **Temperatura de Refrigerante (PID 0105):** Rango 60°C a 120°C. Color dinámico (verde en rango normal, amarillo de advertencia y rojo a partir de 110°C con alarma sonora y visual).
* **Velocidad del Vehículo (PID 010D):** Rango 0 a 160 km/h.
* **Revoluciones por Minuto (PID 010C):** Rango 0 a 6.000 RPM.
* **Voltaje de Batería (Comando ATRV):** Rango 10.0V a 16.0V en tiempo real directo del borne del ELM327.

### 2. Modo Pantalla Completa (Full Screen)
* Tocando cualquier cuadrante, la pantalla se expande a vista completa para ese parámetro.
* Escala curvada de 20 bloques con **antialiasing de subpíxel** para bordes ultra suaves sin efecto serrucho.
* Tipografía digital retrofuturista **DSEG7 Modern 80pt** con coma decimal integrada y actualización veloz sin parpadeo (*flicker-free*).
* Alarma visual sincronizada: el icono, el arco y el título parpadean en rojo de forma simultánea ante sobretemperatura o sobretensión.

### 3. Badge Táctico de Máxima Eficiencia `[ ECO ]`
* Calcula en tiempo real el punto óptimo de funcionamiento y entrega de torque (Sweet Spot) para el Ford Ka Endura 1.3:
  * **RPM:** Entre 1.900 y 2.550 RPM (pico de par motor y mejor rendimiento volumétrico).
  * **Carga de Motor (PID 0104 en segundo plano):** Entre 45% y 82% (apertura de mariposa con mínimas pérdidas por bombeo, antes del enriquecimiento a plena carga).
* **Diseño táctico:** Pastilla rectangular con bordes redondeados en verde esmeralda brillante (`[ ECO ]`) que se ilumina en el cuadrante de RPM y en el encabezado de pantalla completa.
* Al salir del rango óptimo, se apaga de inmediato restaurando de forma invisible el degradado del fondo.

### 4. Audio y Melodías de Alarma
* Control de volumen independiente: Silencio, Ultra Bajo, Bajo (Casio suave), Medio y Alto.
* Selector de sonidos y tonos de alarma:
  * Chime BMW (doble tono sincronizado).
  * Casio Digital (doble chirp suave no invasivo).
  * Tono bitonal clásico.
  * Alarma continua urgente.

### 5. Menú de Configuración Táctil
* **Gestión de Alarmas:** Conmutadores táctiles independientes ON/OFF para cada parámetro con guardado persistente en NVS (Preferences).
* **Temas Visuales:** 6 paletas de color con degradados ambientales de fondo (*Cyan, Emerald, Amber, Violet, Ice Blue, Graphite*).
* **Brillo Automático:** Regulación inteligente mediante sensor de luz ambiente (LDR) integrado en la placa, o selección manual (5% a 100%).
* **Auto-Sleep:** Apagado automático de pantalla y suspensión ligera al detener el motor (RPM <= 300) tras el tiempo configurado (30s, 1m, 2m, 5m u OFF).

---

## Hardware Requerido

1. **Placa ESP32 CYD 2.8" (ESP32-2432S028):**
   * Pantalla TFT 320x240 con controlador ILI9341 / ST7789.
   * Pantalla táctil resistiva con controlador XPT2046.
   * Sensor de luz LDR en pin analógico.
   * LED RGB integrado.
2. **Escáner OBD-II Bluetooth:**
   * Adaptador ELM327 v1.5 (muy recomendado con chip PIC18F25K80, evitar clones v2.1 de baja calidad).
3. **Buzzer / Parlante:**
   * Parlantito o buzzer pasivo de 8 ohms conectado al pin de audio del CYD (controlado por canal PWM con modulación de volumen).
4. **Alimentación:**
   * Módulo convertidor 12V a 5V USB (conectado a positivo bajo llave o directo si se utiliza auto-sleep).

---

## Compilación y Carga de Firmware

El proyecto se encuentra preparado para compilarse tanto con `arduino-cli` como con Arduino IDE:

### Requisitos de Software
* **ESP32 Arduino Core:** Versión 2.0.17 (las ramas 3.x no son compatibles con el esquema de partición).
* **Librería TFT_eSPI:** 2.5.43 o superior con la configuración de pines del CYD.
* **Esquema de Partición:** `huge_app` (3MB APP / No OTA / LittleFS).

### Compilación desde Terminal
```bash
arduino-cli compile -b esp32:esp32:esp32:PartitionScheme=huge_app sketch/obd2_gauge
```

### Carga al Dispositivo
```bash
arduino-cli upload -p /dev/ttyUSB0 --fqbn esp32:esp32:esp32:PartitionScheme=huge_app sketch/obd2_gauge
```

---

## Emulador de Pruebas Bluetooth en Banco

En la carpeta `emulator/` se incluye el script `obd2_emulator.py` para simular un adaptador ELM327 v1.5 y la ECU del auto en Linux vía Bluetooth SPP:

### Modo ECO Fijo (Recomendado para calibración visual)
Mantiene los parámetros fijados en el punto dulce (2.250 RPM, 58% carga, 14.2V, 90°C) con el badge `[ ECO ]` permanentemente encendido:
```bash
python3 emulator/obd2_emulator.py --eco
```

### Modo Ciclo de Demostración
Ejecuta un ciclo dinámico de 36 segundos que incluye batería baja, ralentí, 10 segundos continuos en crucero ECO, aceleración exigida y fondo de escala con alarmas:
```bash
python3 emulator/obd2_emulator.py
```

*Nota: Mientras el emulador corre en la terminal, podés presionar `e` + Enter para activar el modo ECO fijo o `c` + Enter para volver al ciclo dinámico.*