ads-client 2.0.0-beta.4 → 2.0.0-beta.5

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, AdsUploadInfo, ConnectionMetaData, SubscriptionSettings, ReadValueResult, WriteValueResult, VariableHandle, RpcMethodCallResult, CreateVariableHandleMultiResult, ReadRawMultiResult, ReadRawMultiCommand, WriteRawMultiResult, DeleteVariableHandleMultiResult, ReadWriteRawMultiResult, ReadWriteRawMultiCommand, WriteRawMultiCommand, SubscriptionCallback, DebugLevel, AdsClientEvents } from "./types/ads-client-types";
-import { AdsDataType, AdsDeviceInfo, AdsResponse, AdsState, AdsSymbol, AmsAddress, AmsTcpPacket } from "./types/ads-protocol-types";
+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 { AdsDataType, AdsDeviceInfo, AdsResponse, AdsState, AdsSymbol, AmsAddress, AmsTcpPacket, AdsUploadInfo } from "./types/ads-protocol-types";
 export type * from "./types/ads-client-types";
 export type * from './types/ads-protocol-types';
 export type * from './client-error';
@@ -271,6 +271,14 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      * @param subscription The subscription object (unused here)
      */
     private onPlcRuntimeStateChanged;
+    /**
+     * Checks if PLC runtime state has changed, and if so, emits an event.
+     *
+     * Call from `onPlcRuntimeStateChanged()` and `readPlcRuntimeState()`.
+     *
+     * @param state Active PLC runtime state
+     */
+    private handlePlcRuntimeStateChange;
     /**
      * A subscription callback that is called when the target PLC runtime symbol version has changed.
      *
@@ -623,12 +631,69 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      * }
      * ```
      *
+     * @param command The ADS command to send
+     *
      * @template T In Typescript, the type of the ADS response. If omitted, generic {@link AdsResponse} type is used.
      *
      * @throws Throws an error if sending the command fails or if target responds with an error
      *
      */
     sendAdsCommand<T = AdsResponse>(command: AdsCommandToSend): Promise<AmsTcpPacket<T>>;
+    /**
+     * Sends a raw ADS command to the target with fallback. A wrapper for {@link Client.sendAdsCommand}().
+     *
+     * Calls `sendAdsCommand(command)` and if it fails with
+     * ADS error 1793 or 1808 then calls the `sendAdsCommand(fallback)`.
+     *
+     * See {@link Client.readPlcUploadInfo}() for use case.
+     *
+     * The ideas is copied from TwinCAT.Ads.dll (`TwinCAT.Ads.AdsClientExtensions.ReadWithFallbackAsync()`).
+     *
+     * @example
+     * ```js
+     * try {
+     *  const data = Buffer.alloc(12);
+     *  //...code omitted...
+     *
+     *  const command = {
+     *    adsCommand: ADS.ADS_COMMAND.Read,
+     *    targetAmsNetId: targetOpts.amsNetId,
+     *    targetAdsPort: targetOpts.adsPort,
+     *    payload: data
+     *  };
+     *
+     *  const fbData = Buffer.alloc(12);
+     *  //...code omitted...
+     *
+     *  const fallback = {
+     *    adsCommand: ADS.ADS_COMMAND.Read,
+     *    targetAmsNetId: targetOpts.amsNetId,
+     *    targetAdsPort: targetOpts.adsPort,
+     *    payload: fbData
+     *  };
+     *
+     *  const { response: res, fallbackUsed } = await this.sendAdsCommandWithFallback<AdsReadResponse>(command, fallback);
+     *
+     *  //If we are here, one of those commands was succcesful
+     *  if(fallbackUsed) {
+     *    console.log("Fallback was used. Result:", res.ads.payload);
+     *  } else {
+     *    console.log("Fallback was not used. Result:", res.ads.payload);
+     *  }
+     *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @param command The main ADS command to send
+     * @param fallback The fallback ADS command to send
+     *
+     * @template T In Typescript, the type of the ADS response. If omitted, generic {@link AdsResponse} type is used.
+     *
+     * @throws Throws an error if sending the command fails or if target responds with an error
+     */
+    sendAdsCommandWithFallback<T = AdsResponse>(command: AdsCommandToSend, fallback: AdsCommandToSend): Promise<SendAdsCommandWithFallbackResult<T>>;
     /**
      * Sends an ADS `WriteControl` command to the target.
      *
@@ -1501,11 +1566,11 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      *
      * //Writing a POINTER value (Note the dereference operator ^)
      * const ptrValue = ...
-     * await client.writeRawByPath('GVL_Read.ComplexTypes.POINTER_^', ptrValue);
+     * await client.writeRawByPath('GVL_Write.ComplexTypes.POINTER_^', ptrValue);
      *
      * //Writing a REFERENCE value
      * const refValue = ...
-     * await client.readRawByPath('GVL_Read.ComplexTypes.REFERENCE_');
+     * await client.writeRawByPath('GVL_Write.ComplexTypes.REFERENCE_');
      *
      * } catch (err) {
      *  console.log("Error:", err);
@@ -1675,11 +1740,9 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      * @example
      * ```js
      * try {
-     *  const value = {
-     *    example: true
-     *  };
+     *  const res = await client.writeValue('GVL_Write.StandardTypes.INT_', 32767);
+     *  console.log('Value written:', res.value);
      *
-     *  const res = await client.writeValue('GVL_Read.StandardTypes.INT_', value);
      * } catch (err) {
      *  console.log("Error:", err);
      * }