ads-client 2.0.2 → 2.1.0

package/CHANGELOG.md

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

@@ -39,23 +39,13 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -182,10 +172,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 +249,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,
@@ -528,7 +520,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 +544,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 +561,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));
             }
         });
@@ -775,8 +773,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 +842,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 +881,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. 
@@ -1011,6 +1037,7 @@ 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();
@@ -3771,6 +3798,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 +3842,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.
      *