- Bug fix: Some TwinCAT 2 devices (such as BK9050) do not send data l…

…ength if answering with error code - This caused `RangeError: Index out of range` exception as there wasn't enough bytes received - See [issue #116](#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](#116) - 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`)
jisotalo · Sep 23, 2023 · 1f8bd5b · 1f8bd5b
1 parent d5a0fe3
commit 1f8bd5b
Show file tree

Hide file tree

Showing 12 changed files with 288 additions and 181 deletions.
diff --git a/CHANGELOG.md b/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. 

diff --git a/README.md b/README.md
@@ -2,24 +2,27 @@
 
 
 [![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/)
 
 Beckhoff TwinCAT ADS client library for Node.js (unofficial). Connects to Beckhoff TwinCAT automation systems using ADS protocol.
 
 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
 

diff --git a/docs/-_LibraryInternals.html b/docs/-_LibraryInternals.html
@@ -466,7 +466,7 @@ <h4 class="name" id="._checkReceivedData"><span class="type-signature">(static)
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5817">line 5817</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5819">line 5819</a>
     </li></ul></dd>
 
 
@@ -554,7 +554,7 @@ <h4 class="name" id="._clearTimer"><span class="type-signature">(static) </span>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4013">line 4013</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4015">line 4015</a>
     </li></ul></dd>
 
 
@@ -1963,7 +1963,7 @@ <h4 class="name" id="._getDataTypeInfo"><span class="type-signature">(static) </
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5771">line 5771</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5773">line 5773</a>
     </li></ul></dd>
 
 
@@ -2127,7 +2127,7 @@ <h4 class="name" id="._getDataTypeRecursive"><span class="type-signature">(stati
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5586">line 5586</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5588">line 5588</a>
     </li></ul></dd>
 
 
@@ -2801,7 +2801,7 @@ <h4 class="name" id="._onPlcRuntimeStateChanged"><span class="type-signature">(a
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4454">line 4454</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4456">line 4456</a>
     </li></ul></dd>
 
 
@@ -2888,7 +2888,7 @@ <h4 class="name" id="._onRouterStateChanged"><span class="type-signature">(async
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4416">line 4416</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4418">line 4418</a>
     </li></ul></dd>
 
 
@@ -3107,7 +3107,7 @@ <h4 class="name" id="._onSymbolVersionChanged"><span class="type-signature">(asy
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4216">line 4216</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4218">line 4218</a>
     </li></ul></dd>
 
 
@@ -3238,7 +3238,7 @@ <h4 class="name" id="._parseAdsData"><span class="type-signature">(static) </spa
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line6023">line 6023</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line6025">line 6025</a>
     </li></ul></dd>
 
 
@@ -3554,7 +3554,7 @@ <h4 class="name" id="._parseAmsHeader"><span class="type-signature">(static) </s
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5941">line 5941</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5943">line 5943</a>
     </li></ul></dd>
 
 
@@ -3712,7 +3712,7 @@ <h4 class="name" id="._parseAmsTcpHeader"><span class="type-signature">(static)
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5897">line 5897</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5899">line 5899</a>
     </li></ul></dd>
 
 
@@ -3870,7 +3870,7 @@ <h4 class="name" id="._parseAmsTcpPacket"><span class="type-signature">(async, s
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5860">line 5860</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5862">line 5862</a>
     </li></ul></dd>
 
 
@@ -4006,7 +4006,7 @@ <h4 class="name" id="._parseDataType"><span class="type-signature">(async, stati
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4701">line 4701</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4703">line 4703</a>
     </li></ul></dd>
 
 
@@ -4164,7 +4164,7 @@ <h4 class="name" id="._parseJsObjectToBuffer"><span class="type-signature">(stat
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5238">line 5238</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5240">line 5240</a>
     </li></ul></dd>
 
 
@@ -4449,7 +4449,7 @@ <h4 class="name" id="._parseJsVariableToPlc"><span class="type-signature">(stati
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5359">line 5359</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5361">line 5361</a>
     </li></ul></dd>
 
 
@@ -4631,7 +4631,7 @@ <h4 class="name" id="._parsePlcDataToObject"><span class="type-signature">(stati
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5404">line 5404</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5406">line 5406</a>
     </li></ul></dd>
 
 
@@ -4879,7 +4879,7 @@ <h4 class="name" id="._parsePlcVariableToJs"><span class="type-signature">(stati
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5487">line 5487</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5489">line 5489</a>
     </li></ul></dd>
 
 
@@ -5060,7 +5060,7 @@ <h4 class="name" id="._parseSymbolInfo"><span class="type-signature">(static) </
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5042">line 5042</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5044">line 5044</a>
     </li></ul></dd>
 
 
@@ -5218,7 +5218,7 @@ <h4 class="name" id="._readDataTypeInfo"><span class="type-signature">(static) <
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5525">line 5525</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5527">line 5527</a>
     </li></ul></dd>
 
 
@@ -5380,7 +5380,7 @@ <h4 class="name" id="._readSymbolInfo"><span class="type-signature">(static) </s
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5177">line 5177</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line5179">line 5179</a>
     </li></ul></dd>
 
 
@@ -5878,7 +5878,7 @@ <h4 class="name" id="._reInitializeInternals"><span class="type-signature">(asyn
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4037">line 4037</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4039">line 4039</a>
     </li></ul></dd>
 
 
@@ -5994,7 +5994,7 @@ <h4 class="name" id="._reInitializeSubscriptions"><span class="type-signature">(
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4072">line 4072</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4074">line 4074</a>
     </li></ul></dd>
 
 
@@ -6401,7 +6401,7 @@ <h4 class="name" id="._socketReceive"><span class="type-signature">(static) </sp
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4149">line 4149</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4151">line 4151</a>
     </li></ul></dd>
 
 
@@ -6489,7 +6489,7 @@ <h4 class="name" id="._socketWrite"><span class="type-signature">(static) </span
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4124">line 4124</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4126">line 4126</a>
     </li></ul></dd>
 
 
@@ -6621,7 +6621,7 @@ <h4 class="name" id="._subcribeToPlcRuntimeStateChanges"><span class="type-signa
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4375">line 4375</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4377">line 4377</a>
     </li></ul></dd>
 
 
@@ -6708,7 +6708,7 @@ <h4 class="name" id="._subscribe"><span class="type-signature">(static) </span>_
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4510">line 4510</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4512">line 4512</a>
     </li></ul></dd>
 
 
@@ -6919,7 +6919,7 @@ <h4 class="name" id="._subscribeToSymbolVersionChanges"><span class="type-signat
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4180">line 4180</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4182">line 4182</a>
     </li></ul></dd>
 
 
@@ -7007,7 +7007,7 @@ <h4 class="name" id="._systemManagerStatePoller"><span class="type-signature">(s
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4290">line 4290</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4292">line 4292</a>
     </li></ul></dd>
 
 
@@ -7366,7 +7366,7 @@ <h4 class="name" id="._unsubscribeAllInternals"><span class="type-signature">(st
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4652">line 4652</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4654">line 4654</a>
     </li></ul></dd>
 
 
@@ -7481,7 +7481,7 @@ <h4 class="name" id=".subscriptionSettings">subscriptionSettings</h4>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4488">line 4488</a>
+        <a href="ads-client.js.html">ads-client.js</a>, <a href="ads-client.js.html#line4490">line 4490</a>
     </li></ul></dd>
 
 
@@ -7725,7 +7725,7 @@ <h5 class="subsection-title">Properties:</h5>
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.7</a> on Tue May 02 2023 21:37:58 GMT+0300 (Itä-Euroopan kesäaika) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.11</a> on Sat Sep 23 2023 08:34:17 GMT+0300 (Itä-Euroopan kesäaika) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

diff --git a/docs/Client.html b/docs/Client.html
@@ -9027,7 +9027,7 @@ <h5>Returns:</h5>
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.7</a> on Tue May 02 2023 21:37:58 GMT+0300 (Itä-Euroopan kesäaika) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.11</a> on Sat Sep 23 2023 08:34:17 GMT+0300 (Itä-Euroopan kesäaika) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

diff --git a/docs/ClientException.html b/docs/ClientException.html
@@ -857,7 +857,7 @@ <h5>Type:</h5>
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.7</a> on Tue May 02 2023 21:37:58 GMT+0300 (Itä-Euroopan kesäaika) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.6.11</a> on Sat Sep 23 2023 08:34:17 GMT+0300 (Itä-Euroopan kesäaika) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>