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

package/dist/ads-client.js

@@ -148,6 +148,7 @@ class Client extends events_1.default {
             plcSymbols: {},
             allPlcDataTypesCached: false,
             plcDataTypes: {},
+            adsSymbolsUseUtf8: false
         };
         /**
          * Buffer for received data.
@@ -233,7 +234,8 @@ class Client extends events_1.default {
             allowHalfOpen: false,
             rawClient: false,
             disableCaching: false,
-            deleteUnknownSubscriptions: true
+            deleteUnknownSubscriptions: true,
+            forceUtf8ForAdsSymbols: false
         };
         /**
          * Active connection information.
@@ -419,6 +421,8 @@ class Client extends events_1.default {
                 //When socket errors from now on, we will close the connection
                 this.socketErrorHandler = this.onSocketError.bind(this);
                 socket.on("error", this.socketErrorHandler);
+                //Force ADS UTF-8 (note: this is also set later at readPlcUploadInfo() if target is a PLC)
+                this.metaData.adsSymbolsUseUtf8 = this.settings.forceUtf8ForAdsSymbols;
                 //If rawClient setting is true, we are done here (just a connection is enough)
                 if (this.settings.rawClient !== true) {
                     try {
@@ -659,7 +663,7 @@ class Client extends events_1.default {
             };
             this.socket?.once('error', errorHandler);
             try {
-                await this.socketWrite(packet);
+                this.socketWrite(packet);
             }
             catch (err) {
                 this.socket?.off('error', errorHandler);
@@ -715,13 +719,41 @@ class Client extends events_1.default {
             //Sometimes close event is not received, so resolve already here
             this.socket.once('end', () => {
                 this.debugD(`unregisterAdsPort(): Socket connection ended, connection closed.`);
+                clearTimeout(this.portRegisterTimeoutTimer);
+                this.amsTcpCallback = undefined;
                 this.socket?.destroy();
                 resolve();
             });
+            this.amsTcpCallback = (res) => {
+                this.amsTcpCallback = undefined;
+                clearTimeout(this.portRegisterTimeoutTimer);
+                if (res.amsTcp.command === ADS.AMS_HEADER_FLAG.AMS_TCP_PORT_CLOSE) {
+                    this.debug(`unregisterAdsPort(): ADS port unregistered`);
+                    this.socket?.destroy();
+                    resolve();
+                }
+            };
+            //Timeout (if no answer from router)
+            this.portRegisterTimeoutTimer = setTimeout(() => {
+                //Callback is no longer needed, delete it
+                this.amsTcpCallback = undefined;
+                //Create a custom "ads error" so that the info is passed onwards
+                const adsError = {
+                    ads: {
+                        error: true,
+                        errorCode: -1,
+                        errorStr: `Timeout - no response in ${this.settings.timeoutDelay} ms`
+                    }
+                };
+                this.debug(`unregisterAdsPort(): Failed to unregister ADS port: Timeout - no response in ${this.settings.timeoutDelay} ms`);
+                return reject(new client_error_1.default(`unregisterAdsPort(): Timeout - no response in ${this.settings.timeoutDelay} ms`, adsError));
+            }, this.settings.timeoutDelay);
             try {
-                await this.socketWrite(buffer);
+                this.socketWrite(buffer);
             }
             catch (err) {
+                this.amsTcpCallback = undefined;
+                clearTimeout(this.portRegisterTimeoutTimer);
                 reject(err);
             }
         });
@@ -848,29 +880,38 @@ class Client extends events_1.default {
      * @param subscription The subscription object (unused here)
      */
     onPlcRuntimeStateChanged(data, subscription) {
-        const res = {};
+        const state = {};
         let pos = 0;
         //0..1 ADS state
-        res.adsState = data.value.readUInt16LE(pos);
-        res.adsStateStr = ADS.ADS_STATE.toString(res.adsState);
+        state.adsState = data.value.readUInt16LE(pos);
+        state.adsStateStr = ADS.ADS_STATE.toString(state.adsState);
         pos += 2;
         //2..3 Device state
-        res.deviceState = data.value.readUInt16LE(pos);
+        state.deviceState = data.value.readUInt16LE(pos);
         pos += 2;
-        //Checking if PLC runtime state has changed
+        this.handlePlcRuntimeStateChange(state);
+    }
+    /**
+     * Checks if PLC runtime state has changed, and if so, emits an event.
+     *
+     * Call from `onPlcRuntimeStateChanged()` and `readPlcRuntimeState()`.
+     *
+     * @param state Active PLC runtime state
+     */
+    handlePlcRuntimeStateChange(state) {
         let stateChanged = false;
-        if (this.metaData.plcRuntimeState === undefined || this.metaData.plcRuntimeState.adsState !== res.adsState) {
-            this.debug(`onPlcRuntimeStateChanged(): PLC runtime state (adsState) changed from ${this.metaData.plcRuntimeState === undefined ? 'UNKNOWN' : this.metaData.plcRuntimeState.adsStateStr} to ${res.adsStateStr}`);
+        if (this.metaData.plcRuntimeState === undefined || this.metaData.plcRuntimeState.adsState !== state.adsState) {
+            this.debug(`handlePlcRuntimeStateChange(): PLC runtime state (adsState) changed from ${this.metaData.plcRuntimeState === undefined ? 'UNKNOWN' : this.metaData.plcRuntimeState.adsStateStr} to ${state.adsStateStr}`);
             stateChanged = true;
         }
-        if (this.metaData.plcRuntimeState === undefined || this.metaData.plcRuntimeState.deviceState !== res.deviceState) {
-            this.debug(`onPlcRuntimeStateChanged(): PLC runtime state (deviceState) changed from ${this.metaData.plcRuntimeState === undefined ? 'UNKNOWN' : this.metaData.plcRuntimeState.deviceState} to ${res.deviceState}`);
+        if (this.metaData.plcRuntimeState === undefined || this.metaData.plcRuntimeState.deviceState !== state.deviceState) {
+            this.debug(`handlePlcRuntimeStateChange(): PLC runtime state (deviceState) changed from ${this.metaData.plcRuntimeState === undefined ? 'UNKNOWN' : this.metaData.plcRuntimeState.deviceState} to ${state.deviceState}`);
             stateChanged = true;
         }
         let oldState = this.metaData.plcRuntimeState !== undefined
             ? { ...this.metaData.plcRuntimeState }
             : undefined;
-        this.metaData.plcRuntimeState = res;
+        this.metaData.plcRuntimeState = state;
         if (stateChanged) {
             this.emit('plcRuntimeStateChange', this.metaData.plcRuntimeState, oldState);
         }
@@ -1292,8 +1333,7 @@ class Client extends events_1.default {
                     ads.payload.versionBuild = data.readUInt16LE(pos);
                     pos += 2;
                     //8..24 Device name
-                    ads.payload.deviceName = ADS.decodePlcStringBuffer(data.subarray(pos, pos + 16));
-                    ;
+                    ads.payload.deviceName = ADS.decodePlcStringBuffer(data.subarray(pos, pos + 16), this.metaData.adsSymbolsUseUtf8);
                 }
                 break;
             case ADS.ADS_COMMAND.ReadState:
@@ -1379,7 +1419,12 @@ class Client extends events_1.default {
             //AMS port unregister
             case ADS.AMS_HEADER_FLAG.AMS_TCP_PORT_CLOSE:
                 packet.amsTcp.commandStr = 'Port unregister';
-                //No action at the moment
+                if (this.amsTcpCallback) {
+                    this.amsTcpCallback(packet);
+                }
+                else {
+                    this.debug(`onAmsTcpPacketReceived(): Port unregister response received but no callback was assigned (${packet.amsTcp.commandStr})`);
+                }
                 break;
             //AMS port register
             case ADS.AMS_HEADER_FLAG.AMS_TCP_PORT_CONNECT:
@@ -1842,13 +1887,13 @@ class Client extends events_1.default {
         const commentLength = data.readUInt16LE(pos);
         pos += 2;
         //30.... Symbol name
-        symbol.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1));
+        symbol.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1), this.metaData.adsSymbolsUseUtf8);
         pos += nameLength + 1;
         //.. Symbol type
-        symbol.type = ADS.decodePlcStringBuffer(data.subarray(pos, pos + typeLength + 1));
+        symbol.type = ADS.decodePlcStringBuffer(data.subarray(pos, pos + typeLength + 1), this.metaData.adsSymbolsUseUtf8);
         pos += typeLength + 1;
         //.. Symbol comment
-        symbol.comment = ADS.decodePlcStringBuffer(data.subarray(pos, pos + commentLength + 1));
+        symbol.comment = ADS.decodePlcStringBuffer(data.subarray(pos, pos + commentLength + 1), this.metaData.adsSymbolsUseUtf8);
         pos += commentLength + 1;
         //Array information
         symbol.arrayInfo = [];
@@ -1880,10 +1925,10 @@ class Client extends events_1.default {
                 const valueLength = data.readUInt8(pos);
                 pos += 1;
                 //Name
-                attr.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1));
+                attr.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1), this.metaData.adsSymbolsUseUtf8);
                 pos += nameLength + 1;
                 //Value
-                attr.value = ADS.decodePlcStringBuffer(data.subarray(pos, pos + valueLength + 1));
+                attr.value = ADS.decodePlcStringBuffer(data.subarray(pos, pos + valueLength + 1), this.metaData.adsSymbolsUseUtf8);
                 pos += valueLength + 1;
                 symbol.attributes.push(attr);
             }
@@ -1951,13 +1996,13 @@ class Client extends events_1.default {
         const subItemCount = data.readUInt16LE(pos);
         pos += 2;
         //38.. Data type name
-        dataType.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1));
+        dataType.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1), this.metaData.adsSymbolsUseUtf8);
         pos += nameLength + 1;
         //.. Data type type
-        dataType.type = ADS.decodePlcStringBuffer(data.subarray(pos, pos + typeLength + 1));
+        dataType.type = ADS.decodePlcStringBuffer(data.subarray(pos, pos + typeLength + 1), this.metaData.adsSymbolsUseUtf8);
         pos += typeLength + 1;
         //.. Data type comment
-        dataType.comment = ADS.decodePlcStringBuffer(data.subarray(pos, pos + commentLength + 1));
+        dataType.comment = ADS.decodePlcStringBuffer(data.subarray(pos, pos + commentLength + 1), this.metaData.adsSymbolsUseUtf8);
         pos += commentLength + 1;
         //Array information
         dataType.arrayInfos = [];
@@ -2041,13 +2086,13 @@ class Client extends events_1.default {
                 const parameterCount = data.readUInt16LE(pos);
                 pos += 2;
                 //56.. Name
-                method.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1));
+                method.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1), this.metaData.adsSymbolsUseUtf8);
                 pos += nameLength + 1;
                 //.. Return data type
-                method.retunDataType = ADS.decodePlcStringBuffer(data.subarray(pos, pos + returnTypeLength + 1));
+                method.retunDataType = ADS.decodePlcStringBuffer(data.subarray(pos, pos + returnTypeLength + 1), this.metaData.adsSymbolsUseUtf8);
                 pos += returnTypeLength + 1;
                 //.. Comment
-                method.comment = ADS.decodePlcStringBuffer(data.subarray(pos, pos + commentLength + 1));
+                method.comment = ADS.decodePlcStringBuffer(data.subarray(pos, pos + commentLength + 1), this.metaData.adsSymbolsUseUtf8);
                 pos += commentLength + 1;
                 //Parameters
                 method.parameters = [];
@@ -2090,13 +2135,13 @@ class Client extends events_1.default {
                     const commentLength = data.readUInt16LE(pos);
                     pos += 2;
                     //38.. Data type name
-                    param.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1));
+                    param.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1), this.metaData.adsSymbolsUseUtf8);
                     pos += nameLength + 1;
                     //.. Data type type
-                    param.type = ADS.decodePlcStringBuffer(data.subarray(pos, pos + typeLength + 1));
+                    param.type = ADS.decodePlcStringBuffer(data.subarray(pos, pos + typeLength + 1), this.metaData.adsSymbolsUseUtf8);
                     pos += typeLength + 1;
                     //.. Data type comment
-                    param.comment = ADS.decodePlcStringBuffer(data.subarray(pos, pos + commentLength + 1));
+                    param.comment = ADS.decodePlcStringBuffer(data.subarray(pos, pos + commentLength + 1), this.metaData.adsSymbolsUseUtf8);
                     pos += commentLength + 1;
                     //Attributes
                     param.attributes = [];
@@ -2113,18 +2158,19 @@ class Client extends events_1.default {
                             const valueLength = data.readUInt8(pos);
                             pos += 1;
                             //Name
-                            attr.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1));
+                            attr.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1), this.metaData.adsSymbolsUseUtf8);
                             pos += nameLength + 1;
                             //Value
-                            attr.value = ADS.decodePlcStringBuffer(data.subarray(pos, pos + valueLength + 1));
+                            attr.value = ADS.decodePlcStringBuffer(data.subarray(pos, pos + valueLength + 1), this.metaData.adsSymbolsUseUtf8);
                             pos += valueLength + 1;
-                            method.attributes.push(attr);
+                            param.attributes.push(attr);
                         }
                     }
                     if (pos - beginPosition > entryLength) {
                         //There is some additional data left
                         param.reserved2 = data.subarray(pos);
                     }
+                    pos = beginPosition + entryLength;
                     method.parameters.push(param);
                 }
                 //Attributes
@@ -2142,10 +2188,10 @@ class Client extends events_1.default {
                         const valueLength = data.readUInt8(pos);
                         pos += 1;
                         //Name
-                        attr.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1));
+                        attr.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1), this.metaData.adsSymbolsUseUtf8);
                         pos += nameLength + 1;
                         //Value
-                        attr.value = ADS.decodePlcStringBuffer(data.subarray(pos, pos + valueLength + 1));
+                        attr.value = ADS.decodePlcStringBuffer(data.subarray(pos, pos + valueLength + 1), this.metaData.adsSymbolsUseUtf8);
                         pos += valueLength + 1;
                         method.attributes.push(attr);
                     }
@@ -2170,18 +2216,19 @@ class Client extends events_1.default {
                 const valueLength = data.readUInt8(pos);
                 pos += 1;
                 //Name
-                attr.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1));
+                attr.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1), this.metaData.adsSymbolsUseUtf8);
                 pos += nameLength + 1;
                 //Value
-                attr.value = ADS.decodePlcStringBuffer(data.subarray(pos, pos + valueLength + 1));
+                attr.value = ADS.decodePlcStringBuffer(data.subarray(pos, pos + valueLength + 1), this.metaData.adsSymbolsUseUtf8);
                 pos += valueLength + 1;
                 dataType.attributes.push(attr);
             }
         }
         //If flag EnumInfos set
         dataType.enumInfos = [];
+        let enumInfoCount = 0;
         if ((dataType.flags & ADS.ADS_DATA_TYPE_FLAGS.EnumInfos) === ADS.ADS_DATA_TYPE_FLAGS.EnumInfos) {
-            const enumInfoCount = data.readUInt16LE(pos);
+            enumInfoCount = data.readUInt16LE(pos);
             pos += 2;
             for (let i = 0; i < enumInfoCount; i++) {
                 let enumInfo = {};
@@ -2189,7 +2236,7 @@ class Client extends events_1.default {
                 const nameLength = data.readUInt8(pos);
                 pos += 1;
                 //Enumeration name
-                enumInfo.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1));
+                enumInfo.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1), this.metaData.adsSymbolsUseUtf8);
                 pos += nameLength + 1;
                 //Enumeration value
                 enumInfo.value = data.subarray(pos, pos + dataType.size);
@@ -2216,9 +2263,43 @@ class Client extends events_1.default {
         }
         //If flag ExtendedEnumInfos set
         if ((dataType.flags & ADS.ADS_DATA_TYPE_FLAGS.ExtendedEnumInfos) === ADS.ADS_DATA_TYPE_FLAGS.ExtendedEnumInfos) {
-            //TODO: this is not working now
-            //Things probably break now
-            this.warn(`Data type ${dataType.name} (${dataType.type}) has flag "ExtendedEnumInfos" which is not supported. Things might not work now. Please open an issue at Github`);
+            for (let i = 0; i < enumInfoCount; i++) {
+                let beginPosition = pos;
+                //Total entry length (bytes)
+                const entryLength = data.readUInt16LE(pos);
+                pos += 2;
+                //Comment length
+                const commentLength = data.readUInt8(pos);
+                pos += 1;
+                //Attribute count
+                const attributeCount = data.readUInt8(pos);
+                pos += 1;
+                //Enumeration comment
+                dataType.enumInfos[i].comment = ADS.decodePlcStringBuffer(data.subarray(pos, pos + commentLength + 1), this.metaData.adsSymbolsUseUtf8);
+                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 = {};
+                    //Name length
+                    const nameLength = data.readUInt8(pos);
+                    pos += 1;
+                    //Value length
+                    const valueLength = data.readUInt8(pos);
+                    pos += 1;
+                    //Name
+                    attr.name = ADS.decodePlcStringBuffer(data.subarray(pos, pos + nameLength + 1), this.metaData.adsSymbolsUseUtf8);
+                    pos += nameLength + 1;
+                    //Value
+                    attr.value = ADS.decodePlcStringBuffer(data.subarray(pos, pos + valueLength + 1), this.metaData.adsSymbolsUseUtf8);
+                    pos += valueLength + 1;
+                    dataType.enumInfos[i].attributes.push(attr);
+                }
+                //If there are some reserved bytes -> skip
+                pos = beginPosition + entryLength;
+            }
         }
         //If flag SoftwareProtectionLevels set
         if ((dataType.flags & ADS.ADS_DATA_TYPE_FLAGS.SoftwareProtectionLevels) === ADS.ADS_DATA_TYPE_FLAGS.SoftwareProtectionLevels) {
@@ -2325,6 +2406,7 @@ class Client extends events_1.default {
                 if (err.adsError && err.adsError?.errorCode === 1808) {
                     //Type wasn't found.
                     //Might be TwinCAT 2 system that doesn't provide pseudo or base data types by ADS --> check if we know the type ourselves
+                    const originalName = name;
                     if (ADS.BASE_DATA_TYPES.isPseudoType(name)) {
                         //This converts e.g. PVOID to a primitive type
                         if (knownSize === undefined) {
@@ -2358,6 +2440,11 @@ class Client extends events_1.default {
                             extendedFlags: 0,
                             reserved: Buffer.alloc(0)
                         };
+                        //Adding to cache, even though it's not read from the target
+                        //With TwinCAT 2, this prevents trying to read base types again and again from the target (as there aren't any)
+                        if (!this.settings.disableCaching && !targetOpts.adsPort && !targetOpts.amsNetId) {
+                            this.metaData.plcDataTypes[originalName.toLowerCase()] = dataType;
+                        }
                     }
                     else {
                         //Type is unknown - we can't do anything
@@ -2401,7 +2488,7 @@ class Client extends events_1.default {
                 }
             }
             else if ((((dataType.type === '' && !ADS.BASE_DATA_TYPES.isPseudoType(dataType.name)) || ADS.BASE_DATA_TYPES.isKnownType(dataType.name))
-                && dataType.flagsStr.includes('DataType')
+                && (dataType.flagsStr.includes('DataType') || ADS.BASE_DATA_TYPES.isKnownType(dataType.name)) //isKnownType() call is for TwinCAT 2 support, as base types (like INT16) do not have DataType flag (but it's the final base type)
                 && !dataType.flagsStr.includes('EnumInfos')
                 && dataType.arrayDimension === 0)) {
                 //This is final form (no need to go deeper)
@@ -2409,8 +2496,10 @@ class Client extends events_1.default {
             }
             else if (dataType.arrayDimension > 0) {
                 //Data type is an array - get array subtype
+                //TwinCAT 2 support - calculate size if it's array of pointer etc.
+                const size = dataType.size / dataType.arrayInfos.reduce((total, dimension) => total * dimension.length, 1);
                 builtType = {
-                    ...(await this.buildDataType(dataType.type, targetOpts, false))
+                    ...(await this.buildDataType(dataType.type, targetOpts, false, size))
                 };
                 builtType.arrayInfos = [...dataType.arrayInfos, ...builtType.arrayInfos];
             }
@@ -2467,7 +2556,7 @@ class Client extends events_1.default {
      */
     convertBufferToPrimitiveType(buffer, dataType) {
         if (dataType.adsDataType === ADS.ADS_DATA_TYPES.ADST_STRING) {
-            return ADS.decodePlcStringBuffer(buffer);
+            return ADS.decodePlcStringBuffer(buffer); //TODO: If symbol has {attribute 'TcEncoding':='UTF-8'}
         }
         else if (dataType.adsDataType === ADS.ADS_DATA_TYPES.ADST_WSTRING) {
             return ADS.decodePlcWstringBuffer(buffer);
@@ -2972,6 +3061,8 @@ class Client extends events_1.default {
      * }
      * ```
      *
+     * @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
@@ -3057,6 +3148,82 @@ class Client extends events_1.default {
             }
         });
     }
+    /**
+     * 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
+     */
+    async sendAdsCommandWithFallback(command, fallback) {
+        try {
+            this.debug(`sendAdsCommandWithFallback(): Sending ADS command with a fallback`);
+            return {
+                fallbackUsed: false,
+                response: await this.sendAdsCommand(command)
+            };
+        }
+        catch (err) {
+            const clientErr = err;
+            //If error is "Service is not supported by server" (1793) or "Symbol not found" (1808) then we should try the fallback
+            if (clientErr.adsError?.errorCode === 1793 || clientErr.adsError?.errorCode === 1808) {
+                this.debug(`sendAdsCommandWithFallback(): Sending ADS command failed with ADS error ${clientErr.adsError.errorCode} - trying fallback...`);
+                return {
+                    fallbackUsed: true,
+                    response: await this.sendAdsCommand(fallback)
+                };
+            }
+            this.debug(`sendAdsCommandWithFallback(): Sending ADS command failed - skipping fallback (ADS error is not 1793 or 1808)`);
+            throw err;
+        }
+    }
     /**
      * Sends an ADS `WriteControl` command to the target.
      *
@@ -3148,6 +3315,8 @@ class Client extends events_1.default {
             const state = await this.readPlcRuntimeState(targetOpts);
             await this.writeControl("Run", state.deviceState, undefined, targetOpts);
             this.debug(`startPlc(): PLC runtime started at ${this.targetToString(targetOpts)}`);
+            //Reading runtime state to make sure metaData is updated asap
+            await this.readPlcRuntimeState(targetOpts);
         }
         catch (err) {
             this.debug(`startPlc(): Starting PLC runtime at ${this.targetToString(targetOpts)} failed: %o`, err);
@@ -3180,6 +3349,8 @@ class Client extends events_1.default {
             const state = await this.readPlcRuntimeState(targetOpts);
             await this.writeControl("Reset", state.deviceState, undefined, targetOpts);
             this.debug(`resetPlc(): PLC runtime reset at ${this.targetToString(targetOpts)}`);
+            //Reading runtime state to make sure metaData is updated asap
+            await this.readPlcRuntimeState(targetOpts);
         }
         catch (err) {
             this.debug(`resetPlc(): Resetting PLC runtime at ${this.targetToString(targetOpts)} failed: %o`, err);
@@ -3212,6 +3383,8 @@ class Client extends events_1.default {
             const state = await this.readPlcRuntimeState(targetOpts);
             await this.writeControl("Stop", state.deviceState, undefined, targetOpts);
             this.debug(`stopPlc(): PLC runtime stopped at ${this.targetToString(targetOpts)}`);
+            //Reading runtime state to make sure metaData is updated asap
+            await this.readPlcRuntimeState(targetOpts);
         }
         catch (err) {
             this.debug(`stopPlc(): Stopping PLC runtime at ${this.targetToString(targetOpts)} failed: %o`, err);
@@ -3381,7 +3554,7 @@ class Client extends events_1.default {
      * @example
      * ```js
      * try {
-     *  const symbol = await client.getSymbol('GVL_Test.ExampleStruct');
+     *  const symbol = await client.getSymbol('GVL_Read.StandardTypes.INT_');
      * } catch (err) {
      *  console.log("Error:", err);
      * }
@@ -3559,8 +3732,8 @@ class Client extends events_1.default {
             });
             this.debug(`readPlcRuntimeState(): Runtime state read successfully. State is %o`, res.ads.payload);
             if (!targetOpts.adsPort && !targetOpts.amsNetId) {
-                //Target is not overridden -> save to metadata
-                this.metaData.plcRuntimeState = res.ads.payload;
+                //Target is not overridden -> handle the result (check for change and update metadata)
+                this.handlePlcRuntimeStateChange(res.ads.payload);
             }
             return res.ads.payload;
         }
@@ -3677,7 +3850,7 @@ class Client extends events_1.default {
      * //Checks if value has changed every 100ms
      * //Callback is called only when the value has changed
      * await client.subscribeValue(
-     *  'GVL_Test.ExampleStruct.',
+     *  'GVL_Subscription.NumericValue_10ms',
      *  (data, subscription) => {
      *   console.log(`Value of ${subscription.symbol.name} has changed: ${data.value}`);
      *  },
@@ -3825,7 +3998,7 @@ class Client extends events_1.default {
      * //Checks if value has changed every 100ms
      * //Callback is called only when the value has changed
      * await client.subscribe({
-     *  target: 'GVL_Test.ExampleStruct',
+     *  target: 'GVL_Subscription.NumericValue_10ms',
      *  callback: (data, subscription) => {
      *    console.log(`Value of ${subscription.symbol.name} has changed: ${data.value}`);
      *  },
@@ -4053,36 +4226,90 @@ class Client extends events_1.default {
         data.writeUInt32LE(0, pos);
         pos += 4;
         //8..11 Read data length
-        data.writeUInt32LE(24, pos);
+        data.writeUInt32LE(64, pos); //64 = upload info version 3 size (works also for lower versions)
+        pos += 4;
+        const command = {
+            adsCommand: ADS.ADS_COMMAND.Read,
+            targetAmsNetId: targetOpts.amsNetId,
+            targetAdsPort: targetOpts.adsPort,
+            payload: data
+        };
+        //Fallback read command for version 1
+        //Allocating bytes for request
+        const fbData = Buffer.alloc(12);
+        pos = 0;
+        //0..3 IndexGroup 
+        fbData.writeUInt32LE(ADS.ADS_RESERVED_INDEX_GROUPS.SymbolUploadInfo, pos);
         pos += 4;
+        //4..7 IndexOffset
+        fbData.writeUInt32LE(0, pos);
+        pos += 4;
+        //8..11 Read data length
+        fbData.writeUInt32LE(8, pos); //8 = upload info version 1 size
+        pos += 4;
+        const fallback = {
+            adsCommand: ADS.ADS_COMMAND.Read,
+            targetAmsNetId: targetOpts.amsNetId,
+            targetAdsPort: targetOpts.adsPort,
+            payload: fbData
+        };
         try {
-            const res = await this.sendAdsCommand({
-                adsCommand: ADS.ADS_COMMAND.Read,
-                targetAmsNetId: targetOpts.amsNetId,
-                targetAdsPort: targetOpts.adsPort,
-                payload: data
-            });
+            const { response: res, fallbackUsed } = await this.sendAdsCommandWithFallback(command, fallback);
+            this.debug(`readPlcUploadInfo(): Upload info read - fallback was needed: ${fallbackUsed}`);
             const uploadInfo = {};
             let pos = 0;
             const response = res.ads.payload;
+            //If we are here, either the command or fallback was successful
+            //Detect version from byte count
+            if (response.byteLength === 8) {
+                uploadInfo.version = 1;
+            }
+            else if (response.byteLength === 24) {
+                uploadInfo.version = 2;
+            }
+            else if (response.byteLength === 64) {
+                uploadInfo.version = 3;
+            }
+            else {
+                //Shouldn't happen as we request max 64 bytes
+                throw new Error(`Upload info version is unknown (received ${response.byteLength} bytes) - create a GitHub issue`);
+            }
             //0..3 Symbol count
             uploadInfo.symbolCount = response.readUInt32LE(pos);
             pos += 4;
             //4..7 Symbol length
             uploadInfo.symbolLength = response.readUInt32LE(pos);
             pos += 4;
-            //8..11 Data type count
-            uploadInfo.dataTypeCount = response.readUInt32LE(pos);
-            pos += 4;
-            //12..15 Data type length
-            uploadInfo.dataTypeLength = response.readUInt32LE(pos);
-            pos += 4;
-            //16..19 Extra count
-            uploadInfo.extraCount = response.readUInt32LE(pos);
-            pos += 4;
-            //20..23 Extra length
-            uploadInfo.extraLength = response.readUInt32LE(pos);
-            pos += 4;
+            if (uploadInfo.version >= 2) {
+                //8..11 Data type count
+                uploadInfo.dataTypeCount = response.readUInt32LE(pos);
+                pos += 4;
+                //12..15 Data type length
+                uploadInfo.dataTypeLength = response.readUInt32LE(pos);
+                pos += 4;
+                //16..19 Max. allowed dynamic symbol count
+                uploadInfo.maxDynamicSymbolCount = response.readUInt32LE(pos);
+                pos += 4;
+                //20..23 Number of dynamic symbols used (version >= 2)
+                uploadInfo.dynamicSymbolCount = response.readUInt32LE(pos);
+                pos += 4;
+                if (uploadInfo.version >= 3) {
+                    //24..27 Invalid dynamic symbol count
+                    uploadInfo.invalidDynamicSymbolCount = response.readUInt32LE(pos);
+                    pos += 4;
+                    //28..31 Encoding code page used for STRING encoding
+                    uploadInfo.encodingCodePage = response.readUInt32LE(pos);
+                    pos += 4;
+                    //32..35 Upload info flags
+                    uploadInfo.flags = response.readUInt32LE(pos);
+                    uploadInfo.flagsStr = ADS.ADS_UPLOAD_INFO_FLAGS.toStringArray(uploadInfo.flags);
+                    pos += 4;
+                    //36..63 Reserved
+                    uploadInfo.reserved = response.subarray(pos);
+                }
+            }
+            //Target has UTF-8 encoded ADS symbols if encodingCodePage is 65001 (or if forced from settings)
+            this.metaData.adsSymbolsUseUtf8 = uploadInfo.encodingCodePage === 65001 || this.settings.forceUtf8ForAdsSymbols;
             if (!targetOpts.adsPort && !targetOpts.amsNetId) {
                 //Target is not overridden -> save to metadata
                 this.metaData.plcUploadInfo = uploadInfo;
@@ -4271,7 +4498,7 @@ class Client extends events_1.default {
         data.writeUInt32LE(0, pos);
         pos += 4;
         //8..11 Read data length
-        data.writeUInt32LE(uploadInfo.dataTypeLength, pos);
+        data.writeUInt32LE(uploadInfo.dataTypeLength ?? 0xFFFFFFFF, pos); //Using 0xFFFFFFFF is upload info is version 1 (= we don't know the length)
         pos += 4;
         try {
             const res = await this.sendAdsCommand({
@@ -4773,7 +5000,6 @@ class Client extends events_1.default {
      *
      * NOTE: Unlike with {@link readRawByPath}(), this command uses multiple ADS requests for the operation.
      *
-     *
      * @example
      * ```js
      * try {
@@ -4784,11 +5010,11 @@ class Client extends events_1.default {
      *
      * //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);
@@ -5042,7 +5268,7 @@ class Client extends events_1.default {
      * @example
      * ```js
      * try {
-     *  const res = await client.readValue('GVL_Test.ExampleStruct');
+     *  const res = await client.readValue('GVL_Read.StandardTypes.INT_');
      *  console.log(res.value);
      * } catch (err) {
      *  console.log("Error:", err);
@@ -5053,6 +5279,7 @@ class Client extends events_1.default {
      * @param targetOpts Optional target settings that override values in `settings`
      *
      * @template T In Typescript, the data type of the value, for example `readValue<number>(...)` or `readValue<ST_TypedStruct>(...)` (default: `any`)
+     * @throws Throws an error if sending the command fails or if the target responds with an error.
      */
     async readValue(path, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5073,7 +5300,8 @@ class Client extends events_1.default {
         let dataType;
         try {
             this.debugD(`readValue(): Getting data type for ${path}`);
-            dataType = await this.buildDataType(symbol.type, targetOpts);
+            //Also passing size for TC2 pointer/pseudo type support
+            dataType = await this.buildDataType(symbol.type, targetOpts, true, symbol.size);
         }
         catch (err) {
             this.debug(`readValue(): Getting data type for ${path} failed: %o`, err);
@@ -5108,7 +5336,7 @@ class Client extends events_1.default {
         };
     }
     /**
-     * Reads variable's value from the target system by a symbol object
+     * Reads variable's value from the target system by a symbol object (acquired using `getSymbol()`)
      * and returns the value as a Javascript object.
      *
      * Returns variable's
@@ -5122,7 +5350,7 @@ class Client extends events_1.default {
      * @example
      * ```js
      * try {
-     *  const symbol = await client.getSymbol('GVL_Test.ExampleStruct');
+     *  const symbol = await client.getSymbol('GVL_Read.StandardTypes.INT_');
      *
      *  const res = await client.readValueBySymbol(symbol);
      *  console.log(res.value);
@@ -5131,10 +5359,11 @@ class Client extends events_1.default {
      * }
      * ```
      *
-     * @param symbol Symbol object (acquired using {@link getSymbol}())
+     * @param symbol Symbol object
      * @param targetOpts Optional target settings that override values in `settings`
      *
      * @template T In Typescript, the data type of the value, for example `readValueBySymbol<number>(...)` or `readValueBySymbol<ST_TypedStruct>(...)` (default: `any`)
+     * @throws Throws an error if sending the command fails or if the target responds with an error.
      */
     async readValueBySymbol(symbol, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5159,11 +5388,9 @@ class Client extends events_1.default {
      * @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_Test.ExampleStruct', value);
      * } catch (err) {
      *  console.log("Error:", err);
      * }
@@ -5172,9 +5399,10 @@ class Client extends events_1.default {
      * @param path Variable path in the PLC (such as `GVL_Test.ExampleStruct`)
      * @param value Value to write
      * @param targetOpts Optional target settings that override values in `settings`
-     * @param autoFill If set and the data type is a container (`STRUCT`, `FUNCTION_BLOCK` etc.), missing properties are automatically set to default values (usually `0` or `''`).
+     * @param autoFill If set and the data type is a container (`STRUCT`, `FUNCTION_BLOCK` etc.), missing properties are automatically set to active values read from target (kept as-is).
      *
      * @template T In Typescript, the data type of the value, for example `writeValue<number>(...)` or `writeValue<ST_TypedStruct>(...)`
+     * @throws Throws an error if sending the command fails or if the target responds with an error.
      */
     async writeValue(path, value, autoFill = false, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5195,7 +5423,8 @@ class Client extends events_1.default {
         let dataType;
         try {
             this.debugD(`writeValue(): Getting data type for ${path}`);
-            dataType = await this.buildDataType(symbol.type, targetOpts);
+            //Also passing size for TC2 pointer/pseudo type support
+            dataType = await this.buildDataType(symbol.type, targetOpts, true, symbol.size);
         }
         catch (err) {
             this.debug(`writeValue(): Getting data type for ${path} failed: %o`, err);
@@ -5253,20 +5482,37 @@ class Client extends events_1.default {
         };
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Writes variable's value to the target system by a symbol object (acquired using `getSymbol()`).
+     * Converts the value from a Javascript object to a raw value.
      *
-     * Writes a value by symbol. Converts the value from a Javascript object to a raw value.
+     * Returns variable's
+     * - converted value
+     * - raw value
+     * - data type
+     * - symbol
      *
-     * Returns the converted value, the raw value, the data type and the symbol.
+     * **NOTE:** Do not use `autoFill` for `UNION` types, it doesn't work correctly.
+     *
+     * **NOTE:** This requires that the target is a PLC runtime or has equivalent ADS protocol support.
      *
-     * **NOTE:** Do not use `autoFill` for `UNION` types, it works without errors but the result isn't probably the desired one
+     * @example
+     * ```js
+     * try {
+     *  const symbol = await client.getSymbol('GVL_Read.StandardTypes.INT_');
      *
-     * @param symbol Symbol (acquired using `getSymbol()`)
+     *  const res = await client.writeValueBySymbol(symbol, 32767);
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @param symbol Symbol object
      * @param value Value to write
      * @param targetOpts Optional target settings that override values in `settings`
-     * @param autoFill If true and data type is a container (`STRUCT`, `FUNCTION_BLOCK` etc.), missing properties are automatically **set to default values** (usually `0` or `''`)
+     * @param autoFill If set and the data type is a container (`STRUCT`, `FUNCTION_BLOCK` etc.), missing properties are automatically set to active values read from target (kept as-is).
      *
      * @template T In Typescript, the data type of the value, for example `writeValue<number>(...)` or `writeValue<ST_TypedStruct>(...)`
+     * @throws Throws an error if sending the command fails or if the target responds with an error.
      */
     async writeValueBySymbol(symbol, value, autoFill = false, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5275,14 +5521,27 @@ class Client extends events_1.default {
         return this.writeValue(symbol.name, value, autoFill, targetOpts);
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
-     *
      * Returns a default (empty) Javascript object representing provided PLC data type.
      *
-     * @param dataType Data type name in the PLC as string (such as `ST_Struct`) or `AdsDataType` object
+     * @example
+     * ```js
+     * try {
+     *  const res = await client.getDefaultPlcObject('INT');
+     *  console.log(res); //0
+  
+     *  const res2 = await client.getDefaultPlcObject('Tc2_Standard.TON');
+     *  console.log(res2); //{ IN: false, PT: 0, Q: false, ET: 0, M: false, StartTime: 0 }
+     *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @param dataType Data type name in the PLC as string (such as `ST_Struct`) or data type object (acquired using {@link getDataType}())
      * @param targetOpts Optional target settings that override values in `settings`
      *
-     * @template T Typescript data type of the PLC data, for example `readValue<number>(...)` or `readValue<ST_TypedStruct>(...)`
+     * @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 = {}) {
         if (!this.connection.connected) {
@@ -5306,15 +5565,28 @@ class Client extends events_1.default {
         return value;
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Converts raw data to a Javascript object by using the provided data type.
+     *
+     * @example
+     * ```js
+     * try {
+     *  const data = await client.readRaw(16448, 414816, 2);
+     *  console.log(data); //<Buffer ff 7f>
      *
-     * Converts a raw byte value to a Javascript object.
+     *  const converted = await client.convertFromRaw(data, 'INT');
+     *  console.log(converted); //32767
+     *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      *
-     * @param data Raw PLC data as Buffer (read for example with `readRaw()`)
-     * @param dataType Data type name in the PLC as string (such as `ST_Struct`) or `AdsDataType` object
+     * @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 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 = {}) {
         if (!this.connection.connected) {
@@ -5346,18 +5618,27 @@ class Client extends events_1.default {
         return value;
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Converts a Javascript object to raw data by using the provided data type.
      *
-     * Converts a Javascript object to raw byte data.
+     * **NOTE:** Do not use `autoFill` for `UNION` types, it doesn't work correctly.
+     
+     * @example
+     * ```js
+     * try {
+     *  const data = await client.convertToRaw(32767, 'INT');
+     *  console.log(data); //<Buffer ff 7f>
      *
-     * **NOTE:** Do not use `autoFill` for `UNION` types, it works without errors but the result isn't probably the desired one
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      *
-     * @param value Javascript object that represents the `dataType` in target system
-     * @param dataType Data type name in the PLC as string (such as `ST_Struct`) or `AdsDataType` object
-     * @param autoFill If true and data type is a container (`STRUCT`, `FUNCTION_BLOCK` etc.), missing properties are automatically **set to default values** (usually `0` or `''`)
+     * @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 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 convertToRaw(value, dataType, autoFill = false, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5413,14 +5694,39 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Creates a handle to a variable at the target system by variable path (such as `GVL_Test.ExampleStruct`).
      *
-     * Creates a variable handle for a PLC symbol by given variable path
+     * The handle can be then used for reading and writing the value.
      *
-     * Variable value can be accessed by using the handle with `readRawByHandle()` and `writeRawByHandle()`
+     * Reading and writing dereferenced `POINTER` and `REFERENCE` values is also possible.
+     * See {@link readRawByHandle}() and {@link writeRawByHandle}().
      *
-     * @param path Full variable path in the PLC (such as `GVL_Test.ExampleStruct`)
-     * @param targetOpts Optional target settings that override values in `settings` (**NOTE:** If used, no caching is available -> possible performance impact)
+     * NOTE: The handle should be deleted after it's no longer needed,
+     * as there is a limited amount of handles available. See {@link deleteVariableHandle}().
+     *
+     * @example
+     * ```js
+     * try {
+     *  //POINTER value (Note the dereference operator ^)
+     *  const handle1 = await client.createVariableHandle('GVL_Read.ComplexTypes.POINTER_^');
+     *  const value = await client.readRawByHandle(handle1);
+     *  await client.deleteVariableHandle(handle1);
+     *
+     *  const handle2 = await client.createVariableHandle('GVL_Read.StandardTypes.INT_');
+     *  const value2 = await client.readRawByHandle(handle2);
+     *  await client.deleteVariableHandle(handle2);
+     *
+     *  //Now you use convertFromRaw() to get actual values
+     *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @param path Variable path in the PLC to read (such as `GVL_Test.ExampleStruct`)
+     * @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 createVariableHandle(path, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5468,7 +5774,7 @@ class Client extends events_1.default {
             let dataTypeLength = response.readUInt16LE(pos);
             pos += 2;
             //10..n Data type
-            result.dataType = ADS.decodePlcStringBuffer(response.subarray(pos, pos + dataTypeLength + 1));
+            result.dataType = ADS.decodePlcStringBuffer(response.subarray(pos, pos + dataTypeLength + 1), this.metaData.adsSymbolsUseUtf8);
             this.debug(`createVariableHandle(): Variable handle created to ${path}`);
             return result;
         }
@@ -5478,18 +5784,44 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Sends multiple {@link createVariableHandle}() commands in one ADS packet.
+     *
+     * Creates a handle to a variable at the target system by variable path (such as `GVL_Test.ExampleStruct`).
+     *
+     * The handle can be then used for reading and writing the value.
      *
-     * Sends multiple createVariableHandle() commands in one ADS packet
+     * Reading and writing dereferenced `POINTER` and `REFERENCE` values is also possible.
+     * See {@link readRawByHandle}() and {@link writeRawByHandle}().
      *
-     * Creates a variable handle for a PLC symbol by given variable path
+     * NOTE: The handle should be deleted after it's no longer needed,
+     * as there is a limited amount of handles available. See {@link deleteVariableHandle}().
      *
-     * Variable value can be accessed by using the handle with `readRawByHandle()` and `writeRawByHandle()`
+     * Uses ADS sum command under the hood (better and faster performance).
+     * See [Beckhoff Information System](https://infosys.beckhoff.com/english.php?content=../content/1033/tc3_adsdll2/9007199379576075.html&id=9180083787138954512) for more info.
+     *
+     * @example
+     * ```js
+     * try {
+     *  const results = await client.createVariableHandleMulti([
+     *    'GVL_Read.StandardTypes.INT_',
+     *    'GVL_Read.StandardTypes.REAL_'
+     *  ]);
      *
-     * Uses ADS sum command under the hood (better perfomance)
+     *  if(results[0].success) {
+     *    console.log(`First handle: ${results[0].handle}`);
+     *  } else {
+     *    console.log(`Creating first handle failed: ${results[0].errorStr}`);
+     *  }
      *
-     * @param paths Array of full variable paths in the PLC (such as `GVL_Test.ExampleStruct`)
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @param paths Array of variable paths in the PLC to read (such as `GVL_Test.ExampleStruct`)
      * @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 createVariableHandleMulti(paths, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5580,7 +5912,7 @@ class Client extends events_1.default {
                     let dataTypeLength = response.readUInt16LE(pos);
                     pos += 2;
                     //10..n Data type
-                    result.dataType = ADS.decodePlcStringBuffer(response.subarray(pos, pos + dataTypeLength + 1));
+                    result.dataType = ADS.decodePlcStringBuffer(response.subarray(pos, pos + dataTypeLength + 1), this.metaData.adsSymbolsUseUtf8);
                     pos += dataTypeLength + 1;
                     results[i].handle = result;
                 }
@@ -5594,12 +5926,26 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Deletes a variable handle that was previously created
+     * using {@link createVariableHandle}().
      *
-     * Deletes a variable handle that was previously created using `createVariableHandle()`
+     * @example
+     * ```js
+     * try {
+     *  const handle = createVariableHandle(...);
+     *
+     *  //After use, deleting the handle
+     *  await client.deleteVariableHandle(handle);
+     *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      *
      * @param handle Variable handle to delete
-     * @param targetOpts Optional target settings that override values in `settings` (**NOTE:** If used, no caching is available -> possible performance impact)
+     * @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 deleteVariableHandle(handle, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5637,16 +5983,38 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Sends multiple {@link deleteVariableHandle}() commands in one ADS packet.
+     *
+     * Deletes a variable handle that was previously created
+     * using {@link createVariableHandle}().
+     *
+     * Uses ADS sum command under the hood (better and faster performance).
+     * See [Beckhoff Information System](https://infosys.beckhoff.com/english.php?content=../content/1033/tc3_adsdll2/9007199379576075.html&id=9180083787138954512) for more info.
      *
-     * Sends multiple deleteVariableHandle() commands in one ADS packet
+     * @example
+     * ```js
+     * try {
+     *  const handle1 = createVariableHandle(...);
+     *  const handle2 = createVariableHandle(...);
      *
-     * Deletes a variable handle that was previously created using `createVariableHandle()`
+     *  //After use, deleting the handles
+     *  const results = await client.deleteVariableHandleMulti([handle1, handle2]);
+     *
+     *  if(results[0].success) {
+     *    console.log(`First deleted`);
+     *  } else {
+     *    console.log(`Deleting first handle failed: ${results[0].errorStr}`);
+     *  }
      *
-     * Uses ADS sum command under the hood (better performance)
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      *
      * @param handles Array of variable handles to delete
      * @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 deleteVariableHandleMulti(handles, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5718,13 +6086,24 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Reads raw data from the target system by a previously created variable handle (acquired using {@link createVariableHandle}())
      *
-     * Reads raw byte data from the target system by previously created variable handle
+     * @example
+     * ```js
+     * try {
+     *  const handle = await client.createVariableHandle('GVL_Read.StandardTypes.INT_'');
+     *  const value = await client.readRawByHandle(handle);
+     *  await client.deleteVariableHandle(handle);
      *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      * @param handle Variable handle
      * @param size Optional data length to read (bytes) - as default, size in handle is used if available. Uses 0xFFFFFFFF as fallback.
-     * @param targetOpts Optional target settings that override values in `settings` (**NOTE:** If used, no caching is available -> possible performance impact)
+     * @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 readRawByHandle(handle, size, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5748,13 +6127,28 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Writes raw data to the target system by a previously created variable handle (acquired using {@link createVariableHandle}())
      *
-     * Writes raw byte data to the target system by previously created variable handle
+     * @example
+     * ```js
+     * try {
+     *  const value = await client.convertToRaw(32767, 'INT');
+     *  console.log(value); //<Buffer ff 7f>
+     *
+     *  const handle = await client.createVariableHandle('GVL_Read.StandardTypes.INT_');
+     *  await client.writeRawByHandle(handle, value);
+     *  await client.deleteVariableHandle(handle);
+     *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      *
      * @param handle Variable handle
      * @param value Data to write
-     * @param targetOpts Optional target settings that override values in `settings` (**NOTE:** If used, no caching is available -> possible performance impact)
+     * @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 writeRawByHandle(handle, value, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5772,12 +6166,23 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Reads raw data from the target system by a symbol object (acquired using `getSymbol()`)
      *
-     * Reads raw data by symbol
+     * @example
+     * ```js
+     * try {
+     *  const symbol = await client.getSymbol('GVL_Read.StandardTypes.INT_');
+     *  const value = await client.readRawBySymbol(symbol);
      *
-     * @param symbol Symbol (acquired using `getSymbol()`)
-     * @param targetOpts Optional target settings that override values in `settings` (**NOTE:** If used, no caching is available -> possible performance impact)
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @param symbol Symbol
+     * @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 readRawBySymbol(symbol, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5795,13 +6200,27 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Writes raw data to the target system by a symbol object (acquired using `getSymbol()`)
+     *
+     * @example
+     * ```js
+     * try {
+     *  const value = await client.convertToRaw(32767, 'INT');
+     *  console.log(value); //<Buffer ff 7f>
      *
-     * Writes raw data by symbol
+     *  const symbol = await client.getSymbol('GVL_Read.StandardTypes.INT_');
+     *  await client.writeRawBySymbol(symbol, value);
      *
-     * @param symbol Symbol (acquired using `getSymbol()`)
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @param symbol Symbol
      * @param value Data to write
      * @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 writeRawBySymbol(symbol, value, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5818,21 +6237,40 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Invokes a function block RPC method on the target system.
      *
-     * Invokes/calls a function block RPC method from PLC
+     * Returns the return value of the method and outputs (if any).
      *
-     * Returns method return value and/or outputs (if any)
+     * NOTE: In the PLC, `{attribute 'TcRpcEnable'}` is required above the `METHOD` definition.
      *
-     * For RPC support, the method needs to have `{attribute 'TcRpcEnable'}` attribute above the `METHOD` definition
+     * @example
+     * ```js
+     * try {
+     *  const res = await client.invokeRpcMethod('GVL_RPC.RpcBlock', 'Calculator', {
+     *    Value1: 1,
+     *    Value2: 123
+     *  });
+     *
+     *  console.log(res);
+     *  //{
+     *  //  returnValue: true,
+     *  //  outputs: { Sum: 124, Product: 123, Division: 0.008130080997943878 }
+     *  //}
      *
-     * @param path Full function block instance path in the PLC (such as `GVL_Test.ExampleBlock`)
-     * @param method Function block method name to call
-     * @param parameters Function block method parameters (inputs) (if any)
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @param path Variable path in the PLC of the function block instance (such as `GVL_Test.ExampleBlock`)
+     * @param method Function block method name
+     * @param parameters Method parameters (inputs) (if any)
      * @param targetOpts Optional target settings that override values in `settings`
      *
      * @template T Typescript data type of the method return value, for example `invokeRpcMethod<number>(...)` or `invokeRpcMethod<ST_TypedStruct>(...)`
      * @template U Typescript data type of the method outputs object, for example `invokeRpcMethod<number, ST_TypedStruct>(...)`
+     *
+     * @throws Throws an error if sending the command fails or if the target responds with an error.
      */
     async invokeRpcMethod(path, method, parameters = {}, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -5867,8 +6305,8 @@ class Client extends events_1.default {
                 throw new client_error_1.default(`invokeRpcMethod(): Method ${method} was not found from symbol ${path}. Available RPC methods are: ${dataType.rpcMethods.map(m => m.name).join(', ')}`);
             }
             //Method inputs and outputs
-            const inputs = rpcMethod.parameters.filter(p => p.flags === ADS.ADS_RCP_METHOD_PARAM_FLAGS.In);
-            const outputs = rpcMethod.parameters.filter(p => p.flags === ADS.ADS_RCP_METHOD_PARAM_FLAGS.Out);
+            const inputs = rpcMethod.parameters.filter(p => (p.flags & ADS.ADS_RCP_METHOD_PARAM_FLAGS.In) === ADS.ADS_RCP_METHOD_PARAM_FLAGS.In);
+            const outputs = rpcMethod.parameters.filter(p => (p.flags & ADS.ADS_RCP_METHOD_PARAM_FLAGS.Out) === ADS.ADS_RCP_METHOD_PARAM_FLAGS.Out);
             //Creating data buffer for inputs
             let inputsData = Buffer.alloc(0);
             for (const input of inputs) {