DatapointSets declaration¶

En este apartado se establece la configuración para cada conjunto de datapoints.

Se recomienda agrupar los datapoints por tipo de driver, identificando la agrupación con un comentario, y añadir comentarios antes de cada datapoint con una descripción o indicación de su función de forma que sea fácil identificarlo.

Los parámetros que definen un datapointSet (conjunto de datapoints) están contenidos dentro de un array.

Un template puede contener varios datapointSet.

Parámetros¶

DatapointSets¶

datapointSets: array que indica la declaración del conjunto de datapoints.

1. Nombre: al inicio de cada datapointSet se indica su nombre en un comentario.

2. datapointSetType: Tipo de datapointset. Puede ser:

map: mapas clave-valor utilizados para representar estructuras de datos por pares (cada clave tiene un solo valor).
tableStatic: tablas estáticas en las que no varían el número de filas e índices.
tableDynamic: tablas dinámicas que se adaptan cambiando su tamaño o los índices cuando es necesario.

3. datapointSetId: nombre identificativo del datapointSet.

4. alias: texto sencillo y comprensible que identifica al datapointSet.

5. description: descripción detallada del datapointSet.

En el caso de que el tipo del datapointset sea tabla se le añaden los siguientes parámetros de configuración:

6. tableAddress:

rootAddress: dirección principal de la tabla.
indexes: enumeración de los índices de la tabla. Se escriben en diferentes líneas precedidos de un guion medio ( - ).

Ejemplos¶

Mapa¶

Tabla¶

datapoints¶

A continuación se muestran las diferentes opciones que hay a la hora de configurar un datapoint.

Estas configuraciones se agrupan dentro de un array, y se pueden usar diferentes configuraciones dentro de un mismo datapoint.

datapoints: array que contiene el conjunto de datapoints que forman parte de un datapointSet.
Nombre: al inicio de cada datapoint se indica su nombre en un comentario.

A continuación se definen las diferentes configuraciones que puede tener cada datapoint:

commonConfig¶

Permite establecer los parámetros para la identificación del datapoint. Es obligatorio configurarlo para todos los datapoints.

commonConfig:

datapointId: nombre identificativo del datapoint.
alias: texto sencillo y comprensible que identifica al datapoint.
description: descripción detallada del datapoint.
syntaxInfo: describe el tipo de datos de la variable que se va a leer de un dispositivo. Se puede poner cualquier texto.

datapointType: tipo de datapoint definido. Puede ser de dos tipos:

SIMPLE o DATAPOINT: se sobrescribe cada vez que se lee el dato.
TIMEPOINT: se guarda en una base de datos cada vez que se lee para tener un "histórico".
Son configurables como timepoints únicamente los datos de tipo:
- Number
- String
- Boolean
- Bigint o null.
- Otro tipo de dato (incluidos array u objetos) no soportan esta configuración.

Existen 4 posibles configuraciones:

Tipo de dato	datapointType	Timepoint generado por
Datapoint	DATAPOINT o SIMPLE	Zavod
Timepoint	TIMEPOINT	Zavod
Ambos	@DATAPOINT o @TIMEPOINT	Zavod
Ambos	#DATAPOINT	Driver
Timepoint	#TIMEPOINT	Driver

El datapoint siempre será generado por Zavod. La elección de quién debe generar el timepoint (zavod o el driver) está determinada por la cantidad de información enviada por el dispositivo. En dispositivos que realicen un envío continuo y elevado de datos lo más conveniente es optar por el driver para que estos se transmitan como una cola. Zavod, en cambio, recibe estos datos como una lista, sobrescribiendo aquellos que tengan el mismo identificador (mismo datapointSet) si aún no han sido consumidos, por lo que la pérdida de datos es posible.

Info

Si un dato se define como timepoint este desaparecerá de MongoDB. Por tanto, se generan dos valores: un datapointSet en Mongo sin el dato en cuestión y un timepoint en Elasticsearch con un solo valor.

Para conocer la estructura de un timepoint, consultar el siguiente enlace Timepoints

Ejemplo¶

Lectura del estado de un dispositivo, puede ser: Not reachable, Ok o Fault.

  # deviceState
  - commonConfig:
      datapointId: deviceState
      alias: State
      description: Overall device status, including connection status.
      syntaxInfo: string
      datapointType: SIMPLE

addressConfig¶

Permite configurar la información necesaria para acceder a los valores (direccionamiento).

addressConfig:
- dataType: tipo de dato que acepta Netin y que el driver (origin) va a enviar.
  - BYTE
  - INTEGER
  - LONG
  - FLOAT
  - DOUBLE
  - STRING
  - BOOLEAN
  - DATE
  - ARRAY
  - INTEGER_ARRAY
  - STRING_ARRAY
  - DOUBLE_ARRAY
  - BOOLEAN_ARRAY
  - FLOAT_ARRAY
  - LONG_ARRAY
  - OBJECT
- originType: identificación del tipo de fuente del dato (origen), es decir, a través de qué driver se ha leído el valor.
  - netin-ds-drv-icmp
  - netin-ds-drv-snmp
  - netin-ds-drv-pnio
  - netin-ds-drv-modbus-tcp
  - netin-ds-drv-mqtt
  - netin-ds-drv-s7
- originDataType: tipo de dato que el driver va a leer del equipo. Cada driver tiene su topología de datos (se recomienda consultar la documentación del driver para saber los tipos de datos que acepta).
  
  Se transforma esta variable primitiva de un tipo a otro (castear) para ser tratada en Netin. Se muestran algunos ejemplos con datos leídos a través del driver SNMP en la siguiente tabla:
  
  originDataType DataType
  
  Integer Integer
  
  Octet_String String
  
  Gauge32 Long
  
  String String
- originAddress: define la dirección de este datapoint para el originType.
  - SNMP: se utilizan las direcciones de los OIDs contenidos en los MIBs de cada dispositivo.
  - PNIO: se utilizan las direcciones definidas en el estándar Profinet.
  - MODBUS:: se utilizan los registros Modbus. Se define de la siguiente forma: YYY:XXXXX:ZZ
    - YYY: tipo de registro que se va a leer:
      - RHR: Read Holding Register
      - RIR: Read Input Register
    - XXXXX: registro desde donde se quiere empezar a leer.
    - ZZ: número máximo de registros que se quieren leer.
- originAccessType: nivel de acceso al datapoint. Puede ser:
  - read-only (solo lectura).
  - write-only (solo escritura).
  - read-write (lectura y escritura).
  - not-accessible (no accesible).
- receiveMode: modo de lectura del dato. Puede ser:
  - polling: sondeo cada cierto tiempo.
  - singleQuery: ejecuta la lectura una sóla vez.
  - subscription: suscripción de aviso en el momento que se produzcan cambios.
- pollingGroup: si el modo es "polling", en esta propiedad se indica el periodo de lectura del dato. Puede ser:
  - 5s
  - 10s
  - 30s
  - 1m
  - 5m
  - 10m
  - 15m
  - 30m
  - 1h
  - 4h
  - 6h
  - 12h
  - 1d

Info

Los parámetros que comienzan por origin hacen referencia a la configuración del driver, mientras que el resto hacen referencia a la configuración de Netin. Si el driver no soporta la opción configurada, utilizará la que tenga por defecto, es decir, si se configura un polling de 5s y sólo es capaz de leer el dato cada 20s, el dato será leído cada 20s.

Ejemplo¶

Lectura del nombre de un equipo por SNMP.

Name OID	Value	Type
sysName	SCALANCE X204-2	OctetString

  - addressConfig:
      dataType: STRING
      originType: netin-ds-drv-snmp
      originDataType: OCTET_STRING
      originAddress: 1.3.6.1.2.1.1.5.0
      originAccessType: read-write
      receiveMode: polling
      pollingGroup: 1d

alertConfig¶

Contiene la configuración de disparadores, basados en condiciones lógicas, que permiten emitir eventos de alarmas.

Sobre un mismo datapoint pueden configurarse varias alertas que expresen diferentes niveles de severidad, o el mismo nivel con diferentes textos o configuraciones.

alertConfig:
- evaluations: es la instancia donde se definen las propiedades de la alarma para el datapoint. Cada nivel de alarma que se quiere emitir se considera una evaluación. En el caso de que dos evaluaciones se cumplan se emitirá la de mayor nivel de alarma.
  Dentro del mismo nivel de alarma pueden existir una o más expressions.
  - expressions: contiene tantas expression como condiciones deban cumplirse para disparar la alarma. Cada una compuesta por expression y symbol.
    - expression: cada condición cuya evaluación lógica (true o false) indicará si debe dispararse la alerta. Puede haber una o varias.
    - symbol: alias identificativo asignado a cada expression.
  - logic: relaciona (utilizando symbol) las expression configuradas para construir la lógica necesaria para saltar la alerta. Si el resultado de las combinaciones es true (la alarma se considera activa), por el contrario, si es false (no se considera activa).
  - severity: severidad de la alarma (ver tabla de rangos de severidad).
  - text: texto descriptivo que nos proporciona información sobre la alarma.
  - textHelp: texto de ayuda para entender y solucionar la alarma.
    
    Estos dos textos permiten interpolaciones, es decir, permiten sustituir valores (${}) para que el texto se adapte al dispositivo que provoca la alarma. En dichas interpolaciones, se puede poner cualquier direccionamiento de datapoint permitido. Para conocer los direccionamientos, consultar el siguiente enlace.
```
text: SCALANCE ${device[deviceInfo.deviceID].value} - ${device[deviceInfo.deviceAddress].rawValue} is disturbed
```
  - facility: valor que indica la categoría de dispositivos al que pertenece la alarma. Es un número entre 0 hasta 255.
    
    Ejemplo: si a todas las alarmas relacionadas con switches se les asigna el mismo número, al realizar una consulta, se puede conocer cuantas alarmas están afectando a esta categoría de dispositivos.
  - broadcast: valor que indica si la alarma debe ser transmitida a otro sistema (true), por ejemplo, NetinHUB, o no (false, valor por defecto). Si dicho parámetro es true, se puede configurar routing sobre la alarma.
  - routing: Consultar el enlace Timepoints.

Rangos de severidad¶

Rango	Nivel Netin	Automation Level	Representación	Significado
-1	NO SEVERITY	OK	NO COLOR	No tiene configuración de alarma.
0	OK	OK	GREEN - STEADY	Representa estado correcto.
1 - 200	LOG	INFORMATIONAL	GREY - STEADY	Evento meramente informativo, no es necesario ninguna acción.
201 - 400	INFORMATION	LowLow - WARNING	BLUE - STEADY	Información de un estado o configuración incorrecta que no afecta a la operación o funcionamiento del sistema, pero debería ser subsanado.
401 - 600	WARNING	Low - MINOR	YELLOW - STEADY	Notificación de un estado problemático. El sistema puede trabajar de una forma degradada o está cerca del fallo.
601 - 800	ERROR	High - MAJOR	RED - STEADY	Notificación de error o fallo. El sistema falla o no está trabajando con todas sus funciones.
801 - 1000	ERROR	HighHigh - CRITICAL	RED - FLASH	Notificación de fallo crítico. El sistema se encuentra en un estado en el que puede sufrir daños o afectar de forma grave el servicio.

Ejemplo 1¶

Alert config con una evaluación de severidad 600, en la que si evalID1=true o evalID2= true salta la alarma, aportando el texto: SCALANCE X204 - 10.10.50.30 is disturbed.

  - alertConfig:
    evaluations:
    - expressions:
      - expression: datapoint.rawValue == "FAULT"
        symbol: evalID1
      - expression: datapoint.rawValue == "Not reachable"
        symbol: evalID2  
      logic: evalID1 || evalID2
      severity: 600
      text: SCALANCE ${device[deviceInfo.deviceID].value} - ${device[deviceInfo.deviceAddress].rawValue} is disturbed
      textHelp: Please check the SCALANCE state or configuration
      onStartup: true
      ackable: false
      audited: false
      facility: 1
      hidden: false
      broadcast: false
      poppable: false

Ejemplo 2¶

Alert config con dos evaluaciones con severidad distinta y con texto diferente, en la que si A=true saltaría la alarma, aportando el texto: SCALANCE X204 - 10.10.50.30 is in fault. En cambio, si B=true saltaría la alarma, aportando el texto SCALANCE X204 - 10.10.50.30 is not reachable.

  - alertConfig:
    evaluations:
    - expressions:
      - expression: datapoint.rawValue == "FAULT"
        symbol: A
      logic: A
      severity: 600
      text: SCALANCE ${device[deviceInfo.deviceID].value} - ${device[deviceInfo.deviceAddress].rawValue} is in fault.
      textHelp: Please check the SCALANCE state or configuration
      onStartup: true
      ackable: false
      audited: false
      facility: 1
      hidden: false
      broadcast: false
      poppable: false
    - expressions:
      - expression: datapoint.rawValue == "Not reachable"
        symbol: B
      logic: B
      severity: 601
      text: SCALANCE ${device[deviceInfo.deviceID].value} - ${device[deviceInfo.deviceAddress].rawValue} is not reachable.
      textHelp: Please check the SCALANCE state or configuration
      onStartup: true
      ackable: false
      audited: false
      facility: 1
      hidden: false
      broadcast: false
      poppable: false

calcConfig¶

Contiene la configuración para la creación de un nuevo datapoint (calculated datapoint) basado en operaciones lógicas, aritméticas, relacionales o de cadenas de caracteres con uno o varios datapoints. Por lo tanto, al tratarse de un datapoint calculado carece de addressConfig y a este nuevo datapoint generado se le conoce como datapoint virtual.

Los datapoint que intervienen en la operación se llaman operand datapoint y se debe usar siempre el rawValue para evitar conflictos. La fórmula es evaluada y el resultado es almacenado en value.

calcConfig:
- expression: contiene la operación entre los distintos operand datapoints.

En el parámetro expression se puede utilizar cualquier direccionamiento de datapoint permitido. Además, pueden realizarse diferentes tipos de operaciones.

Ejemplo¶

  - calcConfig:
      expression: 'device[ICMP.echoRequest].rawValue ? "OK" : "Fault"'

convConfig¶

Contiene la configuración de un proceso de conversión de los valores brutos (rawValue) de un datapoint mediante expresiones lógicas, aritméticas, relacionales o de cadenas de caracteres. La fórmula es evaluada y el resultado es almacenado en value.

convConfig:
- expression: contiene la operación para realizar la conversión.

En el parámetro expression se puede utilizar cualquier direccionamiento de datapoint permitido. direccionamiento Además, pueden realizarse diferentes tipos de operaciones.

Ejemplo¶

  - convConfig:
      expresion: '${(datapoint.rawValue * 1e3 * 8) > 0.1 ? ((datapoint.rawValue * 1e3 * 8).toFixed(2) + " Mbits/s") : ((datapoint.rawValue * 1e6 * 8).toFixed(2) + " Kbits/s")}'

Info

Resaltar que convConfig sólo puede realizar operaciones con valores del propio datapoint, mientras que calcConfig puede operar con otros datapoints.

defaultValueConfig¶

Contiene la configuración para inicializar los valores de un datapoint con una constante, tanto value como rawValue.

defaultValueConfig:
- rawValue: valor con el que se quiere iniciar el rawValue de este datapoint. Se pueden usar variables de sustitución.
- Value: valor con el que se quiere iniciar el value de este datapoint. Se pueden usar variables de sustitución.
- isDefault: sirve para configurar el valor de sustitución.
  - true: el valor por defecto sólo se pone en el inicio (al arrancar).
  - false: el valor por defecto se pone cada vez que no se puede leer el dato.

Info

Esta estrategia es útil con los valores calculados. Por ejemplo: si se realiza un CalcConfig basadado en 5 variables y no han llegado todos los datos, se obtendrá un NULL; para evitar esto, se pueden configurar los valores por defecto, evitando de esta forma que salten las alarmas.

Ejemplo¶

  - defaultValueConfig:
      rawValue: "/{DCP_IPAddress}/"
      Value: "/{DCP_IPAddress}/"
      isDefault: false

unitsConfig¶

Contiene la configuración para realizar una conversión de unidades de medida de ingeniería, desde rawValue a value.

unitsConfig:
- from: unidad de la que se parte (string).
- to: unidad a la que se quiere llegar (string). No es obligatorio configurarlo.
- toBest: realiza el mejor cambio de unidades (true) o no (false).
- exclude: unidad que se quiere excluir (string), si toBest = true.

Para conocer información detallada de las unidades de las diferentes medidas que se pueden utilizar, dirigirse a símbolos.

Las medidas que se pueden utilizar son:

acceleration
angle
apparentPower
area
bitrate
charge
current
digital
each
energy
force
frequency
illuminance
length
mass
pace
partsPer
power
pressure
reactiveEnergy
reactivePower
speed
temperature
time
voltage
volume
volumeFlowRate

Ejemplo¶

  - unitsConfig:
      from: B
      to: TB
      toBest: true
      exclude: ''

valueMapConfig¶

Contiene la configuración para realizar una sustitución de los valores de un mapa, es decir, desde rawValue a value. Toma el valor de origen (rawValue=key) y lo sustituye en la representación (pantalla dispositivo) por los valores especificados en cada value.

valueMapCofig:
- map: se indica entre corchetes el conjunto de valores de origen y a sustituir que forman el mapa.
- key: valor de origen que se quiere sustituir. Puede ser:
  - STRING
  - NUMBER
  - BOOLEAN
- value: nuevo valor por el que se va a sustituir el dato original (key). Si es texto se pone entre comillas " ".

Info

Esta estrategia sirve para evitar usar el operador ternario, cuando existe una combinación compleja resulta difícil de entender.

Ejemplo¶

  - valueMapConfig:
      map:
      - key: 1
        value: 'High speed redundancy'
      - key: 2
        value: 'No redundancy'
      - key: 3
        value: 'Media redundancy protocol'
      - key: 4
        value: 'Automatic redundancy detection'

rowFilterConfig¶

Contiene la configuración que permite eliminar la fila de una tabla cuando se cumplen las condiciones definidas en expressions.

expressions: contiene tantas expression como condiciones deben cumplirse. Cada una compuesta por expression y symbol.
- expression: indica la condición cuya evaluación lógica obtiene como resultado (true o false) .
- symbol: alias identificativo asignado a cada expression.
  - logic: relaciona (utilizando symbol) las expression configuradas para construir la lógica necesaria para borrar la fila. Si el resultado de las combinaciones es true (la fila se borrará), por el contrario, si es false (no se borrará).

Ejemplo¶

  - rowFilterConfig:
    - expressions:
      - expression: datapoint.rawValue > 10
        symbol: A
      - expression: device[datapointSetId1.*.datapointId2].rawValue > 10
        symbol: B  
      logic: A && B

Info

Esta estrategia es útil, cuando se quiere eliminar la fila de una tabla estática, en la que sus valores no aportan información relevante.

Orden:¶

Netin ejecuta las anteriores estrategias en un orden establecido para evitar obtener resultados incorrectos. Agunas notas importantes a la hora de combinar los diferentes Configs son:

Todos los datapoints deben de tener commonConfig y entre los restantes pueden combinarse entre ellos, existiendo al menos uno de estos tres: adressConfig, calcConfig o defaultValueConfig.
No se pueden combinar adressConfig con CalcConfig.
DefaultValueConfig puede aparecer solo porque no tiene adress ni calculate y nunca va a cambiar, o puede estar combinado con alguno de ellos.

Ejemplo¶

Tipos de expresiones¶

Las expresiones lógicas, aritméticas, relacionales o de cadenas de caracteres, permiten a NetinDS realizar operaciones entre o sobre datapoints utilizando para ello scripts de JavaScript.

Estas expresiones se utilizan en los siguientes casos:

Propiedad expression en la configuración de alarmas.
Propiedades expression en la configuración de datapoints calculados.
Dentro de las expresiones de las plantillas (interpolaciones).

Se distinguen los siguientes tipos de operaciones:

-Operaciones de comparación: comparan sus operandos y devuelven un valor lógico en función de si la comparación es verdadera (true) o falsa (false).

  datapoint.rawValue != "5.2.0"  
  device[ifTable.*.ifIndex].rawValue != 1

-Operaciones aritméticas: toman los valores numéricos (tanto literales como variables) de sus operandos y devuelven un único resultado numérico.

  datapoint.rawValue * 3e8  
  device[ifTable.*.ifSpeed].rawValue / 10e6

-Operaciones de bit a bit: tratan a sus operandos como un conjunto de 32 bits (ceros y unos), en vez de como números decimales, hexadecimales u octales. Por ejemplo, el número decimal 9 se representa en binario como 1001. Los operadores bit a bit realizan sus operaciones en dicha representación binaria, pero devuelven un valor numérico estándar.

  datapoint.rawValue & 0xAC  
  device[systemStatus.statusWord].rawValue | 0x4F

-Operaciones lógicas: son normalmente usadas con valores booleanos; estos operadores devuelven un valor booleano.

  !datapoint.rawValue  
  datapoint.rawValue && device[ICMP.ICMPEchoRequest].rawValue

-Operaciones de cadenas de caracteres: en estas operaciones, además de los operadores de comparación que se pueden usar en cadenas de caracteres, el operador de concatenación (+) une dos valores de tipo String, devolviendo otro String correspondiente a la unión de los dos operandos.

  datapoint.rawValue + "mseg"  
  datapoint.rawValue != "5.0.1"

-Operaciones condicionales (ternario): el operador condicional ternario asigna uno de dos valores basado en una condición.

  datapoint.rawValue > 10 ? "OK" : "DISRUPTED"  
  device[cpuState.runState].rawValue ? "RUN" : "STOP"

-Operaciones relacionales: comparan sus operandos y retornan un valor booleano basado en si la comparación es verdadera.

  0 in datapoint.rawValue

-Operaciones con expresiones regulares: son patrones utilizados para encontrar una determinada combinación de caracteres dentro de una cadena de texto.

  (/6GK7343-1EX30|6GK7343-1EX21/g).test(datapoint.rawValue)  
  datapoint.rawValue.replace(/sampleText/i, "replaceText")

Además de estas operaciones, también son posibles otras funciones estándar sobre objetos:

Significado Unidades¶

Interpolación de cadenas¶

La interpolación de cadenas, permite utilizar cualquier expresión válida de JavaScript dentro de una cadena y obtener como resultado la cadena completa con la expresión evaluada.

Las partes variables utilizan la sintaxis ${ } para diferenciarse del resto de la cadena.

Estas interpolaciones se utilizan en los siguientes casos:

Propiedad text y textHelp en la configuración de alarmas.
Propiedades expression en la configuración de datapoints calculados.

Ejemplo¶

var a = 2;
var c = 5;
console.log('¡Netin se inventó hace ${a+c} años!');

// resultado => ¡Netin se inventó hace 7 años!

Info

Pasos siguientes:
Configuración de la especificación de la sección Representations.

originDataType	DataType
Integer	Integer
Octet_String	String
Gauge32	Long
String	String