VCC Control

Plataforma de telecontrol y monitorización de convertidores de potencia. API en FastAPI con telemetría en tiempo real por WebSocket y panel de control en React + TypeScript.

▶ Probar la demo · usuario admin / admin123

---

Qué es

Un convertidor de potencia (VCC) transforma la energía de un bus de continua (DC) en corriente alterna trifásica para la red, como el inversor de una instalación solar o de un sistema de baterías. Esta plataforma permite supervisarlos y operarlos a distancia:

• Flota en directo: estado de cada equipo, potencia entregada, tendencias y actividad reciente.
• Centro de control por equipo:
  • Esquema unifilar animado: bus DC → convertidor (con la temperatura de cada módulo) → red. Los interruptores se abren y cierran según el estado y el flujo de potencia se mueve más rápido cuanta más potencia hay.
  • Tendencias de potencia, tensiones, corrientes y temperaturas, con las líneas de los límites de protección.
  • Osciloscopio de 4 canales, con escala por canal y acoplamiento AC para ver el rizado del bus DC.
• Control exclusivo: un operador toma el control de un equipo y solo él puede operarlo. El bloqueo caduca si no se usa y un administrador puede forzar su liberación.
• Órdenes y configuración remota:
  • marcha, espera, paro y rearme tras fallo;
  • consignas del regulador PI (potencia, tensión del bus, Kp, Ki);
  • límites de protección;
  • calibración ADC/DAC canal a canal.
• Alarmas: si una medida supera su límite, el equipo dispara, se registra la alarma y hay que rearmarlo. También se pueden provocar fallos simulados para probarlo.
• Registro de eventos de cada orden, cambio de configuración, toma de control y alarma, con usuario y hora.
• Usuarios y permisos: registro con acceso directo, rol de administrador y equipos permitidos por usuario.
• Agente de equipo (tools/publicador.py): se comporta como un equipo real. Descarga las órdenes del servidor y envía telemetría autenticado con su propia clave.

Todos los datos son de prueba. No hay equipos reales conectados: un simulador genera la telemetría con un modelo físico sencillo pero coherente. La potencia sigue a la consigna a través del regulador PI, el bus DC se precarga, los módulos se calientan con la carga y la calibración altera las medidas. Las órdenes del panel tienen efecto visible.

Flota	Centro de control	Control
Calibración	API (Swagger)	Móvil

Arquitectura

flowchart LR
    subgraph Navegador
      UI["Panel React + TypeScript"]
    end
    subgraph Servidor["API FastAPI"]
      REST["REST /api"]
      WS["WebSocket /api/ws"]
      SIM["Simulador de equipos"]
      BUS["Bus de mensajes en memoria"]
    end
    DB[("SQLite / PostgreSQL")]
    AG["Equipo real o agente<br/>tools/publicador.py"]

    UI -- "órdenes y configuración" --> REST
    WS -- "telemetría y eventos" --> UI
    REST --> DB
    SIM --> BUS --> WS
    SIM --> DB
    AG -- "X-Device-Key" --> REST
    REST --> BUS

Loading

• Estado pedido frente a estado real. El operador fija el estado que quiere (target_state) y el equipo informa del que tiene (state). El simulador, o un equipo real a través del agente, evoluciona hacia lo pedido: precarga del bus, espera y marcha. Así funciona el telecontrol real, con órdenes que tardan en cumplirse.
• Tiempo real con un bus de mensajes en memoria y WebSocket. Sustituye a RabbitMQ de la versión original, así que no hay que instalar ningún broker.
• Sesión con JWT en cookie httpOnly y contraseñas con bcrypt.
• Demo sin servidor. En GitHub Pages el panel usa un backend de demostración que se ejecuta en el navegador, con el mismo contrato, las mismas reglas y el mismo modelo físico. Si en local arrancas solo el frontend, también se activa.

API

Documentación interactiva en /docs (Swagger), con todos los endpoints en español. Los principales:

Método	Ruta	Descripción
POST	/api/auth/register · /login · /logout	Registro e inicio de sesión (cookie)
GET	/api/devices · /api/devices/{id}	Equipos visibles y su detalle
POST / DELETE	/api/devices/{id}/lock	Tomar y liberar el control exclusivo
POST	/api/devices/{id}/commands	Órdenes: start, standby, stop, reset
PUT	/api/devices/{id}/control · /limits · /calibration	Consignas, límites y calibración
GET	/api/devices/{id}/telemetry?minutes=60	Serie temporal (promediada a 360 puntos)
GET	/api/devices/{id}/waveform	Captura de osciloscopio
GET / POST	/api/devices/{id}/agent/config · /agent/telemetry	Endpoints del propio equipo (X-Device-Key)
WS	/api/ws	Telemetría y eventos en directo

Ejecutarlo

Opción 1: sin instalar nada

Abre la demo. Funciona entera en el navegador.

Opción 2: Docker

docker compose up --build

Panel en http://localhost:8000 y API en http://localhost:8000/docs, con PostgreSQL.

Opción 3: Python y Node

Requisitos: Python 3.11+ y Node 20+. No hace falta base de datos: por defecto usa SQLite y crea los datos de prueba al arrancar.

# API (http://localhost:8000/docs)
cd backend
python -m venv .venv && .venv/Scripts/activate    # En Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python -m app

# Panel (http://localhost:5173), en otra terminal
cd frontend
npm install
npm run dev

Si compilas el panel (npm run build), la API lo sirve también en http://localhost:8000: un solo proceso para todo.

Conectar un equipo externo

El equipo VCC-05 recibe sus datos de un agente externo. Copia su clave desde Administración → Gestión de equipos y ejecuta:

python tools/publicador.py --device 5 --key <clave>

Desde ese momento el equipo aparece conectado y obedece las órdenes del panel.

Tests

cd backend
pip install -r requirements-dev.txt
pytest                   # autenticación, permisos, control exclusivo, órdenes, validación, ingesta y modelo físico
ruff check app tests

cd frontend
npm run lint && npm run build

GitHub Actions ejecuta los tests con SQLite y con PostgreSQL en cada cambio, y publica la demo en GitHub Pages.

Estructura

├── backend/
│   ├── app/
│   │   ├── routers/      auth, equipos (control, datos, agente), usuarios, WebSocket
│   │   ├── services/     modelo físico, simulador, bus en tiempo real, datos de prueba
│   │   ├── models.py     usuarios, equipos, telemetría, eventos
│   │   └── schemas.py    contrato de la API con validación (Pydantic)
│   └── tests/
├── frontend/src/
│   ├── api/              cliente HTTP + WebSocket y backend de demostración
│   ├── components/       gráficas SVG propias, osciloscopio, esquema unifilar…
│   └── pages/            acceso, flota, centro de control, administración
├── tools/publicador.py   agente de equipo externo
└── docker-compose.yml

Origen del proyecto

Nació durante mi etapa en PowerUS, en la Asociación de Investigación y Cooperación Industrial de Andalucía (AICIA), vinculada a la Universidad de Sevilla. Allí se desarrolló en equipo una primera versión, que tenía:

• una API FastAPI con 13 tablas de PostgreSQL, una por magnitud medida;
• un panel React sin estilos con gráficas de Grafana incrustadas;
• un publicador de mediciones aleatorias y un ejemplo con RabbitMQ.

En la versión 2 he rediseñado y reestructurado todo:

• Modelo de datos: reducido a 4 tablas portables (SQLite y PostgreSQL).
• Seguridad: permisos en el servidor para cada operación, validación de todas las entradas y la clave secreta fuera del código.
• Simulador físico y tiempo real por WebSocket. Todo funciona sin Docker, Grafana ni RabbitMQ.
• Panel nuevo con gráficas, osciloscopio y esquema unifilar propios.
• Tests, CI y demo pública.