ads-client 1.12.1 → 1.13.1

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.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)
+  - [See issue #83](https://github.com/jisotalo/ads-client/issues/83)
+
 ## [1.12.1] - 17.01.2022
 ### Changed
 - Updated dependecies to latest versions 

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,6 +34,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 +342,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 +1649,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.1",
+  "version": "1.13.1",
   "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',
@@ -1011,7 +1017,7 @@ const BASE_DATA_TYPES = {
       fromBuffer: buffer => buffer.readInt32LE(0)
     },
     {
-      name: ['UDINT', 'DWORD', 'TIME', 'TIME_OF_DAY', 'BITARR32', 'UINT32'],
+      name: ['UDINT', 'DWORD', 'TIME', 'TIME_OF_DAY', 'TOD', 'BITARR32', 'UINT32'],
       adsDataType: ADS_DATA_TYPES.ADST_UINT32,
       size: 4,
       toBuffer: (value, buffer) => buffer.writeUInt32LE(value),

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
     }
   }
 
@@ -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