Resumen

El objeto User Code (C#) de la biblioteca matemática de SharpBot permite a los usuarios avanzados incorporar lógica personalizada en C# directamente dentro del motor de ejecución de SharpBot.

Este objeto proporciona un entorno de ejecución controlado, determinista y basado en ciclos de escaneo (scan-based).

El objeto User Code está implementado como un contenedor de código (code wrapper) con un ciclo de vida fijo, lo que permite a los usuarios implementar cálculos personalizados, mantener estados internos y extender la lógica matemática sin necesidad de utilizar scripts externos ni servicios adicionales.

Capacidades principales

• Cálculos matemáticos y lógicos personalizados.
• Memoria interna persistente entre ciclos de escaneo.
• Ejecución determinista a una frecuencia de escaneo definida.
• Verificación automática de límites en entradas y salidas.

Estructura del código

El código del objeto User Code (C#) se compone de cuatro secciones principales:

1. Directivas using y contexto de ejecución, incluyendo declaraciones de variables globales (memoria persistente).
2. Método del ciclo de vida 1: BeginCalculate().
3. Método del ciclo de vida 2: Calculate().
4. Método del ciclo de vida 3: EndCalculate().

Cada sección se ejecuta en un momento específico dentro del entorno de ejecución de SharpBot.

1. Directivas using y contexto de ejecución

using System;  //  ... and any other using directives....
// variables from tables above are available in this code window
// any additional object variables are defined here
// these variables are global, have a permanent memory and can be used in the functions below
// feel free to delete instructions once you know how to use the object!

using System;  //  ... and any other using directives....
// variables from tables above are available in this code window
// any additional object variables are defined here
// these variables are global, have a permanent memory and can be used in the functions below
// feel free to delete instructions once you know how to use the object!

Descripción

Esta sección define qué espacios de nombres (.NET namespaces) estarán disponibles para el objeto User Code.

Notas importantes

• System está incluido de forma predeterminada.
• Solo pueden utilizarse espacios de nombres compatibles con el entorno de ejecución de SharpBot. Actualmente no existe una lista oficial disponible.
• El código se ejecuta dentro de un entorno aislado (sandbox) para garantizar seguridad y estabilidad.

2. Variables globales y memoria persistente

int i;
double myVarX, sum;

int i;
double myVarX, sum;

Descripción

Las variables declaradas fuera de los métodos del ciclo de vida se consideran variables globales del objeto.

Características

• Existen durante toda la vida útil del objeto.
• Conservan sus valores entre ciclos de ejecución.
• Son accesibles desde todos los métodos del ciclo de vida.

Casos de uso típicos

• Contadores y temporizadores.
• Integradores y acumuladores.
• Estados internos de modelos o filtros.
• Máquinas de estados e indicadores (flags).

Entradas y salidas

• Las entradas del conector del objeto (x0, x1, x2, …) y las salidas (y0, y1, …) están disponibles automáticamente.
• Estas variables no deben ser redeclaradas por el usuario.
• Los nombres de estas variables pueden ser modificados por el usuario.

3. Métodos del ciclo de vida

El objeto User Code sigue un ciclo de ejecución estricto para garantizar un comportamiento determinista.

3.1 BeginCalculate() — Fase de inicialización

public void BeginCalculate()
{
	// use this method to initialize any variable values (e.g. sum = 0)
}

public void BeginCalculate()
{
	// use this method to initialize any variable values (e.g. sum = 0)
}

Descripción

Se ejecuta una sola vez al iniciar la simulación, antes del primer ciclo de cálculo.

Usos típicos

• Inicializar variables globales.
• Reiniciar estados internos.
• Definir condiciones iniciales para modelos o algoritmos.

Frecuencia de ejecución

• Se ejecuta una vez por ciclo de ejecución.
• No se ejecuta en cada escaneo.

3.2 Calculate() — Bucle principal de ejecución

public void Calculate()
{
	// this is the main simulation loop.  Based on your scan class, this will be
	// called at a certain frequency.  
	// Inputs and outputs will be automatically checked  for the limits defined 
	// in the table.  If outside the limits, default values will be used
	y0 = ( x0 + x1 ) * x2;
	y1 = y0 / x3;
}

public void Calculate()
{
	// this is the main simulation loop.  Based on your scan class, this will be
	// called at a certain frequency.  
	// Inputs and outputs will be automatically checked  for the limits defined 
	// in the table.  If outside the limits, default values will be used
	y0 = ( x0 + x1 ) * x2;
	y1 = y0 / x3;
}

Descripción

Es el método principal de ejecución y se ejecuta de forma cíclica según la Clase de Escaneo (Scan Class) configurada.

Características principales

• Se ejecuta a una frecuencia fija y determinista.
• Su comportamiento es similar al ciclo de escaneo de un PLC o a un paso de ejecución de un sistema APC.
• Todas las entradas y salidas son automáticamente:
  • Verificadas contra los límites de ingeniería configurados.
  • Sustituidas por valores predeterminados si se exceden dichos límites (por ello es importante definir cuidadosamente los límites).

Usos típicos

• Cálculos matemáticos principales.
• Ecuaciones de modelos.
• Procesamiento y acondicionamiento de señales.
• Lógica de control y toma de decisiones.

3.3 EndCalculate() — Fase de finalización

public void EndCalculate()
{
	// this method is called at the end of the simulation
}

public void EndCalculate()
{
	// this method is called at the end of the simulation
}

Descripción

Se ejecuta una sola vez cuando la simulación termina o cuando el objeto es descargado.

Usos típicos

• Cálculos finales.
• Lógica de cierre controlado.
• Diagnóstico opcional o tareas de limpieza.

Este método es opcional y no es necesario para la mayoría de las aplicaciones.

Flujo de ejecución

La secuencia completa de ejecución del objeto User Code es la siguiente:

Start
├─ BeginCalculate()
├─ Calculate() (executed repeatedly at scan rate)
├─ Calculate()
├─ Calculate()
└─ EndCalculate()
End



Modelo conceptual

El objeto User Code (C#) de SharpBot puede entenderse conceptualmente como:

• Un bloque de función PLC con memoria interna.
• Un bloque matemático personalizado con estado persistente.
• Un contenedor ligero de algoritmos integrado dentro de la capa APC.

Está diseñado para ejecutar lógica durante la simulación con temporización garantizada y resultados reproducibles.

Buenas prácticas

• Inicialice todas las variables persistentes en BeginCalculate().
• Mantenga la lógica de Calculate() determinista y segura para ejecución por escaneo.
• Evite cálculos complejos o bloqueantes.
• Utilice los límites de las tablas para validar las entradas.
• Trate las variables globales como memoria de estado y no como variables temporales.

Resumen final

El objeto User Code (C#) es un potente mecanismo de extensión de la biblioteca matemática de SharpBot. Al combinar memoria persistente, ejecución determinista e integración transparente de entradas y salidas, permite a usuarios avanzados implementar lógica personalizada preservando el rendimiento, la estabilidad y la integridad operativa del sistema.

*Este artículo fue escrito originalmente por Walter Eskuche, posteriormente reescrito con ayuda de inteligencia artificial y finalmente editado por el autor para luego ser traducido al español por otra IA. Walter Eskuche no es escritor ni editor profesional, sino ingeniero y desarrollador de soluciones de automatización y optimización de procesos.