- Source:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
Called when device status has changed (_subcribeToPlcRuntimeStateChanges)
(async, static) _onRouterStateChanged(data)
- Source:
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:
Event listener for socket errors. Just calling the _onConnectionLost handler.
(async, static) _onSymbolVersionChanged(data)
- Source:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
Initializes internal subscriptions and caches symbols/datatypes if required
Throws:
-
If failed, error is thrown
- Type
- Error
(async, static) _reInitializeSubscriptions()
- Source:
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:
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:
Event listener for socket.on('data')
Adds received data to the receive buffer
(static) _socketWrite(data)
- Source:
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:
Subscribes to PLC runtime state changes
(static) _subscribe(target, callback, settings) → {Promise.<object>}
- Source:
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:
Subscribes to symbol version changes
Symbol version is changed for example during PLC program update
(static) _systemManagerStatePoller()
- Source:
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:
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:
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:
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:
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) |