ads-client 1.14.2 → 1.14.3

package/CHANGELOG.md

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

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.2",
+  "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 {
@@ -3658,7 +3658,7 @@ function _reconnect(forceDisconnect = false, isReconnecting = false) {
 
             debug(`_reconnect(): Connection and some subscriptions reinitialized. Connection is back.`)
           })
-        
+
         this.emit('reconnect')
 
         resolve(res)
@@ -3945,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
   }
@@ -3965,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)
 
@@ -3974,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
@@ -4018,7 +4020,7 @@ function _clearTimer(timerObject) {
   //Increasing timer id
   timerObject.id = timerObject.id < Number.MAX_SAFE_INTEGER ? timerObject.id + 1 : 0;
 }
-  
+
 
 
 
@@ -4294,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
     }
 
@@ -4353,7 +4355,7 @@ function _systemManagerStatePoller() {
     () => poller(this._internals.systemManagerStatePoller.id),
     this.settings.checkStateInterval
   )
-    
+
 }
 
 
@@ -5241,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
@@ -6040,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
@@ -6055,8 +6062,6 @@ function _parseAdsData(packet, data) {
 
       break
 
-
-
     //-------------- Write ---------------
     case ADS.ADS_COMMAND.Write:
 
@@ -6066,8 +6071,6 @@ function _parseAdsData(packet, data) {
 
       break
 
-
-
     //-------------- Device info ---------------
     case ADS.ADS_COMMAND.ReadDeviceInfo:
 
@@ -6077,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
@@ -6094,10 +6101,6 @@ function _parseAdsData(packet, data) {
 
       break
 
-
-
-
-
     //-------------- Device status ---------------
     case ADS.ADS_COMMAND.ReadState:
 
@@ -6107,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)
@@ -6118,9 +6125,6 @@ function _parseAdsData(packet, data) {
 
       break
 
-
-
-
     //-------------- Add notification ---------------
     case ADS.ADS_COMMAND.AddNotification:
 
@@ -6130,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:
 
@@ -6148,8 +6153,6 @@ function _parseAdsData(packet, data) {
 
       break
 
-
-
     //-------------- Notification ---------------
     case ADS.ADS_COMMAND.Notification:
 
@@ -6157,8 +6160,6 @@ function _parseAdsData(packet, data) {
 
       break
 
-
-
     //-------------- WriteControl ---------------
     case ADS.ADS_COMMAND.WriteControl:
 
@@ -6168,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}`)