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

package/dist/ads-client.js

@@ -51,29 +51,39 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Client = exports.ADS = void 0;
-const events_1 = __importDefault(require("events"));
 const net_1 = require("net");
+const events_1 = __importDefault(require("events"));
 const debug_1 = __importDefault(require("debug"));
 const long_1 = __importDefault(require("long"));
 const ADS = __importStar(require("./ads-commons"));
 const client_error_1 = __importDefault(require("./client-error"));
+/**
+ * Common ADS constants and helper functions
+ *
+ * @category Client
+ */
 exports.ADS = __importStar(require("./ads-commons"));
 /**
  * A class for handling TwinCAT ADS protocol communication.
  *
  * Settings are provided in constructor - see {@link Client.constructor} and {@link AdsClientSettings}.
  *
- * A client instance should be created for each target, however, a single client
- * can also be used to communicate with multiple endpoints.
+ * A client instance should be created for each target.
+ * However, a single client instance can also be used to communicate with
+ * multiple endpoints using the `targetOpts` parameter available in all methods.
  *
- * @example
+ * Client also emits different events, such as `client.on('connect', ...)`.
+ * See {@link AdsClientEvents} for all available events.
  *
+ * @example
  * ```js
  * const client = new Client({
  *  targetAmsNetId: "192.168.4.1.1.1",
  *  targetAdsPort: 851
  * });
  * ```
+ *
+ * @category Client
  */
 class Client extends events_1.default {
     /**
@@ -222,7 +232,8 @@ class Client extends events_1.default {
             connectionDownDelay: 5000,
             allowHalfOpen: false,
             rawClient: false,
-            disableCaching: false
+            disableCaching: false,
+            deleteUnknownSubscriptions: true
         };
         /**
          * Active connection information.
@@ -247,6 +258,17 @@ class Client extends events_1.default {
         };
     }
     ;
+    /**
+     * Emits a warning, which results in a `warning` event, and a console message if `hideConsoleWarnings` is not set.
+     *
+     * @param message Warning message
+     */
+    warn(message) {
+        if (!this.settings.hideConsoleWarnings) {
+            console.log(`WARNING: ${message}`);
+        }
+        this.emit('warning', message);
+    }
     /**
      * Clears given timer if it's available and increases the ID.
      *
@@ -409,13 +431,13 @@ class Client extends events_1.default {
                         }
                         //allowHalfOpen allows this, but show some warnings..
                         if (!this.metaData.tcSystemState) {
-                            !this.settings.hideConsoleWarnings && console.log(`WARNING: "allowHalfOpen" setting is active. Target is connected but no connection to TwinCAT system. If target is not PLC runtime, use setting "rawClient" instead of "allowHalfOpen".`);
+                            this.warn(`"allowHalfOpen" setting is active. Target is connected but no connection to TwinCAT system. If target is not PLC runtime, use setting "rawClient" instead of "allowHalfOpen".`);
                         }
                         else if (this.metaData.tcSystemState.adsState !== ADS.ADS_STATE.Run) {
-                            !this.settings.hideConsoleWarnings && console.log(`WARNING: "allowHalfOpen" setting is active. Target is connected but TwinCAT system is in ${this.metaData.tcSystemState.adsStateStr} instead of run mode. No connection to PLC runtime.`);
+                            this.warn(`"allowHalfOpen" setting is active. Target is connected but TwinCAT system is in ${this.metaData.tcSystemState.adsStateStr} instead of run mode. No connection to PLC runtime.`);
                         }
                         else {
-                            !this.settings.hideConsoleWarnings && console.log(`WARNING: "allowHalfOpen" setting is active. No connection to PLC runtime. Check "targetAdsPort" setting and PLC status`);
+                            this.warn(`"allowHalfOpen" setting is active. No connection to PLC runtime. Check "targetAdsPort" setting and PLC status`);
                         }
                     }
                 }
@@ -488,6 +510,7 @@ class Client extends events_1.default {
                     connected: false
                 };
                 this.metaData = { ...this.defaultMetaData };
+                this.activeSubscriptions = {};
                 this.socket?.removeAllListeners();
                 this.socket?.destroy();
                 this.socket = undefined;
@@ -508,6 +531,7 @@ class Client extends events_1.default {
                     connected: false
                 };
                 this.metaData = { ...this.defaultMetaData };
+                this.activeSubscriptions = {};
                 this.socket?.removeAllListeners();
                 this.socket?.destroy();
                 this.socket = undefined;
@@ -525,6 +549,7 @@ class Client extends events_1.default {
                     connected: false
                 };
                 this.metaData = { ...this.defaultMetaData };
+                this.activeSubscriptions = {};
                 this.debug(`disconnectFromTarget(): Connection closing failed, connection was forced to close`);
                 this.emit("disconnect", isReconnecting);
                 return reject(new client_error_1.default(`disconnect(): Disconnected with errors: ${disconnectError.message}`, err));
@@ -555,11 +580,11 @@ class Client extends events_1.default {
                 //Trying to subscribe to previous subscriptions again
                 const failures = await this.restoreSubscriptions();
                 if (!failures.length) {
-                    isReconnecting && !this.settings.hideConsoleWarnings && console.log(`Reconnected and all subscriptions were restored!`);
+                    isReconnecting && this.warn(`Reconnected and all subscriptions were restored!`);
                     this.debug(`reconnectToTarget(): Reconnected and all subscriptions were restored!`);
                 }
                 else {
-                    !this.settings.hideConsoleWarnings && console.log(`WARNING: Reconnected but failed to restore following subscriptions:\n - ${failures.join('\n - ')}`);
+                    this.warn(`Reconnected but failed to restore following subscriptions:\n - ${failures.join('\n - ')}`);
                     this.debug(`reconnectToTarget(): Reconnected but failed to restore following subscriptions: ${failures.join(', ')}`);
                 }
                 this.emit('reconnect', !failures.length, failures);
@@ -906,7 +931,7 @@ class Client extends events_1.default {
                 await this.restoreSubscriptions();
             }
             catch (err) {
-                !this.settings.hideConsoleWarnings && console.log(`WARNING: Target PLC symbol version changed and all subscriptions were not restored (data might be lost from now on). Error info: ${JSON.stringify(err)}`);
+                this.warn(`Target PLC symbol version changed and all subscriptions were not restored (data might be lost from now on). Error info: ${JSON.stringify(err)}`);
                 this.debug(`onPlcSymbolVersionChanged(): Failed to restore all subscriptions. Error: %o`, err);
             }
         }
@@ -920,7 +945,7 @@ class Client extends events_1.default {
      * See also {@link Client.socketErrorHandler} which is `onSocketError.bind(this)`
      */
     onSocketError(err) {
-        !this.settings.hideConsoleWarnings && console.log(`WARNING: Socket connection to target closed to an an error, disconnecting: ${JSON.stringify(err)}`);
+        this.warn(`Socket connection to target closed to an an error, disconnecting: ${JSON.stringify(err)}`);
         this.onConnectionLost(true);
     }
     /**
@@ -936,12 +961,12 @@ class Client extends events_1.default {
         this.connection.connected = false;
         this.emit('connectionLost', socketFailure);
         if (this.settings.autoReconnect !== true) {
-            !this.settings.hideConsoleWarnings && console.log("WARNING: Connection to target was lost and setting autoReconnect was false -> disconnecting");
+            this.warn("Connection to target was lost and setting autoReconnect was false -> disconnecting");
             await this.disconnectFromTarget(true).catch();
             return;
         }
         this.socketConnectionLostHandler && this.socket?.off('close', this.socketConnectionLostHandler);
-        !this.settings.hideConsoleWarnings && console.log("WARNING: Connection to target was lost. Trying to reconnect automatically...");
+        this.warn("Connection to target was lost. Trying to reconnect automatically...");
         const tryToReconnect = async (firstRetryAttempt, timerId) => {
             //If the timer has changed, quit here (to prevent multiple timers)
             if (this.reconnectionTimer.id !== timerId) {
@@ -958,7 +983,7 @@ class Client extends events_1.default {
                 //Reconnecting failed
                 if (firstRetryAttempt) {
                     this.debug(`onConnectionLost()/tryToReconnect(): Reconnecting failed, keeping trying in the background (${err.message}`);
-                    !this.settings.hideConsoleWarnings && console.log(`WARNING: Reconnecting failed. Keeping trying in the background every ${this.settings.reconnectInterval} ms...`);
+                    this.warn(`Reconnecting failed. Keeping trying in the background every ${this.settings.reconnectInterval} ms...`);
                 }
                 //If this is still a valid timer, start over again
                 if (this.reconnectionTimer.id === timerId) {
@@ -1434,12 +1459,24 @@ class Client extends events_1.default {
                             })
                                 .catch(err => {
                                 this.debug(`onAdsCommandReceived(): Notification received but parsing Javascript object failed: %o`, err);
-                                this.emit('client-error', new client_error_1.default(`onAdsCommandReceived(): Ntification received but parsing data to Javascript object failed. Subscription: ${JSON.stringify(subscription)}`, err));
+                                this.emit('client-error', new client_error_1.default(`An ADS notification received but parsing data to a Javascript object failed. Subscription: ${JSON.stringify(subscription)}`, err));
+                            });
+                        }
+                        else if (this.settings.deleteUnknownSubscriptions) {
+                            this.debug(`onAdsCommandReceived(): An ADS notification with an unknown handle ${sample.notificationHandle} was received from ${key}. Trying to delete it to save resources (deleteUnknownSubscriptions is set).`);
+                            this.deleteNotificationHandle(sample.notificationHandle, packet.ams.sourceAmsAddress)
+                                .then(() => {
+                                this.debug(`onAdsCommandReceived(): An ADS notification with an unknown handle ${sample.notificationHandle} was received from ${key} and automatically deleted`);
+                                this.warn(`An ADS notification with an unknown handle ${sample.notificationHandle} was received from ${key} and automatically deleted`);
+                            })
+                                .catch(err => {
+                                this.debug(`onAdsCommandReceived(): Failed to delete an unknown ADS notification handle ${sample.notificationHandle} (from ${key}): %o`, err);
+                                this.emit('client-error', new client_error_1.default(`Failed to delete an unknown ADS notification handle ${sample.notificationHandle} (from ${key})`, err));
                             });
                         }
                         else {
-                            this.debugD(`onAdsCommandReceived(): Notification received with unknown handle ${sample.notificationHandle} (${key}). Use unsubscribe() to save resources`);
-                            this.emit('client-error', new client_error_1.default(`onAdsCommandReceived(): Notification received with unknown handle ${sample.notificationHandle} (${key}). Use unsubscribe() to save resources.`));
+                            this.debug(`onAdsCommandReceived(): Notification received with unknown handle ${sample.notificationHandle} (${key})`);
+                            this.warn(`An ADS notification with an unknown handle ${sample.notificationHandle} was received from ${key}. Use unsubscribe() or deleteUnknownSubscriptions setting to save resources.`);
                         }
                     }
                 }
@@ -1454,7 +1491,7 @@ class Client extends events_1.default {
                 }
                 else {
                     this.debugD(`onAdsCommandReceived(): Ads command received with unknown invokeId "${packet.ams.invokeId}"`);
-                    this.emit('client-error', new client_error_1.default(`onAdsCommandReceived(): Ads command received with unknown invokeId "${packet.ams.invokeId}"`));
+                    this.emit('client-error', new client_error_1.default(`Ads command received with unknown invokeId "${packet.ams.invokeId}"`));
                 }
                 break;
         }
@@ -1486,7 +1523,7 @@ class Client extends events_1.default {
             this.clearTimer(this.tcSystemStatePollerTimer);
             this.debug("onRouterStateChanged(): Local loopback connection active, monitoring router state. Reconnecting when router is back running.");
             if (this.metaData.routerState.state === ADS.AMS_ROUTER_STATE.START) {
-                !this.settings.hideConsoleWarnings && console.log(`WARNING: Local AMS router state has changed to ${this.metaData.routerState.stateStr}. Reconnecting...`);
+                this.warn(`Local AMS router state has changed to ${this.metaData.routerState.stateStr}. Reconnecting...`);
                 this.onConnectionLost();
             }
             else {
@@ -1859,7 +1896,7 @@ class Client extends events_1.default {
         }
         //If extended flag RefactorInfo is set
         if ((symbol.extendedFlags & ADS.ADS_SYMBOL_FLAGS_2.RefactorInfo) === ADS.ADS_SYMBOL_FLAGS_2.RefactorInfo) {
-            !this.settings.hideConsoleWarnings && console.log(`WARNING: Symbol ${symbol.name} (${symbol.type}) has extended flag "RefactorInfo" which is not supported. Things might not work now. Please open an issue at Github`);
+            this.warn(`Symbol ${symbol.name} (${symbol.type}) has extended flag "RefactorInfo" which is not supported. Things might not work now. Please open an issue at Github`);
         }
         //Reserved, if any
         symbol.reserved = data.subarray(pos);
@@ -2164,7 +2201,7 @@ class Client extends events_1.default {
         if ((dataType.flags & ADS.ADS_DATA_TYPE_FLAGS.RefactorInfo) === ADS.ADS_DATA_TYPE_FLAGS.RefactorInfo) {
             //TODO: this is not working now
             //Things probably break now
-            !this.settings.hideConsoleWarnings && console.log(`WARNING: Data type ${dataType.name} (${dataType.type}) has flag "RefactorInfo" which is not supported. Things might not work now. Please open an issue at Github`);
+            this.warn(`Data type ${dataType.name} (${dataType.type}) has flag "RefactorInfo" which is not supported. Things might not work now. Please open an issue at Github`);
         }
         //If flag ExtendedFlags set
         if ((dataType.flags & ADS.ADS_DATA_TYPE_FLAGS.ExtendedFlags) === ADS.ADS_DATA_TYPE_FLAGS.ExtendedFlags) {
@@ -2181,13 +2218,13 @@ class Client extends events_1.default {
         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.settings.hideConsoleWarnings && console.log(`WARNING: Data type ${dataType.name} (${dataType.type}) has flag "ExtendedEnumInfos" which is not supported. Things might not work now. Please open an issue at Github`);
+            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`);
         }
         //If flag SoftwareProtectionLevels set
         if ((dataType.flags & ADS.ADS_DATA_TYPE_FLAGS.SoftwareProtectionLevels) === ADS.ADS_DATA_TYPE_FLAGS.SoftwareProtectionLevels) {
             //TODO: this is not working now
             //Things probably break now
-            !this.settings.hideConsoleWarnings && console.log(`WARNING: Data type ${dataType.name} (${dataType.type}) has flag "SoftwareProtectionLevels" which is not supported. Things might not work now. Please open an issue at Github`);
+            this.warn(`Data type ${dataType.name} (${dataType.type}) has flag "SoftwareProtectionLevels" which is not supported. Things might not work now. Please open an issue at Github`);
         }
         //Reserved, if any
         dataType.reserved = data.subarray(pos);
@@ -2901,14 +2938,44 @@ class Client extends events_1.default {
      * - {@link Client.unsubscribe}() - `DeleteNotification` command
      * - {@link Client.readWriteRaw}() - `ReadWrite` command
      *
-     * @template T ADS response type. If omitted, generic {@link AdsResponse} type is used
-     *
-     * @throws Throws an error if sending the command fails or if target responds with an error
-     *
      * @example
      * ```js
-     * TODO - DOCUMENTATION ONGOING
+     * try {
+     *  //Creating readRaw(16448, 414816, 2) command manually and sending it using sendAdsCommand()
+     *
+     *  const data = Buffer.alloc(12);
+     *  let pos = 0;
+     *
+     *  //0..3 IndexGroup
+     *  data.writeUInt32LE(16448, pos);
+     *  pos += 4;
+     *
+     *  //4..7 IndexOffset
+     *  data.writeUInt32LE(414816, pos);
+     *  pos += 4;
+     *
+     *  //8..11 Read data length
+     *  data.writeUInt32LE(2, pos);
+     *  pos += 4;
+     *
+     *  const res = await this.sendAdsCommand<AdsReadResponse>({
+     *    adsCommand: ADS.ADS_COMMAND.Read,
+     *    targetAmsNetId: targetOpts.amsNetId,
+     *    targetAdsPort: targetOpts.adsPort,
+     *    payload: data
+     *  });
+     *
+     *  console.log(res.ads.payload); //<Buffer ff 7f>
+     *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
      * ```
+     *
+     * @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 sendAdsCommand(command) {
         return new Promise(async (resolve, reject) => {
@@ -3221,7 +3288,7 @@ class Client extends events_1.default {
             this.debug(`setTcSystemToRun(): TwinCAT system at ${this.targetToString(targetOpts)} set to run mode`);
             if (reconnect) {
                 this.debug(`setTcSystemToRun(): Reconnecting after TwinCAT system restart`);
-                !this.settings.hideConsoleWarnings && console.log("WARNING: Reconnecting after TwinCAT system restart");
+                this.warn("Reconnecting after TwinCAT system restart");
                 this.onConnectionLost();
             }
         }
@@ -3300,7 +3367,7 @@ class Client extends events_1.default {
         this.debug(`restartTcSystem(): TwinCAT system was restarted`);
     }
     /**
-     * Returns symbol for given variable path, such as `GVL_Test.ExampleStruct`.
+     * Returns a symbol object for given variable path, such as `GVL_Test.ExampleStruct`.
      *
      * Returns previously cached value if available, otherwise reads it from the target
      * and caches it.
@@ -3671,7 +3738,7 @@ class Client extends events_1.default {
         }
     }
     /**
-     * Subscribes to raw value change notifications (ADS notifications) by raw ADS address (index group, index offset and data length).
+     * Subscribes to raw value change notifications (ADS notifications) by a raw ADS address (index group, index offset and data length).
      *
      * Provided callback is called with the latest value when the value changes or when
      * enough time has passed (depending on settings).
@@ -3830,19 +3897,8 @@ class Client extends events_1.default {
             throw new client_error_1.default(`unsubscribe(): Client is not connected. Use connect() to connect to the target first.`);
         }
         this.debug(`unsubscribe(): Unsubscribing %o`, subscription);
-        //Allocating bytes for request
-        const data = Buffer.alloc(4);
-        let pos = 0;
-        //0..3 Notification handle
-        data.writeUInt32LE(subscription.notificationHandle, pos);
-        pos += 4;
         try {
-            const res = await this.sendAdsCommand({
-                adsCommand: ADS.ADS_COMMAND.DeleteNotification,
-                targetAmsNetId: subscription.remoteAddress.amsNetId,
-                targetAdsPort: subscription.remoteAddress.adsPort,
-                payload: data
-            });
+            await this.deleteNotificationHandle(subscription.notificationHandle, subscription.remoteAddress);
             const address = ADS.amsAddressToString(subscription.remoteAddress);
             if (this.activeSubscriptions[address]) {
                 delete this.activeSubscriptions[address][subscription.notificationHandle];
@@ -3854,6 +3910,33 @@ class Client extends events_1.default {
             throw new client_error_1.default(`unsubscribe(): Unsubscribing failed`, err);
         }
     }
+    /**
+     * Sends a delete ADS notification command to the target system.
+     *
+     * Doesn't delete subscriptions, just sends the ADS command.
+     *
+     * @param notificationHandle Notification handle to delete (number)
+     * @param targetAmsAddress Target system address
+     *
+     * @throws NOTE: Throws error if failed
+     */
+    async deleteNotificationHandle(notificationHandle, targetAmsAddress) {
+        this.debug(`deleteNotificationHandle(): Sending DeleteNotification command for handle ${notificationHandle} to ${ADS.amsAddressToString(targetAmsAddress)}`);
+        //Allocating bytes for request
+        const data = Buffer.alloc(4);
+        let pos = 0;
+        //0..3 Notification handle
+        data.writeUInt32LE(notificationHandle, pos);
+        pos += 4;
+        const res = await this.sendAdsCommand({
+            adsCommand: ADS.ADS_COMMAND.DeleteNotification,
+            targetAmsNetId: targetAmsAddress.amsNetId,
+            targetAdsPort: targetAmsAddress.adsPort,
+            payload: data
+        });
+        this.debug(`deleteNotificationHandle(): Notification for handle ${notificationHandle} (${ADS.amsAddressToString(targetAmsAddress)}) deleted!`);
+        return res.ads;
+    }
     /**
      * Unsubscribes all active subscription (deletes all ADS notifications).
      *
@@ -4268,16 +4351,30 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Reads raw data from the target system by a raw ADS address (index group, index offset and data length).
      *
-     * Reads raw byte data from the target system by provided index group, index offset and data length (bytes)
+     * This is the ADS protocol `Read` command.
      *
-     * This is the `ADS read` command in ADS protocol.
+     * @example
+     * ```js
+     * try {
+     *  const data = await client.readRaw(16448, 414816, 2);
+     *  console.log(data); //<Buffer ff 7f>
+     *
+     *  const converted = await client.convertFromRaw(data, 'INT');
+     *  console.log(converted); //32767
+     *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      *
      * @param indexGroup Index group (address) of the data to read
      * @param indexOffset Index offset (address) of the data to read
      * @param size Data length to read (bytes)
      * @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 readRaw(indexGroup, indexOffset, size, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -4312,16 +4409,28 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Writes raw data to the target system by a raw ADS address (index group, index offset and data length).
      *
-     * Writes raw byte data to the target system by provided index group and index offset.
+     * This is the ADS protocol `Write` command.
      *
-     * This is the `ADS write` command in ADS protocol.
+     * @example
+     * ```js
+     * try {
+     *  const data = await client.convertToRaw(32767, 'INT');
+     *  console.log(data); //<Buffer ff 7f>
+     *
+     *  await client.writeRaw(16448, 414816, data);
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      *
      * @param indexGroup Index group (address) of the data to write to
      * @param indexOffset Index offset (address) of the data to write to
      * @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 writeRaw(indexGroup, indexOffset, value, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -4357,16 +4466,45 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Sends multiple `readRaw()` commands in one ADS packet.
      *
-     * Sends multiple readRaw() commands in one ADS packet
+     * Reads raw data from the target system by a raw ADS addresses (index group, index offset and data length).
+     * Results are returned for each command separately - see {@link ReadRawMultiResult} for details.
      *
-     * Reads raw byte data from the target system by provided index group, index offset and data length (bytes)
+     * 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.
      *
-     * Uses ADS sum command under the hood (better performance)
+     * @example
+     * ```js
+     * try {
+     *  const results = await client.readRawMulti([
+     *    {
+     *      indexGroup: 16448,
+     *      indexOffset: 414816,
+     *      size: 2
+     *    },
+     *    {
+     *      indexGroup: 16448,
+     *      indexOffset: 414900,
+     *      size: 128
+     *    }
+     *  ]);
+     *
+     *  if(results[0].success) {
+     *    console.log(`First result: ${results[0].value}`); //First result: <Buffer ff 7f>
+     *  } else {
+     *    console.log(`First read command failed: ${results[0].errorStr}`);
+     *  }
+     *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      *
      * @param commands Array of read commands
      * @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 readRawMulti(commands, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -4442,16 +4580,50 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Sends multiple `writeRaw()` commands in one ADS packet.
      *
-     * Sends multiple writeRaw() commands in one ADS packet
+     * Writes raw data to the target system by a raw ADS addresses (index group and index offset).
+     * Results are returned for each command separately - see {@link WriteRawMultiResult} for details.
      *
-     * Writes raw byte data to the target system by provided index group and index offset.
+     * 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.
      *
-     * Uses ADS sum command under the hood (better performance)
+     * @example
+     * ```js
+     * try {
+     *  const data1 = await client.convertToRaw(32767, 'INT');
+     *  console.log(data1); //<Buffer ff 7f>
+     *
+     *  const data2 = Buffer.alloc(128); //example
+     *
+     *  const results = await client.writeRawMulti([
+     *    {
+     *      indexGroup: 16448,
+     *      indexOffset: 414816,
+     *      value: data1
+     *    },
+     *    {
+     *      indexGroup: 16448,
+     *      indexOffset: 414900,
+     *      value: data2
+     *    }
+     *  ]);
+     *
+     *  if(results[0].success) {
+     *    console.log(`First write command successful`);
+     *  } else {
+     *    console.log(`First write command failed: ${results[0].errorStr}`);
+     *  }
+     *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      *
      * @param commands Array of write commands
      * @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 writeRawMulti(commands, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -4523,16 +4695,37 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Reads raw data from the target system by variable path (such as `GVL_Test.ExampleStruct`).
+     *
+     * Supports also reading `POINTER` and `REFERENCE` values (see example).
+     *
+     * This uses the ADS `READ_SYMVAL_BYNAME` under the hood, so only one
+     * round-trip is needed.
+     *
+     * @example
+     * ```js
+     * try {
+     *  const data = await client.readRawByPath('GVL_Read.StandardTypes.INT_');
+     *  console.log(data); //<Buffer ff 7f>
      *
-     * Reads raw byte data from the target system by symbol path.
+     *  const converted = await client.convertFromRaw(data, 'INT');
+     *  console.log(converted); //32767
      *
-     * Supports also reading POINTER and REFERENCE values by using deference operator in path (`^`)
+     * //Reading a POINTER value (Note the dereference operator ^)
+     * const ptrValue = await client.readRawByPath('GVL_Read.ComplexTypes.POINTER_^');
      *
-     * This uses the ADS command `READ_SYMVAL_BYNAME` under the hood
+     * //Reading a REFERENCE value
+     * const refValue = await client.readRawByPath('GVL_Read.ComplexTypes.REFERENCE_');
+     *
+     * } 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 readRawByPath(path, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -4574,17 +4767,39 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Writes raw data to the target system by variable path (such as `GVL_Test.ExampleStruct`).
      *
-     * Writes raw byte data to the target system by symbol path.
+     * Supports also writing `POINTER` and `REFERENCE` values (see example).
      *
-     * Supports also reading POINTER and REFERENCE values by using deference operator in path (`^`)
+     * NOTE: Unlike with {@link readRawByPath}(), this command uses multiple ADS requests for the operation.
      *
-     * Unlike `readRawByPath()`, this uses variable handles under the hood, the as there is no direct ADS command available for this.
      *
-     * @param path Variable path in the PLC to read (such as `GVL_Test.ExampleStruct`)
+     * @example
+     * ```js
+     * try {
+     *  const data = await client.convertToRaw(32767, 'INT');
+     *  console.log(data); //<Buffer ff 7f>
+     *
+     *  await client.writeRawByPath('GVL_Write.StandardTypes.INT_', data);
+     *
+     * //Writing a POINTER value (Note the dereference operator ^)
+     * const ptrValue = ...
+     * await client.writeRawByPath('GVL_Read.ComplexTypes.POINTER_^', ptrValue);
+     *
+     * //Writing a REFERENCE value
+     * const refValue = ...
+     * await client.readRawByPath('GVL_Read.ComplexTypes.REFERENCE_');
+     *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @param path Variable path in the PLC to write (such as `GVL_Test.ExampleStruct`)
      * @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 writeRawByPath(path, value, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -4594,12 +4809,12 @@ class Client extends events_1.default {
         try {
             let handle = null;
             try {
-                handle = await this.createVariableHandle(path);
-                await this.writeRawByHandle(handle, value);
+                handle = await this.createVariableHandle(path, targetOpts);
+                await this.writeRawByHandle(handle, value, targetOpts);
             }
             finally {
                 if (handle) {
-                    await this.deleteVariableHandle(handle);
+                    await this.deleteVariableHandle(handle, targetOpts);
                 }
             }
             this.debug(`writeRawByPath(): Writing raw data to ${path} done (${value.byteLength} bytes)`);
@@ -4610,25 +4825,41 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Writes raw data to the target system by a raw ADS address (index group, index offset)
+     * and reads the result as raw data.
      *
-     * Writes raw data to the target and reads the result as raw data
+     * This is the ADS protocol `ReadWrite` command.
      *
-     * Uses `ADS ReadWrite` command
+     * @example
+     * ```js
+     * const { ADS } = require('../dist/ads-client');
+     *
+     * try {
+     *  //Reading raw value by symbol path (= same as readRawByPath())
+     *  const path = ADS.encodeStringToPlcStringBuffer('GVL_Read.StandardTypes.INT_');
+     *  const data = await client.readWriteRaw(ADS.ADS_RESERVED_INDEX_GROUPS.SymbolValueByName, 0, 0xFFFFFFFF, path);
+     *  console.log(data); //<Buffer ff 7f>
+     *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      *
      * @param indexGroup Address index group
      * @param indexOffset Address index offset
-     * @param size How many bytes to read
-     * @param writeData Data to write
+     * @param size Data length to read (bytes)
+     * @param value Value 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 readWriteRaw(indexGroup, indexOffset, size, writeData, targetOpts = {}) {
+    async readWriteRaw(indexGroup, indexOffset, size, value, targetOpts = {}) {
         if (!this.connection.connected) {
             throw new client_error_1.default(`readWriteRaw(): Client is not connected. Use connect() to connect to the target first.`);
         }
-        this.debug(`readWriteRaw(): Sending ReadWrite command (${JSON.stringify({ indexGroup, indexOffset, size })} with ${writeData.byteLength} bytes of data`);
+        this.debug(`readWriteRaw(): Sending ReadWrite command (${JSON.stringify({ indexGroup, indexOffset, size })} with ${value.byteLength} bytes of data`);
         //Allocating bytes for request
-        const data = Buffer.alloc(16 + writeData.byteLength);
+        const data = Buffer.alloc(16 + value.byteLength);
         let pos = 0;
         //0..3 IndexGroup 
         data.writeUInt32LE(indexGroup, pos);
@@ -4640,11 +4871,11 @@ class Client extends events_1.default {
         data.writeUInt32LE(size, pos);
         pos += 4;
         //12..15 Write data length
-        data.writeUInt32LE(writeData.byteLength, pos);
+        data.writeUInt32LE(value.byteLength, pos);
         pos += 4;
         //16..n Write data
-        writeData.copy(data, pos);
-        pos += writeData.byteLength;
+        value.copy(data, pos);
+        pos += value.byteLength;
         try {
             const res = await this.sendAdsCommand({
                 adsCommand: ADS.ADS_COMMAND.ReadWrite,
@@ -4661,14 +4892,52 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Sends multiple `readWriteRaw()` commands in one ADS packet.
      *
-     * Sends multiple readWriteRaw() commands in one ADS packet
+     * Writes raw data to the target system by a raw ADS address (index group, index offset)
+     * and reads the result as raw data.
      *
-     * Uses ADS sum command under the hood (better performance)
+     * 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.
      *
-     * @param commands Array of read write commands
+     * @example
+     * ```js
+     * try {
+     *  //Reading raw values by symbol paths (= same as readRawByPath())
+     *  const path = ADS.encodeStringToPlcStringBuffer('GVL_Read.StandardTypes.INT_');
+     *  const path2 = ADS.encodeStringToPlcStringBuffer('GVL_Read.StandardTypes.REAL_');
+     *
+     *  const results = await client.readWriteRawMulti([
+     *    {
+     *      indexGroup: ADS.ADS_RESERVED_INDEX_GROUPS.SymbolValueByName,
+     *      indexOffset: 0,
+     *      size: 0xFFFF,
+     *      value: path
+     *    },
+     *    {
+     *      indexGroup: ADS.ADS_RESERVED_INDEX_GROUPS.SymbolValueByName,
+     *      indexOffset: 0,
+     *      size: 0xFFFF,
+     *      value: path2
+     *    }
+     *  ]);
+     *
+     *  if(results[0].success) {
+     *    console.log(`First result: ${results[0].value}`); //First result: <Buffer ff 7f>
+     *  } else {
+     *    console.log(`First read/write command failed: ${results[0].errorStr}`);
+     *  }
+     *
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     *
+     * ```
+     *
+     * @param commands Array of read/write commands
      * @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 readWriteRawMulti(commands, targetOpts = {}) {
         if (!this.connection.connected) {
@@ -4676,7 +4945,7 @@ class Client extends events_1.default {
         }
         this.debug(`readWriteRawMulti(): Sending ${commands.length} ReadWrite commands`);
         const totalSize = commands.reduce((total, command) => total + command.size, 0);
-        const totalWriteSize = commands.reduce((total, command) => total + command.writeData.byteLength, 0);
+        const totalWriteSize = commands.reduce((total, command) => total + command.value.byteLength, 0);
         //Allocating bytes for request
         const data = Buffer.alloc(16 + commands.length * 16 + totalWriteSize);
         let pos = 0;
@@ -4704,13 +4973,13 @@ class Client extends events_1.default {
             data.writeUInt32LE(command.size, pos);
             pos += 4;
             //12..15 Write data length
-            data.writeUInt32LE(command.writeData.byteLength, pos);
+            data.writeUInt32LE(command.value.byteLength, pos);
             pos += 4;
         });
         //data
         commands.forEach(command => {
-            command.writeData.copy(data, pos);
-            pos += command.writeData.byteLength;
+            command.value.copy(data, pos);
+            pos += command.value.byteLength;
         });
         try {
             const res = await this.sendAdsCommand({
@@ -4759,13 +5028,28 @@ class Client extends events_1.default {
         }
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Reads variable's value from the target system by a variable path (such as `GVL_Test.ExampleStruct`)
+     * and returns the value as a Javascript object.
      *
-     * Reads a value by a variable path (such as `GVL_Test.ExampleStruct`) and converts the value to a Javascript object.
+     * Returns variable's
+     * - converted value
+     * - raw value
+     * - data type
+     * - symbol
      *
-     * Returns the converted value, the raw value, the data type and the symbol.
+     * **NOTE:** This requires that the target is a PLC runtime or has equivalent ADS protocol support.
      *
-     * @param path Variable path in the PLC to read (such as `GVL_Test.ExampleStruct`)
+     * @example
+     * ```js
+     * try {
+     *  const res = await client.readValue('GVL_Test.ExampleStruct');
+     *  console.log(res.value);
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @param path Variable path in the PLC (such as `GVL_Test.ExampleStruct`)
      * @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`)
@@ -4824,13 +5108,30 @@ class Client extends events_1.default {
         };
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Reads variable's value from the target system by a symbol object
+     * and returns the value as a Javascript object.
      *
-     * Reads a value by a symbol and converts the value to a Javascript object.
+     * Returns variable's
+     * - converted value
+     * - raw value
+     * - data type
+     * - symbol
      *
-     * Returns the converted value, the raw value, the data type and the symbol.
+     * **NOTE:** This requires that the target is a PLC runtime or has equivalent ADS protocol support.
      *
-     * @param symbol Symbol (acquired using `getSymbol()`)
+     * @example
+     * ```js
+     * try {
+     *  const symbol = await client.getSymbol('GVL_Test.ExampleStruct');
+     *
+     *  const res = await client.readValueBySymbol(symbol);
+     *  console.log(res.value);
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @param symbol Symbol object (acquired using {@link getSymbol}())
      * @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`)
@@ -4842,18 +5143,36 @@ class Client extends events_1.default {
         return this.readValue(symbol.name, targetOpts);
     }
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Writes variable's value to the target system by a variable path (such as `GVL_Test.ExampleStruct`).
+     * Converts the value from a Javascript object to a raw value.
      *
-     * Writes a value by a variable path (such as `GVL_Test.ExampleStruct`). 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:** Do not use `autoFill` for `UNION` types, it works without errors but the result isn't probably the desired one
+     * **NOTE:** This requires that the target is a PLC runtime or has equivalent ADS protocol support.
      *
-     * @param path Variable path in the PLC to read (such as `GVL_Test.ExampleStruct`)
+     * @example
+     * ```js
+     * try {
+     *  const value = {
+     *    example: true
+     *  };
+     *
+     *  const res = await client.writeValue('GVL_Test.ExampleStruct', value);
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @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 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 default values (usually `0` or `''`).
      *
      * @template T In Typescript, the data type of the value, for example `writeValue<number>(...)` or `writeValue<ST_TypedStruct>(...)`
      */