Saltar al contenido principal

Referencia de la API de Scripts

Esta sección proporciona la documentación técnica detallada de la API disponible para la programación de lógica avanzada. Los scripts pueden ejecutarse tanto en los sinópticos (pantallas) como en el servidor, dependiendo de los disparadores configurados.

Entorno de Ejecución​

El lenguaje utilizado es JavaScript (ES6+). El sistema permite la programación asíncrona de forma nativa, facilitando el uso de await para todas las operaciones de E/S (Entrada/Salida).

Objetos de Ámbito Global​

El sistema inyecta automáticamente los siguientes constructores y servicios en el espacio de nombres global:

1. Gestión de Variables (Tags)​

El objeto Tag es la interfaz principal para la interacción con el servidor de comunicaciones en tiempo real.

Tag(name?: string)​

Recupera una o varias instancias de variables del proyecto.

  • Parámetros:
    • name (Opcional): string. Nombre único del Tag a recuperar.
  • Retorno:
    • Si se omite name: Devuelve Tag[].
    • Si se especifica name: Devuelve la instancia Tag específica o undefined.

Propiedades​

value​
  • Tipo: any
  • Descripción: Acceso reactivo al valor de la variable.
    • Lectura: Devuelve el último valor conocido.
    • Escritura: Emite un comando de escritura al bus de datos (WebSocket).

Ejemplo de uso​

// Lectura y escritura simple
const motor = Tag("MOTOR_01_ON");
console.log(motor.value); // true/false
motor.value = true; // Arrancar motor

// Inversión de estado (Toggle)
motor.value = !motor.value;

// Manipulación de bits (Bitwise XOR)
const statusWord = Tag("STATUS_WORD");
statusWord.value ^= 0x01; // Invierte el primer bit

2. Persistencia (Data Design)​

DataDesign permite realizar operaciones CRUD asíncronas contra el motor de base de datos.

DataDesign(name: string)​

Obtiene la referencia a una colección de datos.

  • Parámetros:
    • name: string. Nombre de la colección (Data Design).
  • Retorno: DataDesignInstance.

Métodos​

async get(query: object)​

Recupera registros que coincidan con el filtro.

async insert(values: object)​

Inserta un nuevo documento en la colección.

async updateMany(query: object, values: object)​

Actualiza múltiples registros que cumplan con la query.

async deleteMany(query: object)​

Elimina registros que cumplan con la query.

Ejemplo de uso​

const logger = DataDesign("EventLog");
const rpm = Tag("MACHINE_RPM").value;

// Registrar evento de parada
if (rpm === 0) {
  try {
    await logger.insert({
      timestamp: new Date(),
      event: "STOP_DETECTED",
      value: rpm,
      userId: User?._id,
    });
  } catch (err) {
    console.error("Error guardando log", err);
  }
}

3. Elementos de Interfaz (DOM)​

Manipulación directa de los elementos visuales del sinóptico.

Item(name: string)​

Busca un elemento HTML en el sinóptico actual.

  • Parámetros:
    • name: string. Atributo Name definido en las propiedades del elemento.
  • Retorno: HTMLElement | undefined.

target​

Variable contextual disponible exclusivamente en scripts disparados por eventos de elemento (ej: On Click).

  • Tipo: HTMLElement.
  • Descripción: Referencia directa al elemento que originó el evento.

Ejemplo de uso​

/* Cambio de estilo dinámico basado en temperatura */
const temp = Tag("OVEN_TEMP").value;
const panel = Item("TempStatusPanel");

if (panel) {
  if (temp > 200) {
    // Estilo de Alarma
    panel.style.backgroundColor = "#ff4d4d"; // Rojo
    panel.style.border = "2px solid #b30000";
    panel.innerText = "¡ALERTA: SOBRETEMPERATURA!";
  } else {
    // Estilo Normal
    panel.style.backgroundColor = "transparent";
    panel.innerText = "Temperatura Normal";
  }
}

4. Comunicación Externa (http)​

Cliente HTTP para integración con APIs REST externas.

Métodos​

  • async http.get(url: string)
  • async http.post(url: string, body: any)
  • async http.put(url: string, body: any)
  • async http.delete(url: string)

Ejemplo de uso​

/* Sincronización con ERP externo */
try {
  const response = await http.get("http://mes-server/api/next-order");

  if (response && response.id) {
    // Asignar valores recibidos a Tags del SCADA
    Tag("CURRENT_ORDER_ID").value = response.id;
    Tag("BATCH_SIZE").value = response.quantity;
  }
} catch (error) {
  dialog({
    title: "Error de Conexión",
    message: "No se pudo obtener la orden de fabricación desde el MES.",
  });
}

5. Sistema y Navegación​

Funciones auxiliares para el control de la aplicación.

Synoptic​

  • open(name: string): Navega hacia el sinóptico especificado.

Interfaces de Usuario​

  • dialog(options: {title: string, message: string}): Muestra una ventana modal de alerta nativa.
  • openLogin(): Fuerza la visualización de la pantalla de inicio de sesión.
  • User: Objeto global con la información de la sesión actual (User._id, User.role, etc.).