ads-client 1.14.1 → 1.14.3

package/CHANGELOG.md

@@ -4,13 +4,44 @@ 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.3] - 23.09.2023
+### Changed
+- Bug fix: Some TwinCAT 2 devices (such as BK9050) do not send data length if answering with error code
+  - This caused `RangeError: Index out of range` exception as there wasn't enough bytes received
+  - See [issue #116](https://github.com/jisotalo/ads-client/issues/116)
+- Bug fix: If using older Node.js versions such as 8.x, connection lost could have caused unhandled exception
+  - Reason was `catch {}` which isn't supported in old versions
+  - See [issue #116](https://github.com/jisotalo/ads-client/issues/116)
+
+### Added
+- Updated readme to include information about TypeScript types
+  - Thanks to [Christian Rishøj](https://github.com/crishoj)
+- Updated readme with FAQ about TwinCAT 2 low-end devices
+- Updated readme about v2 development
+- Added option to run tests with usermode runtime AmsNetId (`192.168.4.1.1.1`) instead of localhost (`npm run test-um`)
+
+## [1.14.2] - 02.05.2023
+### Changed
+- Bug fix: `ADS_DATA_TYPE_FLAGS` (`dataType.flags`) were parsed incorrectly. 
+  - See [issue #109](https://github.com/jisotalo/ads-client/issues/109)
+  - Thank you [Michael Croes](https://github.com/mycroes) for contribution!
+- Bug fix: If calling `unsubcribeAll()` when client is already unsubcribing and disconnecting, an error might be thrown
+  - See [issue #103](https://github.com/jisotalo/ads-client/issues/103#issuecomment-1450640160)
+- Bug fix: Check that subscription callback exists before calling it
+  - Fixes unecessary error if receiving notification data (for subscription) but it's being unsubscribed at the same time
+- Bump json5 from 2.2.1 to 2.2.3
+  - See [pull request 101](https://github.com/jisotalo/ads-client/pull/101)
+  - Not used in production code, only when running tests
+
+### Added
+- New test for [issue #103](https://github.com/jisotalo/ads-client/issues/103)
+
 ## [1.14.1] - 13.09.2022
 ### Changed
 - Bug fix: Connecting to local router failed with ECONNREFUSED error on Node.js version 17 and newer
   - See [https://github.com/nodejs/node/issues/40702](https://github.com/nodejs/node/issues/40702)
   - Fixed by using `127.0.0.1` instead of `localhost`
 
-
 ## [1.14.0] - 23.07.2022
 ### Added
 - Created end-to-end testing for the library using Jest

package/README.md

@@ -2,7 +2,7 @@
 
 
 [![npm version](https://img.shields.io/npm/v/ads-client)](https://www.npmjs.org/package/ads-client) 
-[![Donate](https://img.shields.io/badge/Donate-PayPal-yellow)](https://www.paypal.com/donate/?business=KUWBXXCVGZZME&no_recurring=0&currency_code=EUR)
+[![Donate](https://img.shields.io/badge/Support-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/)
 
@@ -10,16 +10,19 @@ Beckhoff TwinCAT ADS client library for Node.js (unofficial). Connects to Beckho
 
 Coded from scratch using [TwinCAT ADS specification](https://infosys.beckhoff.com/content/1033/tc3_ads_intro/116157835.html?id=124964102706356243) and [Beckhoff.TwinCAT.Ads nuget package](https://www.nuget.org/packages/Beckhoff.TwinCAT.Ads/5.0.0-preview6). Inspiration from similar projects like [node-ads](https://www.npmjs.com/package/node-ads), [beckhoff-js](https://www.npmjs.com/package/beckhoff-js) and [iecstruct](https://www.npmjs.com/package/iecstruct).
 
-There is automatically created documentation available at https://jisotalo.github.io/ads-client/
+There is automatically created documentation available at https://jisotalo.fi/ads-client/
 
 # Project status
 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 :)
+If you want to support my work, you can do it using PayPal. I can provide you support in exchange.
 
-[![Donate](https://img.shields.io/badge/Donate%20a%20beer!-PayPal-yellow)](https://www.paypal.com/donate/?business=KUWBXXCVGZZME&no_recurring=0&currency_code=EUR)
+[![Donate](https://img.shields.io/badge/Support%20my%20work!-PayPal-yellow)](https://www.paypal.com/donate/?business=KUWBXXCVGZZME&no_recurring=0&currency_code=EUR)
+
+## Version 2
+Version 2 is under development in [`v2-dev`](https://github.com/jisotalo/ads-client/tree/v2-dev) branch. It's written in TypeScript (including all types!) and will also be more optimized. At the moment basic functions *might*  work but it's not ready for production use.
 
 
 # Using Node-RED?
@@ -101,6 +104,13 @@ Install the [npm package](https://www.npmjs.com/package/ads-client) using npm co
 npm i ads-client
 ```
 
+If you are using TypeScript, install unofficial types using npm command (thanks [Christian Rishøj](https://github.com/crishoj)):
+```bash
+npm install --save @types/ads-client
+```
+
+*Note: Version 2 under development will be written in 100% TypeScript*
+
 Include the module in your code
 ```js
 const ads = require('ads-client')
@@ -1764,12 +1774,17 @@ Solution:
 * When closing application, first unsubscribe from all notifications using `unsubscribeAll()`
 * Use router instead of direct connection, see https://github.com/jisotalo/ads-client/issues/85#issuecomment-1193098519
 
+### Issues with TwinCAT 2 low-end devices (BK9050, BC9050 etc.)
+* You can only use raw commands (such as `readRaw()`, `writeRaw()`, `subscribeRaw()`) as these devices provide no symbols
+* See [issue 114](https://github.com/jisotalo/ads-client/issues/114) and [issue 116](https://github.com/jisotalo/ads-client/issues/116) for starters
+
+
 # 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).
+Tests are run with command `npm test` or `npm run test-um` (usermode runtime) (not in npm version, please clone this repository).
 
 # Documentation
 

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "ads-client",
-  "version": "1.14.1",
+  "version": "1.14.3",
   "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": "jest --runInBand",
+    "test-um": "set ADS_CLIENT_TEST_AMS=192.168.4.1.1.1 && jest --runInBand",
     "generate-docs": "jsdoc ./src/ads-client.js ./README.md -c ./jsdoc-conf.json -d ./docs/ -t ./node_modules/docdash/"
   },
   "keywords": [

package/src/ads-client.js

@@ -894,7 +894,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 {
@@ -1224,7 +1224,11 @@ class Client extends EventEmitter {
           unSubCount++
 
         } catch (err) {
-          debug(`unsubscribeAll(): Unsubscribing from notification ${JSON.stringify(this._internals.activeSubscriptions[sub].target)} failed`)
+          if (this._internals.activeSubscriptions[sub] && this._internals.activeSubscriptions[sub].target !== undefined) {
+            debug(`unsubscribeAll(): Unsubscribing from notification ${JSON.stringify(this._internals.activeSubscriptions[sub].target)} failed`)
+          } else {
+            debug(`unsubscribeAll(): Unsubscribing from notification with handle ${sub} failed`)
+          }
 
           firstError = new ClientException(this, 'unsubscribeAll()', err)
         }
@@ -3654,7 +3658,7 @@ function _reconnect(forceDisconnect = false, isReconnecting = false) {
 
             debug(`_reconnect(): Connection and some subscriptions reinitialized. Connection is back.`)
           })
-        
+
         this.emit('reconnect')
 
         resolve(res)
@@ -3941,7 +3945,9 @@ async function _onConnectionLost(socketFailure = false) {
     _console.call(this, 'WARNING: Connection was lost and setting autoReconnect=false. Quiting.')
     try {
       await this.disconnect(true)
-    } catch { }
+    } catch (err) {
+      debugD(`_onConnectionLost(): Error during disconnecting. Quiting.`)
+    }
 
     return
   }
@@ -3961,7 +3967,7 @@ async function _onConnectionLost(socketFailure = false) {
     //Try to reconnect
     _reconnect.call(this, socketFailure, true)
       .then(res => {
-        
+
         //Success -> remove timer
         _clearTimer(this._internals.reconnectionTimer)
 
@@ -3970,7 +3976,7 @@ async function _onConnectionLost(socketFailure = false) {
         //Reconnecting failed
         if (firstTime)
           _console.call(this, `WARNING: Reconnecting failed. Keeping trying in the background every ${this.settings.reconnectInterval} ms...`)
-        
+
         //If this is still a valid timer, start over again
         if (this._internals.reconnectionTimer.id === timerId) {
           //Creating a new timer with the same id
@@ -4014,7 +4020,7 @@ function _clearTimer(timerObject) {
   //Increasing timer id
   timerObject.id = timerObject.id < Number.MAX_SAFE_INTEGER ? timerObject.id + 1 : 0;
 }
-  
+
 
 
 
@@ -4290,7 +4296,7 @@ function _systemManagerStatePoller() {
     let oldState = this.metaData.systemManagerState
 
     //If the timer has changed, quit here
-    if (this._internals.systemManagerStatePoller.id !== timerId){
+    if (this._internals.systemManagerStatePoller.id !== timerId) {
       return
     }
 
@@ -4349,7 +4355,7 @@ function _systemManagerStatePoller() {
     () => poller(this._internals.systemManagerStatePoller.id),
     this.settings.checkStateInterval
   )
-    
+
 }
 
 
@@ -4722,32 +4728,32 @@ async function _parseDataType(data) {
   dataType.adsDataTypeStr = ADS.ADS_DATA_TYPES.toString(dataType.adsDataType)
   pos += 4
 
-  //27..30 Flags (AdsDataTypeFlags)
-  dataType.flags = data.readUInt16LE(pos)
+  //28..31 Flags (AdsDataTypeFlags)
+  dataType.flags = data.readUInt32LE(pos)
   dataType.flagsStr = ADS.ADS_DATA_TYPE_FLAGS.toStringArray(dataType.flags)
   pos += 4
 
-  //31..32 Name length
+  //32..33 Name length
   dataType.nameLength = data.readUInt16LE(pos)
   pos += 2
 
-  //33..34 Type length
+  //34..35 Type length
   dataType.typeLength = data.readUInt16LE(pos)
   pos += 2
 
-  //35..36 Comment length
+  //36..37 Comment length
   dataType.commentLength = data.readUInt16LE(pos)
   pos += 2
 
-  //37..40 Array dimension
+  //38..39 Array dimension
   dataType.arrayDimension = data.readUInt16LE(pos)
   pos += 2
 
-  //41..42 Subitem count
+  //40..41 Subitem count
   dataType.subItemCount = data.readUInt16LE(pos)
   pos += 2
 
-  //43.... Name
+  //42.... Name
   dataType.name = _trimPlcString(iconv.decode(data.slice(pos, pos + dataType.nameLength + 1), 'cp1252'))
   pos += dataType.nameLength + 1
 
@@ -5237,7 +5243,7 @@ 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.size)
-    
+
     for (const subItem of dataType.subItems) {
       //Try the find the subitem from javascript object
       let key = null
@@ -6036,11 +6042,16 @@ function _parseAdsData(packet, data) {
     case ADS.ADS_COMMAND.ReadWrite:
     case ADS.ADS_COMMAND.Read:
 
-
       //0..3 Ads error number
       ads.errorCode = data.readUInt32LE(pos)
       pos += 4
 
+      if (data.byteLength <= 4) {
+        ads.dataLength = 0
+        ads.data = Buffer.alloc(0)
+        break
+      }
+
       //4..7 Data length (bytes)
       ads.dataLength = data.readUInt32LE(pos)
       pos += 4
@@ -6051,8 +6062,6 @@ function _parseAdsData(packet, data) {
 
       break
 
-
-
     //-------------- Write ---------------
     case ADS.ADS_COMMAND.Write:
 
@@ -6062,8 +6071,6 @@ function _parseAdsData(packet, data) {
 
       break
 
-
-
     //-------------- Device info ---------------
     case ADS.ADS_COMMAND.ReadDeviceInfo:
 
@@ -6073,6 +6080,10 @@ function _parseAdsData(packet, data) {
 
       ads.data = {}
 
+      if (data.byteLength <= 4) {
+        break
+      }
+
       //4 Major version
       ads.data.majorVersion = data.readUInt8(pos)
       pos += 1
@@ -6090,10 +6101,6 @@ function _parseAdsData(packet, data) {
 
       break
 
-
-
-
-
     //-------------- Device status ---------------
     case ADS.ADS_COMMAND.ReadState:
 
@@ -6103,6 +6110,10 @@ function _parseAdsData(packet, data) {
 
       ads.data = {}
 
+      if (data.byteLength <= 4) {
+        break
+      }
+
       //4..5 ADS state
       ads.data.adsState = data.readUInt16LE(pos)
       ads.data.adsStateStr = ADS.ADS_STATE.toString(ads.data.adsState)
@@ -6114,9 +6125,6 @@ function _parseAdsData(packet, data) {
 
       break
 
-
-
-
     //-------------- Add notification ---------------
     case ADS.ADS_COMMAND.AddNotification:
 
@@ -6126,15 +6134,16 @@ function _parseAdsData(packet, data) {
 
       ads.data = {}
 
+      if (data.byteLength <= 4) {
+        break
+      }
+
       //4..7 Notification handle
       ads.data.notificationHandle = data.readUInt32LE(pos)
       pos += 4
 
       break
 
-
-
-
     //-------------- Delete notification ---------------
     case ADS.ADS_COMMAND.DeleteNotification:
 
@@ -6144,8 +6153,6 @@ function _parseAdsData(packet, data) {
 
       break
 
-
-
     //-------------- Notification ---------------
     case ADS.ADS_COMMAND.Notification:
 
@@ -6153,8 +6160,6 @@ function _parseAdsData(packet, data) {
 
       break
 
-
-
     //-------------- WriteControl ---------------
     case ADS.ADS_COMMAND.WriteControl:
 
@@ -6164,7 +6169,6 @@ function _parseAdsData(packet, data) {
 
       break
 
-
     default:
       //Unknown command, return a custom error
       debug(`_parseAdsResponse: Unknown ads command in response: ${packet.ams.adsCommand}`)
@@ -6327,7 +6331,7 @@ async function _onAdsCommandReceived(packet) {
               parsedValue.timeStamp = stamp.timeStamp
 
               //Then lets call the users callback
-              sub.callback(
+              sub.callback && sub.callback(
                 parsedValue,
                 sub
               )