Actualizaciones en tiempo real y control directo desde la interfaz

La etapa de ejecución de la arquitectura general incluye, además de escrituras, alarmas y MQTT, el servicio directo a interfaces de usuario. Edge-EMS Builder ofrece dos canales WebSocket para que una interfaz personalizada reciba datos en tiempo real y envíe órdenes directamente a dispositivos, sin desarrollar una capa intermedia.

1. Dos canales WebSocket

Canal	Ruta	Autenticación	Finalidad
Canal de actualización de interfaz	ws://<host>:<port>/front	Token obtenido al iniciar sesión con usuario y contraseña	Interfaces personalizadas; validación por roles, suscripciones y escritura directa
Canal de lectura y escritura de datos	ws://<host>:<port>/data/rw	data-rw-token estático configurado en ems.yaml	Integraciones entre sistemas backend, sin inicio de sesión y con lectura y escritura de baja latencia

Ambos canales utilizan exactamente el mismo formato de mensajes. Solo difieren en la autenticación y la granularidad de comprobación de permisos. Esta página se centra en /front; el uso de /data/rw es análogo.

Proporciona los parámetros de consulta al conectar:

ws://<host>:<port>/front?socketId=<ID-de-conexión-personalizado>&token=<token-de-sesión>
ws://<host>:<port>/data/rw?socketId=<ID-de-conexión-personalizado>&token=<data-rw-token>

2. Formato de mensajes

Estructura común de las solicitudes, desde la interfaz hacia Edge-EMS Builder:

{
  "topic": "read | write | clear",
  "messageId": "ID único personalizado para asociar la respuesta",
  "keep": true,
  "content": [
    { "dataKey": "pcsActivePower" }
  ]
}

Las respuestas, desde Edge-EMS Builder hacia la interfaz, se corresponden con cada solicitud mediante messageId:

{
  "code": "200",
  "message": "Processed successfully",
  "topic": "read",
  "messageId": "...",
  "time": "2026-07-23T10:00:00+08:00",
  "data": { "...": "..." }
}

3. Recibir actualizaciones en tiempo real: suscripción = read + keep

El modelo de envío no consiste en publicar o suscribirse a un topic: cada conexión declara su propia configuración de actualización.

1. La interfaz envía topic: "read", enumera los dataKey deseados en content, o utiliza groupCode para un grupo completo, y establece keep en true.
2. Edge-EMS Builder guarda ese content como configuración de la conexión socketId y devuelve inmediatamente los valores actuales.
3. Después, una tarea en segundo plano recorre cada segundo todos los sockets de interfaz conectados y les envía los valores más recientes de su configuración, sin sondeos repetidos del cliente.
4. Si no se requiere envío continuo, establece keep en false u omítelo; Edge-EMS Builder solo enviará actualizaciones durante 30 s.
5. Para eliminar la configuración de actualización de una conexión, envía topic: "clear".

// Suscripción continua a los últimos valores de pcsActivePower y bmsSOC
{
  "topic": "read",
  "messageId": "sub-001",
  "keep": true,
  "content": [
    { "dataKey": "pcsActivePower" },
    { "dataKey": "bmsSOC" }
  ]
}

// O suscribirse por grupo a todos sus puntos, incluidos los subgrupos
{
  "topic": "read",
  "messageId": "sub-002",
  "keep": true,
  "content": [
    { "groupCode": "pcs-group-01" }
  ]
}

Una conexión puede enviar varias solicitudes read con keep:true para añadir o actualizar su configuración. Debe incluirse al menos dataKey o groupCode.

4. Controlar directamente dispositivos mediante write

La interfaz envía topic: "write" y especifica dataKey y dataValue en content. No es necesario indicar el tipo de datos: Edge-EMS Builder identifica si el punto es Collection, Aggregation o Customization a partir de dataKey y lo dirige a la lógica de escritura correspondiente.

{
  "topic": "write",
  "messageId": "ctrl-001",
  "content": [
    { "dataKey": "pcsActivePower", "dataValue": "300" }
  ]
}

Al escribir datos por franjas horarias (Customization), puede incluirse un intervalo de vigencia:

{
  "topic": "write",
  "messageId": "ctrl-002",
  "resetCustomValue": true,
  "content": [
    {
      "dataKey": "import_price",
      "dataValue": "0.85",
      "availableDate": "2026-06-25T00:00:00+08:00",
      "expiredDate": "2026-06-25T08:00:00+08:00"
    }
  ]
}

• resetCustomValue: true elimina primero los valores existentes de ese punto Customization y después escribe el contenido nuevo. Sirve para sustituir un plan completo y evitar solapamientos entre intervalos antiguos y nuevos.
• Para escribir puntos de otros dispositivos compartidos, añade deviceCode al elemento correspondiente de content. Edge-EMS Builder reconoce la escritura compartida y la dirige al dispositivo de destino.

Reglas de permisos

• Con /data/rw y el data-rw-token estático, se permite el acceso directamente, sin comprobar roles; está orientado a integración entre sistemas backend.
• Con /front y un token de inicio de sesión, se comprueba que el rol sea superadministrador, administrador u operador. El observador no puede escribir. Se aplican las mismas reglas que en la página, sin una vía de escritura que eluda sus permisos.

Planes de repetición diaria

DAILY_REPEAT utiliza availableTime / expiredTime, por ejemplo de 08:00:00 a 12:00:00; las fechas globales de vigencia se configuran en el punto Customization. DAILY_CHANGE utiliza intervalos completos de fecha y hora. No mezcles ambos conjuntos de parámetros y divide los intervalos que atraviesen medianoche.

Conexión y resultados de ejecución

/front supervisa la conexión mediante Ping/Pong. El cliente debe gestionar el código y el mensaje de cierre y restablecer las suscripciones al reconectar. No reproduzcas automáticamente las solicitudes de escritura junto con las suscripciones.

Las escrituras en dispositivos se confirman según la respuesta de CommBridge o el vencimiento del tiempo de espera. Un envío correcto no prueba que el dispositivo haya ejecutado la orden. Consulta los estados En proceso, Éxito y Fallo en Registros de control de dispositivos. CommBridge realiza la conversión inversa de coeficientes de escritura; el cliente no debe repetirla.

Durante la congelación para mantenimiento, las escrituras de control protegidas devuelven 200162. No salgas automáticamente de la congelación para reintentarlas.

5. Ejemplo completo de integración de interfaz

const ws = new WebSocket(`ws://<host>:<port>/front?socketId=web-ui-01&token=${loginToken}`);

ws.onopen = () => {
  // Suscribirse a potencia activa del PCS y SOC en tiempo real
  ws.send(JSON.stringify({
    topic: 'read',
    messageId: 'sub-' + Date.now(),
    keep: true,
    content: [
      { dataKey: 'pcsActivePower' },
      { dataKey: 'bmsSOC' }
    ]
  }));
};

ws.onmessage = (event) => {
  const resp = JSON.parse(event.data);
  if (resp.topic === 'read') {
    // Recibir valores cada segundo y actualizar paneles y gráficos de la interfaz
    renderDashboard(resp.data);
  }
  if (resp.topic === 'write') {
    // Resultado de escritura: resp.successContent / resp.errorContent
    showWriteResult(resp);
  }
};

// Cuando el usuario pulse «Establecer potencia en 300kW» en la interfaz:
function setPower(value) {
  ws.send(JSON.stringify({
    topic: 'write',
    messageId: 'ctrl-' + Date.now(),
    content: [{ dataKey: 'pcsActivePower', dataValue: String(value) }]
  }));
}

El código cubre el bucle habitual: suscribirse al cargar la página, actualizar la interfaz cada segundo, enviar órdenes desde las acciones del usuario y recibir resultados de escritura. No necesita un servicio backend adicional de intermediación.

6. Relación con otras capacidades

• Los datos escritos mediante /front o /data/rw son los mismos que leen los disparadores y el motor de expresiones. Tras adquirir de nuevo el estado del dispositivo, el resultado del control puede participar en agregaciones y condiciones. Consulta Modelo de datos.
• Puedes utilizar simultáneamente /front para tu interfaz y MQTT entre nube y borde para enviar los mismos datos a paneles en la nube.
• La Skill de configuración con IA aems-write-data encapsula las llamadas a /data/rw y /front, permitiendo depurar órdenes de escritura con un agente de IA mediante lenguaje natural.

Siguientes pasos

• Para la lista completa de interfaces HTTP/WebSocket, solicita a soporte técnico el documento «Interfaces HTTP de Edge-EMS Builder».
• Consulta cómo utilizan los datos escritos el motor de expresiones y los esquemas de disparadores.
• Para escrituras entre dispositivos, consulta Coordinación entre dispositivos y objetivos compartidos.