Guía de Uso de PyZKTecoClocks

⚠️ Nota / Note:
Esta página está disponible solo en Español temporalmente.
This page is currently available in Spanish only.

Tabla de Contenidos

Introducción
Interfaz de usuario
Programa Reloj de Asistencias
Acciones principales
- Lista de acciones
- Modificar dispositivos
- Reiniciar dispositivos
- Probar conexiones
- Actualizar hora
- Obtener marcaciones
Configuración en acciones principales
Acciones de configuración del menú contextual
Otras acciones
Servicio Reloj de Asistencias
Acciones principales del servicio
Configuración del servicio
Comportamiento del servicio
Carpetas generadas
Archivos generados
Por el usuario
Por el programa y el servicio
Logs
Archivo de configuración config.ini
Resumen de parámetros
Attendance_status
Cpu_config
Device_config
Program_config
Network_config

Introducción

Este documento describe cómo utilizar las herramientas Programa Reloj de Asistencias y Servicio Reloj de Asistencias del proyecto PyZKTecoClocks. Aquí encontrarás:

Descripción de las interfaces de usuario.
Detalle de cada acción disponible.
Explicación de la configuración y de los archivos generados.
Estructura de las carpetas y logs.

Interfaz de usuario

El proyecto cuenta con dos aplicaciones independientes, cada uno con su propia interfaz de bandeja. Al hacer clic derecho sobre el ícono, se despliega un menú contextual con acciones propias del ejecutable.

Ver apartados Programa Reloj de Asistencias y Servicio Reloj de Asistencias para más información.

Programa Reloj de Asistencias

Para usar el programa, ejecutar Programa Reloj de Asistencias.exe. Para ello, asegúrese de tener en el directorio raíz donde se encuentran los ejecutables, los archivos config.ini (ver Archivo de configuración) y info_devices.txt (ver Archivos generados por el usuario).

Acciones principales

El menú contextual del programa ofrece cinco acciones principales que abren ventanas con tablas interactivas y controles de ejecución.

Lista de acciones

Acción	Descripción breve
Modificar dispositivos	Edita `info_devices.txt` desde una tabla interactiva.
Reiniciar dispositivos	Envía comando de reinicio y muestra progreso con barra y alertas.
Probar conexiones	Verifica conexión, marcaciones, serie, plataforma y firmware.
Actualizar hora	Sincroniza la hora de los dispositivos seleccionados.
Obtener marcaciones	Descarga registros y sincroniza hora, con gestión de errores.

Cada acción incluye Tiempo de Espera y Reintentos (ver Configuración en acciones principales) y utiliza variables de config.ini (ver Archivo de configuración). Además, genera archivos de log mensuales en la carpeta logs/ (ver Carpetas generadas).

Modificar dispositivos

Abre una ventana en la que permite modificar el archivo info_devices.txt a través de una tabla que contiene los dispositivos configurados para las acciones de:

Reiniciar dispositivos
Probar conexiones
Actualizar hora
Obtener marcaciones

La tabla es interactiva: al hacer doble clic sobre cualquier campo, se habilita la edición in situ, pero no se guardan los cambios en tiempo real en el archivo.

Botones disponibles:

Cargar: recarga desde info_devices.txt todos los dispositivos y actualiza la tabla.
Modificar: guarda en info_devices.txt los cambios realizados en la tabla.
Agregar: abre un formulario para incluir un nuevo dispositivo; solicita:
- Distrito
- Modelo
- Punto de marcación
- IP
- Tipo de comunicación (TCP o UDP)
Activar todo: marca la casilla "Activo" para todos los dispositivos listados, de modo que aparezcan y estén disponibles en las demás ventanas de acciones.
Desactivar todo: desmarca la casilla "Activo" para todos los dispositivos listados, de modo que queden ocultos y no se incluyan en las demás acciones.

Reiniciar dispositivos

Abre una ventana con:

Inputs:
- Tiempo de Espera
- Reintentos
(Ver Configuración en acciones principales).
Tabla interactiva de dispositivos activos (selección mediante clic izquierdo).
Botones disponibles:
- Reiniciar dispositivos: envía el comando de reinicio a cada dispositivo seleccionado; se muestra:
  - Barra de progreso verde indicando avance.
  - Conteo “dispositivos finalizados / total activos”.
  - Al finalizar, ventana emergente con listado de dispositivos cuya conexión falló.
- Seleccionar todo: marca todos los dispositivos para reinicio.
- Deseleccionar todo: desmarca todos.

Esta acción utiliza las variables del config.ini:

threads_pool_max_size
retry_connection
timeout

(Ver Archivo de configuración).

Probar conexiones

Abre una ventana con:

Inputs:
- Tiempo de Espera
- Reintentos
(Ver Configuración en acciones principales).
Tabla interactiva de dispositivos activos (selección mediante clic izquierdo).
Botones disponibles:
- Probar conexiones: envía comandos a cada dispositivo seleccionado; despliega:
  - Barra de progreso verde y conteo “finalizados / total”.
  - Al completar, la tabla añade las columnas:
    - Estado de Conexión: "Conectado" o "Error".
    - Cant. de Marcaciones: número de registros ("No aplica" si 0).
    - Número de Serie
    - Plataforma
    - Firmware
  - Coloreado de celdas:
    - Verde si el valor fue obtenido correctamente.
    - Gris con leyenda "No aplica" si el campo no corresponde.
    - Rojo si hubo fallo de conexión o de obtención.
- Seleccionar todo / Deseleccionar todo.

Esta acción utiliza las variables del config.ini:

threads_pool_max_size
retry_connection
size_ping_test_connection
timeout

(Ver Archivo de configuración).

Actualizar hora

Abre una ventana con:

Inputs:
- Tiempo de Espera
- Reintentos
(Ver Configuración en acciones principales).
Tabla interactiva de dispositivos activos (selección mediante clic izquierdo).
Botones disponibles:
- Actualizar hora: envía comando a cada dispositivo seleccionado; muestra barra de progreso.
- Seleccionar todo / Deseleccionar todo.
- Al finalizar, la tabla añade:
  - Estado de Conexión: "Conectado" (verde) o "Error" (rojo).
  - Estado de Pila:
  - "Pila funcionando" (verde)
  - "Pila fallando" (rojo)
  - "No aplica" (gris) si hubo error de conexión.

Esta acción utiliza las variables del config.ini:

threads_pool_max_size
retry_connection
timeout

(Ver Archivo de configuración).

Obtener marcaciones

Abre una ventana con:

Inputs:
- Tiempo de Espera
- Reintentos
(Ver Configuración en acciones principales).
Tabla interactiva de dispositivos activos (selección mediante clic izquierdo).
Botones disponibles:
- Obtener marcaciones: envía comandos para descargar marcaciones, sincronizar la hora, actualizar el modelo en el nombre de las carpetas ubicadas en devices/{distrito}/; muestra barra de progreso con conteo.
- Seleccionar todo / Deseleccionar todo.
- Reintentar todos / Reintentar fallidos (aparecen si hubo fallos).

Al terminar, se agrega:

Cant. de Marcaciones: número de marcaciones descargadas (verde con cantidad) o "Conexión fallida" (rojo).

Gestión de errores de formato:

Dispositivos con registros fuera de rango (más de 3 meses antiguos o fechas futuras al día de hoy) mostrarán hipervínculos a sus archivos.
Si "Eliminar marcaciones" está activo, permite forzar eliminación en próxima ejecución; luego se deshabilita.
Si no, solo listará enlaces a archivos afectados.

Archivos de salida diarios: devices/{distrito}/{modelo}-{punto_de_marcacion}/ y %ProgramData%/.../Backup/devices/{distrito}/{modelo}-{punto_de_marcacion}/ (ver Carpetas generadas).

Configuración en acciones principales

Tiempo de Espera: modifica timeout (segundos) en config.ini.
Reintentos: modifica retry_connection (intentos) en config.ini.

Eliminar marcaciones: edita clear_attendance en config.ini.
Iniciar automáticamente: registra programa en inicio del sistema.

Otras acciones

Salir: cierra el programa.

Servicio Reloj de Asistencias

El servicio se compone de 2 ejecutables: schedulerService.exe y Servicio Reloj de Asistencias.exe.

schedulerService.exe es el servicio automático per se.
Servicio Reloj de Asistencias.exe es el gestor del servicio. Con él, se pueden hacer las acciones tabuladas en la siguiente sección.

Para usar el servicio, ejecutar Servicio Reloj de Asistencias.exe. Para ello, asegúrese de tener en el directorio raíz donde se encuentran los ejecutables, los archivos config.ini (ver Archivo de configuración), info_devices.txt y schedule.txt (ver Archivos generados por el usuario).

Acciones principales del servicio

Acción	Descripción
Iniciar servicio	Arranca el servicio manualmente.
Detener servicio	Detiene la ejecución del servicio.
Reiniciar servicio	Detiene y vuelve a iniciar el servicio.
Reinstalar servicio	Reinstala el servicio en el sistema.
Desinstalar servicio	Elimina el servicio del sistema.

Configuración del servicio

Eliminar marcaciones: edita clear_attendance_service en config.ini.
Iniciar automáticamente: registra servicio en inicio del sistema.

Comportamiento del servicio

Arranca automáticamente al ejecutar el ejecutable.
Permanece activo tras cerrar la app, siguiendo schedule.txt.
Usa dispositivos activos en info_devices.txt.
No elimina marcaciones erróneas; el programa las procesa en la próxima ejecución de “Obtener marcaciones”.

Carpetas generadas

Ruta	Descripción
`devices/{distrito}/{modelo}-{punto_de_marcacion}/`	Marcaciones organizadas por distrito y modelo / punto de marcación.
`logs/{año-mes}/`	Logs mensuales de programa y servicio.
`%ProgramData%/.../Backup/devices/{distrito}/{modelo}`	Copia de seguridad de archivos de asistencia.

Archivos generados

Por el usuario

schedule.txt: define horarios de tareas (no modificar títulos).

# Hours for gestionar_marcaciones_dispositivos ... # Hours for actualizar_hora_dispositivos ...

info_devices.txt: lista de dispositivos:

DISTRITO - MODELO - PUNTO - IP - ID - TCP/UDP - Activado (True/False)

Por el programa y el servicio

{name_attendances_file}.txt: archivo global de marcaciones.
ip_date_file.cro: registros por dispositivo y fecha en devices/{distrito}/{modelo}-{punto_de_marcacion}/.

Logs

programa_reloj_de_asistencias_{VERSION}_debug.log: mensajes de depuración e info.
programa_reloj_de_asistencias_{VERSION}_error.log: advertencias y errores.
console_log.txt: logs de consola.
servicio_reloj_de_asistencias_{VERSION}_debug.txt y _error.txt: logs del servicio.
icono_reloj_de_asistencias_{VERSION}_{tipo}.txt: logs del icono del servicio.

Archivo de configuración `config.ini`

Resumen de parámetros

Sección	Parámetro	Tipo	Descripción
Attendance_status	IDs de tipo de marcación	Entero	Relaciona ID con tipo de marcación (face, fingerprint, card).
Cpu_config	threads_pool_max_size	Entero	Máximo de conexiones paralelas en acciones de red.
Device_config	clear_attendance	Booleano	Elimina marcaciones en ejecución manual.
	clear_attendance_service	Booleano	Elimina marcaciones en servicio programado.
	disable_device	Booleano	Bloqueo del dispositivo al acceder (no recomendado).
Program_config	name_attendances_file	Cadena	Nombre del archivo global de marcaciones.
Network_config	retry_connection	Entero	Cantidad de reintentos en operaciones de red.
	size_ping_test_connection	Entero	Paquetes enviados en test de conexión.
	timeout	Entero	Segundos antes de considerar caída de conexión.

Attendance_status

Asocia IDs con tipos de marcación.

Ejemplo en config.ini:

[Attendance_status]
status_face = 2
status_fingerprint = 1
status_card = 3

Cpu_config

threads_pool_max_size: conexiones paralelas.

Ejemplo en config.ini:

[Cpu_config]
threads_pool_max_size = 50

Device_config

clear_attendance: elimina marcaciones manuales.
clear_attendance_service: elimina marcaciones en el servicio.
disable_device: bloquea dispositivo al acceder (no recomendado).

Ejemplo en config.ini:

[Device_config]
clear_attendance = False
force_clear_attendance = False
clear_attendance_service = False
disable_device = False

Program_config

name_attendances_file: nombre del archivo global de marcaciones.

Ejemplo en config.ini:

[Program_config]
name_attendances_file = attendances_file

Network_config

retry_connection: reintentos en operaciones de red.
size_ping_test_connection: paquetes en test de conexión.
timeout: segundos de espera.

Ejemplo en config.ini:

[Network_config]
retry_connection = 3
size_ping_test_connection = 5
timeout = 15

Fin de la documentación.

Guía de Uso de PyZKTecoClocks

Tabla de Contenidos

Introducción

Interfaz de usuario

Programa Reloj de Asistencias

Acciones principales

Lista de acciones

Modificar dispositivos

Reiniciar dispositivos

Probar conexiones

Actualizar hora

Obtener marcaciones

Configuración en acciones principales

Acciones de configuración del menú contextual

Otras acciones

Servicio Reloj de Asistencias

Acciones principales del servicio

Configuración del servicio

Comportamiento del servicio

Carpetas generadas

Archivos generados

Por el usuario

Por el programa y el servicio

Logs

Archivo de configuración config.ini

Resumen de parámetros

Attendance_status

Cpu_config

Device_config

Program_config

Network_config

Archivo de configuración `config.ini`