ads-client 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ 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.14.0] - 23.07.2022
+### Added
+- Created end-to-end testing for the library using Jest
+  - Separate PLC project required for testing: https://github.com/jisotalo/ads-client-test-plc-project
+  - Test is started using command `npm test`
+  - First version tests
+    - Connecting
+    - Reading
+    - Writing
+    - RPC methods
+
+### Changed
+- Bug fix: Value converted to Javascript variable incorrectly in some edge cases [See issue #94](https://github.com/jisotalo/ads-client/issues/94)
+
+## [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

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.
 
@@ -33,6 +38,7 @@ Check out the [node-red-contrib-ads-client](https://www.npmjs.com/package/node-r
 - [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)
@@ -83,6 +89,7 @@ Check out the [node-red-contrib-ads-client](https://www.npmjs.com/package/node-r
   * [Enabling debug from code](#enabling-debug-from-code)
   * [Enabling debugging from terminal](#enabling-debugging-from-terminal)
 - [FAQ](#faq)
+- [Automatic testing](#automatic-testing)
 - [Documentation](#documentation)
 - [License](#license)
 
@@ -406,8 +413,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')
 
@@ -417,6 +422,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
@@ -1662,6 +1745,24 @@ See https://github.com/jisotalo/ads-client/issues/82
 
 - 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.
+
+# Automatic testing
+Since version 1.14.0 the library has automatic testing using Jest. Idea is to run the tests before updates to make sure everything works OK (this should have been done much earlier...)
+
+Separate PLC project is required for testing, see https://github.com/jisotalo/ads-client-test-plc-project for more project and more info.
+
+Tests are run with command `npm test` (not in npm version, please clone this repository).
+
 # Documentation
 
 You can find the full html documentation from the project [GitHub home page](https://jisotalo.github.io/ads-client/) as well as from `./docs/` folder in the repository.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "ads-client",
-  "version": "1.13.0",
+  "version": "1.14.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": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "jest --runInBand",
     "generate-docs": "jsdoc ./src/ads-client.js ./README.md -c ./jsdoc-conf.json -d ./docs/ -t ./node_modules/docdash/"
   },
   "keywords": [
@@ -39,6 +39,7 @@
   },
   "devDependencies": {
     "docdash": "^1.2.0",
+    "jest": "^28.1.3",
     "jsdoc": "^3.6.7"
   },
   "files": [

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

@@ -888,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 {
@@ -3128,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
     }
 
     /** 
@@ -5230,8 +5230,8 @@ function _parseJsObjectToBuffer(value, dataType, objectPathStr = '', isArraySubI
 
   //Struct or array subitem - Go through each subitem 
   if ((dataType.arrayData.length === 0 || isArraySubItem) && dataType.subItems.length > 0) {
-    buffer = Buffer.alloc(dataType.offset + dataType.size)
-
+    buffer = Buffer.alloc(dataType.size)
+    
     for (const subItem of dataType.subItems) {
       //Try the find the subitem from javascript object
       let key = null
@@ -5684,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')) {