ads-client 2.0.2 → 2.2.0

package/CHANGELOG.md

@@ -4,6 +4,40 @@ 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).
 
+## [2.2.0] - 27.12.2025
+### Added
+- Added caching of built data types to improve performance
+  - See [pull request #178](https://github.com/jisotalo/ads-client/pull/178)
+  
+### Changed
+- Bug fix: Unhandled Promise rejections during automatic reconnecting
+  - See [pull request #177](https://github.com/jisotalo/ads-client/pull/177)
+- Fixed a Typescript warning at `socket.on("data", (data) => {...})` as the data chunk could be a string as well
+- Dependencies updated
+- Documentation updated
+
+Thank you [Christian Rishøj](https://github.com/crishoj) for contribution!
+
+All tests passing.
+
+## [2.1.0] - 27.01.2025
+### Added
+- New method `readTcSystemExtendedState()`
+  - Reads [extended target TwinCAT system state](https://jisotalo.fi/ads-client/interfaces/AdsTcSystemExtendedState.html) (if available)
+- Improved detection of TwinCAT system service restart
+  - Available if remote system supports `readTcSystemExtendedState()`
+  - Tested with TwinCAT 3.1.4022, 3.1.4024 and 3.1.4026
+  - Client detects a restart of TwinCAT system and reconnects to re-establish subscriptions
+  - See issue [issue #159](https://github.com/jisotalo/ads-client/issues/159)
+- Added tests for subscription persistence during TwinCAT system restart
+
+### Changed
+- Changed `activeSubscriptions` property visibility from private to public
+- `disconnect` event is no longer emitted continuously each reconnect attempt (only during the initial disconnect / connection lost event)
+- `disconnect` event parameter `isReconnecting` changed to `connectionLost`
+- TwinCAT system state type (`metaData.tcSystemState`) changed from `AdsState` to `AdsTcSystemState`
+  - Not a breaking change - the new type extends `AdsState`
+
 ## [2.0.2] - 14.12.2024
 **IMPORTANT:** This is a major version update. There are lots of **breaking changes**! 
 

package/README.md

@@ -34,6 +34,7 @@ See [`legacy-v1` branch](https://github.com/jisotalo/ads-client/tree/legacy-v1)
 - Calling function block methods (RPC)
 - Automatic 32/64 bit variable support (PVOID, XINT, etc.)
 - Automatic byte alignment support (all pack-modes automatically supported)
+- Handles TwinCAT restarts, configuration changes and PLC software updates automatically 
 
 # Table of contents
 - [ads-client](#ads-client)
@@ -457,6 +458,7 @@ Click a method to open it's documentation.
 | [`readRawMulti()`](https://jisotalo.fi/ads-client/classes/Client.html#readRawMulti)                             | Sends multiple `readRaw()` commands in one ADS packet (ADS sum command).                                                                                                         |
 | [`readState()`](https://jisotalo.fi/ads-client/classes/Client.html#readState)                                   | Reads target ADS state.                                                                                                                                                          |
 | [`readTcSystemState()`](https://jisotalo.fi/ads-client/classes/Client.html#readTcSystemState)                   | Reads target TwinCAT system state from ADS port 10000 (usually `Run` or `Config`).                                                                                               |
+| [`readTcSystemExtendedState()`](https://jisotalo.fi/ads-client/classes/Client.html#readTcSystemExtendedState)   | Reads extended target TwinCAT system service state from ADS port 10000 if supported by target system. Tested to work with 3.1.4022 and newer.                                    |
 | [`readValue()`](https://jisotalo.fi/ads-client/classes/Client.html#readValue)                                   | Reads variable's value from the target system by a variable path (such as `GVL_Test.ExampleStruct`) and returns the value as a Javascript object.                                |
 | [`readValueBySymbol()`](https://jisotalo.fi/ads-client/classes/Client.html#readValueBySymbol)                   | Reads variable's value from the target system by a symbol object (acquired using `getSymbol()`) and returns the value as a Javascript object.                                    |
 | [`readWriteRaw()`](https://jisotalo.fi/ads-client/classes/Client.html#readWriteRaw)                             | Writes raw data to the target system by a raw ADS address (index group, index offset) and reads the result as raw data.                                                          |

package/dist/ads-client.d.ts

@@ -1,7 +1,7 @@
 import EventEmitter from "events";
 import * as ADS from './ads-commons';
-import type { ActiveSubscription, AdsClientConnection, AdsClientSettings, AdsCommandToSend, AdsDataTypeContainer, AdsSymbolContainer, ConnectionMetaData, SubscriptionSettings, ReadValueResult, WriteValueResult, VariableHandle, RpcMethodCallResult, CreateVariableHandleMultiResult, ReadRawMultiResult, ReadRawMultiCommand, WriteRawMultiResult, DeleteVariableHandleMultiResult, ReadWriteRawMultiResult, ReadWriteRawMultiCommand, WriteRawMultiCommand, SubscriptionCallback, DebugLevel, AdsClientEvents, SendAdsCommandWithFallbackResult } from "./types/ads-client-types";
-import { AdsAttributeEntry, AdsDataType, AdsDeviceInfo, AdsResponse, AdsState, AdsSymbol, AmsAddress, AmsTcpPacket, AdsUploadInfo } from "./types/ads-protocol-types";
+import type { ActiveSubscription, ActiveSubscriptionContainer, AdsClientConnection, AdsClientSettings, AdsCommandToSend, AdsDataTypeContainer, AdsSymbolContainer, ConnectionMetaData, SubscriptionSettings, ReadValueResult, WriteValueResult, VariableHandle, RpcMethodCallResult, CreateVariableHandleMultiResult, ReadRawMultiResult, ReadRawMultiCommand, WriteRawMultiResult, DeleteVariableHandleMultiResult, ReadWriteRawMultiResult, ReadWriteRawMultiCommand, WriteRawMultiCommand, SubscriptionCallback, DebugLevel, AdsClientEvents, SendAdsCommandWithFallbackResult } from "./types/ads-client-types";
+import { AdsAttributeEntry, AdsDataType, AdsDeviceInfo, AdsResponse, AdsState, AdsSymbol, AmsAddress, AmsTcpPacket, AdsUploadInfo, AdsTcSystemExtendedState } from "./types/ads-protocol-types";
 export type * from "./types/ads-client-types";
 export type * from './types/ads-protocol-types';
 export type * from './client-error';
@@ -94,10 +94,6 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      * Timer handle of the timer used for detecting ADS port registeration timeout.
      */
     private portRegisterTimeoutTimer?;
-    /**
-     * Container for all active subscriptions.
-     */
-    private activeSubscriptions;
     /**
      * Container for previous subscriptions that were active
      * before reconnecting or when PLC runtime symbol version changed.
@@ -164,6 +160,12 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      * Some properties might not be available in all connection setups and setting combinations.
      */
     metaData: ConnectionMetaData;
+    /**
+     * Container for all active subscriptions.
+     *
+     * Do not edit this directly.
+     */
+    activeSubscriptions: ActiveSubscriptionContainer;
     /**
      * Creates a new ADS client instance.
      *
@@ -976,6 +978,8 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
     /**
      * Reads target TwinCAT system state from ADS port 10000 (usually `Run` or `Config`).
      *
+     * NOTE: You might want to use the extended {@link readTcSystemExtendedState}() instead.
+     *
      * If `targetOpts` is not used to override target, the state is also
      * saved to the `metaData.tcSystemState`.
      *
@@ -996,6 +1000,30 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      * @throws Throws an error if sending the command fails or if the target responds with an error.
      */
     readTcSystemState(targetOpts?: Partial<AmsAddress>): Promise<AdsState>;
+    /**
+     * Reads extended target TwinCAT system service state from ADS port 10000
+     * if supported by target system. Extended version of the {@link readTcSystemState}().
+     *
+     * If `targetOpts` is not used to override target, the state is also
+     * saved to the `metaData.tcSystemState`.
+     *
+     * NOTE: Might not be supported in older TwinCAT versions. If so, use {@link readTcSystemState}() instead.
+     * Tested to work with 3.1.4022 and newer.
+     *
+     * @example
+     * ```js
+     * try {
+     *  const tcSystemState = await client.readTcSystemServiceState();
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @param targetOpts Optional target settings that override values in `settings`
+     *
+     * @throws Throws an error if sending the command fails or if the target responds with an error.
+     */
+    readTcSystemExtendedState(targetOpts?: Partial<AmsAddress>): Promise<AdsTcSystemExtendedState>;
     /**
      * Reads target PLC runtime symbol version.
      *

package/dist/ads-client.js

@@ -158,6 +158,7 @@ class Client extends events_1.default {
             plcSymbols: {},
             allPlcDataTypesCached: false,
             plcDataTypes: {},
+            builtDataTypes: {},
             adsSymbolsUseUtf8: false
         };
         /**
@@ -182,10 +183,6 @@ class Client extends events_1.default {
          * Timer handle of the timer used for detecting ADS port registeration timeout.
          */
         this.portRegisterTimeoutTimer = undefined;
-        /**
-         * Container for all active subscriptions.
-         */
-        this.activeSubscriptions = {};
         /**
          * Container for previous subscriptions that were active
          * before reconnecting or when PLC runtime symbol version changed.
@@ -263,6 +260,12 @@ class Client extends events_1.default {
          * Some properties might not be available in all connection setups and setting combinations.
          */
         this.metaData = { ...this.defaultMetaData };
+        /**
+         * Container for all active subscriptions.
+         *
+         * Do not edit this directly.
+         */
+        this.activeSubscriptions = {};
         //Taking the default settings and then updating the provided ones
         this.settings = {
             ...this.settings,
@@ -463,15 +466,21 @@ class Client extends events_1.default {
                 resolve(this.connection);
             });
             //Listening data event
-            socket.on("data", data => {
-                if (this.debugIO.enabled) {
-                    this.debugIO(`IO in  <------ ${data.byteLength} bytes from ${socket.remoteAddress}: ${data.toString("hex")}`);
+            socket.on("data", (data) => {
+                if (Buffer.isBuffer(data)) {
+                    if (this.debugIO.enabled) {
+                        this.debugIO(`IO in  <------ ${data.byteLength} bytes from ${socket.remoteAddress}: ${data.toString("hex")}`);
+                    }
+                    else if (this.debugD.enabled) {
+                        this.debugD(`IO in  <------ ${data.byteLength} bytes from ${socket.remoteAddress}`);
+                    }
+                    this.receiveBuffer = Buffer.concat([this.receiveBuffer, data]);
+                    this.handleReceivedData();
                 }
-                else if (this.debugD.enabled) {
-                    this.debugD(`IO in  <------ ${data.byteLength} bytes from ${socket.remoteAddress}`);
+                else {
+                    //This should never happen, as the Socket defaults to Buffer
+                    this.debug(`Socket callback data type is unknown (${typeof data})`);
                 }
-                this.receiveBuffer = Buffer.concat([this.receiveBuffer, data]);
-                this.handleReceivedData();
             });
             //Timeout only during connecting, other timeouts are handled elsewhere
             socket.setTimeout(this.settings.timeoutDelay);
@@ -528,7 +537,9 @@ class Client extends events_1.default {
                 this.socket?.removeAllListeners();
                 this.socket?.destroy();
                 this.socket = undefined;
-                this.emit("disconnect", isReconnecting);
+                if (!isReconnecting) {
+                    this.emit("disconnect", isReconnecting);
+                }
                 return resolve();
             }
             let disconnectError = null;
@@ -550,7 +561,9 @@ class Client extends events_1.default {
                 this.socket?.destroy();
                 this.socket = undefined;
                 this.debug(`disconnectFromTarget(): Connection closed successfully`);
-                this.emit("disconnect", isReconnecting);
+                if (!isReconnecting) {
+                    this.emit("disconnect", isReconnecting);
+                }
                 return resolve();
             }
             catch (err) {
@@ -565,7 +578,9 @@ class Client extends events_1.default {
                 this.metaData = { ...this.defaultMetaData };
                 this.activeSubscriptions = {};
                 this.debug(`disconnectFromTarget(): Connection closing failed, connection was forced to close`);
-                this.emit("disconnect", isReconnecting);
+                if (isReconnecting) {
+                    this.emit("disconnect", isReconnecting);
+                }
                 return reject(new client_error_1.default(`disconnect(): Disconnected with errors: ${disconnectError.message}`, err));
             }
         });
@@ -585,7 +600,7 @@ class Client extends events_1.default {
             await this.backupSubscriptions(false);
             if (this.socket) {
                 this.debug(`reconnectToTarget(): Trying to disconnect`);
-                await this.disconnectFromTarget(forceDisconnect, isReconnecting).catch();
+                await this.disconnectFromTarget(forceDisconnect, isReconnecting).catch(() => { });
             }
             this.debug(`reconnectToTarget(): Trying to connect...`);
             return this.connectToTarget(true)
@@ -775,8 +790,13 @@ class Client extends events_1.default {
      * This is not called if the `settings.rawClient` is `true`.
      */
     async setupPlcConnection() {
-        //Read system state
-        await this.readTcSystemState();
+        //Read system state - try the extended version first
+        try {
+            await this.readTcSystemExtendedState();
+        }
+        catch (err) {
+            await this.readTcSystemState();
+        }
         //Start system state poller
         await this.startTcSystemStatePoller();
         //Subscribe to runtime state changes (detect PLC run/stop etc.)
@@ -839,10 +859,27 @@ class Client extends events_1.default {
         }
         let startTimer = true;
         try {
-            let oldState = this.metaData.tcSystemState !== undefined
+            const oldState = this.metaData.tcSystemState
                 ? { ...this.metaData.tcSystemState }
                 : undefined;
-            const state = await this.readTcSystemState();
+            let state;
+            //If we have extended state, then use it for better restart detection
+            if (this.metaData.tcSystemState?.restartIndex !== undefined) {
+                state = await this.readTcSystemExtendedState();
+            }
+            else if (this.metaData.tcSystemState) {
+                state = await this.readTcSystemState();
+            }
+            else {
+                //We don't know yet so try the extended first
+                try {
+                    state = await this.readTcSystemExtendedState();
+                }
+                catch (err) {
+                    state = await this.readTcSystemState();
+                }
+            }
+            //State read successfully
             this.connectionDownSince = undefined;
             if (!oldState || state.adsState !== oldState.adsState) {
                 this.debug(`checkTcSystemState(): TwinCAT system state has changed from ${oldState?.adsStateStr} to ${state.adsStateStr}`);
@@ -861,6 +898,12 @@ class Client extends events_1.default {
                     this.onConnectionLost();
                 }
             }
+            else if (state.restartIndex !== undefined && oldState?.restartIndex !== state.restartIndex) {
+                this.debug(`checkTcSystemState(): TwinCAT system service has restarted -> reconnecting`);
+                this.emit('tcSystemStateChange', state, oldState);
+                startTimer = false;
+                this.onConnectionLost();
+            }
         }
         catch (err) {
             //Reading state failed. 
@@ -949,6 +992,7 @@ class Client extends events_1.default {
             this.debug(`onPlcSymbolVersionChanged(): PLC runtime symbol version changed from ${this.metaData.plcSymbolVersion === undefined ? 'UNKNOWN' : this.metaData.plcSymbolVersion} to ${symbolVersion} -> Refreshing all cached data and subscriptions`);
             //Clear all cached symbol and data types etc.
             this.metaData.plcDataTypes = {};
+            this.metaData.builtDataTypes = {};
             this.metaData.plcSymbols = {};
             this.metaData.plcUploadInfo = undefined;
             //Refreshing upload info
@@ -1011,9 +1055,10 @@ class Client extends events_1.default {
         this.debug(`onConnectionLost(): Connection was lost. Socket failure: ${socketFailure}`);
         this.connection.connected = false;
         this.emit('connectionLost', socketFailure);
+        this.emit('disconnect', true);
         if (this.settings.autoReconnect !== true) {
             this.warn("Connection to target was lost and setting autoReconnect was false -> disconnecting");
-            await this.disconnectFromTarget(true).catch();
+            await this.disconnectFromTarget(true).catch(() => { });
             return;
         }
         this.socketConnectionLostHandler && this.socket?.off('close', this.socketConnectionLostHandler);
@@ -2407,6 +2452,16 @@ class Client extends events_1.default {
     async buildDataType(name, targetOpts = {}, isRootType = true, knownSize) {
         try {
             this.debug(`buildDataType(): Building data type for ${name}`);
+            //Check cache first (only for root types without custom target options)
+            const cacheKey = name.toLowerCase();
+            if (isRootType
+                && !this.settings.disableCaching
+                && !targetOpts.adsPort
+                && !targetOpts.amsNetId
+                && this.metaData.builtDataTypes[cacheKey]) {
+                this.debug(`buildDataType(): Returning cached built data type for ${name}`);
+                return this.metaData.builtDataTypes[cacheKey];
+            }
             let dataType;
             try {
                 dataType = await this.getDataTypeDeclaration(name, targetOpts);
@@ -2551,6 +2606,10 @@ class Client extends events_1.default {
                 //The root type has actually the data type in "name" property
                 builtType.type = builtType.name;
                 builtType.name = '';
+                //Cache the built type (only for root types without custom target options)
+                if (!this.settings.disableCaching && !targetOpts.adsPort && !targetOpts.amsNetId) {
+                    this.metaData.builtDataTypes[cacheKey] = builtType;
+                }
             }
             return builtType;
         }
@@ -3771,6 +3830,8 @@ class Client extends events_1.default {
     /**
      * Reads target TwinCAT system state from ADS port 10000 (usually `Run` or `Config`).
      *
+     * NOTE: You might want to use the extended {@link readTcSystemExtendedState}() instead.
+     *
      * If `targetOpts` is not used to override target, the state is also
      * saved to the `metaData.tcSystemState`.
      *
@@ -3813,6 +3874,85 @@ class Client extends events_1.default {
             throw new client_error_1.default(`readTcSystemState(): Reading TwinCAT system state failed`, err);
         }
     }
+    /**
+     * Reads extended target TwinCAT system service state from ADS port 10000
+     * if supported by target system. Extended version of the {@link readTcSystemState}().
+     *
+     * If `targetOpts` is not used to override target, the state is also
+     * saved to the `metaData.tcSystemState`.
+     *
+     * NOTE: Might not be supported in older TwinCAT versions. If so, use {@link readTcSystemState}() instead.
+     * Tested to work with 3.1.4022 and newer.
+     *
+     * @example
+     * ```js
+     * try {
+     *  const tcSystemState = await client.readTcSystemServiceState();
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @param targetOpts Optional target settings that override values in `settings`
+     *
+     * @throws Throws an error if sending the command fails or if the target responds with an error.
+     */
+    async readTcSystemExtendedState(targetOpts = {}) {
+        if (!this.connection.connected) {
+            throw new client_error_1.default(`readTcSystemServiceState(): Client is not connected. Use connect() to connect to the target first.`);
+        }
+        this.debug(`readTcSystemServiceState(): Reading TwinCAT system service state`);
+        try {
+            const target = {
+                adsPort: 10000,
+                ...targetOpts
+            };
+            const response = await this.readRaw(240, 0, 16, target);
+            const result = {};
+            let pos = 0;
+            //0..1 ADS state
+            result.adsState = response.readUInt16LE(pos);
+            result.adsStateStr = ADS.ADS_STATE.toString(result.adsState);
+            pos += 2;
+            //2..3 Device state
+            result.deviceState = response.readUInt16LE(pos);
+            pos += 2;
+            //4..5 Restart index
+            result.restartIndex = response.readUInt16LE(pos);
+            pos += 2;
+            //6 Version
+            result.version = response.readUInt8(pos);
+            pos += 1;
+            //7 Revision
+            result.revision = response.readUInt8(pos);
+            pos += 1;
+            //8..9 Build
+            result.build = response.readUInt16LE(pos);
+            pos += 2;
+            //10 Platform
+            result.platform = response.readUInt8(pos);
+            pos += 1;
+            //11 OS type
+            result.osType = response.readUInt8(pos);
+            pos += 1;
+            //12..13 Flags
+            result.flags = response.readUInt16LE(pos);
+            result.flagsStr = ADS.ADS_SYSTEM_SERVICE_STATE_FLAGS.toStringArray(result.flags);
+            pos += 2;
+            //14.. Reserved
+            result.reserved = response.subarray(pos);
+            this.debug(`readTcSystemServiceState(): TwinCAT system service state read successfully`);
+            if (!targetOpts.adsPort && !targetOpts.amsNetId) {
+                //Target is not overridden -> save to metadata
+                this.metaData.tcSystemState = result;
+            }
+            return result;
+        }
+        catch (err) {
+            this.debug(`readTcSystemServiceState(): Reading TwinCAT system service state failed: %o`, err);
+            throw new client_error_1.default(`readTcSystemServiceState(): Reading TwinCAT system service state failed`, err);
+        }
+    }
     /**
      * Reads target PLC runtime symbol version.
      *