ads-client 1.12.2 → 1.13.2

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.13.2] - 17.05.2022
+### Changed
+- Bug fix: Incorrect parsing of ARRAY OF ARRAY, now works as should [See issue #91](https://github.com/jisotalo/ads-client/issues/91)
+- Added settings descriptions to README
+
+## [1.13.1] - 04.04.2022
+### Changed
+- Bug fix: Undefined variable `message` [See issue #89](https://github.com/jisotalo/ads-client/issues/89)
+- Updated ADS error codes with new ones [See issue #88](https://github.com/jisotalo/ads-client/issues/88)
+- Updated README
+
+## [1.13.0] - 27.02.2022
+### Added
+- Added new setting `bareClient`. If it's set, the client will only connect to the target, nothing else
+  - No system manager, symbol version, device info and upload info are read
+  - Can be used to connect to non-PLC systems such as [ads-server](https://github.com/jisotalo/ads-server) targets and other ADS supported devices
+  - Only requirement is that ADS route is available
+
+### Changed
+- Updated README
+
 ## [1.12.2] - 12.02.2022
 ### Changed
 - Bug fix: `TOD` data type was not regonized on TwinCAT 2 and TwinCAT 3 (TC3 builds <= 4020)

package/README.md

@@ -2,7 +2,7 @@
 
 
 [![npm version](https://img.shields.io/npm/v/ads-client)](https://www.npmjs.org/package/ads-client) 
-[![GitHub milestone](https://img.shields.io/github/milestones/progress-percent/jisotalo/ads-client/1)](https://github.com/jisotalo/ads-client/milestone/1)
+[![Donate](https://img.shields.io/badge/Donate-PayPal-yellow)](https://www.paypal.com/donate/?business=KUWBXXCVGZZME&no_recurring=0&currency_code=EUR)
 [![GitHub](https://img.shields.io/badge/View%20on-GitHub-brightgreen)](https://github.com/jisotalo/ads-client)
 [![License](https://img.shields.io/github/license/jisotalo/ads-client)](https://choosealicense.com/licenses/mit/)
 
@@ -13,10 +13,15 @@ Coded from scratch using [TwinCAT ADS specification](https://infosys.beckhoff.co
 There is automatically created documentation available at https://jisotalo.github.io/ads-client/
 
 # Project status
-This project is currently "ready". It's maintained actively and used in projects by the author and others.
+This project is currently "ready". It's maintained actively and used in projects by the author and others (also lot's of commercial projects)
 
 Bugs are fixed if found and new features can be added. Please let me know if you have any ideas!
 
+And if you want you can buy me a beer using PayPal :)
+
+[![Donate](https://img.shields.io/badge/Donate%20a%20beer!-PayPal-yellow)](https://www.paypal.com/donate/?business=KUWBXXCVGZZME&no_recurring=0&currency_code=EUR)
+
+
 # Using Node-RED?
 Check out the [node-red-contrib-ads-client](https://www.npmjs.com/package/node-red-contrib-ads-client) package. It's an `ads-client` wrapper for Node-RED to get the same functionality.
 
@@ -29,9 +34,11 @@ Check out the [node-red-contrib-ads-client](https://www.npmjs.com/package/node-r
 - [Enabling localhost support on TwinCAT 3](#enabling-localhost-support-on-twincat-3)
 - [IMPORTANT: Writing STRUCT variables](#important-writing-struct-variables)
 - [IMPORTANT: Things to know when using with TwinCAT 2](#important-things-to-know-when-using-with-twincat-2)
+- [Connecting to systems without PLC runtime](#connecting-to-systems-without-plc-runtime)
 - [Getting started](#getting-started)
   * [Data types used in getting started](#data-types-used-in-getting-started)
   * [Creating a new Client instance](#creating-a-new-client-instance)
+    * [Available settings](#available-settings)
   * [Connecting and disconnecting](#connecting-and-disconnecting)
   * [Reading any type PLC variable](#reading-any-type-plc-variable)
     + [Example: Reading `INT` type variable](#example-reading-int-type-variable)
@@ -336,6 +343,26 @@ await client.readSymbol('.ExampleSTRUCT') //TwinCAT 2
 This is the only one non-working feature as there are no methods in TC2.
 
 
+# Connecting to systems without PLC runtime
+
+Since version 1.13.0 it's possible to connect to systems without PLC runtime and/or system manager using `ads-client`.
+
+In previous versions, the client always checked the system state (RUN, CONFIG). However when connecting to different systems (non-PLC systems), there might be no system manager service. With default configuration this causes an error:
+```
+ClientException: Connection failed: Device system manager state read failed
+```
+
+By providing `bareClient` setting, the client connects to the router or target and nothing else. After that, the client can be used to read/write data. However, connection losses etc. need to be handled by the user.
+
+
+```js
+const client = new ads.Client({
+  targetAmsNetId: '192.168.5.131.3.1', 
+  targetAdsPort: 1002,
+  bareClient: true //NOTE
+})
+```
+
 # Getting started
 
 This chapter includes some short getting started examples. See the JSDoc [documentation](#documentation) for detailed description of library classes and methods.
@@ -385,8 +412,6 @@ END_TYPE
 
 The constructor takes settings as its parameter. Two settings are mandatory: `targetAmsNetId` and `targetAdsPort`. The first is the target PLC system AmsNetId (like *127.0.0.1.1.1* or *192.168.1.10.1.1*) and the latter is target system ADS port (*like 851 for TwinCAT 3 runtime 1*).
 
-See all settings from the [Settings documentation](https://jisotalo.github.io/ads-client/global.html#Settings)
-
 ```js
 const ads = require('ads-client')
 
@@ -396,6 +421,84 @@ const client = new ads.Client({
   targetAdsPort: 851,
 })
 ```
+### Available settings
+**REQUIRED:**
+* `targetAmsNetId`
+  * Target system AmsNetId
+  * Use `127.0.0.1.1.1` or `localhost` if connecting to a local system
+* `targetAdsPort`
+  * Target system ADS port.
+  * TwinCAT 3: 851 (1st runtime), 852 (2nd runtime) and so on
+  * TwinCAT 2: 801 (1st runtime)
+
+**Optional:**
+* `objectifyEnumerations`
+  * Default value: `true`
+  * If true, read ENUM data types are converted to objects instead of numbers, e.g. `{name: 'enumValue', value: 5}` instead of 5
+* `convertDatesToJavascript`
+  * Default value: `true`
+  * If true, PLC DT (DATE_AND_TIME) and DATE types are converted to Javascript dates
+* `readAndCacheSymbols`
+  * Default value: `false`
+  * If true, **all** PLC symbols are cached during connecting. Otherwise they are read and cached only when needed
+* `readAndCacheDataTypes`
+  * Default value: `false`
+  * If true, **all** PLC data types are cached during connecting. Otherwise they are read and cached only when needed
+* `disableSymbolVersionMonitoring`
+  * Default value: `false`
+  * If true, PLC symbol version changes aren't monitored and cached symbols and datatypes won't be updated after PLC program download
+* `routerTcpPort`
+  * Default value: `48898`
+  * Target ADS router TCP port
+* `routerAddress`
+  * Default value: `localhost`
+  * Target ADS router IP address/hostname
+* `localAddress`
+  * Default value: `system default`
+  * Local IP address to use, use this to change used network interface if required
+* `localTcpPort`
+  * Default value: `system default`
+  * Local TCP port to use for outgoing connections
+* `localAmsNetId`
+  * Default value: `AMS router provides`
+  * Local AmsNetId to use
+  * Used especially when connecting from systems without own AMS router, like Raspberry Pi
+    * See: [Connecting from any Node.js supported system to the PLC](#setup-3---connecting-from-any-nodejs-supported-system-to-the-plc)
+* `localAdsPort`
+  * Default value: `AMS router provides`
+  * Local ADS port to use 
+  * Used especially when connecting from systems without own AMS router, like Raspberry Pi
+    * See: [Connecting from any Node.js supported system to the PLC](#setup-3---connecting-from-any-nodejs-supported-system-to-the-plc)
+* `timeoutDelay`
+  * Default value: `2000`
+  * Time (milliseconds) after connecting to the router or waiting for command response is canceled to a timeout
+* `hideConsoleWarnings`
+  * Default value: `false`
+  * If true, no warnings are written to console (=nothing is **ever** written to console)
+* `autoReconnect`
+  * Default value: `true`
+  * If true and connection is lost, the client tries to reconnect automatically
+* `reconnectInterval`
+  * Default value: `2000`
+  * Time (milliseconds) how often the lost connection is tried to re-establish
+* `checkStateInterval`
+  * Default value: `1000`
+  * Time (milliseconds) how often the system manager state is read to see if connection is OK
+* `connectionDownDelay`
+  * Default value: `5000`
+  * Time (milliseconds) after no successful reading of the system manager state the connection is determined to be lost
+* `allowHalfOpen`
+  * Default value: `false`
+  * If true, connect() is successful even if no PLC runtime is found (but target and system manager are available) - Can be useful if it's ok that after connecting the PLC runtime is not immediately available (example: connecting before uploading PLC code and reading data later) - 
+  * WARNING: If true, reinitializing subscriptions might fail after connection loss.
+* `disableBigInt`
+  * Default value: `false`
+  * If true, 64-bit integer PLC variables are kept as `Buffer` objects instead of converting to Javascript `BigInt` variables (JSON.strigify and libraries that use it have no BigInt support)
+* `bareClient`
+  * Default value: `false`
+  * If true, only direct ads connection is established (no system manager)
+  * Can be used to connect to systems without PLC runtime
+  * See [Connecting to systems without PLC runtime](#connecting-to-systems-without-plc-runtime)
 
 
 ## Connecting and disconnecting
@@ -1623,6 +1726,36 @@ For example, when copying a variable name from TwinCAT online view using CTRL+C,
 
 If you have problems, try to read the variable information using `readSymbolInfo()`. The final solution is to read all data types using `readAndCacheDataTypes()` and manually finding the correct type.
 
+### ClientException: Connection failed: Device system manager state read failed
+
+This error indicates that the given AmsnetId didn't contain system manager service (port 10000). If you connect to the PLC system, there is always system manager and PLC runtime(s). However, when connecting to other systems than PLC, it might be that there is no system manager service.
+
+Solution:
+- Double check AmsNetId settings (if connecting directly to PLC)
+- [Set `bareClient` setting to skip all system manager and PLC runtime checks](#connecting-to-systems-without-plc-runtime) (version 1.13.0 ->)
+
+### Connection failed (error EADDRNOTAVAIL)
+This could happen if you have manually provided `localAddress` or `localTcpPort` that don't exist.
+For example, setting localAddress to 192.168.10.1 when the computer has only ethernet interface with IP 192.168.1.1.
+
+See https://github.com/jisotalo/ads-client/issues/82
+
+### Problems running ads-client with docker
+
+- EADDRNOTAVAIL: See above and https://github.com/jisotalo/ads-client/issues/82
+
+### How to connect to PLC that is in CONFIG mode?
+As default, the ads-client checks if the target has PLC runtime at given port. However, when target system manager is at config mode, there is none. The client will throw an error during connecting.
+
+`Target and system manager found but couldn't connect to the PLC runtime (see settings allowHalfOpen and bareClient)`
+
+You can disable the check by providing setting `allowHalfOpen: true`. After that, it's possible to start the PLC by `setSystemManagerToRun()`. However, when using this setting internal subscription like symbol version etc. might not work properly.
+
+Another option is to use setting `bareClient: true` (since v.1.13.0). However, when using this option, the ads-client does not handle anything automatically - it's just a bare client (duh).
+
+I would suggest to use ads-client normally without any special settings. If the target is at config mode, use separate client instance to start it, and the again the normal instance to connect to a running system. This way the client works the best.
+
+
 
 # Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ads-client",
-  "version": "1.12.2",
+  "version": "1.13.2",
   "description": "Beckhoff TwinCAT ADS client library for Node.js (unofficial). Connects to Beckhoff TwinCAT automation systems using ADS protocol.",
   "main": "./src/ads-client.js",
   "scripts": {

package/src/ads-client-ads.js

@@ -352,6 +352,8 @@ const ADS_ERROR = {
   26: 'TCP send error',
   27: 'Host unreachable',
   28: 'Invalid AMS fragment',
+  29: 'TLS send error – secure ADS connection failed.',
+  30: 'Access denied – secure ADS access denied.',
   1280: 'No locked memory can be allocated',
   1281: 'The size of the router memory could not be changed',
   1282: 'The mailbox has reached the maximum number of possible messages. The current sent message was rejected',
@@ -363,6 +365,9 @@ const ADS_ERROR = {
   1288: 'The maximum number of Ports reached',
   1289: 'Invalid port',
   1290: 'TwinCAT Router not active',
+  1291: 'The mailbox has reached the maximum number for fragmented messages.',
+  1292: 'A fragment timeout has occurred.',
+  1293: 'The port is removed.',
   1792: 'General device error',
   1793: 'Service is not supported by server',
   1794: 'Invalid index group',
@@ -420,6 +425,7 @@ const ADS_ERROR = {
   1862: 'Error in win32 subsystem',
   1863: 'Invalid client timeout value',
   1864: 'Ads-port not opened',
+  1865: 'No AMS address.',
   1872: 'Internal error in ads sync',
   1873: 'Hash table overflow',
   1874: 'Key not found in hash',

package/src/ads-client.js

@@ -74,6 +74,7 @@ class Client extends EventEmitter {
    * @property {number} [connectionDownDelay=5000] - Time (milliseconds) after no successful reading of the system manager state the connection is determined to be lost - Optional (**default**: 5000 ms)
    * @property {boolean} [allowHalfOpen=false] - If true, connect() is successful even if no PLC runtime is found (but target and system manager are available) - Can be useful if it's ok that after connect() the PLC runtime is not immediately available (example: connecting before uploading PLC code and reading data later) - WARNING: If true, reinitializing subscriptions might fail after connection loss.
    * @property {boolean} [disableBigInt=false] - If true, 64 bit integer PLC variables are kept as Buffer objects instead of converting to Javascript BigInt variables (JSON.strigify and libraries that use it have no BigInt support)
+   * @property {boolean} [bareClient=false] - If true, only direct ads connection is established (no system manager etc) - Can be used to connect to systems without PLC runtimes etc.
    */
 
 
@@ -102,7 +103,8 @@ class Client extends EventEmitter {
       checkStateInterval: 1000,
       connectionDownDelay: 5000,
       allowHalfOpen: false,
-      disableBigInt: false
+      disableBigInt: false,
+      bareClient: false
     }
   }
 
@@ -886,7 +888,7 @@ class Client extends EventEmitter {
       } catch (err) {
         return reject(new ClientException(this, 'readSymbol()', `Reading symbol ${variableName} failed: Reading data type failed`, err))
       }
-
+      
       //4. Parse the data to javascript object
       let data = {}
       try {
@@ -3126,7 +3128,7 @@ class ClientException extends Error {
     if (typeof Error.captureStackTrace === 'function') {
       Error.captureStackTrace(this, this.constructor)
     } else {
-      this.stack = (new Error(message)).stack
+      this.stack = (new Error(messageOrError)).stack
     }
 
     /** 
@@ -3396,43 +3398,45 @@ function _connect(isReconnecting = false) {
       this._internals.socketErrorHandler = _onSocketError.bind(this)
       socket.on('error', this._internals.socketErrorHandler)
 
-      try {
-        //Try to read system manager state - If it's OK, connection is successful to the target
-        await this.readSystemManagerState()
-        _systemManagerStatePoller.call(this)
-
-      } catch (err) {
+      if (this.settings.bareClient !== true) {
         try {
-          await _disconnect.call(this, false, isReconnecting)
+          //Try to read system manager state - If it's OK, connection is successful to the target
+          await this.readSystemManagerState()
+          _systemManagerStatePoller.call(this)
+
         } catch (err) {
-          debug(`_connect(): Reading target system manager failed -> Connection closed`)
+          try {
+            await _disconnect.call(this, false, isReconnecting)
+          } catch (err) {
+            debug(`_connect(): Reading target system manager failed -> Connection closed`)
+          }
+          this.connection.connected = false
+
+          return reject(new ClientException(this, '_connect()', `Connection failed: ${err.message}`, err))
         }
-        this.connection.connected = false
 
-        return reject(new ClientException(this, '_connect()', `Connection failed: ${err.message}`, err))
-      }
 
+        try {
+          await _reInitializeInternals.call(this)
 
-      try {
-        await _reInitializeInternals.call(this)
+        } catch (err) {
+          if (this.settings.allowHalfOpen !== true) {
+            try {
+              await _disconnect.call(this, false, true)
+            } catch (err) {
+              debug(`_connect(): Connecting to target PLC runtime failed -> Connection closed`)
+            }
+            this.connection.connected = false
 
-      } catch (err) {
-        if (this.settings.allowHalfOpen !== true) {
-          try {
-            await _disconnect.call(this, false, true)
-          } catch (err) {
-            debug(`_connect(): Connecting to target PLC runtime failed -> Connection closed`)
+            return reject(new ClientException(this, '_connect()', `Target and system manager found but couldn't connect to the PLC runtime (see settings allowHalfOpen and bareClient): ${err.message}`, err))
           }
-          this.connection.connected = false
 
-          return reject(new ClientException(this, '_connect()', `Target and system manager found but couldn't connect to the PLC runtime (see setting allowHalfOpen): ${err.message}`, err))
+          //Todo: Redesign this
+          if (this.metaData.systemManagerState.adsState !== ADS.ADS_STATE.Run)
+            _console.call(this, `WARNING: Target is connected but not in RUN mode (mode: ${this.metaData.systemManagerState.adsStateStr}) - connecting to runtime (ADS port ${this.settings.targetAdsPort}) failed`)
+          else
+            _console.call(this, `WARNING: Target is connected but connecting to runtime (ADS port ${this.settings.targetAdsPort}) failed - Check the port number and that the target system state (${this.metaData.systemManagerState.adsStateStr}) is valid.`)
         }
-
-        //Todo: Redesign this
-        if (this.metaData.systemManagerState.adsState !== ADS.ADS_STATE.Run)
-          _console.call(this, `WARNING: Target is connected but not in RUN mode (mode: ${this.metaData.systemManagerState.adsStateStr}) - connecting to runtime (ADS port ${this.settings.targetAdsPort}) failed`)
-        else
-          _console.call(this, `WARNING: Target is connected but connecting to runtime (ADS port ${this.settings.targetAdsPort}) failed - Check the port number and that the target system state (${this.metaData.systemManagerState.adsStateStr}) is valid.`)
       }
 
       //Listening connection lost events
@@ -5680,8 +5684,8 @@ function _getDataTypeRecursive(dataTypeName, firstLevel = true, size = null) {
       const arrayType = await _getDataTypeRecursive.call(this, dataType.type, false)
 
       parsedDataType = arrayType
-      parsedDataType.arrayData = dataType.arrayData
-
+      //Combining array information (for ARRAY OF ARRAY support)
+      parsedDataType.arrayData = dataType.arrayData.concat(parsedDataType.arrayData)
 
       //If the data type has flag "DataType" and it's enum
     } else if (dataType.flagsStr.includes('DataType') && dataType.flagsStr.includes('EnumInfos')) {