_LibraryInternals - ads-client.js | Beckhoff TwinCAT ADS client library for Node.js (unofficial)

Source:

ads-client.js, line 3260

Libray internal methods are documented inside a virtual namespace _LibraryInternals.

These methods are not meant for end-user and they are not available through module exports.

Methods

(static) _amsNetIdStrToByteArray(byteArray) → {array}

Source:

ads-client.js, line 6875

Helper: Converts AmsNetId string to byte array

Parameters:

Name	Type	Description
`byteArray`	string	String that represents an AmsNetId

Returns:

AmsNetId as array

Type: array

(static) _byteArrayToAmsNetIdStr(byteArray) → {string}

Source:

ads-client.js, line 6859

Helper: Converts byte array (Buffer) to AmsNetId string

Parameters:

Name	Type	Description
`byteArray`	Buffer \| array	Buffer/array that contains AmsNetId bytes

Returns:

AmsNetId as string

Type: string

(static) _checkReceivedData()

Source:

ads-client.js, line 5819

Checks received data buffer for full AMS packets. If full packet is found, it is parsed and handled.

Calls itself recursively if multiple packets available. Added also setImmediate calls to prevent event loop from blocking

(static) _clearTimer(timerObject)

Source:

ads-client.js, line 4015

Clears given object timer if it's available and increases the id

Parameters:

Name	Type	Description
`timerObject`	object	Timer object {id, timer}

(static) _connect(isReconnectingopt) → {Promise.<object>}

Source:

ads-client.js, line 3284

Connects to the target system using pre-defined Client::settings (at constructor or manually given)

Parameters:

Name	Type	Attributes	Default	Description
`isReconnecting`	boolean	<optional>	`false`	If true, the _connect() call is made during reconnection (-> affects disconnect() calls if connecting fails)

Returns:

Returns a promise (async function)

If resolved, client is connected successfully and connection info is returned (object)
If rejected, something went wrong and error info is returned (object)

Type: Promise.<object>

(static) _console(str)

Source:

ads-client.js, line 6711

Writes given message to console if settings.hideConsoleWarnings is false

Parameters:

Name	Type	Description
`str`	string	Message to console.log()

(static) _createAmsHeader(packet) → {Buffer}

Source:

ads-client.js, line 6608

Creates an AMS header from given packet

Parameters:

Name	Type	Description
`packet`	object	Object containing the full AMS/TCP packet

Returns:

Created AMS header as a (byte) Buffer

Type: Buffer

(static) _createAmsTcpHeader(packet, amsHeader) → {Buffer}

Source:

ads-client.js, line 6676

Creates an AMS/TCP header from given packet and AMS header

Parameters:

Name	Type	Description
`packet`	object	Object containing the full AMS/TCP packet
`amsHeader`	Buffer	Buffer containing the previously created AMS header

Returns:

Created AMS/TCP header as a (byte) Buffer

Type: Buffer

(static) _createAmsTcpRequest(packet) → {Buffer}

Source:

ads-client.js, line 6572

Creates an AMS/TCP request from given packet

Parameters:

Name	Type	Description
`packet`	object	Object containing the full AMS/TCP packet

Returns:

Full created AMS/TCP request as a (byte) Buffer

Type: Buffer

(static) _deepMergeObjects(isCaseSensitive, target, …sources) → {object}

Source:

ads-client.js, line 6745

Helper: Marges objects together recursively. Used for example at writeSymbol() to combine active values and new (uncomplete) object values

Based on https://stackoverflow.com/a/34749873/8140625 by Salakar and https://stackoverflow.com/a/49727784/8140625

Later modified to work with in both case-sensitive and case-insensitive ways (as the PLC is case-insensitive too). Also fixed isObjectOrArray to return true only when input is object literal {} or array (https://stackoverflow.com/a/16608074/8140625)

Parameters:

Name	Type	Attributes	Description
`isCaseSensitive`	boolean		True = Object keys are merged case-sensitively --> target['key'] !== target['KEY'], false = case-insensitively
`target`	object		Target object to copy data to
`sources`	object	<repeatable>	Source objects to copy data from

Returns:

Merged object

Type: object

(static) _disconnect(forceDisconnectopt, isReconnectingopt) → {Promise.<object>}

Source:

ads-client.js, line 3501

Unsubscribes all notifications, unregisters ADS port from router (if it was registered) and disconnects target system and ADS router

Parameters:

Name	Type	Attributes	Default	Description
`forceDisconnect`	boolean	<optional>	`false`	If true, the connection is dropped immediately (default = false)
`isReconnecting`	boolean	<optional>	`false`	If true, _disconnect() call is made during reconnecting

Returns:

Returns a promise (async function)

If resolved, disconnect was successful
If rejected, connection is still closed but something went wrong during disconnecting and error info is returned

Type: Promise.<object>

(static) _getDataTypeInfo(dataTypeName) → {Promise.<object>}

Source:

ads-client.js, line 5773

Returns data type information for a data type. NOTE: Returns only the upmost level info, not subitems of subitems (not recursively for the whole data type). Use _getDataTypeRecursive() to receive the whole type

First looks in the cache, if not found, reads it from the PLC

Parameters:

Name	Type	Description
`dataTypeName`	string	Data type name in the PLC - Example: 'INT', 'E_SomeEnum', 'ST_SomeStruct' etc.

Returns:

Returns a promise (async function)

If resolved, data type is returned (object)
If rejected, reading failed and error info is returned (object)

Type: Promise.<object>

(static) _getDataTypeRecursive(dataTypeName, firstLevelopt, sizeopt) → {Promise.<object>}

Source:

ads-client.js, line 5588

Parses full data type information recursively and returns it as object

Parameters:

Name	Type	Attributes	Default	Description
`dataTypeName`	string			Data type name in the PLC - Example: 'INT', 'E_SomeEnum', 'ST_SomeStruct' etc.
`firstLevel`	boolean	<optional>	`true`	DO NOT ASSIGN MANUALLY True if this is the first recursion / top level of the data type
`size`	number	<optional>	`null`	The size of the data type. This is used if we are connected to older runtime that doesn't provide base data type info -> we need to know the size at least in some cases

Returns:

Returns a promise (async function)

If resolved, data type is returned (object)
If rejected, reading failed and error info is returned (object)

Type: Promise.<object>

(async, static) _onAdsCommandReceived(packet)

Source:

ads-client.js, line 6312

Handles incoming ADS commands

Parameters:

Name	Type	Description
`packet`	object	Fully parsed AMS/TCP packet, includes AMS/TCP header, AMS header and ADS data *

(async, static) _onAmsTcpPacketReceived(packet)

Source:

ads-client.js, line 6215

Handles the parsed AMS/TCP packet and actions/callbacks etc. related to it.

Parameters:

Name	Type	Description
`packet`	object	Fully parsed AMS/TCP packet, includes AMS/TCP header and if available, also AMS header and ADS data *

(async, static) _onConnectionLost(socketFailure)

Source:

ads-client.js, line 3935

Called when connection to the remote is lost

Parameters:

Name	Type	Default	Description
`socketFailure`	boolean	`false`	If true, connection was lost due socket/tcp problem -> Just destroy the socket

(async, static) _onPlcRuntimeStateChanged()

Source:

ads-client.js, line 4456

Called when device status has changed (_subcribeToPlcRuntimeStateChanges)

(async, static) _onRouterStateChanged(data)

Source:

ads-client.js, line 4418

Called when local AMS router status has changed (Router notification received) For example router state changes when local TwinCAT changes from Config to Run state and vice-versa

Parameters:

Name	Type	Description
`data`		Buffer that contains the new router state

(async, static) _onSocketError()

Source:

ads-client.js, line 3918

Event listener for socket errors. Just calling the _onConnectionLost handler.

(async, static) _onSymbolVersionChanged(data)

Source:

ads-client.js, line 4218

Called when PLC symbol version is changed (_subscribeToSymbolVersionChanges())

Parameters:

Name	Type	Description
`data`		Buffer that contains the new symbol version

(static) _parseAdsData(data) → {object}

Source:

ads-client.js, line 6025

Parses ADS data from given (byte) Buffer. Uses packet.ams to determine the ADS command

Parameters:

Name	Type	Description
`data`	Buffer	Buffer that contains data for a single ADS packet (without AMS/TCP header and AMS header)

Returns:

Object that contains the parsed ADS data

Type: object

(static) _parseAdsNotification(data) → {object}

Source:

ads-client.js, line 6394

Parses received ADS notification data (stamps) from given (byte) Buffer

Parameters:

Name	Type	Description
`data`	Buffer	Buffer that contains ADS notification stamp data

Returns:

Object that contains the parsed ADS notification

Type: object

(static) _parseAmsHeader(data) → {object}

Source:

ads-client.js, line 5943

Parses an AMS header from given (byte) Buffer

Parameters:

Name	Type	Description
`data`	Buffer	Buffer that contains data for a single AMS packet (without AMS/TCP header)

Returns:

Object {ams, data}, where ams is the parsed AMS header and data is rest of the data

Type: object

(static) _parseAmsTcpHeader(data) → {object}

Source:

ads-client.js, line 5899

Parses an AMS/TCP header from given (byte) Buffer

Parameters:

Name	Type	Description
`data`	Buffer	Buffer that contains data for a single full AMS/TCP packet

Returns:

Object {amsTcp, data}, where amsTcp is the parsed header and data is rest of the data

Type: object

(async, static) _parseAmsTcpPacket(data)

Source:

ads-client.js, line 5862

Parses an AMS/TCP packet from given (byte) Buffer and then handles it

Parameters:

Name	Type	Description
`data`	Buffer	Buffer that contains data for a single full AMS/TCP packet

(async, static) _parseDataType(data) → {object}

Source:

ads-client.js, line 4703

Parses data type information from given (byte) Buffer. Recursively parses all sub types also

Parameters:

Name	Type	Description
`data`	Buffer	Buffer object that contains the data

Returns:

Returns the data type information as object

Type: object

(static) _parseJsObjectToBuffer(value, dataType, objectPathStropt, isArraySubItemopt) → {Buffer}

Source:

ads-client.js, line 5240

Recursively parses given object to (byte) Buffer for PLC using data type information

Parameters:

Name	Type	Attributes	Default	Description
`value`	object			Object containing the data
`dataType`	object			Data type information object, that corresponds to the given value and the PLC type
`objectPathStr`	string	<optional>		DO NOT ASSIGN MANUALLY Object path that is being parsed (eg. 'SomeStruct.InnerStruct.SomeValue') for debugging.
`isArraySubItem`	boolean	<optional>	`false`	DO NOT ASSIGN MANUALLY True if the object that is being parsed is an array subitem

Returns:

Returns a Buffer that contains the data ready for PLC

Type: Buffer

(static) _parseJsVariableToPlc(value, dataType, dataBuffer)

Source:

ads-client.js, line 5361

Parses given javascript variable to (byte) Buffer for PLC

Parameters:

Name	Type	Description
`value`	object	Variable containing the data
`dataType`	object	Data type information object, that corresponds to the given value and the PLC type
`dataBuffer`	Buffer	Target Buffer where that data is saved (used as reference so is the output also)

(static) _parsePlcDataToObject(dataBuffer, dataType, isArraySubItemopt) → {object}

Source:

ads-client.js, line 5406

Recursively parses given (byte) Buffer to javascript object using data type information

Parameters:

Name	Type	Attributes	Default	Description
`dataBuffer`	Buffer			Buffer that contains the PLC data
`dataType`	object			Data type information object, that corresponds to the given value and the PLC type
`isArraySubItem`	boolean	<optional>	`false`	DO NOT ASSIGN MANUALLY True if the buffer that is being parsed is an array subitem

Returns:

Parsed data as Javascript object

Type: object

(static) _parsePlcVariableToJs(dataBuffer, dataType) → {object}

Source:

ads-client.js, line 5489

Parses javascript variable from given (byte) Buffer using data type information

Parameters:

Name	Type	Description
`dataBuffer`	Buffer	Target Buffer where that data is saved (used as reference so is the output also)
`dataType`	object	Data type information object, that corresponds to the given value and the PLC type

Returns:

Parsed variable

Type: object

(static) _parseSymbolInfo(data) → {object}

Source:

ads-client.js, line 5044

Parses symbol information from given (byte) Buffer

Parameters:

Name	Type	Description
`data`	Buffer	Buffer object that contains the data Note: The data should not contain the first 4 bytes of symbol entry data length, it should be already parsed

Returns:

Returns the symbol information as object

Type: object

(static) _readDataTypeInfo(dataTypeName) → {Promise.<object>}

Source:

ads-client.js, line 5527

Reads data type information from PLC for given data type

Parameters:

Name	Type	Description
`dataTypeName`	string	Data type name in the PLC - Example: 'INT', 'E_SomeEnum', 'ST_SomeStruct' etc.

Returns:

Returns a promise (async function)

If resolved, reading was successful and parsed data type information is returned (object)
If rejected, reading failed and error info is returned (object)

Type: Promise.<object>

(static) _readSymbolInfo(variableName) → {Promise.<object>}

Source:

ads-client.js, line 5179

Reads symbol information from PLC for given variable

Parameters:

Name	Type	Description
`variableName`	string	Variable name in the PLC (full path) - Example: 'MAIN.SomeStruct.SomeValue'

Returns:

Returns a promise (async function)

If resolved, reading was successful and parsed symbol information is returned (object)
If rejected, reading failed and error info is returned (object)

Type: Promise.<object>

(static) _reconnect(forceDisconnectopt, isReconnectingopt) → {Promise.<object>}

Source:

ads-client.js, line 3615

Disconnects and reconnects again. Subscribes again to all active subscriptions. To prevent subscribing, call unsubscribeAll() before reconnecting.

Parameters:

Name	Type	Attributes	Default	Description
`forceDisconnect`	boolean	<optional>	`false`	If true, the connection is dropped immediately (default = false)
`isReconnecting`	boolean	<optional>	`false`	If true, _reconnect() call is made during reconnecting

Returns:

Returns a promise (async function)

If resolved, reconnecting was successful
If rejected, reconnecting failed and error info is returned

Type: Promise.<object>

(static) _registerAdsPort() → {Promise.<object>}

Source:

ads-client.js, line 3685

Registers a new ADS port from used AMS router

Principe is from .NET library TwinCAT.Ads.dll

Returns:

Returns a promise (async function)

If resolved, registering a port was successful and local AmsNetId and ADS port are returned (object)
If rejected, registering failed and error info is returned (object)

Type: Promise.<object>

(async, static) _reInitializeInternals()

Source:

ads-client.js, line 4039

Initializes internal subscriptions and caches symbols/datatypes if required

Throws:

If failed, error is thrown
Type Error

(async, static) _reInitializeSubscriptions()

Source:

ads-client.js, line 4074

Reinitializes user-made subscriptions (not internal ones)

Throws:

If failed, array of errors is thrown
Type Error

(static) _sendAdsCommand(adsCommand, adsData, targetAdsPortopt, targetAmsNetIdopt) → {Promise.<object>}

Source:

ads-client.js, line 6469

Sends an ADS command with given data to the PLC

Parameters:

Name	Type	Attributes	Default	Description
`adsCommand`	number			ADS command to send (see ADS.ADS_COMMAND)
`adsData`	Buffer			Buffer object that contains the data to send
`targetAdsPort`	number	<optional>	`null`	Target ADS port (optional) - default is this.settings.targetAdsPort
`targetAmsNetId`	string	<optional>	`null`	Target AmsNetID (optional) - default is this.settings.targetAmsNetId

Returns:

Returns a promise (async function)

If resolved, command was sent successfully and response was received. The received reponse is parsed and returned (object)
If rejected, sending, receiving or parsing failed and error info is returned (object)

Type: Promise.<object>

(static) _socketReceive()

Source:

ads-client.js, line 4151

Event listener for socket.on('data')

Adds received data to the receive buffer

(static) _socketWrite(data)

Source:

ads-client.js, line 4126

Writes given data buffer to the socket

Just a simple wrapper for socket.write()

Parameters:

Name	Type	Description
`data`		Buffer to write

(static) _subcribeToPlcRuntimeStateChanges()

Source:

ads-client.js, line 4377

Subscribes to PLC runtime state changes

(static) _subscribe(target, callback, settings) → {Promise.<object>}

Source:

ads-client.js, line 4512

Subscribes to variable value change notifications

Parameters:

Name	Type	Description
`target`	string \| object	Variable name in the PLC (full path, example: 'MAIN.SomeStruct.SomeValue') OR symbol object containing {indexGroup, indexOffset, size}
`callback`	subscriptionCallback	Callback function that is called when notification is received
`settings`	subscriptionSettings	Settings object for subscription

Returns:

Returns a promise (async function)

If resolved, subscribing is successful and notification data is returned (object)
If rejected, subscribing failed and error info is returned (object)

Type: Promise.<object>

(static) _subscribeToSymbolVersionChanges()

Source:

ads-client.js, line 4182

Subscribes to symbol version changes

Symbol version is changed for example during PLC program update

(static) _systemManagerStatePoller()

Source:

ads-client.js, line 4292

Starts a poller that reads system manager state to see if connection is ok and if the manager state has changed

(static) _trimPlcString(plcString) → {string}

Source:

ads-client.js, line 6833

Helper: Trims the given PLC string until en mark (\0, 0 byte) is found

Parameters:

Name	Type	Description
`plcString`	string	String to trim

Returns:

Trimmed string

Type: string

(static) _unregisterAdsPort() → {Promise.<object>}

Source:

ads-client.js, line 3781

Unregisters previously registered ADS port from AMS router

Principe is from .NET library TwinCAT.Ads.dll

Returns:

Returns a promise (async function)

In all cases this is resolved, ADS port is unregistered

Type: Promise.<object>

(static) _unsubscribeAllInternals() → {Promise.<object>}

Source:

ads-client.js, line 4654

Unsubscribes all internal (library) subscriptions

Returns:

Returns a promise (async function)

If resolved, subscribing from all was successful and number of unsubscribed notifications is returned (object)
If rejected, subscribing failed for some of the notifications, number of successful, number of failed and error info are returned (object)

Type: Promise.<object>

Type Definitions

subscriptionSettings

Source:

ads-client.js, line 4490

Properties:

Name	Type	Attributes	Description
`transmissionMode`	number		How the PLC checks for value changes (Cyclic or on-change - ADS.ADS_TRANS_MODE)
`maximumDelay`	number		When subscribing, a notification is sent after this time even if no changes (milliseconds)
`cycleTime`	number		How often the PLC checks for value changes (milliseconds)
`targetAdsPort`	number	<optional>	Target ADS port, optional.
`internal`	boolean	<optional>	If true, the subscription is library internal (e.g. symbol version change notification)