ads-client 2.0.0-beta.5 → 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, 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";
+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';
@@ -471,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.
      *
@@ -480,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;
@@ -488,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`)
      */
@@ -498,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;
     /**
@@ -1809,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.
      *
@@ -1834,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.
      *
@@ -1859,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`).
      *

package/dist/ads-client.js

@@ -39,13 +39,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-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 __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 __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -1708,7 +1718,7 @@ class Client extends events_1.default {
                     };
                     if (this.symbol) {
                         const dataType = await clientRef.getDataType(this.symbol.type, this.targetOpts);
-                        result.value = clientRef.convertBufferToObject(data, dataType);
+                        result.value = clientRef.convertBufferToObject(data, dataType, this.symbol.attributes);
                     }
                     this.latestData = result;
                     return result;
@@ -2279,7 +2289,6 @@ class Client extends events_1.default {
                 pos += commentLength + 1;
                 //Enumeration attributes
                 dataType.enumInfos[i].attributes = [];
-                //console.log(enumInfoCount, num1, commentLength, attributeCount, test, attributes);
                 //Attributes
                 for (let i = 0; i < attributeCount; i++) {
                     const attr = {};
@@ -2483,6 +2492,8 @@ class Client extends events_1.default {
                         subItemType.hashValue = dataType.subItems[i].hashValue;
                         subItemType.offset = dataType.subItems[i].offset;
                         subItemType.comment = dataType.subItems[i].comment;
+                        //Let's keep attributes from parent as well as subitem's own attributes
+                        subItemType.attributes = [...subItemType.attributes, ...dataType.subItems[i].attributes];
                     }
                     builtType.subItems.push(subItemType);
                 }
@@ -2553,10 +2564,11 @@ class Client extends events_1.default {
      *
      * @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
      */
-    convertBufferToPrimitiveType(buffer, dataType) {
+    convertBufferToPrimitiveType(buffer, dataType, attributes) {
         if (dataType.adsDataType === ADS.ADS_DATA_TYPES.ADST_STRING) {
-            return ADS.decodePlcStringBuffer(buffer); //TODO: If symbol has {attribute 'TcEncoding':='UTF-8'}
+            return ADS.decodePlcStringBuffer(buffer, this.getStringDataTypeEncoding(dataType, attributes) === 'UTF-8');
         }
         else if (dataType.adsDataType === ADS.ADS_DATA_TYPES.ADST_WSTRING) {
             return ADS.decodePlcWstringBuffer(buffer);
@@ -2565,6 +2577,16 @@ class Client extends events_1.default {
             return ADS.BASE_DATA_TYPES.fromBuffer(dataType.type, buffer, this.settings.convertDatesToJavascript);
         }
     }
+    /**
+     * 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
+     */
+    getStringDataTypeEncoding(dataType, attributes) {
+        return dataType.attributes.find((attr) => attr.name === 'TcEncoding')?.value
+            || attributes?.find((attr) => attr.name === 'TcEncoding')?.value;
+    }
     /**
      * Converts raw data to Javascript object.
      *
@@ -2572,9 +2594,10 @@ class Client extends events_1.default {
      *
      * @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`)
      */
-    convertBufferToObject(data, dataType, isArrayItem = false) {
+    convertBufferToObject(data, dataType, attributes, isArrayItem = false) {
         let result;
         if ((dataType.arrayInfos.length === 0 || isArrayItem) && dataType.subItems.length > 0) {
             //Struct or array item
@@ -2596,7 +2619,7 @@ class Client extends events_1.default {
                     }
                     else {
                         //Final dimension
-                        temp.push(this.convertBufferToObject(data, dataType, true));
+                        temp.push(this.convertBufferToObject(data, dataType, undefined, true));
                         data = data.subarray(dataType.size);
                     }
                 }
@@ -2642,7 +2665,7 @@ class Client extends events_1.default {
         }
         else {
             //Primitive type
-            result = this.convertBufferToPrimitiveType(data.subarray(dataType.offset, dataType.offset + dataType.size), dataType);
+            result = this.convertBufferToPrimitiveType(data.subarray(dataType.offset, dataType.offset + dataType.size), dataType, attributes);
         }
         return result;
     }
@@ -2651,10 +2674,11 @@ class Client extends events_1.default {
      *
      * @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`)
      */
-    convertObjectToBuffer(value, dataType, objectPath = '', isArrayItem = false) {
+    convertObjectToBuffer(value, dataType, attributes, objectPath = '', isArrayItem = false) {
         let rawValue = Buffer.alloc(0);
         const pathInfo = objectPath === '' && dataType.name === ''
             ? ''
@@ -2688,7 +2712,7 @@ class Client extends events_1.default {
                     };
                 }
                 //Converting subItem
-                let res = this.convertObjectToBuffer(value[key], subItem, `${pathInfo}.${subItem.name}`);
+                let res = this.convertObjectToBuffer(value[key], subItem, undefined, `${pathInfo}.${subItem.name}`);
                 if (res.missingProperty) {
                     //We have a missing property somewhere -> quit
                     return res;
@@ -2743,7 +2767,7 @@ class Client extends events_1.default {
                             return `${pathInfo}${path}[${child}]`;
                         }
                         //Converting array item
-                        let res = this.convertObjectToBuffer(value[child], dataType, `${pathInfo}.${path}[${child}]`, true);
+                        let res = this.convertObjectToBuffer(value[child], dataType, undefined, `${pathInfo}.${path}[${child}]`, true);
                         if (res.missingProperty) {
                             //We have a missing property somewhere -> quit
                             return res.missingProperty;
@@ -2794,11 +2818,11 @@ class Client extends events_1.default {
             else {
                 throw new client_error_1.default(`Provided value ${JSON.stringify(value)}${pathInfo} is not valid value for this ENUM. Allowed values are a number and any of the following: ${allowedEnumValuesStr}`);
             }
-            this.convertPrimitiveTypeToBuffer(enumEntry.value, dataType, rawValue);
+            this.convertPrimitiveTypeToBuffer(enumEntry.value, dataType, rawValue, attributes);
         }
         else if (ADS.BASE_DATA_TYPES.isKnownType(dataType.type)) {
             rawValue = Buffer.alloc(dataType.size);
-            this.convertPrimitiveTypeToBuffer(value, dataType, rawValue);
+            this.convertPrimitiveTypeToBuffer(value, dataType, rawValue, attributes);
         }
         else if (dataType.adsDataType === ADS.ADS_DATA_TYPES.ADST_BIGTYPE && dataType.subItems.length === 0) {
             //If size is 0, then it's empty struct -> rawValue is already OK
@@ -2833,15 +2857,17 @@ class Client extends events_1.default {
      * @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
      */
-    convertPrimitiveTypeToBuffer(value, dataType, buffer) {
+    convertPrimitiveTypeToBuffer(value, dataType, buffer, attributes) {
         if (dataType.size === 0) {
             return;
         }
         if (dataType.adsDataType === ADS.ADS_DATA_TYPES.ADST_STRING) {
+            const encoded = ADS.encodeStringToPlcStringBuffer(value, this.getStringDataTypeEncoding(dataType, attributes) === 'UTF-8');
             //If string is too long for target data type, truncate it
-            const length = Math.min(dataType.size - 1, value.length);
-            ADS.encodeStringToPlcStringBuffer(value).copy(buffer, 0, 0, length);
+            const length = Math.min(dataType.size - 1, encoded.length);
+            encoded.copy(buffer, 0, 0, length);
         }
         else if (dataType.adsDataType === ADS.ADS_DATA_TYPES.ADST_WSTRING) {
             ADS.encodeStringToPlcWstringBuffer(value).copy(buffer);
@@ -5317,11 +5343,11 @@ class Client extends events_1.default {
             this.debug(`readValue(): Reading raw value from ${path} failed: %o`, err);
             throw new client_error_1.default(`readValue(): Reading raw value from ${path} failed`, err);
         }
-        //Converting byte data to javascript object
+        //Converting byte data to javascript object 
         let value;
         try {
             this.debugD(`readValue(): Converting raw value to object for ${path}`);
-            value = await this.convertBufferToObject(rawValue, dataType);
+            value = await this.convertBufferToObject(rawValue, dataType, symbol.attributes);
         }
         catch (err) {
             this.debug(`readValue(): Converting raw value to object for ${path} failed: %o`, err);
@@ -5433,7 +5459,7 @@ class Client extends events_1.default {
         //Creating raw data from object
         let rawValue;
         try {
-            let res = this.convertObjectToBuffer(value, dataType);
+            let res = this.convertObjectToBuffer(value, dataType, symbol.attributes);
             if (res.missingProperty && autoFill) {
                 //Some fields are missing and autoFill is used -> try to auto fill missing values
                 this.debug(`writeValue(): Autofilling missing fields with active values`);
@@ -5442,7 +5468,7 @@ class Client extends events_1.default {
                 this.debugD(`writeValue(): Merging objects (adding missing fields)`);
                 value = this.deepMergeObjects(false, valueNow.value, value);
                 //Try conversion again - should work now
-                res = this.convertObjectToBuffer(value, dataType);
+                res = this.convertObjectToBuffer(value, dataType, symbol.attributes);
                 if (res.missingProperty) {
                     //This shouldn't really happen
                     //However, if it happened, the merge isn't working as it should
@@ -5538,12 +5564,13 @@ class Client extends events_1.default {
      * ```
      *
      * @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.
      */
-    async getDefaultPlcObject(dataType, targetOpts = {}) {
+    async getDefaultPlcObject(dataType, attributes, targetOpts = {}) {
         if (!this.connection.connected) {
             throw new client_error_1.default(`getDefaultPlcObject(): Client is not connected. Use connect() to connect to the target first.`);
         }
@@ -5560,7 +5587,7 @@ class Client extends events_1.default {
             }
         }
         //Converting raw byte data to Javascript object
-        let value = await this.convertFromRaw(Buffer.alloc(dataType.size), dataType, targetOpts);
+        let value = await this.convertFromRaw(Buffer.alloc(dataType.size), dataType, attributes, targetOpts);
         this.debug(`getDefaultPlcObject(): Empty default object created for ${dataType.type}`);
         return value;
     }
@@ -5583,12 +5610,13 @@ class Client extends events_1.default {
      *
      * @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.
      */
-    async convertFromRaw(data, dataType, targetOpts = {}) {
+    async convertFromRaw(data, dataType, attributes, targetOpts = {}) {
         if (!this.connection.connected) {
             throw new client_error_1.default(`convertFromRaw(): Client is not connected. Use connect() to connect to the target first.`);
         }
@@ -5608,7 +5636,7 @@ class Client extends events_1.default {
         let value;
         try {
             this.debugD(`convertFromRaw(): Converting raw value to object for ${dataType.type}`);
-            value = await this.convertBufferToObject(data, dataType);
+            value = await this.convertBufferToObject(data, dataType, attributes);
         }
         catch (err) {
             this.debug(`convertFromRaw(): Converting raw value to object for ${dataType.type} failed: %o`, err);
@@ -5636,11 +5664,12 @@ class Client extends events_1.default {
      * @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.
      */
-    async convertToRaw(value, dataType, autoFill = false, targetOpts = {}) {
+    async convertToRaw(value, dataType, autoFill = false, attributes, targetOpts = {}) {
         if (!this.connection.connected) {
             throw new client_error_1.default(`convertToRaw(): Client is not connected. Use connect() to connect to the target first.`);
         }
@@ -5659,16 +5688,16 @@ class Client extends events_1.default {
         //Converting Javascript object to raw byte data
         let rawValue;
         try {
-            let res = this.convertObjectToBuffer(value, dataType);
+            let res = this.convertObjectToBuffer(value, dataType, attributes);
             if (res.missingProperty && autoFill) {
                 //Some fields are missing and autoFill is used -> try to auto fill missing values
                 this.debug(`convertToRaw(): Autofilling missing fields with default/zero values`);
                 this.debugD(`convertToRaw(): Creating default object`);
-                const defaultValue = await this.getDefaultPlcObject(dataType, targetOpts);
+                const defaultValue = await this.getDefaultPlcObject(dataType, attributes, targetOpts);
                 this.debugD(`convertToRaw(): Merging objects (adding missing fields)`);
                 value = this.deepMergeObjects(false, defaultValue, value);
                 //Try conversion again - should work now
-                res = this.convertObjectToBuffer(value, dataType);
+                res = this.convertObjectToBuffer(value, dataType, attributes);
                 if (res.missingProperty) {
                     //This shouldn't really happen
                     //However, if it happened, the merge isn't working as it should