WinCC OA Node.JS Manager

Introduction

Being a multi disciplinary developer, I really wanted to combine my favourite SCADA system with my favourite web stack. Node.JS and WinCC OA, in my opinion, are quite a good match. They are both event driven systems and callback based.

I have developed a Node.JS module that you can use to connect directly into WinCC OA then use the dpGet, dpSet, dpConnect, dpDisconnect and dpQuery functions directly from your JavaScript code. This opens up a world of opportunities for displaying data in a web format, interacting with WinCC OA from a web browser, or linking to any number of other systems that Node.JS can connect with.

The world is your oyster!!!

I have tested this module with 3.15 and 3.16 and works fine with both. I have not tested with 3.17.

Disclaimer

This module is currently in Beta. I have tested and it works for my solutions, but the code, to put it generously, requires some refactoring. As such I’m not at a point where I am ready to release the code publicly. However, you can download the binaries and use at your leisure.

This software comes with absolutely no warranty what so ever. Use at your own risk.

In other words, if this doesn’t work, don’t expect me to be able to help or have timely responses. I do have a day job that I need to maintain.

Future Plans

With this project, firstly I want to refactor the C++ code to make it more readable, then I will release the source as well. After that I will add more API functions. Be aware that I’m not planning on doing this any time soon. For now the code and binaries work for my use case so updates wont necessarily happen unless I need to functionality (or someone pays me to do it!!!)

Notes

The code uses both the Node.JS v8, Nan API and the WinCC OA C++ API. After you connect to WinCC OA using this module, the WinCC OA event manager can make a call to the module to disconnect and stop. This is built into the WinCC OA API code, so be aware that your Node.JS application may terminate due to calls from the event manager.

This is not a manager that you monitor through the WinCC Console. However, it will still consume 1 API addon licence. So just be aware of that.

Installation

Download compiled binaries. Extract the zip file into your project directory.

Usage

const winccoa = require('./winccoa');
winccoa.connect('-proj ExampleProject', 'nodejs');
dpGet('ExampleDP.ExampleFloat', function(err, value) {
    if(err) console.error(err);
    else console.log(value);
});

Function Reference

connect(cmd, [managerName]=’node.exe’)

Description
Connects to WinCC OA event and data manager. Must be called before any other functions can be used. This function runs synchronously.

Arguments

  • cmd: string – normal command line arguments for connecting to a project. Usually ‘-proj <project_name>’. However, all usual manager command line arguments work as per the WinCC OA documentation.
  • managerName: string – optional default: ‘node.exe’ the manager name to use. This relates directly to the WinCC OA project config file. Config parameter will be read from the section that matches this argument.

Returns
Boolean. True is connection was successful, false otherwise.

Example

winccoa.connect('-proj ExampleProject', 'NodeJSManager');

disconnect()

Description
Disconnects from WinCC OA event manager and data manager. This call will also terminate your Node.JS application.

Example

winccoa.disconnect();

dpGet(dp, [cb])

Description
Calls dpGet on the WinCC OA API and returns the value

Arguments

  • dp: string – the data point element to get
  • cb: function(err, value) – optional the callback function. Omit if you want to use a promise/async
    • err: string – description if any error occurred
    • value: any – the value of the data point element

Returns
Promise if cb is omitted, otherwise undefinded

Example

const value = await winccoa.dpGet('ExampleDP.ExampleFloat');

dpSet(dp, value, [cb])

Description
Calls dpSet on the WinCC OA API and sets the value of the data point element

Arguments

  • dp: string – the data point element to set
  • value: any – the value to set the data point element to
  • cb: function(err) – optional the callback function. Omit if you want to use a promise/async
    • err: string – description if any error occurred.

Returns
Promise if cb is omitted, otherwise undefinded

Example

await winccoa.dpSet('ExampleDP.ExampleFloat', 12.34);

dpConnect(dp, cb)

Description
Connects to a data point element and receive updates when the value changes in the Raima database. N.B. this version of dpConnect does not return the value immediately on first call, only on updates. Use dpGet if you need the value immediately.

Arguments

  • dp: string – the data point element to connect to
  • cb: function(err, value) – the callback function.
    • err: string – description if any error occurred
    • value: any – the value of the data point element as it updates

Example

function cb(err, value) {
    console.log(value);
}
winccoa.dpConnect('ExampleDP.ExampleFloat', cb);

dpDisconnect(dp, cb)

Description
Disconnects from a previous dpConnect call.

Arguments

  • dp: string – the data point element to disconnect from
  • cb: function – the callback function that was passed into the dpConnect call.

Example

winccoa.disconnect('ExampleDP.ExampleFloat', cb);

dpQuery(query, [cb])

Description
Calls the WinCC OA dpQuery API. Queries the Raima database and returns a table of the data

Arguments

  • query: string – the SQL query string
  • cb: function(err, data) – optional the callback function. Omit if you want to use a promise/async
    • err: string – description if any error occurred.
    • data: any[] – array of the results

Returns
Promise if cb is omitted, otherwise undefinded

Example

const data = await winccoa.dpQuery(`SELECT '_online.._value' FROM '*.**' WHERE _DPT="ExampleType"`);

dpElementType(dp, [cb])

Description
Gets the data type of a data point element. Return is an int from the enum list of data types in the WinCC OA API.

Arguments

  • dp: string – the data point to get the type of
  • cb: function – optionl the callback function. Omit if using promise.
    • err: string – description if any error occurred.
    • type: int – the data point type

Returns
Promise if cb is omitted, otherwise undefinded

Example

const type = await winccoa.dpElementType('ExampleDP.ExampleFloat');