Este repositorio contiene el Producto Mínimo Viable (MVP) de un sistema de control de asistencia basado en NFC e IoT, diseñado para entornos reales de operación (oficinas, talleres, sucursales).

El sistema utiliza un NodeMCU ESP8266 para leer tarjetas NFC de empleados, obtener la hora exacta desde un servidor en la nube y enviar los registros de asistencia a un Webhook HTTP para su posterior procesamiento (bases de datos, bots, dashboards o sistemas de RRHH).

⚡️ Guía Rápida (TL;DR)

Instala dependencias (ESP8266 core + librerías listadas más abajo) en Arduino IDE.
Duplica secrets.h.example → secrets.h y rellena Wi‑Fi, URLs y zona horaria.
Carga el sketch soul23_time_attendance.ino en tu NodeMCU 1.0 (ESP‑12E).
Cablea RC522 y OLED siguiendo el pinout seguro descrito en este documento.
Graba tarjetas NFC con JSON válido usando NFC Tools.
Abre el monitor serie (115200) para verificar conexión, hora y peticiones HTTP.

📁 Estructura del Repositorio

soul23_time_attendance/
├── soul23_time_attendance.ino
├── README.md
├── secrets.h.example
├── secrets.h
└── test/

Solo es necesario editar secrets.h para credenciales y constantes sensibles.

🚀 Funcionalidades

Lectura NFC/RFID (Mifare / NTAG 13.56 MHz)
Decodificación NDEF en JSON
Sincronización de hora en la nube (sin RTC físico)
Feedback visual en OLED
Integración vía Webhook HTTP (POST JSON)

🧠 Arquitectura del Firmware

Módulo	Función
`setup()`	Inicializa Wi‑Fi, OLED, SPI, NFC y sincroniza hora
`loop()`	Muestra hora, refresca estado y espera tarjeta
`processTag()`	Lee UID + JSON NFC y dispara envío
`syncTimeWithServer()`	Obtiene `unixtime` desde servidor
`sendToWebhook()`	Envía payload JSON vía POST

🔬 Flujo de Operación

Arranque: conexión Wi‑Fi + sincronización de hora.
Espera: muestra reloj y mensaje ACERQUE TARJETA.
Lectura NFC: UID + payload JSON.
Validación: deserialización segura.
Envío: POST al webhook.
Feedback: confirmación visual/sonora.

🛠️ Hardware Requerido

Componente	Descripción
NodeMCU ESP8266	MCU con Wi‑Fi
RC522	Lector NFC SPI
OLED 0.96"	SSD1306 I2C
LED	Indicador visual
Buzzer	Indicador audible
Tags NFC	NTAG213 / Mifare

🔌 Pinout Seguro (Producción)

RC522 (SPI)

RC522	NodeMCU	GPIO	Color Cable	Nota
SDA	D8	GPIO15	Azul	Pull‑down interno (seguro como SS)
SCK	D5	GPIO14	Amarillo	SPI
MOSI	D7	GPIO13	Morado	SPI
MISO	D6	GPIO12	Blanco	SPI
IRQ	NC	—	Naranja	No conectado
GND	GND	—	Verde	Tierra común
RST	D0	GPIO16	Negro	Seguro para reset
3.3V	3.3V	—	Rojo	⚠️ No usar 5V

OLED (I2C)

OLED	NodeMCU	Color Cable
SDA	D2	Azul
SCL	D1	Naranja
VCC	3.3V	Rojo
GND	GND	Negro

LED y Buzzer

Componente	NodeMCU	GPIO	Uso
LED	D3	GPIO0	Estado visual
Buzzer	D4	GPIO2	Feedback sonoro

🔧 Pull‑Up Resistors y Pines de Boot (Explicación Clave)

El ESP8266 tiene pines críticos durante el arranque. Si alguno está en el nivel incorrecto, el microcontrolador entra en modo programación o falla el boot.

GPIO 0 (D3) – LED

Requisito: debe estar en HIGH durante el boot.
Riesgo: un LED mal cableado puede forzar LOW.
Solución aplicada:
- El firmware inicializa primero:
```
pinMode(LED_PIN, INPUT_PULLUP);
```
- Luego se configura como salida cuando el sistema ya arrancó.
Resultado: se evita entrar en modo flash accidentalmente.

GPIO 2 (D4) – Buzzer

Tiene pull‑up interno por defecto.
Problema común: un buzzer pasivo conectado durante la carga puede generar interferencia.
Buenas prácticas:
- Inicializar el buzzer al final del setup().
- Desconectar GND del buzzer durante la carga del firmware.
- Opcional: resistencia serie de 220 Ω.

GPIO 15 (D8)

Tiene pull‑down interno.
Ideal para SS (SDA) del RC522.
Nunca usar para señales que requieran HIGH en boot.

GPIO 16 (D0)

No tiene pull‑up/pull‑down.
Seguro para RST del RC522.
No soporta PWM.

💳 Formato del Payload NFC (Entrada)

El tag NFC debe contener un registro NDEF de texto con JSON válido.

Ejemplo recomendado:

{
  "name": "Juan",
  "num_emp": "XXXX250117",
  "sucursal": "sucursal_1",
  "telegram_id": "123456789"
}

Campos adicionales son ignorados de forma segura si no se usan.

📡 Payload Enviado al Webhook (Salida)

Ejemplo real del POST generado por el dispositivo:

{
  "card_uid": "04A1B2C3",
  "name": "Juan",
  "num_emp": "XXXX250117",
  "sucursal": "sucursal_1",
  "telegram_id": "123456789",
  "timestamp": 1765913424,
  "device": "Checador_Oficina_1"
}

⚙️ Configuración (`secrets.h`)

const char* ssid = "TU_WIFI";
const char* password = "TU_PASSWORD";

const char* webhookUrl = "https://api.tudominio.com/webhook";
const char* timeServerUrl = "https://soul23.cloud/time-server";

#define DEVICE_NAME "Checador_Oficina_1"
#define TIMEZONE_OFFSET -21600

🐛 Troubleshooting Rápido

No arranca: revisar GPIO0 y GPIO2.
No lee NFC: revisar 3.3 V y RST.
No carga firmware: desconectar buzzer temporalmente.
JSON inválido: validar comillas rectas y formato.

📌 Estado

MVP funcional, listo para pilotos, dashboards y automatización RH.

👤 Autor

Marco — Inventor · Automatización · IoT

📄 Licencia

MIT

README.md Unescape Escape

🕒 Checador Inteligente NFC IoT (ESP8266 · MVP)