Hardware open source

Tholus Flow

Capteur open source pour comptage de personnes et détection de proximité basé sur ESP32 + VL53L8CH. Cette page rassemble hardware, composants, assembly, firmware, commissioning et références essentielles pour la publication et la reproductibilité.

Télécharger le firmware Aller au flashing Télécharger Arduino IDE
Catégorie
Nœud capteur open source
Stack
ESP32 + VL53L8CH
Use case
Comptage de personnes et détection de proximité
Firmware
v2.0.1

Build de référence concrète

Composants faciles à trouver, flashing simple et documentation prête pour les équipes qui doivent réellement reproduire le nœud.

Configuration sur le device

Wi-Fi, threshold, ROI et counting line sont enregistrés localement sur le capteur pour une maintenance plus simple.

Pensé pour le terrain

Provisioning AP, calibration live et commissioning sur scène réelle pour entrées, passages et installations permanentes.

Index

Carte ESP32 Type-C CP2102
Carte ESP32 Type-C avec CP2102, utilisée pour le flashing, la sortie série et la gestion du firmware.
Carte breakout du capteur VL53L8CH avec barrette de broches
Module breakout VL53L8CH : capteur ToF multizone 8×8 choisi pour sa polyvalence et les données CNH.
Connecteur USB-C panel mount waterproof à deux fils
Entrée d’alimentation du boîtier final : power only, utile pour un boîtier propre et fermé.
Boîtier ABS waterproof 100x68x50 millimètres
Boîtier ABS 100 × 68 × 50 mm utilisé comme référence pour la build publiée.
Firmware de référence Téléchargez directement le fichier `.ino` publié sur le site. Arduino IDE officiel Toolchain minimale pour compiler, téléverser et vérifier la build. Flux de commissioning Accédez tout de suite à la séquence recommandée pour pairing, réseau et calibration.

Overview

Une plateforme de référence pensée pour être reproductible.

Tholus Flow a été conçu comme un nœud capteur reproductible, économique et simple à assembler. La configuration opérationnelle vit sur le device, tandis que le firmware est chargé via Arduino IDE puis géré via application ou API réseau.

L’objectif est de publier non seulement le code, mais le flux complet : choix des composants, notes de sourcing, assembly, wiring, flashing et commissioning réel à l’entrée ou sur le passage à surveiller.

Reproductibilité avec des composants faciles à trouver Polyvalence du capteur 8×8 pour de futurs cas d’usage Flashing et calibration maintenables Documentation prête pour le site et le support

Architecture

Nœud compact, bus I²C simple, alimentation séparée.

Power input USB-C panel mount 2 fils, alimentation seulement
Main board ESP32 + CP2102 USB native pour flash et série
Sensor bus I²C sur GPIO 21/22 Wire.begin(21, 22)
Optical sensing VL53L8CH 8×8 ToF Comptage et présence

La carte ESP32 avec bridge CP2102 a été choisie pour la facilité de développement et de flashing, tandis que le VL53L8CH apporte plus de souplesse qu’un simple capteur de distance grâce au capteur multizone 8×8 et aux données CNH, utiles aussi pour des cas d’usage futurs.

Bill of materials

BOM recommandée pour la build de référence.

Composant Qté Source Search / reference Notes projet
ESP32 Development Board Type-C CP2102 WiFi 1 AliExpress ESP32 CP2102 Type-C board Choisie pour un flashing simple, l’accès série et une bonne compatibilité pratique sur Mac ; de préférence avec headers déjà soudés.
VL53L8CH breakout board + pin strip 1 AliExpress VL53L8CH module board Capteur ToF multizone 8×8 ; s’il n’arrive pas préassemblé, il faut souder les broches.
24AWG Dupont jumper wires 1 kit AliExpress 10 cm / 20 cm kit Il faut assez de câbles female-to-female pour relier les deux cartes avec des headers mâles.
USB-C panel-mount waterproof connector, 2 wires 1 AliExpress USB-C waterproof panel mount 2pin Entrée d’alimentation du boîtier. Power only, pas de données USB.
Waterproof ABS enclosure 100 × 68 × 50 mm 1 AliExpress ABS waterproof enclosure 100x68x50 La taille correcte est exprimée en millimètres et correspond au volume utile du boîtier final.

Wiring

Connexions logiques avant la fermeture du boîtier.

Référence Usage Note d’implémentation
ESP32 GPIO 21 → sensor SDA I²C data Le firmware utilise `Wire.begin(21, 22)`. Toujours vérifier le pinout du breakout acheté.
ESP32 GPIO 22 → sensor SCL I²C clock Garder les fils courts et propres pour réduire le bruit et les lectures instables.
ESP32 3V3 / VIN correct → sensor power Power sensor Certains breakouts exposent VIN, d’autres 3V3. Ne pas envoyer 5 V à des cartes qui ne le supportent pas.
ESP32 GND → sensor GND Common ground Une masse partagée propre est nécessaire entre capteur, carte et alimentation.
USB-C panel red wire → ESP32 5V / VIN Power enclosure Le connecteur 2 fils alimente le boîtier final et n’est pas utilisé pour le flashing ni les données USB.
USB-C panel black wire → ESP32 GND Power enclosure Programmer le device depuis l’USB natif de la carte avant la fermeture finale du boîtier.
Flow recommandé : flasher le firmware, tester le capteur à l’air libre, finaliser le câblage, tester dans le boîtier puis installer sur le site réel.

Assembly

Montage et packaging pensés pour la scène réelle.

La build de référence veut rester simple à assembler, mais le résultat final dépend beaucoup de la manière dont le boîtier est percé, dont le capteur est fixé et dont l’ouverture optique reste propre. Ici, le choix pratique compte plus que l’élégance.

  • Programmer et tester la carte sur table avant de fermer le boîtier définitif.
  • Si le capteur fonctionne derrière une fenêtre, garder l’ouverture optique propre et peu encaissée.
  • Éviter les tunnels profonds devant le capteur, car ils réduisent inutilement le champ de vision.
  • Fixer le capteur de manière stable et perpendiculaire au passage avec entretoises, supports ou adhésif technique.
  • Si l’usage est vraiment outdoor, l’étanchéité dépend de la qualité du perçage et du scellement du boîtier et du connecteur.
Boîtier ABS waterproof 100x68x50 millimètres
Boîtier ABS 100 × 68 × 50 mm utilisé comme référence pour la build publiée.

Firmware

Fonctions cœur déjà incluses dans la build de référence.

  • configuration persistante sur le device pour Wi-Fi, threshold, ROI et tracking
  • point d’accès initial pour provisioning et commissioning
  • pairing avec setup code et token administrateur pour les opérations en écriture
  • stream live de la matrice 8×8 via WebSocket
  • API HTTP pour statut, configuration, Wi-Fi provisioning et restart
  • blob tracking et line crossing pour événements IN / OUT
  • upload d’événements vers backend ou cloud, tout en gardant la calibration directement sur le capteur

Utilitaire web

Tholus Flow Lite ajoute une couche prête à l’emploi au-dessus du firmware.

Jusqu’ici, le projet mettait à disposition le capteur et le firmware, mais beaucoup de makers devaient encore construire eux-mêmes la couche logicielle. Tholus Flow Lite est un petit utilitaire web qui se connecte au capteur et rend le firmware immédiatement plus exploitable depuis le navigateur.

Il reste volontairement léger : un dashboard pratique pour visualiser les données, tester le nœud plus facilement et partir d’une base déjà utile et hackable pour de petits projets réels.

Ouvrir Tholus Flow Lite sur GitHub
Aperçu animé du dashboard live de Tholus Flow Lite
Un utilitaire web léger pour comptages live, activité à l’entrée et calibration rapide depuis le navigateur.

Ce qu’il fait

  • comptage live des entrées et sorties
  • estimation de l’occupation en cours
  • visualisation live simple de l’activité près de l’entrée
  • graphiques horaires ou journaliers légers
  • historique d’événements basique
  • interface simple pour calibration et réglages

Comment l’utiliser

  1. assembler le capteur et flasher le firmware
  2. connecter le device au réseau ou utiliser le mode setup
  3. ouvrir l’utilitaire dans un navigateur et le connecter au capteur
  4. consulter les données live et les analytics de base
  5. vérifier l’historique et les graphiques sur la scène réelle
  6. ajuster calibration et paramètres si nécessaire
Infrastructure : dans la configuration la plus simple, il suffit d’avoir le capteur sur le réseau local et d’ouvrir l’utilitaire dans un navigateur. Un historique léger peut rester dans le navigateur ou en stockage local, tandis que les intégrations cloud ou base de données comme Supabase sont des extensions optionnelles, pas des prérequis du flux principal.

Idées d’usage

compteur de passage sur une porte suivi d’occupation d’un atelier ou studio monitoring de flux pour événement ou pop-up couche d’entrée pour installation interactive point de départ pour intégrations custom

Flashing

Installation du firmware avec Arduino IDE.

Toolchain essentielle

Pour que la page soit réellement utile, vous pouvez télécharger à la fois le firmware publié et l’environnement officiel utilisé pour le compiler et le téléverser.

Télécharger Arduino IDE Télécharger le firmware
  1. Installer une version à jour d’Arduino IDE.
  2. Ajouter dans les préférences l’URL du package manager Espressif ESP32.
  3. Installer depuis Boards Manager le paquet “esp32 by Espressif Systems”.
  4. Sélectionner une carte compatible avec le hardware utilisé ; dans la plupart des cas “ESP32 Dev Module” est le point de départ le plus pratique.
  5. Installer les bibliothèques requises : ArduinoJson, arduinoWebSockets (Links2004) et STM32duino VL53L8CH.
  6. Connecter l’ESP32 via le port USB-C natif de la carte.
  7. Ouvrir le fichier firmware, vérifier le port série et la carte sélectionnée, puis compiler et téléverser.
  8. Si l’upload sur Mac est instable, réessayer avec une vitesse plus conservatrice, par exemple 115200.
Provisioning AP : lors de la première configuration, le nœud expose un SSID du type `TholusFlow-XXXX`. Le mot de passe suit la règle `TF-<setup code>`.

Boards Manager

esp32 by Espressif Systems

Fournit le core, WiFi, WebServer, Preferences, ESPmDNS, HTTPClient et la toolchain d’upload.

Library Manager

ArduinoJson

Utilisée pour les payloads JSON et la configuration.

Library Manager

arduinoWebSockets (Links2004)

Gère le flux live via WebSocket.

Library Manager

STM32duino VL53L8CH

Driver Arduino pour le capteur ToF VL53L8CH.

Commissioning

Premier démarrage, pairing et calibration.

  1. Allumer le nœud et vérifier en série l’adresse MAC et le nom du nœud ; garder setup code et étiquette de provisioning à portée de main.
  2. Associer le capteur depuis l’app ou l’outil de provisioning.
  3. Configurer SSID, mot de passe Wi-Fi et paramètres cloud.
  4. Attendre que le nœud réapparaisse sur le LAN.
  5. Ouvrir l’écran de calibration, vérifier la matrice live et ajuster threshold, ROI et counting line dans le contexte réel d’installation.
Pour le people-counting en entrée, il est préférable de monter le capteur orienté vers le bas, avec une vue dégagée sur le passage, puis d’ajuster counting line, ROI et threshold directement sur la scène réelle.

Checklist

Points à ne pas oublier avant l’installation.

  • assez de câbles female-to-female pour relier l’ESP32 et le breakout du capteur
  • étain, panne fine et outils pour souder les headers du VL53L8CH
  • alimentation 5 V stable et câble USB-C externe
  • méthode de fixation interne : entretoises, standoffs, adhésif technique ou support 3D
  • fenêtre optique ou protection propre devant le capteur, si le boîtier l’exige
  • étiquette externe avec serial / MAC / setup code pour support et commissioning

Références

Références techniques essentielles.

Tholus Flow Lite - utilitaire web sur GitHub Arduino IDE — téléchargement officiel 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

Questions fréquentes pour celles et ceux qui consultent ou réutilisent le projet.

Y a-t-il quelque chose à considérer avant d’utiliser le firmware sur le terrain ?

Oui. La build publiée n’utilise plus de mot de passe AP statique : le mot de passe de provisioning est unique par device et suit la règle `TF-<setup code>`. Les logs série n’affichent les valeurs sensibles qu’en version masquée.

Pourquoi le VL53L8CH a-t-il été choisi ?

Parce qu’il combine un FoV plus contrôlable que le VL53L7CH avec des données CNH utiles pour de futurs scénarios au-delà du simple comptage de personnes : gesture sensing, presence detection et classifications plus avancées.

Quel est le bon flux d’assemblage ?

Flash du firmware, test du capteur à l’air libre, câblage final, test dans le boîtier puis installation et calibration sur site réel.