Use this connector to write Node.JS code for calls into WinCC OA. You could use this for a web application that uses WinCC OA functions or any other Node.JS application. It achieves this by exposing the C++ API manager functions through JavaScript code.
This has been tested and functional with V3.15, V3.16 and V3.17 of WinCC OA only. V3.18 may work but use at your own risk.
The code connects as an API manager. You will need API manager licences for production use.
Requirements:
WinCC OA V3.15-17 installed prior
npm install winccoanodejs
Require the package in your script, then you must connect to the WinCC OA server before making and calls to WinCC OA.
const winccoanodejs = require('winccoanodejs');
if(winccoanodejs.connect('-currproj -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
const val = await winccoanodejs.dpGet('System1:ExampleDP.');
console.log(val);
- dpGet
- dpSet
- dpConnect
- dpDisconnect
- dpQuery
- dpElementType
- dpExists
- getTypeName
- dpGetDescription
- dpGetUnit
- dpGetFormat
- dpNames
Connects your Node.JS application to the WinCC OA Server
NB: This function is blocking
bool connect(string params, [string appName])
Parameter | Meaning |
---|---|
params | The command line params you would send to a manager. E.G. -proj Test -num 2 -event 192.168.1.1 -data 192.168.1.1 |
appName | optional - the application name. This will appear in the log viewer |
The function returns true if the connection was successful
const winccoanodejs = require('winccoanodejs');
if(winccoanodejs.connect('-currproj -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
Disconnects your application from the WinCC OA Server.
NB: this is the same as disconnecting a manager and the API will also quit your application
void disconnect()
const winccoanodejs = require('winccoanodejs');
if(winccoanodejs.connect('-currproj -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
winccoanodejs.disconnect();
Gets the value of a data point. This implementation can only read one data point at a time.
Promise<any> dpGet(string dpe, [function callback])
Parameter | Meaning |
---|---|
dpe | Data point attributes to be read. If no config is specified for the data point the the default of _online.._value is used |
callback | optional - a callback with the signature function(err, value). If omitted then a Promise is returned. |
If successful and the callback
variable is omitted then a Promise
is returned that can be used with async calls.
const {connect, dpGet} = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
const dp = 'System1.ExampleDP_Arg1.';
async function main() {
try {
var value = await dpGet(dp);
console.log(`${dp} value ${value}`);
} catch(err) { console.error(err); }
}
main();
Sets that value of a data point. This implementation can only write one data point at a time.
Promise<void> dpSet(string dpe, anytype value, [function callback])
Parameter | Meaning |
---|---|
dpe | Data point attributes to be written. If no config is specified for the data point the the default of _original.._value is used |
value | The value to set the data point to. If the data point type does not match the value type a cast will be attempted. |
callback | optional - a callback with the signature function(err). If omitted then a Promise is returned. |
If successful and the callback
variable is omitted then a Promise
is returned that can be used with async calls.
const {connect, dpSet} = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
const dp = 'System1.ExampleDP_Arg1.';
const value = 25.2;
async function main() {
try {
await dpSet(dp, value);
console.log(`${dp} value set to ${value}`);
} catch(err) { console.error(err); }
}
main();
Connects to a datapoint and calls a function whenever the data point value changes
Promise<any> dpConnect(string dpe, [function callback], [int maxCallCount = 0])
Parameter | Meaning |
---|---|
dpe | Data point attributes to connect to. If no config is specified for the data point the the default of _online.._value is used |
callback | optional - a callback with the signature function(err, value). This could be called multiple times until dpDisconnect is called |
maxCallCount | optional - default = 0. If set to non zero then the callback will only be called the number of times specified |
If the callback
variable is omitted then a Promise
is returned otherwise no value is returned
If the callback
variable is omitted then dpConnect will call dpDisconnect directly after the first change because the Promise cannot be
called multiple times.
When a callback is supplied the connection will persist and the function will continue to receive updates until dpDisconnect is called.
const {connect, dpConnect} = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
const dp = 'System1:ExampleDP_Arg1.';
function connectCallback(err, value) {
if(err)
return console.error(err);
console.log(`${new Date().toLocaleString()} - ${dp} value ${value}`);
}
dpConnect(dp, connectCallback);
Disconnects a data point from a previous dpConnect call
Promise<void> dpDisconnect(string dpe, function connectCallback, [function callback])
Parameter | Meaning |
---|---|
dpe | Data point attributes to disconnect from. If no config is specified for the data point the the default of _online.._value is used |
connectCallback | The callback function used in the dpConnect call |
callback | optional - a callback with the signature function(err). Will be called when dpDisconnect is complete. |
If the callback
variable is omitted then a Promise
is returned otherwise no value is returned
const {connect, dpConnect, dpDisconnect} = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
const dp = 'System1:ExampleDP_Arg1.';
function connectCallback(err, value) {
if(err)
return console.error(err);
console.log(`${new Date().toLocaleString()} - ${dp} value ${value}`);
}
dpConnect(dp, connectCallback);
setTimeout(async () => {
try {
await dpDisconnect(dp, connectCallback);
console.log(`Disconnected from ${dp}`);
} catch (err) {
console.error(err);
}
}, 10000);
Retrieves attribute values with the help of SQL-like statements. See qthelp://wincc_oa/doc/SQL/Query-05.htm in the WinCC OA Documentation for query structure.
Promise<Array> dpQuery(string query, [function callback])
Parameter | Meaning |
---|---|
query | The SQL-like query for WinCC OA |
callback | optional - a callback with the signature function(err, table). table has the results from the query in a tabular array. First row is the column headers. |
If the callback
variable is omitted then a Promise
is returned otherwise no value is returned
const {connect, dpQuery} = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
/*
Example output
[
[ '', ':_online.._value', ':_online.._stime' ],
[ 'System1:ExampleDP_Arg1.', 4, 2022-09-12T05:20:26.473Z ],
[ 'System1:ExampleDP_Rpt1.', 0, 1970-01-01T00:00:00.000Z ],
[ 'System1:ExampleDP_Rpt2.', 0, 1970-01-01T00:00:00.000Z ],
[ 'System1:ExampleDP_Arg2.', 50, 2022-09-12T04:14:21.062Z ],
[ 'System1:ExampleDP_Rpt3.', 0, 1970-01-01T00:00:00.000Z ],
[ 'System1:ExampleDP_Rpt4.', 0, 1970-01-01T00:00:00.000Z ],
[ 'System1:ExampleDP_Result.', 54, 2022-09-12T05:20:26.473Z ],
[ 'System1:ExampleDP_Trend1.', 0.947601318359375, 2022-09-12T04:14:21.062Z]
]
*/
async function main() {
try {
const table = await dpQuery(`SELECT '_online.._value', '_online.._stime' FROM '*ExampleDP*' WHERE _DPT="ExampleDP_Float"`);
console.log(table);
} catch(err) {
console.error(err);
}
}
main();
Gets the integer value for a dp elements type. Type numbers can be found in the API header file DpElementType.hxx
Promise<number> dpElementType(string element, [function callback])
Parameter | Meaning |
---|---|
element | The the datapoint element to get the type for |
callback | optional - a callback with the signature function(err, type). |
If the callback
variable is omitted then a Promise
is returned otherwise no value is returned
const {connect, dpElementType} = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
const type = await dpElementType('System1:ExampleDP_Arg1.');
console.log(type); //Output: 22
Return the type name of a data point or data point element as a string. This function is blocking.
string getTypeName(string dp, [string sys])
Parameter | Meaning |
---|---|
dp | The data point or data point element to get the type name for. |
sys | optional The name of the system to where the data point exists. This parameter is optional if you include the system in the dp parameter. E.G. System1:ExampleDP_Arg1. |
Returns the strring name of the data point. E.G. float, ExampleDP_Float
const {connect, getTypeName} = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
const typeName = getTypeName('ExampleDP_Arg1.','System1');
console.log(typeName); //OUTPUT: ExampleDP_Float
Checks if a datapoint or element exists
bool dpExists(string dp)
Parameter | Meaning |
---|---|
dp | The data point or data point element to check. If the system is ommitted from the dp then the local system is assumed. |
Returns true if the datapoint or element exists. Otherwise false.
const {connect, dpExists} = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
//OUTPUT: true false
console.log(dpExists('ExampleDP_Arg1.'), dpExists('ExampleDP_Arg0.'));
Checks a list of systems for a given datapoint. Will return the first system that it finds the data point on.
string getDpSys(string dp, Array<string> systems)
Parameter | Meaning |
---|---|
dp | The data point or data point element to check. Do not include a system prefix. |
systems | Array of systems to check in for the data point. |
Returns the system that the data point exists in. If the data point is not found in any system then an error is thrown.
const {connect, getDpSys} = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
//OUTPUT: 'System1:'
console.log(getDpSys('ExampleDP_Arg1.', ['System2:', 'System1:']));
//OUTPUT: Uncaught Error: Could not get system for DP ExampleDP_Arg0.
getDpSys('ExampleDP_Arg0.', ['System2:','System1:']);
Gets the integer user id value for a given username
int getUserId(string username)
Parameter | Meaning |
---|---|
username | The username of the user that you need to know the UserID for. |
Returns the integer value for the UserID. If the user does not exist then it returns 65535
const {connect, getUserId} = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
//OUTPUT: 0 65535
console.log(getUserId('root'), getUserId('test'));
Checks the password for a given UserID. Use getUserId if you have the Username instead of the UserID
bool checkPassword(int userId, string password)
Parameter | Meaning |
---|---|
userId | The UserID of the password to check. |
password | The password in plain text. Care when using this that the password is not transmitted over unencrypted channels |
Returns true is the password matches. False otherwise.
const {connect, checkPassword} = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
//OUTPUT: true false - only if default password for root used in example project.
//user 0 = root
console.log(checkPassword(0, ''), checkPassword(0, '1234'));
Connect to an alert value and execute a callback when the alert changes.
bool alertConnect(string alertAttr1, [string alertAttr2, ...], function callback)
Parameter | Meaning |
---|---|
alertAttr1, [alertAttr2, ...] | _alert_hdl config attributes to connect to. See _alert_hdl in documentation for valid attributes. |
callback | The callback to execute on alert changes with signature function(err, Array<any>) |
const {connect, alertConnect} = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
function cb(err, values) {
if(err) {
console.error(err);
} else {
console.log(values);
}
}
//OUTPUT: true
console.log(alertConnect(':_alert_hdl.._text', ':_alert_hdl.._act_state', cb);
//OUTPUT: when System1:ExampleDP_AlertHdl1. is set to TRUE
/*
[
'System1:ExampleDP_AlertHdl1.:_alert_hdl.._text',
'Value to 1',
'System1:ExampleDP_AlertHdl1.:_alert_hdl.._ack_type',
3
]
*/
Set attributes of alarms in a similar way to dpSet.
bool alertSet(string dpe, date alertTime, any value)
Parameter | Meaning |
---|---|
dpe | The data point element with an alert that you want to set values of. |
alertTime | The time of the alert that you want to set the value for. |
value | The value to set on the attribute |
Return true if the set was successful. False otherwise.
//This example requires ExampleDP_AlertHdl1. to be set to TRUE and unacknowledged
const {connect, alertSet, dpQuery } = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
async function main() {
const tab = await dpQuery(`SELECT ALERT '_alert_hdl.._came_time' FROM 'ExampleDP_AlertHdl1.'`);
const time = tab[1][1];
//_ack_state constants
//DPATTR_ACKTYPE_NOT = 0
//DPATTR_ACKTYPE_MULTIPLE = 1
//DPATTR_ACKTYPE_SINGLE = 2
alertSet('System1:ExampleDP_AlertHdl1.:_alert_hdl.._ack_state', time, 2);
}
main();
Get the data point description from the _common config. This function is blocking.
string dpGetDescription(string dpe)
Parameter | Meaning |
---|---|
dpe | The data point element that you want to get the description for. |
A string with the description
//This example requires you to set a description in the _common config for ExampleDP_Arg1.
const {connect, dpGetDescription } = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
//OUTPUT: Description for ExampleDP_Arg1
console.log(dpGetDescription('ExampleDP_Arg1.'));
Get the data point unit from the _common config. This function is blocking.
string dpGetUnit(string dpe)
Parameter | Meaning |
---|---|
dpe | The data point element that you want to get the units for. |
A string with the units
//This example requires you to set a unit in the _common config for ExampleDP_Arg1.
const {connect, dpGetUnit } = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
//OUTPUT: °C
console.log(dpGetUnit('ExampleDP_Arg1.'));
Get the data point format from the _common config. This function is blocking.
string dpGetFormat(string dpe)
Parameter | Meaning |
---|---|
dpe | The data point element that you want to get the format for. |
A string with the format
//This example requires you to set a format in the _common config for ExampleDP_Arg1.
const {connect, dpGetFormat } = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
//OUTPUT: %15.3f
console.log(dpGetFormat('ExampleDP_Arg1.'));
Get a list of data point names that match a pattern
Array<string> dpNames(string pattern)
Parameter | Meaning |
---|---|
pattern | The data point pattern to search for. |
Returns an array containing the data points that match the pattern
const {connect, dpNames } = require('winccoanodejs');
if(connect('-proj Example -num 2', 'my-nodejs-app'))
console.log('WinCC OA Connected');
const arr = dpNames('Example*');
console.log(arr);
/* OUTPUT
[
'System1:ExampleDP_AlertHdl1',
'System1:ExampleDP_AlertHdl2',
'System1:ExampleDP_Arg1',
'System1:ExampleDP_Arg2',
'System1:ExampleDP_BarTrend',
'System1:ExampleDP_DDE',
'System1:ExampleDP_Result',
'System1:ExampleDP_Rpt1',
'System1:ExampleDP_Rpt2',
'System1:ExampleDP_Rpt3',
'System1:ExampleDP_Rpt4',
'System1:ExampleDP_SumAlert',
'System1:ExampleDP_Trend1',
'System1:ExampleDP_bt'
]*/