🇬🇧 English | 🇮🇹 Italiano | 🇩🇪 Deutsch

---

🚗 Cyberpandino Cluster - PandaOS

Quadro strumenti digitale per Fiat Panda 141 basato su Arduino / Raspberry Pi 4B.

📋 Descrizione

Sistema completo di quadro strumenti digitale che sostituisce la strumentazione analogica originale della Fiat Panda 141. Il sistema si interfaccia con la centralina tramite protocollo OBD-II (ELM327) e legge le spie luminose tramite optoaccoppiatori collegati ai pin GPIO dell'Arduino / Raspberry Pi.

Caratteristiche Principali (v0.9.0)

• ✅ Lettura dati OBD-II: Velocità, giri motore, temperatura, pressione olio, etc.
• ✅ Rilevamento spie veicolo: Abbaglianti, anabbaglianti, frecce, livello olio, etc.
• ✅ Sensori esterni:
• Temperatura esterna (DS18B20)
• Livello carburante (ADS1115)
• ✅ Gestione quadro accensione: Sistema di power-saving automatico
• ✅ Interfaccia moderna: Dashboard 3D con modello Panda interattivo
• ✅ Modalità demo: Per sviluppo senza hardware

---

📸 Anteprima

Dashboard Principale

Il cluster digitale sostituisce completamente il quadro strumenti analogico originale con un'interfaccia moderna e personalizzabile.

Dashboard principale con modello 3D interattivo

---

🗺️ Feature Future

Scopri cosa stiamo pianificando: Roadmap & Wishlist

Alcune idee in lista: - 📹 Retrocamera e sensori parcheggio - 🚪 Animazioni 3D avanzate (portiere, luci) - 🎨 Dashboard e temi personalizzabili - 🌍 Internazionalizzazione - 📱 App mobile companion - E molto altro!

Vuoi contribuire? Ogni aiuto è benvenuto! Vedi la guida per contribuire.

---

📚 Indice della Documentazione

🚀 Inizia Qui

• Quick Start - Guida rapida per iniziare subito
• Hardware - Lista completa componenti e schema di montaggio

📖 Documentazione Tecnica

• Architettura - Architettura dettagliata del sistema
• Documentazione Generale - Overview completa del progetto
• Configurazione Client - Setup e configurazione frontend
• Configurazione Server - Setup e configurazione backend
• Configurazione Environment - Variabili d'ambiente e parametri

🤝 Contribuzione

• Come Contribuire - Guida completa per contribuire al progetto

📋 Altro

• Roadmap - Piano di sviluppo e wishlist
• Autori - Chi ha contribuito al progetto
• Licenza - GNU General Public License v3.0

---

⚠️ Disclaimer

PandaOS è un progetto hobbistico e sperimentale, nato per curiosità tecnica e spirito di avventura digitale. Non è un prodotto certificato, non è pensato per la produzione e non ha alcuna pretesa di rispettare standard industriali, automotive o galattici.

Tutto il materiale presente in questo repository, inclusi codice, guide, schemi e idee più o meno sensate, è fornito "AS IS", senza garanzie di funzionamento, affidabilità o compatibilità con l'impianto elettrico della vostra eroica utilitaria.

Gli autori e i contributori non si assumono alcuna responsabilità in caso di:

• guasti elettrici o elettronici
• comportamenti anomali del veicolo
• cortocircuiti imprevisti
• danni a persone, cose, animali e simili
• qualsiasi effetto collaterale derivante dall'uso del software o dal seguire le istruzioni presenti in questa documentazione

L'utilizzo di PandaOS su veicoli in circolazione o in qualsiasi contesto in cui potrebbero essere richiesti requisiti di conformità, omologazione o buon senso è fortemente sconsigliato. Qualsiasi installazione o sperimentazione avviene a rischio esclusivo dell'utente, che si assume ogni responsabilità in merito alle conseguenze tecniche e pratiche delle proprie scelte.

---

🏗️ Architettura

Il progetto è composto da tre moduli principali:

cluster/
├── client/          → Interfaccia grafica (React + Vite + Electron)
├── server/          → Backend comunicazione OBD-II e GPIO (Node.js)
└── main.js          → Wrapper Electron per desktop app

Tecnologie Utilizzate

• Frontend: React 18, TypeScript, Three.js, Socket.IO Client
• Backend: Node.js, Socket.IO Server, SerialPort, GPIO (onoff)
• Desktop: Electron 36
• Hardware: Raspberry Pi 4B, ELM327, DS18B20, ADS1115

🤔 Ma React + Electron su un Automotive?! Siete Pazzi?

Sì, lo sappiamo. Qualsiasi ingegnere embedded che vede questo progetto probabilmente sta avendo un attacco di panico.

Come andrebbero fatte le cose per bene: - C/C++ - Perché JavaScript su un'auto è come mettere le ruote quadrate - Qt/QML - Lo standard dell'industria (Tesla, Audi, BMW lo usano) - Yocto/Buildroot - Linux embedded serio, non Raspberry Pi OS con tutto il ciarpame - Direct framebuffer - Non Electron che gira un intero browser per mostrare 4 numeri

E allora perché React/Electron/Node.js?

Perché è un progetto hobbistico e vogliamo divertirci, non impazzire.

Pro del nostro approccio discutibile: - ⚡ Veloce da sviluppare - Hai visto Three.js? Fai un modello 3D in 5 minuti. Prova con OpenGL nativo. - 🎨 Librerie ovunque - npm ha tutto. C++ ha... ehm... boost? - 🧑‍💻 Accessibile - Sai React? Benvenuto. Sai CMake? Condoglianze. - 🐛 Debug - F12 e vedi tutto. GDB invece è... un'esperienza. - 🚀 Divertimento - Più tempo a smanettare, meno a lottare con toolchain - 💡 Prova il concetto - Funziona? Bene! Poi si vedrà.

Contro (che accettiamo consapevolmente): - 💾 Mangia RAM come fosse pasta (~500MB vs ~50MB) - 🐌 Boot lento (~30s vs ~3s) - ma con modalità standby sempre acceso diventa istantaneo - 🔋 Consuma più di quanto dovrebbe (ma standby consuma solo 0.4W, trascurabile) - 📊 JavaScript - Sì, JavaScript. Su un'auto. Deal with it.

Il punto è: Stiamo parlando di una Panda del 1990. Non è un F-35. Non deve andare sulla Luna.
Deve mostrarti i giri motore in modo figo mentre ascolti i Pink Floyd. E questo lo fa benissimo. 🚗💨

💡 Vuoi rifarlo in C++/Qt "come si deve"? Fantastico! Saremmo curiosi di vedere un port nativo e ti aiuteremmo volentieri.

---

⚙️ Requisiti di Sistema

Prerequisiti Software

Software	Versione Minima	Consigliata
Node.js	18.0.0	20.x LTS
npm	9.0.0	10.x
Git	2.0+	Latest

# Verifica rapida
node --version  # >= v18.0.0
npm --version   # >= 9.0.0
git --version   # >= 2.0.0

⚠️ Raspberry Pi: Non usare apt install nodejs (versione obsoleta). Vedi CONFIGURAZIONE_SERVER.md per NodeSource/nvm.

---

Per Raspberry Pi (Produzione)

• Hardware:
• Raspberry Pi 4B (4GB o superiore consigliato) o Raspberry Pi 5
• Adattatore ELM327 USB (porta seriale /dev/ttyUSB0)
• Optoaccoppiatori per rilevamento spie (PC817 o simili)
• Display LCD ultra-wide (1920×480 consigliato)
• Sensore temperatura DS18B20 (opzionale)
• Convertitore ADC ADS1115 (opzionale, per sensore carburante)

Raspberry Pi 3 Model B+: Funziona in modalità Headless (solo server)
📋 Lista completa hardware: Vedi HARDWARE.md per dettagli su tutti i componenti necessari

• Sistema Operativo:
• Raspberry Pi OS Lite (64-bit) - Debian-based consigliato
• Boot time: ~30s (ottimizzabile a ~20s, o istantaneo con modalità standby)
• Architettura ARM/ARM64

📘 Scelta OS e Boot Time: Vedi CONFIGURAZIONE_SERVER.md per dettagli su come scegliere la distro giusta, ottimizzare il boot time e configurare la modalità standby sempre acceso (consumo trascurabile, avvio istantaneo)

• Software: Vedi CONFIGURAZIONE_SERVER.md per istruzioni installazione su Raspberry Pi

Per Sviluppo Locale (Mac/Windows/Linux)

• Node.js 18+ (20 LTS consigliato)
• npm 9+ (10.x consigliato)
• Git 2.0+

💡 Setup Veloce: Vedi istruzioni installazione nella sezione Prerequisiti Software sopra

⚠️ NOTA: Eseguendo il progetto su sistemi non-Raspberry Pi, il server fallirà all'avvio per mancanza di dipendenze hardware specifiche (GPIO, sensori, porta seriale OBD). È possibile usare la modalità mock nel client per sviluppo senza server.

---

🚀 Setup del Progetto

1. Clonare il Repository

git clone https://github.com/cyberpandino/cluster
cd cluster

2. Installare le Dipendenze

Il progetto fornisce uno script di installazione che configura tutte le dipendenze:

npm run install:all

Questo comando installa le dipendenze per: - Root (Electron + concurrently) - Client (React + dipendenze frontend) - Server (Node.js + dipendenze hardware)

3. Configurazione

a) Configurazione Client

Modifica il file di configurazione client:

File: client/src/config/environment.ts

export const environment: EnvironmentConfig = {
  websocket: {
    url: 'http://127.0.0.1:3001',  // URL del server WebSocket
    mock: true,                      // true = modalità demo | false = connessione reale
    reconnectionAttempts: 3,
    reconnectionDelay: 1000,
    timeout: 5000,
  },
  debug: {
    enabled: true,                   // Abilita debug mode
    showConsoleViewer: true,         // Mostra console viewer (tasto 'd')
  },
  app: {
    name: "PandaOS Cluster",
    version: "0.9.0",
    locale: "it",
    timezone: "Europe/Rome",
    timeFormat: "24h",
  },
};

Parametri Chiave: - websocket.url: Indirizzo del server WebSocket (default: http://127.0.0.1:3001) - websocket.mock: - true = Modalità demo con animazioni simulate (per sviluppo locale) - false = Connessione reale al server (per produzione su Raspberry Pi) - debug.enabled: Abilita funzionalità di debug - debug.showConsoleViewer: Mostra console viewer (attivabile con tasto d)

b) Configurazione Server

Modifica il file di configurazione GPIO e sensori:

File: server/config/gpio-mapping.js

Vedi la sezione Configurazione GPIO per i dettagli completi.

---

🎯 Avvio del Progetto

Modalità Completa (Raspberry Pi)

Avvia client, server ed Electron contemporaneamente:

npm start

Questo comando esegue: 1. Server OBD-II sulla porta 3001 2. Client React/Vite sulla porta 5173 3. Electron desktop app

Modalità Sviluppo (Locale senza Raspberry)

Opzione 1: Solo Client (Modalità Mock)

1. Assicurati che websocket.mock = true in client/src/config/environment.ts
2. Avvia solo il client:

npm run client

L'applicazione sarà disponibile su http://localhost:5173 con dati simulati.

Opzione 2: Client + Electron

npm run client    # In un terminale
npm run electron  # In un altro terminale

Comandi Individuali

# Solo server (richiede Raspberry Pi)
npm run server

# Solo client
npm run client

# Solo Electron (attende client su porta 5173)
npm run electron

---

🔌 Configurazione GPIO e Sensori

Mappatura GPIO per Spie Veicolo

Il file server/config/gpio-mapping.js contiene la mappatura completa dei pin GPIO.

📘 Schema Elettrico Veicolo: Per identificare i cavi corretti delle spie sul quadro originale della Panda, consulta lo Schema Elettrico Ufficiale Fiat Panda 141 con tutti i codici colore e le connessioni.

Pin Utilizzati

Spia/Funzione	Pin GPIO (BCM)	Descrizione
Frecce	17	Indicatori di direzione
Alternatore	27	Carica batteria
Pressione olio	22	Pressione olio motore
Sistema frenante	23	Freni
Iniettori	24	Sistema iniezione
Quadro acceso (KEY)	25	Chiave inserita
Abbaglianti	5	Fari abbaglianti
Anabbaglianti	6	Fari anabbaglianti
Quattro frecce	12	Luci emergenza
Fendinebbia	13	Fendinebbia posteriore
Temperatura raffreddamento	16	Liquido refrigerante
Termoresistenza lunotto	19	Sbrinatore lunotto
Riserva carburante	20	Livello carburante basso
Ignition (quadro)	21	Rilevamento quadro acceso/spento

Configurazione Optoaccoppiatori

config: {
  mode: 'BCM',              // Numerazione Broadcom GPIO
  pullMode: 'PUD_DOWN',     // Resistenza pull-down interna
  debounceTime: 50,         // Filtro anti-rimbalzo (ms)
  pollingInterval: 100,     // Frequenza lettura GPIO (ms)
}

Logica di Funzionamento: - HIGH (1) = Spia accesa - LOW (0) = Spia spenta

Gestione Quadro Accensione (Ignition)

```javascript ignition: { enabled: true, pin: 21, // Pin GPIO dedicato activeOn: 0, // 0 = active low | 1 = active high scripts: { lowPower: './scripts/low-power.sh', // Eseguito quando quadro si spe