Keyon v3.15.5 — con Terminal Pro v2

Control de acceso escolar, en menos de un segundo.

Keyon registra cada entrada con cara o QR, avisa al tutor en tiempo real y opera sin servidor propio. Una sola plataforma reemplaza la lista en papel, las tarjetas RFID y los avisos por correo — ahora también con kiosco físico embebido sobre Raspberry Pi.

v3.15.5 · release actual

< 1 s por registro

Offline-first real

LFPDPPP compliant

Terminal Pi autónoma

Presentando Keyon v3.15

La versión 3 es un rediseño completo del sistema. Bajo el capó: build con Vite, dominios separados, descriptores faciales cifrados por escuela y consentimiento del tutor en doble canal (web y móvil). El resultado es un sistema medible, reproducible y alineado con la legislación mexicana de datos personales.

Benchmarks

Cifras medidas en entornos reales: planteles de 300–2,000 alumnos, red escolar estándar (50 Mbps), hardware común (Chromebook, tablet Android 10+, ESP32 DevKit, Raspberry Pi Zero 2W). Comparamos Keyon contra los tres enfoques más extendidos en escuelas mexicanas: lista en papel, tarjetas RFID y plataformas SaaS genéricas.

Cómo leer los gráficos: las barras oscuras son Keyon; las grises, sistemas comparados. Donde menor es mejor (tiempos, tamaños) las barras de Keyon son más cortas. Donde mayor es mejor (precisión) las de Keyon llenan casi todo.

Velocidad de registro

Precisión de identificación

Latencia de aviso al tutor

Eficiencia de hardware

Dos métricas relevantes para la adopción real en escuelas: qué pesa el sistema en dispositivos y cuánta energía consume el kiosco físico.

Costo inicial vs alternativas

Tabla comparativa consolidada

Todas las métricas relevantes en una sola vista. Keyon aparece en dos modos: web (Chromebook + navegador) y Terminal Pro v2 (kiosco físico embebido).

Métrica	Keyon web	Terminal Pro v2	Hikvision	ZKTeco	RFID	Pase manual
Tiempo por registro	0.8 s	3.0 s	3.0 s	4.0 s	2.5 s	45 s
Precisión	99.1%	98.8%	98.5%	98.0%	94.0%	92.0%
Aviso al tutor	2.8 s	2.8 s	SaaS pagado	SaaS pagado	Ninguno	Diferido
Consumo eléctrico	~75 W (PC)	3 W	12 W	10 W	15 W	0 W
Costo por punto	$4,900	$3,225	$8,000	$5,000	$18,000+	$0
Operación offline	Completa	Completa	Parcial	Parcial	Parcial	Por naturaleza
LFPDPPP compliant	Sí (Arts. 8, 9, 16, 22)	Sí (hereda)	N/A México	N/A México	No	Responsabilidad centro
Monitoreo remoto	Panel admin	Heartbeat 5 min	SaaS pagado	SaaS pagado	No	No
Código fuente	Open source	Open source	Propietario	Propietario	Propietario	N/A
Multi-escuela	Nativo (schoolId)	Nativo	Por instalación	Por instalación	Por instalación	N/A

Capacidades clave

Seis capacidades que definen a Keyon v3 frente a sus predecesores y competidores.

Arquitectura

Cliente monolítico con carga por orden de dependencias, backend completamente serverless en Firebase, y app móvil nativa para el tutor. Un solo bundle sirve los cuatro roles; el router decide la vista.

Principios de diseño

• Multi-tenant por escuela. Todo documento lleva schoolId. Las reglas lo exigen.
• Un bundle, cuatro roles. auth-router.js decide la vista según el documento en usuarios/.
• Offline-first en el kiosco. Cola persistente con reenvío ordenado y deduplicación.
• Privacidad por diseño. Consentimiento tutor antes de cualquier captura biométrica.
• Sin servidor propio. Firebase cubre auth, base, hosting y storage. Cero ops de infraestructura.

Stack técnico

Área	Tecnología	Versión
Build	Vite	5.0.10
Runtime	Node	≥18
Base de datos	Firestore (compat v9)	9.x
Auth	Firebase Auth	9.x
Hosting	Firebase Hosting	—
Reconocimiento facial	face-api.js (TinyFaceDetector)	0.22.2
QR	html5-qrcode	2.3.x
PDF	jsPDF + AutoTable	2.x
Testing	Vitest	1.1.0
Mobile	Expo SDK	51
Mobile Router	expo-router	4
Push	OneSignal	—
Hardware kiosco	ESP32 DevKit + relé	—

Módulos del sistema

Doce dominios funcionales. Cada uno vive bajo su carpeta en public/js/ y carga en orden por public/index.html.

Extensiones .ext

Los archivos con sufijo .ext-*.js son sobrescrituras legítimas por módulo. Reemplazan la antigua convención *-patch.js, que mezclaba parches temporales con extensiones permanentes.

Archivo	Extiende	Propósito
kiosco-acceso.ext-offline.js	kiosco-acceso.js	Persistencia offline de registros y reenvío al recuperar red.
scanner-processor.ext-kiosco.js	scanner-processor.js	Pipeline optimizado para alta tasa de escaneos en kiosco.
kiosco-esp32-bridge.ext.js	kiosco-esp32-dual.js	Puente WebSocket para relé físico ESP32 (apertura de torniquete).

Kiosco

La terminal tipo kiosco corre la misma PWA, pero con modo dual (QR + facial) y un puente hacia un microcontrolador ESP32 que activa el torniquete.

Especificaciones

Tópicos clave

• Alto throughput. Cola por lote para registrar decenas de accesos por minuto sin bloquear la UI.
• Offline. Persiste en IndexedDB y reenvía al volver.
• Detección dual. Si el alumno ya tiene descriptor facial, basta su cara; si no, QR.
• Relé ESP32. El puente emite el pulso sólo tras validar identidad + horario vigente.

Reconocimiento facial

El registro facial captura cinco frames, promedia los descriptores y cifra el resultado antes de subirlo a Firestore. La comparación usa distancia euclidiana con umbral 0.42.

// public/js/09-facial/biometric-crypto.js
await BiometricCrypto.initSchoolKey(schoolId);
const encrypted = await BiometricCrypto.encrypt(descriptor128);
await db.collection('alumnos').doc(uid).update({
  reconocimientoFacial: { encryptedDescriptor: encrypted, ... }
});

Parámetros

Algoritmo	AES-GCM-256
Derivación de clave	PBKDF2-SHA256, 150,000 iteraciones
Sal	Por escuela (schoolId), persistida en config/crypto
Modelo	TinyFaceDetector + FaceLandmark68Net + FaceRecognitionNet
Descriptor	128 flotantes (face-api.js)
Umbral de match	0.42 distancia euclidiana
Frames por captura	5, promediados
Tasa FAR / FRR	FAR < 0.1% · FRR ~ 0.9%

Reportes SEP / DGETI

Generador admin-reportes-*.js emite documentos PDF con formato institucional. Firmas, cabeceras y agregados se resuelven en cliente.

• Indicadores de riesgo por alumno (retardos, faltas, inasistencias justificadas).
• Agregado por grupo, profesor o materia.
• Firmas automáticas de director y encargado de control escolar.
• Formato nativo SEP (básica) y DGETI (media superior).

Terminal Pro v2 — Kiosco físico embebido

Terminal Pro v2 es la evolución hardware del sistema Keyon: un kiosco físico autónomo basado en Raspberry Pi Zero 2W que reemplaza la PC + navegador por un dispositivo dedicado con reconocimiento facial nativo en Python + OpenCV + modelos ONNX, sincronización directa a Firestore y monitoreo remoto vía heartbeat.

Hardware embebido

La terminal opera sobre un SBC ARM de bajo costo y bajo consumo con cámara USB estándar. Todos los componentes son comerciales off-the-shelf, disponibles en Mercado Libre o AliExpress, sin piezas propietarias.

Desglose de costos

Componente	Costo (MXN)	Estado
Raspberry Pi Zero 2W	806.44	✓ En uso
Fuente 5V 3A Tecneu	139.56	✓ En uso
microSD ADATA 128GB	378.00	✓ En uso
Cámara Logitech C270	486.00	✓ En uso
Pantalla SPI 3.5" ILI9486	474.05	Pendiente
Cable OTG Soku V8	159.99	✓ En uso
2x PAM8403 + 2x bocinas 50mm	225.91	Pendiente
Headers + adaptador HDMI	~160.00	Compra 20 abr
Case 3D impreso	~400.00	Pendiente
Total proyectado	~3,225

Pipeline de reconocimiento facial

La terminal implementa el pipeline completo nativo en Python sin dependencia de JavaScript ni navegador. Todo el cómputo ocurre en el SBC, con sincronización a Firestore solo del resultado final.

Stack técnico

OS	Debian 13 Trixie (kernel Linux 6.12.75 aarch64)
Python	3.13.5
Visión	opencv-python-headless 4.13.0
Numérico	numpy 2.4.4
Firebase	firebase-admin 7.4.0
BD local	SQLite 3.46 (embeddings BLOB 512 bytes)
Gestor proceso	systemd con auto-restart on-failure
Modelos	YuNet + SFace del OpenCV Model Zoo (libre uso)

Monitoreo remoto vía heartbeat

La terminal reporta su estado cada 5 minutos a la colección terminal_status en Firestore. El panel admin del sistema web (v3.15.5) muestra en tiempo real temperatura CPU, RAM, disco, uptime, último heartbeat y total de registros del día.

Schema del documento terminal_status

Campo	Tipo	Ejemplo
terminalId	string	"keyon-pi-zero2w-01"
dispositivo	string	"Raspberry Pi Zero 2W"
estado	enum	"online" | "offline"
ultimoHeartbeat	Timestamp	Server timestamp Google
temperaturaCpu	number (°C)	45.1
ramUsadaMB	number	225
espacioDiscoLibreGB	number	105.4
uptimeSegundos	number	2867
totalRegistrosHoy	number	5
ip	string	"192.168.101.74"
versionTerminal	string	"2.0.4-dev"
origen	string	"terminal_pi"

El panel admin Sidebar → Sistema → Terminales (deployed en v3.15.5) consume estos datos con listener Firestore en tiempo real, mostrando badge "Pi" cyan y auto-refresh cada 30 segundos.

Auto-start con systemd

La terminal arranca automáticamente al bootear el SBC. No requiere login SSH, ejecución manual de scripts, ni intervención humana. El servicio keyon-terminal.service se autoregistra con systemd, respeta dependencias de red y se auto-recupera ante crashes.

Cronología post-reboot validada

Métricas validadas en producción

Todas las métricas provienen de la sesión de desarrollo end-to-end del 19 de abril de 2026, con registros reales escritos a la colección de producción ingresos_cbtis del proyecto scanner-v3.

Métricas de hardware

Métrica	Valor medido	Umbral
Temperatura CPU idle	40–45 °C	Throttling a 80 °C
Temperatura CPU en carga	50–55 °C	Margen amplio
RAM usada en operación	~225 MB	de 416 disponibles
Espacio disco libre	105 GB	de 114 totales
Boot a operativa (post-reboot)	49 s	Objetivo <120 s
Confianza detección YuNet	92–95 %	Mínimo 60%
Score SFace coseno	0.722–0.834	>0.363 para match
Score SFace L2	0.577–0.752	<1.128 para match

Comparativa con competencia

Aspecto	Terminal Pro v2	Hikvision DS-K1T343	ZKTeco SpeedFace-V5L
Precio	$3,225 MXN	$4,000–$8,000	$3,000–$5,000
Consumo	2–5 W	10–15 W	8–12 W
Código fuente	Open source	Propietario	Propietario
LFPDPPP México	Compliance integrado	No aplica	No aplica
Integración Firebase	Nativa	Requiere bridge	Requiere API gateway
Modificable	Total	Muy limitado	Muy limitado
Monitoreo remoto	Heartbeat 5min	Plataforma cloud pagada	Platform SaaS pagada

Portal padres (web)

Vista web accesible desde /padres/ dentro de la misma PWA. Autentica por token enviado por WhatsApp y muestra:

• Historial de accesos del hijo, día por día.
• Estado de consentimiento biométrico vigente.
• Revocación del consentimiento con generación de código OTP verificado.

App móvil padres

App nativa en el repositorio C:\Dev\keyon-padres-app\. Construida con Expo Router 4 y autenticación anónima en Firebase.

Flujo de consentimiento

Los datos biométricos del alumno sólo se procesan con autorización expresa del tutor. El flujo aplica a ambas apps.

1. Admin inicia el alta del alumno y captura el teléfono del tutor.
2. Tutor recibe enlace o abre la app móvil.
3. Tutor firma el aviso de privacidad (LFPDPPP Art. 8, 11).
4. App escribe consent_pending/{alumnoId} con la firma.
5. Admin confirma en web; se fija tutorAutoriza: true en alumnos/{id}.
6. Alumno queda habilitado para registrar su descriptor facial.

Modelo Firestore

Todas las colecciones llevan schoolId para partición multi-tenant. Agrupación por dominio:

Identidad y acceso

Colección	Rol principal	Descripción
usuarios	todos	Documento base con rol y schoolId.
alumnos	alumno	Datos académicos, QR, consentimiento, descriptor facial cifrado.
profesores	profesor	Alta docente y asignación de materias.
prefectos	prefectura	Cuentas de prefectura con permisos de registro manual.
admins	admin	Administradores escolares.
super_admins	super	Root; acceso transversal a todas las escuelas.

Horarios y clases

Colección	Rol principal	Descripción
horarios	admin	Matriz de clases por grupo, día y hora.
clases	profesor	Clase activa con bitácora y pase de lista.
grupos	admin	Alta y configuración de grupos escolares.
materias	admin	Catálogo de materias por nivel.
ciclos	admin	Ciclo escolar vigente y archivo histórico.

Registros

Colección	Rol principal	Descripción
registros	sistema	Entradas y salidas registradas por QR, facial o prefectura.
asistencias	profesor	Pase de lista por clase.
retardos	sistema	Tabla derivada calculada por retardos-motor.js.
incidentes	prefectura	Incidencias manuales con tipo y descripción.

Privacidad y consentimiento

Colección	Rol principal	Descripción
consent_pending	tutor	Firmas entregadas desde la app de padres.
consent_codes	tutor	Códigos OTP para revocación verificada.
avisos_privacidad	admin	Versiones del aviso LFPDPPP vigente.

Comunicación con tutores

Colección	Rol principal	Descripción
tutores	tutor	Vínculo tutor ↔ alumno y contacto (WhatsApp, OneSignal).
mensajes	sistema	Historial de notificaciones enviadas.
plantillas	admin	Plantillas reutilizables por tipo de evento.
onesignal_tokens	app-padres	Tokens push de la app móvil.

Auditoría y sistema

Colección	Rol principal	Descripción
audit_log	sistema	Cambios críticos firmados (quién, qué, cuándo).
config	super	Parámetros globales y claves criptográficas por escuela.
schools	super	Alta de escuelas y configuración por inquilino.
migrations	super	Registro de migraciones ejecutadas.

Reglas de seguridad

firestore.rules aplica un patrón de whitelist por campo en las escrituras sensibles. Sólo se aceptan diffs que afecten campos explícitamente listados.

match /alumnos/{id} {
  allow update: if noMaliciousFields() && isReasonableSize() && (
    isAdmin() ||
    request.resource.data.diff(resource.data).affectedKeys().hasOnly([
      'password', 'passwordCreatedAt', 'passwordResetAt', 'passwordResetBy',
      'reconocimientoFacial',
      'onesignal_id', 'onesignal_token',
      'whatsapp',
      'consentimientoBiometrico', 'fechaConsentimiento',
      'tutorAutoriza', 'fechaRevocacion'
    ])
  );
}

Helpers compartidos

• isAuthenticated() — exige request.auth != null.
• isAdmin() / isSuperAdmin() — verifican documento en admins/ y super_admins/.
• noMaliciousFields() — bloquea campos reservados (__proto__, constructores).
• isReasonableSize() — rechaza documentos mayores a 1 MB.

Cumplimiento LFPDPPP

El sistema implementa los artículos relevantes de la Ley Federal de Protección de Datos Personales en Posesión de los Particulares:

Art.	Exigencia	Implementación
8	Consentimiento del titular.	Flujo de firma tutor → consent_pending.
9	Consentimiento expreso para datos sensibles.	Segunda firma antes de captura biométrica.
11	Calidad y vigencia del dato.	Política de retención: descriptor borrado al egresar o al revocar.
22	Derechos ARCO.	Dashboard tutor con visualización y revocación.
23	Medidas de seguridad.	AES-GCM-256 + PBKDF2 + reglas por campo.

Cifrado biométrico

public/js/09-facial/biometric-crypto.js aisla toda la criptografía. Nunca salen descriptores en claro de la capa criptográfica.

API

Método	Descripción
initSchoolKey(schoolId)	Deriva la clave maestra por escuela y la cachea en memoria.
encrypt(descriptor)	Cifra un descriptor 128-D y devuelve Base64 + IV.
decrypt(blob)	Revierte a Float32Array listo para comparar.
rotate(schoolId)	Rotación de clave con recifrado en lote.

Build y despliegue

El build de producción usa Vite con un plugin closeBundle personalizado que copia los scripts legados no bundleados.

# build local
npm run build

# preview local del build
npm run preview

# despliegue a Firebase Hosting
npm run deploy

Las reglas Firestore se despliegan por separado:

firebase deploy --only firestore:rules

Scripts NPM

Script	Descripción
npm run dev	Servidor Vite con hot-reload.
npm run build	Build de producción en dist/.
npm run build:legacy	Build con el antiguo build.js (respaldo).
npm run preview	Sirve el build local para verificación.
npm run deploy	Build + despliegue a Firebase Hosting.
npm run test	Suite Vitest en modo watch.
npm run test:run	Ejecuta la suite una vez (CI).
npm run test:coverage	Cobertura con @vitest/coverage-v8.
npm run lint	ESLint sobre public/js.
npm run lint:fix	ESLint con --fix.
npm run docs	Genera JSDoc a partir de la config del repo.
npm run clean	Elimina dist/, coverage/ y test-results/.

Versionado

Semver manual en package.json. Publicación recomendada cada 3–5 cambios o al cerrar una feature.

git add -A
git commit -m "feat: <resumen>"
git tag v3.15.1
git push origin main --tags
gh release create v3.15.1 --generate-notes

Changelog reciente

Últimas versiones publicadas en main (sistema web) y en el repo keyon-terminal.

Terminal Pro v2 — releases

Repositorio: github.com/santirivera-oss/keyon-terminal

---