TotalConnect 2.0 - Panel de Monitoreo de Alarmería

Este proyecto proporciona un panel web centralizado, responsivo y de alto rendimiento para el monitoreo consolidado de múltiples cuentas de alarmas de TotalConnect 2.0 (Resideo/Honeywell). Está diseñado para ejecutarse nativamente tanto en Linux como en Windows y generar reportes visuales dinámicos.

🛠️ Requerimientos del Sistema y Servicios

1. Sistema Operativo y Servidor

Linux (Debian/Ubuntu/Proxmox VM o similar): Probado y validado en Debian/Ubuntu con Python 3.11.
Windows (7/10/11 o Windows Server): Ejecutable mediante el binario autónomo totalconnect.exe (compilado con PyInstaller).
Acceso de Red: El host debe tener salida a Internet (para conectarse al API de Total Connect) y ser accesible en la red local (para visualizar el panel en el puerto configurado).

2. Servicios de Sistema Recomendados

En Linux: Servicio Systemd (totalconnect.service) configurado para mantener el servidor web encendido de forma persistente y asegurar su auto-recuperación.
En Windows: Ejecutar el binario en segundo plano o utilizar el Programador de Tareas para actualizaciones silenciosas.

📦 Dependencias de Python

Si ejecutas el script directamente desde el código fuente (index.py), se requiere:

total-connect-client: Librería principal para interactuar con la API REST y OAuth2 de Total Connect.
tzdata: Requerido en Windows para soportar zonas horarias locales (America/Mexico_City).

Nota: Si utilizas el ejecutable compilado totalconnect.exe, estas dependencias ya vienen empaquetadas en su interior.

📂 Estructura de Archivos del Proyecto

totalconnect.exe / totalconnect: El binario ejecutable autónomo.
index.py: El script principal de código fuente en Python.
credentials.json: Archivo confidencial que contiene las credenciales y el puerto HTTP.
locations_cache.json: Historial temporal auto-generado de nombres de sucursales para soporte sin conexión.
status.html: Reporte final auto-generado.
activity.log: Archivo de logs de la aplicación.
activity.log.1: Respaldo anterior del log (se rota automáticamente al superar los 5 MB).
server.log: Registro de errores del sistema del comando de arranque en segundo plano.

🚀 Modos de Ejecución y Guía rápida

Modo 1: Servidor Web Continuo (Por Defecto)

Arranca el Servidor HTTP integrado. Lee el puerto del archivo credentials.json (por defecto 8080).

En Windows: Haz doble clic en totalconnect.exe o corre en consola: totalconnect.exe
En Linux: Ejecuta ./totalconnect
Acceso: Abre tu navegador en http://localhost:PORT/ o http://IP_DEL_SERVIDOR:PORT/

Modo 2: Actualización Única (On-Demand / Tareas Programadas)

Consulta los estados una sola vez, genera status.html and finaliza. Ideal para automatizar con Cron (Linux) o Programador de Tareas (Windows).

Comando: Agregar el argumento --once o -o (ej: totalconnect.exe --once o ./totalconnect -o).

🔑 Formato de Configuración (`credentials.json`)

El archivo credentials.json debe colocarse junto al ejecutable o script y soporta dos formatos:

Formato A (Formato por objeto con puerto, exclusiones y navegador - RECOMENDADO):

{
  "port": 8080,
  "exclude": ["1071", "1171", "1215"],  // Lista de sucursales a ignorar (ID, número o nombre)
  "open_browser": true,                  // true para abrir navegador al iniciar (defecto en GUI)
  "accounts": [
    {
      "label": "2020",
      "username": "TuUsuario2020",
      "password": "TuPassword2020"
    },
    {
      "label": "2019",
      "username": "TuUsuario2019",
      "password": "TuPassword2019"
    }
  ]
}

Formato B (Formato original de lista - Puerto por defecto 8080):

[
  {
    "label": "2020",
    "username": "TuUsuario2020",
    "password": "TuPassword2020"
  },
  {
    "label": "2019",
    "username": "TuUsuario2019",
    "password": "TuPassword2019"
  }
]

🔒 Robustez y Resiliencia Implementada

Motor Híbrido Dinámico (27 + 7): En cada ciclo de 30s se procesan 27 sucursales del turno ordinario (ordenadas secuencialmente por antigüedad) + hasta 7 de alta frecuencia (desarmadas/alarmadas/fallos), previniendo rate-limits.
Decisión Inteligente (SOAP vs REST): Realiza un Poll Lite SOAP (GetLiveEvents) rápido si los datos de la sucursal tienen menos de 10 minutos. Si detecta actividad física, programa un Poll Full REST (fullStatus) para la siguiente vuelta.
Tope de Consultas REST: Limitador integrado de máximo 35 consultas REST por ciclo para un arranque en frío seguro sin bloqueos de cuenta.
Visor de Logs Interactiva (150 líneas): Botón "Ver Log" en el dashboard para auditar el servidor en vivo directamente desde el navegador.
Autogestión de Espacio: Rotación automática de logs a los 5 MB de tamaño.
Arranque Silencioso en Producción (VM): nohup ./venv/bin/python3 index.py > /dev/null 2> server.log & Descarta prints de consola duplicados y deja server.log activo únicamente para atrapar excepciones de crash.
Reinicio de Fábrica (Hard Reset) por Clic Largo (3s): Al mantener presionado el botón "Actualizar" por 3 segundos, se purga la memoria y base de datos física para resolver inconsistencias. Cuenta con retraso de 1 segundo en el cambio de color para evitar destellos y cancelación silenciosa ergonómica si te arrepientes antes de completarse los 3 segundos.

5.5 KiB Raw Permalink Blame History