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

package/dist/ads-client.d.ts

@@ -1,29 +1,39 @@
 import EventEmitter from "events";
-import type { ActiveSubscription, AdsClientConnection, AdsClientSettings, AdsCommandToSend, AdsDataTypeContainer, AdsSymbolContainer, AdsUploadInfo, ConnectionMetaData, SubscriptionSettings, ReadValueResult, WriteValueResult, VariableHandle, RpcMethodCallResult, CreateVariableHandleMultiResult, ReadRawMultiResult, ReadRawMultiCommand, WriteRawMultiResult, DeleteVariableHandleMultiResult, ReadWriteRawMultiResult, ReadWriteRawMultiCommand, WriteRawMultiCommand, ClientEvents, SubscriptionCallback, DebugLevel } from "./types/ads-client-types";
-import { AdsDataType, AdsDeviceInfo, AdsResponse, AdsState, AdsSymbol, AmsAddress, AmsTcpPacket } from "./types/ads-protocol-types";
 import * as ADS from './ads-commons';
-export * as ADS from './ads-commons';
+import type { ActiveSubscription, AdsClientConnection, AdsClientSettings, AdsCommandToSend, AdsDataTypeContainer, AdsSymbolContainer, AdsUploadInfo, ConnectionMetaData, SubscriptionSettings, ReadValueResult, WriteValueResult, VariableHandle, RpcMethodCallResult, CreateVariableHandleMultiResult, ReadRawMultiResult, ReadRawMultiCommand, WriteRawMultiResult, DeleteVariableHandleMultiResult, ReadWriteRawMultiResult, ReadWriteRawMultiCommand, WriteRawMultiCommand, SubscriptionCallback, DebugLevel, AdsClientEvents } from "./types/ads-client-types";
+import { AdsDataType, AdsDeviceInfo, AdsResponse, AdsState, AdsSymbol, AmsAddress, AmsTcpPacket } from "./types/ads-protocol-types";
 export type * from "./types/ads-client-types";
 export type * from './types/ads-protocol-types';
 export type * from './client-error';
+/**
+ * Common ADS constants and helper functions
+ *
+ * @category Client
+ */
+export * as ADS from './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
  */
-export declare class Client extends EventEmitter<ClientEvents> {
+export declare class Client extends EventEmitter<AdsClientEvents> {
     /**
      * Debug instance for debug level 1.
      */
@@ -169,6 +179,12 @@ export declare class Client extends EventEmitter<ClientEvents> {
      * ```
      */
     constructor(settings: AdsClientSettings);
+    /**
+     * Emits a warning, which results in a `warning` event, and a console message if `hideConsoleWarnings` is not set.
+     *
+     * @param message Warning message
+     */
+    private warn;
     /**
      * Clears given timer if it's available and increases the ID.
      *
@@ -573,14 +589,44 @@ export declare class Client extends EventEmitter<ClientEvents> {
      * - {@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
+     *
      */
     sendAdsCommand<T = AdsResponse>(command: AdsCommandToSend): Promise<AmsTcpPacket<T>>;
     /**
@@ -752,7 +798,7 @@ export declare class Client extends EventEmitter<ClientEvents> {
      */
     restartTcSystem(reconnect?: boolean, targetOpts?: Partial<AmsAddress>): Promise<void>;
     /**
-     * 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.
@@ -766,7 +812,7 @@ export declare class Client extends EventEmitter<ClientEvents> {
      * @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);
      * }
@@ -918,7 +964,7 @@ export declare class Client extends EventEmitter<ClientEvents> {
      * //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}`);
      *  },
@@ -961,7 +1007,7 @@ export declare class Client extends EventEmitter<ClientEvents> {
      */
     subscribeValue<T = any>(path: string, callback: SubscriptionCallback<T>, cycleTime?: number, sendOnChange?: boolean, maxDelay?: number, targetOpts?: Partial<AmsAddress>): Promise<ActiveSubscription<T>>;
     /**
-     * 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).
@@ -1026,7 +1072,7 @@ export declare class Client extends EventEmitter<ClientEvents> {
      * //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}`);
      *  },
@@ -1082,6 +1128,17 @@ export declare class Client extends EventEmitter<ClientEvents> {
      * @throws Throws an error if sending the command fails or if the target responds with an error.
      */
     unsubscribe(subscription: ActiveSubscription): Promise<void>;
+    /**
+     * 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
+     */
+    private deleteNotificationHandle;
     /**
      * Unsubscribes all active subscription (deletes all ADS notifications).
      *
@@ -1253,310 +1310,757 @@ export declare class Client extends EventEmitter<ClientEvents> {
      */
     cacheDataTypes(): Promise<void>;
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Reads raw data from the target system by a raw ADS address (index group, index offset and data length).
+     *
+     * This is the ADS protocol `Read` command.
+     *
+     * @example
+     * ```js
+     * try {
+     *  const data = await client.readRaw(16448, 414816, 2);
+     *  console.log(data); //<Buffer ff 7f>
      *
-     * Reads raw byte data from the target system by provided index group, index offset and data length (bytes)
+     *  const converted = await client.convertFromRaw(data, 'INT');
+     *  console.log(converted); //32767
      *
-     * This is the `ADS read` command in ADS protocol.
+     * } 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.
      */
     readRaw(indexGroup: number, indexOffset: number, size: number, targetOpts?: Partial<AmsAddress>): Promise<Buffer>;
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Writes raw data to the target system by a raw ADS address (index group, index offset and data length).
+     *
+     * This is the ADS protocol `Write` command.
      *
-     * Writes raw byte data to the target system by provided index group and index offset.
+     * @example
+     * ```js
+     * try {
+     *  const data = await client.convertToRaw(32767, 'INT');
+     *  console.log(data); //<Buffer ff 7f>
      *
-     * This is the `ADS write` command in ADS protocol.
+     *  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.
      */
     writeRaw(indexGroup: number, indexOffset: number, value: Buffer, targetOpts?: Partial<AmsAddress>): Promise<void>;
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * 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.
      *
-     * Sends multiple readRaw() commands in one ADS packet
+     * 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.
      *
-     * Reads raw byte data from the target system by provided index group, index offset and data length (bytes)
+     * @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}`);
+     *  }
      *
-     * Uses ADS sum command under the hood (better performance)
+     * } 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.
      */
     readRawMulti(commands: ReadRawMultiCommand[], targetOpts?: Partial<AmsAddress>): Promise<ReadRawMultiResult[]>;
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * 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.
      *
-     * Sends multiple writeRaw() commands in one ADS packet
+     * 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.
      *
-     * Writes raw byte data to the target system by provided index group and index offset.
+     * @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}`);
+     *  }
      *
-     * Uses ADS sum command under the hood (better performance)
+     * } 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.
      */
     writeRawMulti(commands: WriteRawMultiCommand[], targetOpts?: Partial<AmsAddress>): Promise<WriteRawMultiResult[]>;
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Reads raw data from the target system by variable path (such as `GVL_Test.ExampleStruct`).
      *
-     * Reads raw byte data from the target system by symbol path.
+     * Supports also reading `POINTER` and `REFERENCE` values (see example).
      *
-     * Supports also reading POINTER and REFERENCE values by using deference operator in path (`^`)
+     * This uses the ADS `READ_SYMVAL_BYNAME` under the hood, so only one
+     * round-trip is needed.
      *
-     * This uses the ADS command `READ_SYMVAL_BYNAME` under the hood
+     * @example
+     * ```js
+     * try {
+     *  const data = await client.readRawByPath('GVL_Read.StandardTypes.INT_');
+     *  console.log(data); //<Buffer ff 7f>
+     *
+     *  const converted = await client.convertFromRaw(data, 'INT');
+     *  console.log(converted); //32767
+     *
+     * //Reading a POINTER value (Note the dereference operator ^)
+     * const ptrValue = await client.readRawByPath('GVL_Read.ComplexTypes.POINTER_^');
+     *
+     * //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.
      */
     readRawByPath(path: string, targetOpts?: Partial<AmsAddress>): Promise<Buffer>;
     /**
-     * **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.
+     * @example
+     * ```js
+     * try {
+     *  const data = await client.convertToRaw(32767, 'INT');
+     *  console.log(data); //<Buffer ff 7f>
      *
-     * @param path Variable path in the PLC to read (such as `GVL_Test.ExampleStruct`)
+     *  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.
      */
     writeRawByPath(path: string, value: Buffer, targetOpts?: Partial<AmsAddress>): Promise<void>;
     /**
-     * **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.
+     *
+     * This is the ADS protocol `ReadWrite` command.
      *
-     * Writes raw data to the target and reads the result as raw data
+     * @example
+     * ```js
+     * const { ADS } = require('../dist/ads-client');
      *
-     * Uses `ADS ReadWrite` command
+     * 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.
      */
-    readWriteRaw(indexGroup: number, indexOffset: number, size: number, writeData: Buffer, targetOpts?: Partial<AmsAddress>): Promise<Buffer>;
+    readWriteRaw(indexGroup: number, indexOffset: number, size: number, value: Buffer, targetOpts?: Partial<AmsAddress>): Promise<Buffer>;
     /**
-     * **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.
      */
     readWriteRawMulti(commands: ReadWriteRawMultiCommand[], targetOpts?: Partial<AmsAddress>): Promise<ReadWriteRawMultiResult[]>;
     /**
-     * **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.
+     *
+     * Returns variable's
+     * - converted value
+     * - raw value
+     * - data type
+     * - symbol
      *
-     * Reads a value by a variable path (such as `GVL_Test.ExampleStruct`) and converts the value to a Javascript object.
+     * **NOTE:** This requires that the target is a PLC runtime or has equivalent ADS protocol support.
      *
-     * Returns the converted value, the raw value, the data type and the symbol.
+     * @example
+     * ```js
+     * try {
+     *  const res = await client.readValue('GVL_Read.StandardTypes.INT_');
+     *  console.log(res.value);
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      *
-     * @param path Variable path in the PLC to read (such as `GVL_Test.ExampleStruct`)
+     * @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`)
+     * @throws Throws an error if sending the command fails or if the target responds with an error.
      */
     readValue<T = any>(path: string, targetOpts?: Partial<AmsAddress>): Promise<ReadValueResult<T>>;
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Reads variable's value from the target system by a symbol object (acquired using `getSymbol()`)
+     * 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.
+     *
+     * @example
+     * ```js
+     * try {
+     *  const symbol = await client.getSymbol('GVL_Read.StandardTypes.INT_');
+     *
+     *  const res = await client.readValueBySymbol(symbol);
+     *  console.log(res.value);
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      *
-     * @param symbol Symbol (acquired using `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.
      */
     readValueBySymbol<T = any>(symbol: AdsSymbol, targetOpts?: Partial<AmsAddress>): Promise<ReadValueResult<T>>;
     /**
-     * **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_Read.StandardTypes.INT_', 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 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.
      */
     writeValue<T = any>(path: string, value: T, autoFill?: boolean, targetOpts?: Partial<AmsAddress>): Promise<WriteValueResult<T>>;
     /**
-     * **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.
+     *
+     * Returns variable's
+     * - converted value
+     * - raw value
+     * - data type
+     * - symbol
      *
-     * Writes a value by symbol. Converts the value from a Javascript object to a raw value.
+     * **NOTE:** Do not use `autoFill` for `UNION` types, it doesn't work correctly.
      *
-     * 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.
+     *
+     * @example
+     * ```js
+     * try {
+     *  const symbol = await client.getSymbol('GVL_Read.StandardTypes.INT_');
      *
-     * **NOTE:** Do not use `autoFill` for `UNION` types, it works without errors but the result isn't probably the desired one
+     *  const res = await client.writeValueBySymbol(symbol, 32767);
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
      *
-     * @param symbol Symbol (acquired using `getSymbol()`)
+     * @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.
      */
     writeValueBySymbol<T = any>(symbol: AdsSymbol, value: T, autoFill?: boolean, targetOpts?: Partial<AmsAddress>): Promise<WriteValueResult<T>>;
     /**
-     * **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.
      */
     getDefaultPlcObject<T = any>(dataType: string | AdsDataType, targetOpts?: Partial<AmsAddress>): Promise<T>;
     /**
-     * **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
      *
-     * @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
+     * } catch (err) {
+     *  console.log("Error:", err);
+     * }
+     * ```
+     *
+     * @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.
      */
     convertFromRaw<T = any>(data: Buffer, dataType: string | AdsDataType, targetOpts?: Partial<AmsAddress>): Promise<T>;
     /**
-     * **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.
      */
     convertToRaw(value: any, dataType: string | AdsDataType, autoFill?: boolean, targetOpts?: Partial<AmsAddress>): Promise<Buffer>;
     /**
-     * **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.
      */
     createVariableHandle(path: string, targetOpts?: Partial<AmsAddress>): Promise<VariableHandle>;
     /**
-     * **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.
+     *
+     * Reading and writing dereferenced `POINTER` and `REFERENCE` values is also possible.
+     * See {@link readRawByHandle}() and {@link writeRawByHandle}().
      *
-     * Sends multiple createVariableHandle() commands in one ADS packet
+     * NOTE: The handle should be deleted after it's no longer needed,
+     * as there is a limited amount of handles available. See {@link deleteVariableHandle}().
      *
-     * Creates a variable handle for a PLC symbol by given variable path
+     * 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.
      *
-     * Variable value can be accessed by using the handle with `readRawByHandle()` and `writeRawByHandle()`
+     * @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.
      */
     createVariableHandleMulti(paths: string[], targetOpts?: Partial<AmsAddress>): Promise<CreateVariableHandleMultiResult[]>;
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Deletes a variable handle that was previously created
+     * using {@link createVariableHandle}().
+     *
+     * @example
+     * ```js
+     * try {
+     *  const handle = createVariableHandle(...);
      *
-     * Deletes a variable handle that was previously created using `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.
      */
     deleteVariableHandle(handle: VariableHandle | number, targetOpts?: Partial<AmsAddress>): Promise<void>;
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Sends multiple {@link deleteVariableHandle}() commands in one ADS packet.
+     *
+     * Deletes a variable handle that was previously created
+     * using {@link createVariableHandle}().
      *
-     * Sends multiple deleteVariableHandle() commands in one ADS packet
+     * 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.
      *
-     * Deletes a variable handle that was previously created using `createVariableHandle()`
+     * @example
+     * ```js
+     * try {
+     *  const handle1 = createVariableHandle(...);
+     *  const handle2 = 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.
      */
     deleteVariableHandleMulti(handles: (VariableHandle | number)[], targetOpts?: Partial<AmsAddress>): Promise<DeleteVariableHandleMultiResult[]>;
     /**
-     * **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.
      */
     readRawByHandle(handle: VariableHandle | number, size?: number, targetOpts?: Partial<AmsAddress>): Promise<Buffer>;
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Writes raw data to the target system by a previously created variable handle (acquired using {@link createVariableHandle}())
+     *
+     * @example
+     * ```js
+     * try {
+     *  const value = await client.convertToRaw(32767, 'INT');
+     *  console.log(value); //<Buffer ff 7f>
      *
-     * Writes raw byte data to the target system by previously created variable handle
+     *  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.
      */
     writeRawByHandle(handle: VariableHandle | number, value: Buffer, targetOpts?: Partial<AmsAddress>): Promise<void>;
     /**
-     * **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.
      */
     readRawBySymbol(symbol: AdsSymbol, targetOpts?: Partial<AmsAddress>): Promise<Buffer>;
     /**
-     * **TODO - DOCUMENTATION ONGOING**
+     * Writes raw data to the target system by a symbol object (acquired using `getSymbol()`)
      *
-     * Writes raw data by symbol
+     * @example
+     * ```js
+     * try {
+     *  const value = await client.convertToRaw(32767, 'INT');
+     *  console.log(value); //<Buffer ff 7f>
      *
-     * @param symbol Symbol (acquired using `getSymbol()`)
+     *  const symbol = await client.getSymbol('GVL_Read.StandardTypes.INT_');
+     *  await client.writeRawBySymbol(symbol, value);
+     *
+     * } 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.
      */
     writeRawBySymbol(symbol: AdsSymbol, value: Buffer, targetOpts?: Partial<AmsAddress>): Promise<void>;
     /**
-     * **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.
      */
     invokeRpcMethod<T = any, U = Record<string, any>>(path: string, method: string, parameters?: Record<string, any>, targetOpts?: Partial<AmsAddress>): Promise<RpcMethodCallResult<T, U>>;
 }