s23_time-attend-v2/README.md

🕒 Checador Inteligente NFC IoT (ESP8266 · Production Ready)

Este repositorio contiene el firmware para un sistema de control de asistencia profesional basado en NFC e IoT. Diseñado para ser robusto, autogestionable y fácil de desplegar en entornos reales.

El sistema utiliza un NodeMCU ESP8266 para leer tarjetas NFC, validar datos y enviarlos a un Webhook en la nube, todo configurable mediante un Portal Cautivo Web sin necesidad de recompensar el código para cambiar credenciales.

---

⚡️ Características Destacadas

• 🛡️ Robustez Industrial:

  • NFC Watchdog: Verificación cada 15s. Si el lector se congela, el sistema realiza un Hard Reset físico al módulo RC522 y fuerza la ganancia de antena al máximo.
  • Auto-Formato: Gestión automática del sistema de archivos (LittleFS) si se detecta corrupción.
  • Anti-Bloqueo: Uso de ESP8266WebServer síncrono y gestión de memoria optimizada (PROGMEM) para evitar reinicios por desbordamiento de pila.

• ⚙️ Configuración Vía Web (Portal Cautivo):

  • No requiere editar código (secrets.h) para cambiar WiFi o URLs.
  • Configura SSID, Password, Webhook URL y Nombre del Dispositivo (User-Agent) desde el navegador.

• 🎮 Controles Físicos y Gestuales:

  • Doble Reset (Double Tap): Presiona el botón RST dos veces rápido para forzar el Modo Configuración sin abrir la carcasa.
  • Botón Físico: Opción de forzar config manteniendo presionado el botón (GPIO 0 / Flash) al arrancar.

---

🚀 Guía de Inicio Rápido

1. Hardware Requerido

Componente	Descripción
NodeMCU v2/v3	ESP8266 (ESP-12E)
RC522	Lector NFC (SPI)
OLED 0.96"	Pantalla SSD1306 (I2C)
Buzzer	Activo/Pasivo (3.3V)
LED	Indicador de estado

2. Carga del Firmware

Usa el script automatizado para compilar y subir (requiere arduino-cli):

./compile_and_upload.sh

3. Configuración Inicial

1. Al encender por primera vez, el dispositivo creará una red WiFi llamada:
   • SSID: Soul23
   • Password: 1234567890
2. Conéctate con tu móvil o PC.
3. Accede a http://192.168.4.1 en tu navegador.
4. Ingresa los datos:
   • SSID / Password: Tu red WiFi local.
   • Webhook URL: Endpoint donde recibirás los registros (ej. https://api.tuempresa.com/asistencia).
   • Nombre del Dispositivo: Identificador único (se envía como User-Agent y en el JSON).
5. Dale a "Guardar y Reiniciar". ¡Listo!

---

🔌 Diagrama de Conexión (Pinout Seguro)

Este pinout evita conflictos con el proceso de arranque (Boot) del ESP8266.

RC522	NodeMCU	GPIO	Notas
SDA (SS)	D8	GPIO15	Pull-down interno
SCK	D5	GPIO14	SPI Clock
MOSI	D7	GPIO13	SPI MOSI
MISO	D6	GPIO12	SPI MISO
RST	D0	GPIO16	CRÍTICO: Usado para Hard Reset del lector
3.3V	3V3	-	⚠️ No usar 5V
GND	GND	-	-

Periférico	NodeMCU	GPIO	Notas
OLED SDA	D2	GPIO4	I2C Data
OLED SCL	D1	GPIO5	I2C Clock
Buzzer	D4	GPIO2	Inicializado tarde en setup()
LED / Botón	D3	GPIO0	Flash Button (Pull-up)

---

🧠 Funcionamiento del Watchdog NFC

El lector RC522 es propenso a congelarse por interferencia electromagnética. Este firmware implementa una solución de 3 capas:

1. Monitorización: Cada 15 segundos se consulta la versión del firmware del chip RC522.
2. Detección: Si responde 0x00 o 0xFF, se considera fallo.
3. Recuperación:
   • Se pone el pin RST (D0) en LOW por 50ms (corte de energía lógico).
   • Se restaura a HIGH.
   • Se re-inicializa la librería y se fuerza la ganancia de antena a Max (48dB).

---

📡 Payloads

Entrada (En Tarjeta NFC)

El tag debe contener un registro NDEF con un JSON válido:

{
  "name": "Ana Lopez",
  "num_emp": "EMP001",
  "sucursal": "Centro",
  "telegram_id": "12345"
}

Salida (Webhook POST)

El dispositivo envía este JSON al servidor:

{
  "uuid": "AbC123XyZ",
  "timestamp": 1703435600,
  "datetime_utc": "2025-12-24T12:00:00Z",
  "date": "2025-12-24",
  "num_empleado": "EMP001",
  "name": "Ana Lopez",
  "branch": "Centro",
  "telegram_id": "12345"
}

Headers: User-Agent: (Nombre configurado en el portal)

---

🗺️ Roadmap de Desarrollo

📍 Fase 1: Optimización de Transmisión (Corto Plazo)

• Payload Base64: Migrar el formato de envío de JSON plano a su equivalente codificado en Base64. Esto mejorará la integridad de los datos y facilitará el manejo de caracteres especiales en el transporte HTTP.

📍 Fase 2: Persistencia Offline (Medio Plazo)

• Lector MicroSD: Integración de hardware para almacenamiento local mediante bus SPI.
• Sincronización Inteligente:
  • Guardado automático de registros en la MicroSD cuando falla la conexión WiFi/Internet.
  • Lógica de "Checkpoint": Al recuperar la conexión, el dispositivo verificará cuál fue el último registro recibido por el servidor y enviará en ráfaga los datos pendientes para garantizar cero pérdida de información.

📍 Fase 3: Modernización de Hardware (Investigación)

• Soporte para Apple/Google Wallet: Investigación y prototipado con lectores que soporten protocolos NFC VAS (Apple) y Smart Tap (Google). El objetivo es permitir que los empleados usen sus pases digitales en el móvil en lugar de tarjetas físicas, mejorando la seguridad y la experiencia de usuario.

---

📄 Licencia

MIT License.