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

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 { AdsAttributeEntry, 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.
      *
@@ -463,8 +471,16 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      *
      * @param buffer The raw data to convert
      * @param dataType Target data type
+     * @param attributes Additional attributes of the symbol or data type to use for conversion
      */
     private convertBufferToPrimitiveType;
+    /**
+     * Extracts TcEncoding attribute from the data datatype attributes or additional attributes
+     *
+     * @param dataType The data type
+     * @param attributes Additional attributes of the symbol or data type
+     */
+    private getStringDataTypeEncoding;
     /**
      * Converts raw data to Javascript object.
      *
@@ -472,6 +488,7 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      *
      * @param data The raw data to convert
      * @param dataType Target data type
+     * @param attributes Additional attributes of the symbol or data type used for conversion
      * @param isArrayItem If `true`, this is an array item (default: `false`)
      */
     private convertBufferToObject;
@@ -480,6 +497,7 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      *
      * @param value Javascript object to convert
      * @param dataType Target data type
+     * @param attributes Additional attributes of the symbol or data type used for conversion
      * @param objectPath Object path that is passed forward when calling recursively. This is used for error reporting if a property is missing
      * @param isArrayItem If `true`, this is an array item (default: `false`)
      */
@@ -490,6 +508,7 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      * @param value Javascript object to convert
      * @param dataType Data type
      * @param buffer Reference to Buffer object where to write the raw value
+     * @param attributes Additional attributes of the symbol or data type used for conversion
      */
     private convertPrimitiveTypeToBuffer;
     /**
@@ -623,12 +642,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 +1577,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 +1751,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);
      * }
@@ -1746,12 +1820,13 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      * ```
      *
      * @param dataType Data type name in the PLC as string (such as `ST_Struct`) or data type object (acquired using {@link getDataType}())
+     * @param attributes Additional attributes of the symbol or data type used for conversion
      * @param targetOpts Optional target settings that override values in `settings`
      *
      * @template T Typescript data type of the PLC data, for example `getDefaultPlcObject<number>(...)` or `getDefaultPlcObject<ST_TypedStruct>(...)`
      * @throws Throws an error if sending the command fails or if the target responds with an error.
      */
-    getDefaultPlcObject<T = any>(dataType: string | AdsDataType, targetOpts?: Partial<AmsAddress>): Promise<T>;
+    getDefaultPlcObject<T = any>(dataType: string | AdsDataType, attributes?: AdsAttributeEntry[], targetOpts?: Partial<AmsAddress>): Promise<T>;
     /**
      * Converts raw data to a Javascript object by using the provided data type.
      *
@@ -1771,12 +1846,13 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      *
      * @param data Raw data (acquired for example using {@link readRaw}())
      * @param dataType Data type name in the PLC as string (such as `ST_Struct`) or data type object (acquired using {@link getDataType}())
+     * @param attributes Additional attributes of the symbol or data type used for conversion
      * @param targetOpts Optional target settings that override values in `settings`
      *
      * @template T Typescript data type of the PLC data, for example `convertFromRaw<number>(...)` or `convertFromRaw<ST_TypedStruct>(...)`
      * @throws Throws an error if sending the command fails or if the target responds with an error.
      */
-    convertFromRaw<T = any>(data: Buffer, dataType: string | AdsDataType, targetOpts?: Partial<AmsAddress>): Promise<T>;
+    convertFromRaw<T = any>(data: Buffer, dataType: string | AdsDataType, attributes?: AdsAttributeEntry[], targetOpts?: Partial<AmsAddress>): Promise<T>;
     /**
      * Converts a Javascript object to raw data by using the provided data type.
      *
@@ -1796,11 +1872,12 @@ export declare class Client extends EventEmitter<AdsClientEvents> {
      * @param value Value to convert
      * @param dataType Data type name in the PLC as string (such as `ST_Struct`) or data type object (acquired using {@link getDataType}())
      * @param autoFill autoFill If set and the data type is a container (`STRUCT`, `FUNCTION_BLOCK` etc.), missing properties are automatically set to default values (`0` or empty string).
+     * @param attributes Additional attributes of the symbol or data type used for conversion
      * @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.
      */
-    convertToRaw(value: any, dataType: string | AdsDataType, autoFill?: boolean, targetOpts?: Partial<AmsAddress>): Promise<Buffer>;
+    convertToRaw(value: any, dataType: string | AdsDataType, autoFill?: boolean, attributes?: AdsAttributeEntry[], targetOpts?: Partial<AmsAddress>): Promise<Buffer>;
     /**
      * Creates a handle to a variable at the target system by variable path (such as `GVL_Test.ExampleStruct`).
      *