Open-source hardware

Tholus Flow

Sensore open-source per people counting e proximity detection basato su ESP32 + VL53L8CH. La pagina raccoglie hardware, componenti, assembly, firmware, commissioning e riferimenti essenziali per pubblicazione e replicabilità.

Scarica firmware Vai al flashing Scarica Arduino IDE
Categoria
Open-source sensor node
Stack
ESP32 + VL53L8CH
Use case
People counting e proximity detection
Firmware
v2.0.1

Reference build concreta

Componenti facili da reperire, flashing semplice e documentazione pronta per chi deve replicare davvero il nodo.

Configurazione sul device

Wi-Fi, threshold, ROI e counting line vengono salvati localmente sul sensore per una manutenzione più semplice.

Pensato per il campo

Provisioning AP, calibrazione live e commissioning da scena reale per ingressi, passaggi e installazioni permanenti.

Board ESP32 Type-C CP2102
Board ESP32 Type-C con CP2102, usata per flashing, seriale e gestione del firmware.
Breakout board del sensore VL53L8CH con strip di pin
Modulo breakout del VL53L8CH: sensore ToF 8×8 multizone scelto per versatilità e dati CNH.
Connettore USB-C panel mount waterproof a due fili
Ingresso alimentazione del box finale: solo power, utile per un case ordinato e chiuso.
Box ABS waterproof 100x68x50 millimetri
Box ABS 100 × 68 × 50 mm usato come riferimento per la build pubblicata.
Firmware reference build Scarica direttamente il file `.ino` pubblicato sul sito. Arduino IDE ufficiale Toolchain minima per compilare, caricare e verificare la build. Flow di commissioning Apri subito la sequenza consigliata per pairing, rete e taratura.

Overview

Una reference platform pensata per essere replicabile.

Tholus Flow è stato progettato come nodo sensore replicabile, economico e semplice da assemblare. La configurazione operativa vive sul device, mentre il firmware viene caricato via Arduino IDE e poi gestito tramite applicazione o API di rete.

L’obiettivo è pubblicare non solo il codice, ma il flusso completo: scelta dei componenti, note di sourcing, assembly, wiring, flashing e commissioning reale all’ingresso o nel passaggio da monitorare.

Replicabilità con componenti facili da reperire Versatilità del sensore 8×8 per usi futuri Manutenibilità del flashing e della calibrazione Documentazione pronta per sito e supporto

Architettura

Nodo compatto, bus I²C semplice, alimentazione separata.

Power input USB-C panel mount 2 fili, solo alimentazione
Main board ESP32 + CP2102 USB nativa per flash e seriale
Sensor bus I²C su GPIO 21/22 Wire.begin(21, 22)
Optical sensing VL53L8CH 8×8 ToF People counting e presenza

La board ESP32 con bridge CP2102 è stata scelta per comodità di sviluppo e flashing, mentre il VL53L8CH aggiunge al semplice ranging una maggiore versatilità grazie al sensore multizone 8×8 e ai dati CNH, utili anche per use case futuri.

Bill of materials

BOM raccomandata per la build di riferimento.

Componente Qtà Source Search / reference Note di progetto
ESP32 Development Board Type-C CP2102 WiFi 1 AliExpress ESP32 CP2102 Type-C board Scelta per flashing semplice, accesso seriale e buona compatibilità pratica su Mac; consigliata con header già saldati.
VL53L8CH breakout board + pin strip 1 AliExpress VL53L8CH module board Sensore ToF 8×8 multizone; se non arriva preassemblato richiede la saldatura dei pin.
24AWG Dupont jumper wires 1 kit AliExpress 10 cm / 20 cm kit Servono abbastanza cavi female-to-female per collegare le due board con header maschi.
USB-C panel-mount waterproof connector, 2 wires 1 AliExpress USB-C waterproof panel mount 2pin Ingresso alimentazione del box. Solo power, non trasporta dati USB.
Waterproof ABS enclosure 100 × 68 × 50 mm 1 AliExpress ABS waterproof enclosure 100x68x50 La misura corretta è in millimetri e rappresenta il volume utile del box finale.

Wiring

Connessioni logiche prima della chiusura del box.

Riferimento Uso Nota di implementazione
ESP32 GPIO 21 → sensor SDA I²C data Il firmware usa `Wire.begin(21, 22)`. Verificare sempre il pinout del breakout acquistato.
ESP32 GPIO 22 → sensor SCL I²C clock Mantenere i fili corti e ordinati per ridurre rumore e letture instabili.
ESP32 3V3 / corretto VIN → sensor power Power sensor Alcuni breakout espongono VIN, altri 3V3. Non inviare 5 V a schede che non lo supportano.
ESP32 GND → sensor GND Common ground Serve una massa condivisa pulita tra sensore, board e alimentazione.
USB-C panel red wire → ESP32 5V / VIN Power enclosure Il connettore a 2 fili alimenta il box finale, non viene usato per flashing o dati USB.
USB-C panel black wire → ESP32 GND Power enclosure Programmare il dispositivo dalla USB nativa della board prima della chiusura finale del box.
Flow consigliato: flash del firmware, test del sensore in aria libera, cablaggio finale, test nel box, installazione sul sito reale.

Assembly

Montaggio e packaging con attenzione alla scena reale.

La build di riferimento nasce per essere semplice da assemblare, ma il risultato dipende molto da come viene chiuso il box, fissato il sensore e mantenuta pulita la finestra ottica. Qui conviene essere pratici più che eleganti.

  • Programmare e testare la board sul banco prima di chiudere il box definitivo.
  • Se il sensore lavora dietro una finestra, mantenere l’apertura ottica pulita e poco incassata.
  • Evitare tunnel profondi davanti al sensore, perché restringono inutilmente il field of view.
  • Bloccare il sensore in modo stabile e perpendicolare al passaggio con distanziali, staffe o biadesivo tecnico.
  • Se l’uso è davvero outdoor, la tenuta dipende dalla qualità di foratura e sigillatura del box e del connettore.
Box ABS waterproof 100x68x50 millimetri
Box ABS 100 × 68 × 50 mm usato come riferimento per la build pubblicata.

Firmware

Funzioni core già incluse nella reference build.

  • configurazione persistente sul device per Wi-Fi, threshold, ROI e tracking
  • access point iniziale per provisioning e commissioning
  • pairing con setup code e token amministrativo per le operazioni in scrittura
  • stream live della matrice 8×8 via WebSocket
  • HTTP API per stato, configurazione, Wi-Fi provisioning e restart
  • blob tracking e line crossing per eventi IN / OUT
  • upload eventi verso backend o cloud, mantenendo la calibrazione direttamente sul sensore

Flashing

Installazione firmware con Arduino IDE.

Toolchain essenziale

Per rendere la pagina utile davvero, qui trovi sia il download del firmware sia il link diretto all’ambiente ufficiale usato per compilarlo e caricarlo.

Scarica Arduino IDE Scarica firmware
  1. Installare una versione aggiornata di Arduino IDE.
  2. Aggiungere nelle preferenze l’URL del package manager Espressif ESP32.
  3. Installare da Boards Manager il pacchetto “esp32 by Espressif Systems”.
  4. Selezionare una board compatibile con l’hardware in uso; nella maggior parte dei casi “ESP32 Dev Module” è il punto di partenza più pratico.
  5. Installare le librerie richieste: ArduinoJson, arduinoWebSockets (Links2004) e STM32duino VL53L8CH.
  6. Collegare l’ESP32 via USB-C alla porta nativa della board.
  7. Aprire il file firmware, verificare porta seriale e board selezionata, quindi compilare e caricare.
  8. Se l’upload su Mac è instabile, riprovare con upload speed più conservativa, per esempio 115200.
Provisioning AP: durante la prima configurazione il nodo espone un SSID del tipo `TholusFlow-XXXX`. La password di accesso segue la regola `TF-<setup code>`.

Boards Manager

esp32 by Espressif Systems

Fornisce core, WiFi, WebServer, Preferences, ESPmDNS, HTTPClient e toolchain di upload.

Library Manager

ArduinoJson

Usata per payload JSON e configurazione.

Library Manager

arduinoWebSockets (Links2004)

Gestisce lo stream live via WebSocket.

Library Manager

STM32duino VL53L8CH

Driver Arduino per il sensore ToF VL53L8CH.

Commissioning

Primo avvio, pairing e taratura.

  1. Accendere il nodo e controllare in seriale MAC address e nome nodo; tenere a portata setup code ed etichetta di provisioning.
  2. Associare il sensore dall’app o dallo strumento di provisioning.
  3. Impostare SSID, password Wi-Fi e parametri cloud.
  4. Attendere che il nodo ricompaia sulla LAN.
  5. Aprire la schermata di calibrazione, verificare la matrice live e regolare threshold, ROI e counting line nel contesto reale di installazione.
Per uso people-counting su ingresso è preferibile montare il sensore rivolto verso il basso, con vista pulita sul passaggio, quindi regolare counting line, ROI e threshold direttamente sulla scena reale.

Checklist

Cose da non dimenticare prima dell’installazione.

  • abbastanza cavi female-to-female per collegare ESP32 e breakout del sensore
  • stagno, punta fine e attrezzi per saldare gli header del VL53L8CH
  • alimentatore 5 V stabile e cavo USB-C esterno
  • metodo di fissaggio interno: distanziali, standoff, biadesivo tecnico o staffa 3D
  • finestra ottica o cover pulita davanti al sensore, se richiesta dal box
  • etichetta esterna con seriale / MAC / setup code per supporto e commissioning

Riferimenti

Essential technical references.

Arduino IDE — download ufficiale Silicon Labs — CP210x USB to UART Bridge VCP Drivers Espressif — Arduino-ESP32 Getting Started / installation STM32duino — VL53L8CH Arduino library STMicroelectronics — VL53L8CH product page STMicroelectronics — VL53L8CH datasheet (PDF)

FAQ

Domande frequenti per chi consulta o riusa il progetto.

C’è qualcosa da considerare prima di usare il firmware in campo?

Sì. La build pubblicata non usa più una password AP statica: la password di provisioning è univoca per device e segue la regola `TF-<setup code>`. I log seriali mostrano i valori sensibili solo in forma mascherata.

Perché è stato scelto il VL53L8CH?

Perché combina un FoV più controllabile del VL53L7CH con i dati CNH, utili per scenari futuri oltre al semplice people counting: gesture sensing, presence detection e classificazioni più evolute.

Qual è il flusso corretto di assemblaggio?

Flash del firmware, test del sensore in aria libera, cablaggio finale, test nel box, installazione e calibrazione sul sito reale.