tlsupportfunctions

General

This package includes frequently used functions used by the Transformation Layer (node red). Every aspect of the package can function on its own though the use case is highly specific and it is not recommended to use this package for anything but the project it was created for. It can however be used as an inspiration for similar projects.

Usage

In your user directory, go to ".node-red". Install package with:

npm i tlsupportfunctions

In the same directory, find "settings.js". Locate the object functionGlobalContext and add the entry

"tlsupportfunctions": require('tlsupportfunctions')

to the object. Now the package can be used in any function node. At the beginning of the function node, add the line

const tls = global.get("tlsupportfunctions");

The functions implemented in the package can be used with the declared constant, for example

tls.calculateCounterIncrement(10, 8);

Implemented Functions

calculateCounterIncrement(counter, lastCounter, checkRange = 15, range = false, min = false, reset = false)

Calculates a counter increment given the current counter value (counter) and previous counter value (lastCounter).

Parameters:

• counter: current counter value (e.g. 10)
• lastCounter: previous counter value (e.g. 8)
• checkRange (optional, default 15): detection range for overflows, should always be larger than normal counter increases but only as big as necessary
• range (optional): value range of the counter, calculated as max + abs(min) (e.g. 65535)
• min (optional): the lowest possible value of the counter, usually 0 or a negative power of 2 (e.g. -32768)
• reset (optional): the value the counter takes when manually reset (e.g. 0)

counterChangedObject(msg, increment)

Returns a specifically formatted object.

Parameters:

• msg: the node red message object
• increment: the counter increment (e.g. 2)

runningStateChangedObject(msg, isRunning, faultCodes = [])

Returns a specifically formatted object.

Parameters:

• msg: the node red message object
• isRunning: boolean value whether the machine is running (e.g. true)
• faultCodes (optional, default []): array containing fault codes of the machine

messagePreprocessor(msg, dynamic_line_data, lineName, f_metadata, one_time_cyclics, contexualizer_func = false)

Updated 2023-03-10

• Code refactored and "EndOfMessage" messages added.
• optional parameter added to provide one of the added contextualizer functions (see below)

Prepares a message for later use.

Parameters:

• msg: the node red message object
• dynamic_line_data: dynamic line data stored in the flow
• lineName: line name stored in environment
• f_metadata: metadata stored in the flow
• one_time_cyclics: cyclics data stored in the flow

The function returns the following object:

{
    success: false,
    error_text: false,
    flow_dynamic_line_data: false,
    flow_one_time_cyclics: false,
    returnMsg: false
}

Example usage:

let ppmsg = tls.messagePreprocessor(  msg, 
                                flow.get("dynamic_line_data", "file"), 
                                env.get("LineName"),
                                flow.get("metadata"),
                                flow.get("one_time_cyclics"));
if(ppmsg.success){
    msg = ppmsg.returnMsg;
    flow.set("dynamic_line_data", ppmsg.flow_dynamic_line_data);
    flow.set("one_time_cyclics", ppmsg.flow_one_time_cyclics);
} else {
    node.error(ppmsg.error_text);
}

edhMsg2JSON(msg)

(Obsolete)

Converts and formats incoming messages.

Parameters:

• msg: the node red message object

Contextualizers

The transfomation layer needs some context information of the data to be processes. Therefore the messagePreprocessor is enabled to add a context to each individual tag message.

The messagePreprocessor expects a contextualizer to be a void function:

(tag, machine_metadata) => { /* adding the context to the tag */ }

Contectualizers...

• extende an existing property named Context on the tag message.
• have to flag the tag as valid for properly assigned conext information, by changing the tag property InvalidTagName to false. Invalid tags will not be processed by the transformation layer.

The Context get extended with following properties:

• Category : To categorize the tag in groups of similar concerns, e.g. status, faults, counters, etc.
• Parameter : Semantical name of the tag
• Attribute : Optional context information for further differentiation of a parameter

This version of the tlsupportfunctions provide two predefined contextualizers:

ctx_by_naming_convention_berlin

This contextualizer reads the context information from the tag.id based on the local standard. It sets the tag as valid if Category and Parameter are set.

ctx_by_metadata_whitelist

This contextualizer does a lookup in the machine_metadata property TagWhitelistAndContext. It provides a white list of supported tags with each's context values:

    TagWhitelistAndContext: {
        "This.is.tag.a": { "Category": "MSTATE", "Parameter": "CurrentState", "Attribute": "PDA" },
        "This.is.tag.b": { "Category": "MFAULT", "Parameter": "MachineStop", "Attribute": "Code" },
        "This.is.tag.c": { "Category": "COUNTER", "Parameter": "Good" }
    }

It sets the tag as valid if the tag.id exists as object in the TagWhitelistAndContext and provides context details for Category and Parameter.

Fault code handlers

These handler are providing standard functionality to maintain the a machiens fault code array base on the technical representation of machine faults.

The fault codes are maintained in an array of objects with the properties

• code : storing the numeric value of the machines fault code
• t : the timestamp as provided by the connected OPC server in milliseconds

    faultArray = [
        {code: 1234, t : 1679392604015},
        {code: 815, t : 1679350658430},
        ...
    ];

OPC Tag provides just one numeric value

A value of zero empties the array, any other value gets stored in code along with t the timestamp or replaces the existing value.

    let result = update_fault_codes_by_numeric_tag_value(fault_codes, preprocessed_tag);

OPC Tag provides a blooean flag for one fault code

The tag's context attribute provides the related fault code. Any numeric tag value greater than zero indicated the fault is set active, otherwise the fault is set inactive. Active fault codes gets added to the 'fault_codes' array if not already existing, inactive fault code gets removed from the array if existing.

    let result = update_fault_codes_by_tag_value_boolean(fault_codes, preprocessed_tag);

OPC Tag provides a bitbask based coding of multiple fault codes in one OPC tag.

(this implementation is based on a Siemens PLC representation)

The tag's context attribute provides details about the 1 up to 4 bytes sized tag value, including the start and end value of the bit rang, and optionally a mask to filter out non fault relevant bits that must be ignored. Example: 0-7-254

• 0 : lower number of the bit range
• 7 : higer number of the bit range (low and high together must be a range of 8, 15, 24 or 32)
• 254 : is the mask, masking out bit 0 as to be ignored. A tag value of 3 (0b00000011) will be masked with 254 (0b00000010), so bit 0 gets ignored. Only bit 1 is set and according to the range it represents fault code 1. (if the range would go from 8 to 15, this bit would represent the fault code 9).

All masked bit gets updated in the fault code array, for a set bit (active fault) the code get added to the fault code array, an unset bit (inactive fault), the code gets removed. This happens in decending order! That means the highest value gets updates first.

    let result = update_fault_codes_by_tag_value_bitwise_siemens(fault_codes, preprocessed_tag);

Testing

there are automated tests prepared to have a technical secification to check any code changes against.

It utilizes the mocha test framework and it is recommended to install the "Mocha Test Explorer" in VSCode for interacice code testing during development.

Installation of test framework depedencies

use the following statemnt to install all development dependencies on the development computer

npm install --save-dev

This installs the following "devDependencies" as registered in the package.json file:

• Mocha
• Chai
• Chai-things

Deployment

follow this sequence to deploy the tlsupportfunction to NPM:

• push code changes to github
• increase NPM package version number: npm version patch
• publish npm package npm publish
• push code changes to github for new version number