ChainSense2 è un progetto sviluppato durante un tirocinio per acquisire, validare, memorizzare e visualizzare dati provenienti da un dispositivo Chain2Gate.
Il sistema utilizza un ESP32 come interfaccia hardware: il firmware comunica con Chain2Gate tramite UART, gestisce lo scambio delle Compact Frame CF3 e CF21, mostra lo stato su un display OLED e inoltra i dati al computer in formato JSON. Sul computer, una serie di script Python salva le misure in un database SQLite e le rende consultabili tramite una dashboard Streamlit.
Chain2Gate
│
│ UART 115200 baud, 8N1
▼
ESP32 ───► display OLED
│
│ USB seriale / JSON
▼
serial_reader.py
│
▼
storage.py ───► python/data/chainsense.db
│
▼
dashboard.py
│
▼
dashboard Streamlit
- comunicazione seriale tra ESP32 e Chain2Gate;
- macchina a stati per la gestione ordinata del protocollo;
- invio della Compact Frame CF3;
- ricezione e validazione della Compact Frame CF21;
- gestione delle risposte ACK e NACK;
- visualizzazione dello stato operativo su display OLED;
- invio dei dati acquisiti al computer in formato JSON;
- lettura continua della porta seriale tramite Python;
- persistenza delle acquisizioni in un database SQLite;
- dashboard web realizzata con Streamlit e pandas;
- esecuzione opzionale della sola dashboard tramite Docker Compose.
- scheda di sviluppo ESP32;
- dispositivo Chain2Gate;
- display OLED I²C;
- collegamento USB tra ESP32 e computer;
- collegamenti UART e massa comune tra ESP32 e Chain2Gate.
| Funzione | ESP32 | Dispositivo collegato |
|---|---|---|
| UART RX | GPIO 16 | TX Chain2Gate |
| UART TX | GPIO 17 | RX Chain2Gate |
| I²C SDA | GPIO 21 | SDA OLED |
| I²C SCL | GPIO 22 | SCL OLED |
| Riferimento elettrico | GND | GND Chain2Gate e OLED |
Prima dell'accensione verificare i livelli logici e il pinout della specifica versione hardware di Chain2Gate. TX e RX devono essere incrociati e i dispositivi devono condividere la massa.
La comunicazione ESP32–Chain2Gate usa i seguenti parametri:
- velocità: 115200 baud;
- formato: 8N1 (8 bit dati, nessuna parità, 1 bit di stop);
- controllo di flusso: non previsto.
Il firmware è organizzato come una macchina a stati. In sintesi:
- inizializza UART e display OLED;
- prepara e invia una Compact Frame CF3;
- attende la risposta del dispositivo;
- interpreta ACK o NACK;
- riceve la Compact Frame CF21;
- controlla struttura, lunghezza e validità della frame;
- estrae i dati utili e li pubblica sulla seriale USB in formato JSON;
- aggiorna l'OLED e torna nello stato di attesa o ripete l'operazione in caso di errore.
La separazione in stati evita attese bloccanti e rende più chiara la gestione di timeout, frame incomplete e risposte non valide.
Le acquisizioni vengono inviate dall'ESP32 al computer come oggetti JSON, uno per riga. Questo permette a serial_reader.py di distinguere i messaggi diagnostici dai record validi, decodificare i dati e passarli al livello di persistenza.
Il contenuto effettivo del record dipende dai campi estratti dalla CF21. In forma generale:
{
"tipo_frame": "CF21",
"stato": "valida",
"dati": {}
}ChainSense2/
├── docs/
│ └── ChainSense2V3_manualeTecnico.pdf
├── firmware/
│ └── src/
│ └── main.cpp
├── python/
│ ├── dashboard.py
│ ├── serial_reader.py
│ ├── storage.py
│ ├── test_database.py
│ └── data/
│ └── chainsense.db # creato durante l'utilizzo
├── Dockerfile
├── compose.yaml
├── requirements.txt
└── README.md
Il manuale tecnico completo è disponibile in docs/ChainSense2V3_manualeTecnico.pdf.
Il firmware si trova in firmware/src/main.cpp ed è sviluppato per l'ambiente PlatformIO.
- Visual Studio Code;
- estensione PlatformIO IDE, oppure PlatformIO Core da riga di comando;
- driver USB della scheda ESP32, se richiesto dal sistema operativo.
- Aprire il progetto firmware con PlatformIO.
- Collegare l'ESP32 al computer tramite USB.
- Selezionare la scheda e la porta seriale corrette.
- Compilare il firmware.
- Caricarlo sull'ESP32.
- Aprire il monitor seriale alla velocità prevista dalla configurazione del firmware.
Con PlatformIO Core, dalla directory del progetto firmware:
pio run
pio run --target upload
pio device monitorÈ consigliato Python 3 con un ambiente virtuale.
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txtIl file requirements.txt, nella root del repository, contiene:
streamlit
pandas
pyserial
Collegare l'ESP32 al computer, verificare la porta seriale configurata nello script e avviare:
python python/serial_reader.pyserial_reader.py riceve le righe JSON prodotte dal firmware e utilizza storage.py per inizializzare e aggiornare il database.
Il database viene creato nel percorso:
python/data/chainsense.db
Sia storage.py sia dashboard.py costruiscono questo percorso a partire dalla directory del rispettivo file:
Path(__file__).resolve().parent / "data" / "chainsense.db"In questo modo l'acquisizione e la dashboard fanno riferimento allo stesso database indipendentemente dalla directory dalla quale vengono avviate.
Per verificare separatamente la creazione e l'accesso al database:
python python/test_database.pyDopo aver installato le dipendenze e creato il database:
streamlit run python/dashboard.pyStreamlit mostra nel terminale l'indirizzo locale della dashboard, normalmente:
http://localhost:8501
La dashboard legge python/data/chainsense.db, elabora i dati con pandas e presenta le acquisizioni in forma consultabile.
Il repository include un Dockerfile e un file compose.yaml per eseguire la dashboard in un container.
Il Dockerfile copia python/dashboard.py in:
/app/dashboard.py
La dashboard cerca quindi il database in /app/data/chainsense.db. Docker Compose collega a tale directory il database presente sul computer:
volumes:
- ./python/data:/app/data:roIl suffisso :ro rende il database accessibile al container in sola lettura. La porta è pubblicata soltanto sull'interfaccia locale:
ports:
- "127.0.0.1:8501:8501"Quando Docker è disponibile, la dashboard può essere costruita e avviata dalla root del repository con:
docker compose up --buildQuindi può essere aperta all'indirizzo http://127.0.0.1:8501.
La cartella
python/data/e il databasechainsense.dbdevono esistere prima dell'avvio del container. Docker non è installato sul laptop usato per lo sviluppo: la configurazione è stata predisposta, ma non è ancora stata verificata in esecuzione su tale macchina.
Il progetto comprende:
- firmware ESP32 per la comunicazione con Chain2Gate;
- gestione CF3, CF21, ACK/NACK e validazione delle frame;
- uscita JSON sulla seriale USB;
- acquisizione e persistenza tramite Python e SQLite;
- dashboard Streamlit;
- configurazione Docker della dashboard;
- manuale tecnico V3.
Il lavoro è in fase di sviluppo e validazione. In particolare, l'esecuzione tramite Docker resta da provare su un sistema dotato di Docker.
Per la descrizione dettagliata dell'hardware, del protocollo, della macchina a stati, del formato delle frame e delle prove svolte, consultare il manuale tecnico V3.
Mattia
Progetto realizzato nell'ambito di un tirocinio.
Il codice sorgente di ChainSense2 è distribuito sotto licenza MIT. Per maggiori informazioni, consultare il file LICENSE.
Il progetto è stato sviluppato da Mattia Floriani durante il tirocinio formativo presso Cinetix Group nel 2026.