ads-client 1.12.2 → 1.13.0

package/CHANGELOG.md

@@ -4,6 +4,16 @@ 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.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

@@ -29,6 +29,7 @@ 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)
@@ -336,6 +337,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.
@@ -1623,6 +1644,23 @@ 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
 
 # Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ads-client",
-  "version": "1.12.2",
+  "version": "1.13.0",
   "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.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
     }
   }
 
@@ -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