mirror of
https://github.com/marcogll/s23_time-attend-v1.git
synced 2026-01-13 13:15:16 +00:00
first commit
This commit is contained in:
Marco Gallegos
231
README.md
Normal file
231
README.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# 🕒 Checador Inteligente NFC IoT (ESP8266 · MVP)
|
||||
|
||||
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)
|
||||
|
||||
1. Instala dependencias (ESP8266 core + librerías listadas más abajo) en Arduino IDE.
|
||||
2. Duplica `secrets.h.example` → `secrets.h` y rellena Wi‑Fi, URLs y zona horaria.
|
||||
3. Carga el sketch `soul23_time_attendance.ino` en tu NodeMCU 1.0 (ESP‑12E).
|
||||
4. Cablea RC522 y OLED siguiendo el **pinout seguro** descrito en este documento.
|
||||
5. Graba tarjetas NFC con **JSON válido** usando NFC Tools.
|
||||
6. 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
|
||||
|
||||
1. **Arranque:** conexión Wi‑Fi + sincronización de hora.
|
||||
2. **Espera:** muestra reloj y mensaje *ACERQUE TARJETA*.
|
||||
3. **Lectura NFC:** UID + payload JSON.
|
||||
4. **Validación:** deserialización segura.
|
||||
5. **Envío:** POST al webhook.
|
||||
6. **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:
|
||||
|
||||
```cpp
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```json
|
||||
{
|
||||
"card_uid": "04A1B2C3",
|
||||
"name": "Juan",
|
||||
"num_emp": "XXXX250117",
|
||||
"sucursal": "sucursal_1",
|
||||
"telegram_id": "123456789",
|
||||
"timestamp": 1765913424,
|
||||
"device": "Checador_Oficina_1"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Configuración (`secrets.h`)
|
||||
|
||||
```cpp
|
||||
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
|
||||
Reference in New Issue
Block a user