Hardware open source

Tholus Flow

Sensor open source para conteo de personas y detección de proximidad basado en ESP32 + VL53L8CH. Esta página reúne hardware, componentes, montaje, firmware, commissioning y referencias esenciales para publicación y reproducibilidad.

Descargar firmware Ir al flashing Descargar Arduino IDE
Categoría
Nodo sensor open source
Stack
ESP32 + VL53L8CH
Use case
Conteo de personas y detección de proximidad
Firmware
v2.0.1

Build de referencia práctica

Componentes fáciles de conseguir, flashing sencillo y documentación lista para equipos que realmente necesitan replicar el nodo.

Configuración en el dispositivo

Wi-Fi, threshold, ROI y counting line se guardan localmente en el sensor para un mantenimiento más simple.

Pensado para campo

Provisioning AP, calibración en vivo y commissioning sobre la escena real para accesos, pasajes e instalaciones permanentes.

Índice

Placa ESP32 Type-C CP2102
Placa ESP32 Type-C con CP2102, usada para flashing, serial y gestión del firmware.
Breakout del sensor VL53L8CH con tira de pines
Módulo breakout VL53L8CH: sensor ToF multizona 8×8 elegido por versatilidad y datos CNH.
Conector USB-C panel mount waterproof de dos hilos
Entrada de alimentación de la caja final: solo power, útil para un enclosure limpio y cerrado.
Caja ABS waterproof de 100x68x50 milímetros
Caja ABS 100 × 68 × 50 mm usada como referencia para la build publicada.
Firmware de referencia Descarga el archivo `.ino` publicado directamente en el sitio. Arduino IDE oficial Toolchain mínima para compilar, cargar y verificar la build. Flujo de commissioning Ve directamente a la secuencia recomendada para pairing, red y calibración.

Overview

Una plataforma de referencia pensada para ser reproducible.

Tholus Flow fue diseñado como un nodo sensor replicable, económico y fácil de montar. La configuración operativa vive en el dispositivo, mientras que el firmware se carga con Arduino IDE y luego se gestiona mediante aplicación o APIs de red.

El objetivo es publicar no solo el código, sino el flujo completo: elección de componentes, notas de sourcing, assembly, wiring, flashing y commissioning real en la entrada o paso que se quiere monitorizar.

Reproducibilidad con componentes fáciles de conseguir Versatilidad del sensor 8×8 para futuros casos de uso Flashing y calibración mantenibles Documentación lista para web y soporte

Arquitectura

Nodo compacto, bus I²C simple y alimentación separada.

Power input USB-C panel mount 2 hilos, solo alimentación
Main board ESP32 + CP2102 USB nativa para flash y serial
Sensor bus I²C en GPIO 21/22 Wire.begin(21, 22)
Optical sensing VL53L8CH 8×8 ToF Conteo de personas y presencia

La placa ESP32 con bridge CP2102 fue elegida por comodidad de desarrollo y flashing, mientras que el VL53L8CH añade más versatilidad que un simple ranging gracias al sensor multizona 8×8 y a los datos CNH, útiles también para casos de uso futuros.

Bill of materials

BOM recomendada para la build de referencia.

Componente Cant. Source Search / reference Notas de proyecto
ESP32 Development Board Type-C CP2102 WiFi 1 AliExpress ESP32 CP2102 Type-C board Elegida por flashing sencillo, acceso serial y buena compatibilidad práctica en Mac; preferible con headers ya soldados.
VL53L8CH breakout board + pin strip 1 AliExpress VL53L8CH module board Sensor ToF multizona 8×8; si no llega preensamblado requiere soldar los pines.
24AWG Dupont jumper wires 1 kit AliExpress 10 cm / 20 cm kit Hace falta suficiente cable female-to-female para conectar ambas placas con headers macho.
USB-C panel-mount waterproof connector, 2 wires 1 AliExpress USB-C waterproof panel mount 2pin Entrada de alimentación del box. Solo power, sin datos USB.
Waterproof ABS enclosure 100 × 68 × 50 mm 1 AliExpress ABS waterproof enclosure 100x68x50 La medida correcta está en milímetros y representa el volumen útil del box final.

Wiring

Conexiones lógicas antes de cerrar la caja.

Referencia Uso Nota de implementación
ESP32 GPIO 21 → sensor SDA I²C data El firmware usa `Wire.begin(21, 22)`. Verifica siempre el pinout del breakout comprado.
ESP32 GPIO 22 → sensor SCL I²C clock Mantén los cables cortos y ordenados para reducir ruido y lecturas inestables.
ESP32 3V3 / VIN correcto → sensor power Power sensor Algunos breakouts exponen VIN, otros 3V3. No envíes 5 V a placas que no lo soportan.
ESP32 GND → sensor GND Common ground Se necesita una masa compartida limpia entre sensor, placa y alimentación.
USB-C panel red wire → ESP32 5V / VIN Power enclosure El conector de 2 hilos alimenta la caja final y no se usa para flashing ni datos USB.
USB-C panel black wire → ESP32 GND Power enclosure Programa el dispositivo desde el USB nativo de la placa antes de cerrar la caja definitiva.
Flujo recomendado: flash del firmware, prueba del sensor al aire libre, cableado final, prueba dentro del box e instalación en el sitio real.

Assembly

Montaje y packaging pensando en la escena real.

La build de referencia busca ser simple de montar, pero el resultado final depende mucho de cómo se perfora la caja, cómo se fija el sensor y cómo se mantiene limpia la ventana óptica. Aquí conviene ser práctico antes que elegante.

  • Programa y prueba la placa en banco antes de cerrar la caja definitiva.
  • Si el sensor trabaja detrás de una ventana, mantén la apertura óptica limpia y poco hundida.
  • Evita túneles profundos delante del sensor, porque reducen innecesariamente el campo de visión.
  • Fija el sensor de forma estable y perpendicular al paso con separadores, soportes o adhesivo técnico.
  • Si el uso es realmente outdoor, la estanqueidad depende de la calidad del taladrado y sellado del box y del conector.
Caja ABS waterproof de 100x68x50 milímetros
Caja ABS 100 × 68 × 50 mm usada como referencia para la build publicada.

Firmware

Funciones core ya incluidas en la build de referencia.

  • configuración persistente en el dispositivo para Wi-Fi, threshold, ROI y tracking
  • access point inicial para provisioning y commissioning
  • pairing con setup code y token administrativo para operaciones de escritura
  • streaming en vivo de la matriz 8×8 por WebSocket
  • HTTP API para estado, configuración, Wi-Fi provisioning y restart
  • blob tracking y line crossing para eventos IN / OUT
  • subida de eventos a backend o cloud manteniendo la calibración directamente en el sensor

Utilidad web

Tholus Flow Lite añade una capa lista para usar sobre el firmware.

Hasta ahora el proyecto ofrecía el sensor y el firmware, pero muchos makers seguían teniendo que construir su propia capa de software para usar los datos de verdad. Tholus Flow Lite es una pequeña utilidad web que se conecta al sensor y hace que el firmware sea inmediatamente más útil desde el navegador.

Está pensada para seguir siendo ligera: un dashboard práctico para visualizar datos, probar el nodo con más facilidad y partir de una base ya útil y hackable para pequeños proyectos reales.

Abrir Tholus Flow Lite en GitHub
Vista previa animada del dashboard en vivo de Tholus Flow Lite
Una utilidad web ligera para conteos en vivo, actividad en la entrada y calibración rápida desde el navegador.

Qué puede hacer

  • conteos en vivo de entradas y salidas
  • estimación de la ocupación actual
  • visualización en vivo simple de la actividad cerca de la entrada
  • gráficos horarios o diarios ligeros
  • historial básico de eventos
  • interfaz simple para calibración y ajustes

Cómo se usa

  1. montar el sensor y cargar el firmware
  2. conectar el dispositivo a la red o usar el modo de setup
  3. abrir la utilidad en el navegador y conectarla al sensor
  4. ver datos en vivo y analíticas básicas
  5. revisar histórico y gráficos para validar el comportamiento real
  6. ajustar calibración y parámetros si hace falta
Infraestructura: en la configuración más simple solo hace falta tener el sensor en la red local y abrir la utilidad en un navegador. Un historial ligero puede quedarse en el navegador o en almacenamiento local, mientras que integraciones cloud o de base de datos como Supabase son extensiones opcionales, no requisitos del flujo principal.

Ideas de uso

contador de paso en una puerta seguimiento de ocupación de taller o estudio monitor de flujo para evento o pop-up capa de entrada para instalación interactiva punto de partida para integraciones custom

Flashing

Instalación del firmware con Arduino IDE.

Toolchain esencial

Para que la página sea realmente útil, aquí puedes descargar tanto el firmware publicado como el entorno oficial usado para compilarlo y cargarlo.

Descargar Arduino IDE Descargar firmware
  1. Instalar una versión actualizada de Arduino IDE.
  2. Añadir en preferencias la URL del package manager de Espressif ESP32.
  3. Instalar desde Boards Manager el paquete “esp32 by Espressif Systems”.
  4. Seleccionar una placa compatible con el hardware usado; en la mayoría de los casos “ESP32 Dev Module” es el punto de partida más práctico.
  5. Instalar las librerías requeridas: ArduinoJson, arduinoWebSockets (Links2004) y STM32duino VL53L8CH.
  6. Conectar el ESP32 mediante el puerto USB-C nativo de la placa.
  7. Abrir el archivo firmware, verificar puerto serial y placa seleccionada, luego compilar y cargar.
  8. Si la subida en Mac es inestable, repetir con una upload speed más conservadora, por ejemplo 115200.
Provisioning AP: durante la primera configuración el nodo expone un SSID del tipo `TholusFlow-XXXX`. La contraseña sigue la regla `TF-<setup code>`.

Boards Manager

esp32 by Espressif Systems

Proporciona core, WiFi, WebServer, Preferences, ESPmDNS, HTTPClient y toolchain de upload.

Library Manager

ArduinoJson

Se usa para payloads JSON y configuración.

Library Manager

arduinoWebSockets (Links2004)

Gestiona el stream en vivo por WebSocket.

Library Manager

STM32duino VL53L8CH

Driver Arduino para el sensor ToF VL53L8CH.

Commissioning

Primer arranque, pairing y calibración.

  1. Encender el nodo y comprobar en serial la MAC y el nombre del nodo; mantener a mano setup code y etiqueta de provisioning.
  2. Asociar el sensor desde la app o herramienta de provisioning.
  3. Configurar SSID, contraseña Wi-Fi y parámetros cloud.
  4. Esperar a que el nodo reaparezca en la LAN.
  5. Abrir la pantalla de calibración, verificar la matriz en vivo y ajustar threshold, ROI y counting line en el contexto real de instalación.
Para conteo de personas en entradas es preferible montar el sensor orientado hacia abajo, con vista limpia sobre el paso, y ajustar counting line, ROI y threshold directamente sobre la escena real.

Checklist

Cosas que no hay que olvidar antes de la instalación.

  • suficientes cables female-to-female para conectar ESP32 y breakout del sensor
  • estaño, punta fina y herramientas para soldar los headers del VL53L8CH
  • alimentador 5 V estable y cable USB-C externo
  • método de fijación interna: separadores, standoffs, adhesivo técnico o soporte 3D
  • ventana óptica o cubierta limpia delante del sensor, si la caja lo requiere
  • etiqueta externa con serial / MAC / setup code para soporte y commissioning

Referencias

Referencias técnicas esenciales.

Tholus Flow Lite - utilidad web en GitHub Arduino IDE — descarga oficial 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

Preguntas frecuentes para quien consulta o reutiliza el proyecto.

¿Hay algo a tener en cuenta antes de usar el firmware en campo?

Sí. La build publicada ya no usa una contraseña AP estática: la contraseña de provisioning es única por dispositivo y sigue la regla `TF-<setup code>`. Los logs seriales muestran los valores sensibles solo en forma enmascarada.

¿Por qué se eligió el VL53L8CH?

Porque combina un FoV más controlable que el VL53L7CH con datos CNH útiles para escenarios futuros más allá del simple conteo de personas: gesture sensing, presence detection y clasificaciones más avanzadas.

¿Cuál es el flujo correcto de montaje?

Flash del firmware, prueba del sensor al aire libre, cableado final, prueba dentro de la caja e instalación y calibración en el sitio real.