motion-master-client 0.0.2 → 0.0.3

package/README.md

@@ -20,7 +20,7 @@ const clientId = v4();
 reqResSocket.open(`ws://oblac-drives-7dc95497.local:63524?clientId=${clientId}`);
 pubSubSocket.open(`ws://oblac-drives-7dc95497.local:63525?clientId=${clientId}`);
 
-this.client.request.getDeviceInfo().subscribe(console.log);
+client.request.getDeviceInfo().subscribe(console.log);
 ```
 
 ## Communication

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "motion-master-client",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "description": "A library and CLI program used for communicating with Motion Master."
 }

package/src/lib/motion-master-req-res-client.ts

@@ -13,19 +13,22 @@ import { decodeTextContent, valueTypeToParameterTypeValueKeyMap, getParameterVal
 /**
  * This class contains methods for making requests to Motion Master using the injected request/response socket.
  *
- * Each request message defined in the proto file has two corresponding request methods in this class. One method supports Reactive and the other Promise-based API.
- * Reactive API is the default one. Unlike promises which resolve to a single value, observables can emit multiple values over time. For some requests like firmware installation,
- * Motion Master will send progress messages until the firmware installation is done.
+ * Each request message defined in the proto file has two corresponding request methods in this class.
+ * One method supports Reactive and the other Promise-based API. Reactive API is the default one.
+ * Unlike promises which resolve to a single value, observables can emit multiple values over time.
+ * For some requests like firmware installation, Motion Master will send progress messages until the firmware installation is done.
  * Reactive request methods are named like `getDeviceInfo` and Promise-based are named like `getDeviceInfoAsync` (notice the `Async` suffix).
  *
  * Reactive and Promise-based request methods have the same set of input parameters, but they differ in the return values.
  * Call to Reactive request methods will return an Observable of (1) corresponding status message, for example call to `getDeviceInfo`
  * will return an instance of `MotionMasterMessage.Status.DeviceInfo`, (2) request status, and (3) request message id.
- * Promise-based request methods can only return (resolve to) a single value. These methods call the corresponding Reactive request method and return data
- * from the last emmited status message. For example `getDeviceInfoAsync` calls `getDeviceInfo` and returns a list of devices from
- * the last emmited status message. If the request fails on Motion Master the function will throw an error. It can also throw an error if request times out.
+ * Promise-based request methods can only return (resolve to) a single value.
+ * These methods call the corresponding Reactive request method and return data from the last emmited status message.
+ * For example `getDeviceInfoAsync` calls `getDeviceInfo` and returns a list of devices from the last emmited status message.
+ * If the request fails on Motion Master the function will throw an error. It can also throw an error if the request times out.
  *
- * Request methods have optional `messageId` input parameter. If `messageId` is not provided, one will be generated before sending the request message to Motion Master.
+ * Request methods have optional `messageId` input parameter.
+ * If `messageId` is not provided, one will be generated before sending the request message to Motion Master.
  * Status messages (responses) received from Motion Master that correspond to the previous request will have the same `messageId` as the one in the request.
  * This is how we match request with response messages in the full-duplex asynchronous communication (WebSockets, ZeroMQ).
  * Matching request/response by message id is inspired by [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification).
@@ -70,7 +73,7 @@ import { decodeTextContent, valueTypeToParameterTypeValueKeyMap, getParameterVal
  * Beside device address and device serial number, devices can be referenced by position (sequence number in the network).
  *
  * It is ensured that Observable returned from a call to Reactive request method will eventually complete, so a call to unsubscribe is not required.
- * Observable will complete when request status is either "succeeded" or "failed", and it can complete (error) due to timeout.
+ * Observable will complete when request status is either "succeeded" or "failed", or it will complete (error) due to timeout.
  * Finding out if a request has completed, failed or is it still on-going is different for each request - it dependends on the status messages, see {@link requestStatusResolver}.
  * Reactive request methods handle this and for each request they will emit status messages with one of "succeeded", "failed", or "running" request status.
  *
@@ -98,7 +101,7 @@ export class MotionMasterReqResClient {
    * When device parameter info is fetched this map gets updated by mapping device parameters type to oneof proto type, e.g. `INTEGER32 -> intValue`.
    *
    * This map helps in simplifying the API by allowing users to set parameter values without specifying the type value field.
-   * One can simply call `await setParameterValue(2045285448, 0x2004, 0x03, 2500)` and the correct type value field on the proto message will be set, `uintValue` in this example.
+   * One can simply call `setParameterValue(2045285448, 0x2004, 0x03, 2500)` and the correct type value field on the proto message will be set, `uintValue` in this example.
    */
   readonly parameterTypeValueKeyMap = new Map<number, Map<string, ParameterTypeValueKey>>();
 
@@ -117,8 +120,8 @@ export class MotionMasterReqResClient {
    * For scripts and applications that use this library, having a permanent device identifier is a better option.
    * Device serial number read from the hardware description file (.hardware_description) stored on a device is a permanent identifier.
    *
-   * This map helps in making all request functions related to a device accept device reference instead of just device address as an identifier.
-   * Device reference can be one of: device address, device serial number, or device position.
+   * This map helps in making all request methods related to a device accept device reference instead of just device address as an identifier.
+   * Device reference {@link DeviceRefObj} can be one of: device address, device serial number, or device position.
    * Prior to sending a request message to Motion Master, device address is resolved from device reference and this map is used for that.
    */
   readonly deviceAddressMap = new Map<string, number>();
@@ -180,8 +183,12 @@ export class MotionMasterReqResClient {
   /**
    * Get device info.
    *
-   * Device info includes a list of devices on network.
-   * Call this method to get device addresses for requests specific to devices.
+   * Device info includes a list of devices on the network. Each device has a type, position in the network, and device address.
+   *
+   * Motion Master will assign a unique device address to each device in the list.
+   * Device address is what the client libraries use to make requests like `getDeviceParameter` from a particular device.
+   * Device address is only valid for the duration of the session, that is until the list of devices is read again, for example
+   * when devices are power cycled or Motion Master process is restarted.
    */
   getDeviceInfo(requestTimeout: number, messageId?: string) {
     const getDeviceInfo = MotionMasterMessage.Request.GetDeviceInfo.create();
@@ -204,6 +211,22 @@ export class MotionMasterReqResClient {
     throw new Error('Get device info request failed.');
   }
 
+  /**
+   * Get device parameter info.
+   *
+   * Device parameter info includes a list of all parameters for the requested device, but without the parameter values.
+   * Getting device parameter values can take more than 20ms per parameter using the IgH EtherCAT Master library.
+   * Not all clients require all the parameter values at once like OBLAC Drives, so this method is good for getting
+   * the list of available parameters and then getting the values of only some parameters.
+   *
+   * The returned list of device parameters will include some basic data for each parameter: index, subindex,
+   * name, unit, group (ARRAY or RECORD name for subitems), read and write access, min and max, and value type.
+   * The same info and more can be read from the "SOMANET_CiA_402.xml" file, but getting info from ESI file is more complicated.
+   * It requires an XML parsing library and knowing how to read objects info from a dictionary and assigned modules.
+   *
+   * In addition to fetching device parameter info, this method will map parameter base data type (ETG.1020) to proto3 types.
+   * The map removes the need to specify proto3 type field when setting a parameter value {@link parameterTypeValueKeyMap}.
+   */
   getDeviceParameterInfo(props: MotionMasterMessage.Request.IGetDeviceParameterInfo & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -231,6 +254,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc getDeviceParameterInfo}
+   */
   async getDeviceParameterInfoAsync(props: MotionMasterMessage.Request.IGetDeviceParameterInfo & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<MotionMasterMessage.Status.DeviceParameterInfo.IParameter[]> {
     const status = await lastValueFrom(this.getDeviceParameterInfo(props, requestTimeout, messageId));
 
@@ -241,6 +267,9 @@ export class MotionMasterReqResClient {
     throw new Error('Get device parameter info request failed.');
   }
 
+  /**
+   * Get device parameter values.
+   */
   getDeviceParameterValues(props: MotionMasterMessage.Request.IGetDeviceParameterValues & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -250,15 +279,21 @@ export class MotionMasterReqResClient {
           transformMotionMasterMessageToStatus<MotionMasterMessage.Status.DeviceParameterValues>('deviceParameterValues', requestTimeout, id),
         );
       }),
-    )
+    );
   }
 
+  /**
+   * {@inheritDoc getDeviceParameterValues}
+   */
   async getDeviceParameterValuesAsync(props: MotionMasterMessage.Request.IGetDeviceParameterValues & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<MotionMasterMessage.Status.DeviceParameterValues.IParameterValue[]> {
     const status = await lastValueFrom(this.getDeviceParameterValues(props, requestTimeout, messageId));
 
     return status.parameterValues;
   }
 
+  /**
+   * Get multi device parameter values.
+   */
   getMultiDeviceParameterValues(props: MotionMasterMessage.Request.IGetMultiDeviceParameterValues, requestTimeout: number, messageId?: string) {
     const getMultiDeviceParameterValues = MotionMasterMessage.Request.GetMultiDeviceParameterValues.create(props);
     const id = this.sendRequest({ getMultiDeviceParameterValues }, messageId);
@@ -267,12 +302,18 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc getMultiDeviceParameterValues}
+   */
   async getMultiDeviceParameterValuesAsync(props: MotionMasterMessage.Request.IGetMultiDeviceParameterValues, requestTimeout: number, messageId?: string): Promise<MotionMasterMessage.Status.IDeviceParameterValues[]> {
     const status = await lastValueFrom(this.getMultiDeviceParameterValues(props, requestTimeout, messageId));
 
     return status.collection;
   }
 
+  /**
+   * Set device parameter values.
+   */
   setDeviceParameterValues(props: MotionMasterMessage.Request.ISetDeviceParameterValues & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -285,12 +326,18 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc setDeviceParameterValues}
+   */
   async setDeviceParameterValuesAsync(props: MotionMasterMessage.Request.ISetDeviceParameterValues & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<MotionMasterMessage.Status.DeviceParameterValues.IParameterValue[]> {
     const status = await lastValueFrom(this.setDeviceParameterValues(props, requestTimeout, messageId));
 
     return status.parameterValues;
   }
 
+  /**
+   * Set multi device parameter values.
+   */
   setMultiDeviceParameterValues(props: MotionMasterMessage.Request.ISetMultiDeviceParameterValues, requestTimeout: number, messageId?: string) {
     const setMultiDeviceParameterValues = MotionMasterMessage.Request.SetMultiDeviceParameterValues.create(props);
     const id = this.sendRequest({ setMultiDeviceParameterValues }, messageId);
@@ -299,6 +346,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc setMultiDeviceParameterValues}
+   */
   async setMultiDeviceParameterValuesAsync(props: MotionMasterMessage.Request.ISetMultiDeviceParameterValues, requestTimeout: number, messageId?: string): Promise<MotionMasterMessage.Status.IDeviceParameterValues[]> {
     const status = await lastValueFrom(this.setMultiDeviceParameterValues(props, requestTimeout, messageId));
 
@@ -350,7 +400,7 @@ export class MotionMasterReqResClient {
   /**
    * Get device file.
    *
-   * Motion Master uses the Filetransfer over EtherCAT (FoE) to read and send back the content of a file from device flash memory.
+   * Motion Master uses the Filetransfer over EtherCAT (FoE) to read and send back content of a file from device flash memory.
    *
    * The IgH EtherCAT Master library used by Motion Master limits the file read buffer to 9KB, so any file written to flash that is larger than 9KB
    * needs to be split into parts of max 9KB. Motion Master does this automatically on request to {@link setDeviceFile}.
@@ -428,6 +478,15 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed to set device file. ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Delete device file.
+   *
+   * Motion Master uses the Filetransfer over EtherCAT (FoE) to delete files from device flash memory.
+   *
+   * If the file to delete is written in parts, Motion Master will ensure that all parts are deleted.
+   * It does that by reading the list of files on a device, see {@link getDeviceFileList}. It will remove all parts from the list and then
+   * it will re-read the list again to ensure that there are no left overs if there were more than 32 files in the list.
+   */
   deleteDeviceFile(props: MotionMasterMessage.Request.IDeleteDeviceFile & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -440,6 +499,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc deleteDeviceFile}
+   */
   async deleteDeviceFileAsync(props: MotionMasterMessage.Request.IDeleteDeviceFile & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<void> {
     const status = await lastValueFrom(this.deleteDeviceFile(props, requestTimeout, messageId));
 
@@ -525,6 +587,19 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed to stop device. ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Start device firmware installation.
+   *
+   * When Motion Master receives this request it will do the following:
+   * - switch device to BOOT EtherCAT state, device will then run the bootloader instead of the firmware
+   * - delete files from device that it finds in the provided package (SOMANET_CiA_402.xml and stack_image.svg)
+   * - write files other than firmware binaries and SII from package to device (SOMANET_CiA_402.xml and stack_image.svg)
+   * - optionally install the SII file using the IgH EtherCAT Master library write SII function
+   * - write firmware binaries to device using the predefined names like app_firmware.bin
+   *
+   * During the firmware installation Motion Master will send progress messages back to clients.
+   * If Motion Master fails in any step other than SII write it will send error. If SII write fails only warning will be sent.
+   */
   startDeviceFirmwareInstallation(props: MotionMasterMessage.Request.IStartDeviceFirmwareInstallation & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -537,6 +612,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc startDeviceFirmwareInstallation}
+   */
   async startDeviceFirmwareInstallationAsync(props: MotionMasterMessage.Request.IStartDeviceFirmwareInstallation & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<void> {
     const status = await lastValueFrom(this.startDeviceFirmwareInstallation(props, requestTimeout, messageId));
 
@@ -547,6 +625,13 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed to start device firmware installation. ${status.error?.code}: ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Get device log.
+   *
+   * Device log is stored in two files due to IgH EtherCAT Master library 9KB file size limitation, see {@link getDeviceFile}.
+   * Device automatically writes log to logging_curr.log and copies that file to logging_prev.log once it reaches 9KB.
+   * When Motion Master receives this request it will read the both files and return their combined contents.
+   */
   getDeviceLog(props: MotionMasterMessage.Request.IGetDeviceLog & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -559,6 +644,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc getDeviceLog}
+   */
   async getDeviceLogAsync(props: MotionMasterMessage.Request.IGetDeviceLog & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<string | null | undefined> {
     const status = await lastValueFrom(this.getDeviceLog(props, requestTimeout, messageId));
 
@@ -569,6 +657,33 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed to get device log. ${status.error?.code}: ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Start cogging torque recording.
+   *
+   * Cogging torque recording (CTC) can be started with or without auto-config.
+   * In the proto file skipping the auto-config is currently named skip_auto_tuning. The field name is deprecated and will be renamed.
+   *
+   * If CTC is started without auto-config then users must ensure that encoder on the motor shaft is used for all functions: commutation, position, and velocity.
+   * If this is not the case, then Motion Master will return invalid encoder configuration error.
+   * Recording can also fail if the position controller is not tuned.
+   *
+   * If CTC is started with auto-config then Motion Master will:
+   * - change the encoder configuration to have all functions on the motor shaft
+   * - disabled CTC
+   * - change the velocity feed forward value
+   * - change the position and velocity filter types and cutoff frequencies
+   * - run iterative sharpening position auto-tuning in order to compute the optimal PID values (gains) using the auto tuning
+   *
+   * All parameter values that Motion Master changes as part of the auto-config are first stored in memory and once the CTC recording is done are reverted back.
+   *
+   * CTC recording is started by changing the Modes of operation (0x6060) parameter value to -1 (Cogging compensation recording mode).
+   * During the operation Motion Master will monitor the Cogging torque compensation state parameter (0x2008:01) to know when the recording is in progress and when it's done.
+   *
+   * The result of recording CTC is the cogging_torque.bin file written to device flash memory. Size of this file is 2048 bytes.
+   * Each pair of bytes represents a 16-bit signed integer value in mNm (milli newton meter).
+   *
+   * This request will turn the motor.
+   */
   startCoggingTorqueRecording(props: MotionMasterMessage.Request.IStartCoggingTorqueRecording & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -581,6 +696,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc startCoggingTorqueRecording}
+   */
   async startCoggingTorqueRecordingAsync(props: MotionMasterMessage.Request.IStartCoggingTorqueRecording & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<void> {
     const status = await lastValueFrom(this.startCoggingTorqueRecording(props, requestTimeout, messageId));
 
@@ -591,6 +709,14 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed to start cogging torque recording. ${status.error?.code}: ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Get cogging torque data.
+   *
+   * The cogging_torque.bin file is the result of recording cogging torque compensation, see {@link startCoggingTorqueRecording}.
+   * The size of this file is 2048 bytes where each pair of bytes represents a 16-bit signed integer value in mNm (milli newton meter).
+   *
+   * Motion Master will read the cogging_torque.bin file, convert bytes to 16-bit signed integer values and return that as an array.
+   */
   getCoggingTorqueData(props: MotionMasterMessage.Request.IGetCoggingTorqueData & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -603,6 +729,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc getCoggingTorqueData}
+   */
   async getCoggingTorqueDataAsync(props: MotionMasterMessage.Request.IGetCoggingTorqueData & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<number[]> {
     const status = await lastValueFrom(this.getCoggingTorqueData(props, requestTimeout, messageId));
 
@@ -613,6 +742,34 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed to get cogging torque data. ${status.error?.code}: ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Start offset detection.
+   *
+   * Running offset detection is different in firmwares <v5 and >=v5.
+   *
+   * For devices that run firmware >=v5 Motion Master will run multiple OS commands.
+   * Before starting any command device is switched to Modes of operation -2 (Diagnostics mode) and
+   * it's put into operation enabled CiA402 state. The OS commands are run in the following order:
+   * - open phase detection
+   * - phase resistance measurement
+   * - phase inductance measurement
+   * - pole pair detection
+   * - motor phase order detection
+   * - commutation offset measurement
+   *
+   * Motion Master will return error if any of the following OS commands fail: open phase detection,
+   * phase order detection, commutation offset measurement.
+   * If other OS commands fail Motion Master will continue with the procedure and only return warning.
+   *
+   * Once the commutation offset measurement command completes it will update:
+   * - 0x2001:00 Commutation angle offset to the computed offset value
+   * - 0x2009:01 Commutation offset State to 2 (OFFSET_VALID)
+   *
+   * For devices that run firmware <5 the same Modes of operation -2 is used, but it's named Commutation offset detection mode.
+   * The end result is the same, the procedure will update 0x2001:00 and 0x2009:01 parameter values.
+   *
+   * This request will turn the motor.
+   */
   startOffsetDetection(props: MotionMasterMessage.Request.IStartOffsetDetection & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -625,6 +782,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc startOffsetDetection}
+   */
   async startOffsetDetectionAsync(props: MotionMasterMessage.Request.IStartOffsetDetection & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<void> {
     const status = await lastValueFrom(this.startOffsetDetection(props, requestTimeout, messageId));
 
@@ -663,6 +823,21 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed start plant identification. ${status.error?.code}: ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Compute auto tuning gains.
+   *
+   * Auto tuning gains can be computed for position or velocity controller.
+   *
+   * Prerequisites for running this procedure are the configured motor and the existence of
+   * plant_model.csv file created by a previous run of the system identification {@link startSystemIdentification}.
+   * Motion Master will return error if the plant_model.csv file is not found.
+   *
+   * In OBLAC Drives this request is called when the tuning sliders (damping ratio, bandwidth) are moved and
+   * during the CTC recording {@link startCoggingTorqueRecording} when auto config is not skipped.
+   *
+   * Motion Master will compute the PID gains using the Python scripts and it will
+   * update the Kp, Ki, Kd values of 0x2011 and 0x2012 parameters.
+   */
   computeAutoTuningGains(props: MotionMasterMessage.Request.IComputeAutoTuningGains & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -675,6 +850,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc computeAutoTuningGains}
+   */
   async computeAutoTuningGainsAsync(props: MotionMasterMessage.Request.IComputeAutoTuningGains & DeviceRefObj, requestTimeout: number, messageId?: string) {
     const status = await lastValueFrom(this.computeAutoTuningGains(props, requestTimeout, messageId));
 
@@ -685,6 +863,13 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed to compute auto tuning gains. ${status.error?.code}: ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Set motion controller parameters.
+   *
+   * This request sets the target value for a device on Motion Master.
+   *
+   * A previous call to {@link enableMotionController} will set the mode of operation to CSP, CSV, or CST and optionally enable filtering.
+   */
   setMotionControllerParameters(props: MotionMasterMessage.Request.ISetMotionControllerParameters & DeviceRefObj, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -695,10 +880,23 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc setMotionControllerParameters}
+   */
   async setMotionControllerParametersAsync(props: MotionMasterMessage.Request.ISetMotionControllerParameters & DeviceRefObj, messageId?: string): Promise<void> {
     return await lastValueFrom(this.setMotionControllerParameters(props, messageId), { defaultValue: undefined });
   }
 
+  /**
+   * Enable motion controller.
+   *
+   * This request will set the mode of operation to CSP, CSV, or CST and optionally enable filtering.
+   *
+   * If filtering is enabled Motion Master will compute an intermediate target value in each cycle, and depending on the active mode of operation
+   * set the value of one of 0x607A Target position, 0x60FF Target velocity, 0x6071 Target torque to that value.
+   *
+   * Target value can be updated with {@link setMotionControllerParameters}.
+   */
   enableMotionController(props: MotionMasterMessage.Request.IEnableMotionController & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -711,6 +909,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc enableMotionController}
+   */
   async enableMotionControllerAsync(props: MotionMasterMessage.Request.IEnableMotionController & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<{ controllerType: MotionMasterMessage.Request.EnableMotionController.ControllerType, enabled: boolean, filter: boolean }> {
     const status = await lastValueFrom(this.enableMotionController(props, requestTimeout, messageId));
 
@@ -721,6 +922,13 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed to enable motion controller. ${status.error?.code}: ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Disable motion controller.
+   *
+   * Depending on the current CiA402 state this request will do the following:
+   * - if device is in Quick stop active it will transition to Switch on disabled state
+   * - if device is in Operation enabled it will transition to Switched on state
+   */
   disableMotionController(props: MotionMasterMessage.Request.IDisableMotionController & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -733,6 +941,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc disableMotionController}
+   */
   async disableMotionControllerAsync(props: MotionMasterMessage.Request.IDisableMotionController & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<{ controllerType: MotionMasterMessage.Request.EnableMotionController.ControllerType, enabled: boolean, filter: boolean }> {
     const status = await lastValueFrom(this.disableMotionController(props, requestTimeout, messageId));
 
@@ -743,6 +954,13 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed to disable motion controller. ${status.error?.code}: ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Set signal generator parameters.
+   *
+   * This request will update the signal generator parameters for a device on Motion Master.
+   * The selected signal generator is then started by {@link startSignalGenerator}.
+   * Signal generator must be started in the next 60 seconds before Motion Master invalidates the previously set parameters.
+   */
   setSignalGeneratorParameters(props: MotionMasterMessage.Request.ISetSignalGeneratorParameters & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -755,6 +973,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc setSignalGeneratorParameters}
+   */
   async setSignalGeneratorParametersAsync(props: MotionMasterMessage.Request.ISetSignalGeneratorParameters & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<void> {
     const status = await lastValueFrom(this.setSignalGeneratorParameters(props, requestTimeout, messageId));
 
@@ -765,6 +986,47 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed to set signal generator parameters. ${status.error?.code}: ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Start signal generator.
+   *
+   * This request will start one of the signal generators based on the
+   * previously set parameters with {@link setSignalGeneratorParameters}.
+   *
+   * Signal generators are started by changing the mode of operation, putting device into Operation enabled CiA402 state,
+   * and setting the target value. What mode of operation is set depends on the type of signal generator and controller:
+   * - For the simple & advanced step response and sine wave one of CSP, CSV, or CST is set.
+   * - For ramp, trapezoidal, and bidirectional signal generators, also called profiles, one of PP, PV, TQ is set.
+   *
+   * Currently the only profile type that firmware supports is ramp.
+   * Motion Master uses this profile type to run the following signal generators: ramp, trapezoidal, and bidirectional.
+   * Sine wave is also a profile but it is currently generated on Motion Master.
+   * Firmwares >=5.2 will support generating and running sine wave profiles on devices. This will enable lossless profile
+   * execution on possibly higher frequencies. Future Motion Master versions will switch to this method.
+   *
+   * For the simple step response Motion Master will only set the target value,
+   * wait for the specified holding duration, and then send Quick Stop.
+   *
+   * The advanced step response is similar to simple, but after the holding duration it will set the new target
+   * multiple times depending on the shape, and then send Quick Stop if repeat is set to NO. If repeat is set to YES,
+   * then the signal generator will run indefinitely and users must stop it.
+   *
+   * Before running profiles Motion Master will check if device supports the profile modes by looking at 0x6502 Supported drives modes.
+   * If profile modes are not supported then the profiles will be generated on Motion Master. This means the targets will be computed up-front.
+   * If profiles are supported then ramp, trapezoidal, and bidirectional signal generators are run in profile mode of operation.
+   * Motion Master will set the following parameters:
+   * - 0x6081:00 Profile velocity (only for position controller)
+   * - 0x6083:00 Profile acceleration
+   * - 0x6084:00 Profile deceleration
+   * Motion Master knows when the profile has completed by comparing the demand with the actual value, taking into account the
+   * holding duration and the shape of profile. Once the profile is considered complete Motion Master will send Quick Stop, but
+   * only if repeat is set to NO.
+   *
+   * Sine wave profile is generated up-front on Motion Master. Targets are computed for each master cycle (millisecond).
+   * Once the last computed target has been set, Motion Master will send Quick Stop if repeat is set to NO.
+   *
+   * For all signal generators Motion Master will modify the requested target based on
+   * the software position limits and it will return warning.
+   */
   startSignalGenerator(props: MotionMasterMessage.Request.IStartSignalGenerator & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -777,6 +1039,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc startSignalGenerator}
+   */
   async startSignalGeneratorAsync(props: MotionMasterMessage.Request.IStartSignalGenerator & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<void> {
     const status = await lastValueFrom(this.startSignalGenerator(props, requestTimeout, messageId));
 
@@ -787,6 +1052,11 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed to start signal generator. ${status.error?.code}: ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Stop signal generator.
+   *
+   * This request will send Quick Stop to a device.
+   */
   stopSignalGenerator(props: MotionMasterMessage.Request.IStopSignalGenerator & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -799,6 +1069,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc stopSignalGenerator}
+   */
   async stopSignalGeneratorAsync(props: MotionMasterMessage.Request.IStopSignalGenerator & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<void> {
     const status = await lastValueFrom(this.stopSignalGenerator(props, requestTimeout, messageId));
 
@@ -861,6 +1134,13 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed get ethercat network state. ${status.error?.code}: ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Set EtherCAT network state.
+   *
+   * Set EtherCAT network state to one of: BOOT, INIT, PRE-OP, SAFE-OP, OP.
+   *
+   * From PRE-OP to OP MM will reinitialize slaves in order to get new PDO mapping.
+   */
   setEthercatNetworkState(props: MotionMasterMessage.Request.ISetEthercatNetworkState & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -873,6 +1153,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc setEthercatNetworkState}
+   */
   async setEthercatNetworkStateAsync(props: MotionMasterMessage.Request.ISetEthercatNetworkState & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<void> {
     const status = await lastValueFrom(this.setEthercatNetworkState(props, requestTimeout, messageId));
 
@@ -911,16 +1194,47 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed start narrow angle calibration. ${status.error?.code}: ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Set system client timeout.
+   *
+   * This request will update the client timeout.
+   *
+   * Client timeout specifies how long will Motion Master wait for the client to send ping or any other message before
+   * considering it gone and clearing the resources (stopping procedures and monitorings) related to that client.
+   *
+   * Default client timeout is 1000ms.
+   *
+   * Client will typically change this once the connection is established.
+   */
   setSystemClientTimeout(props: MotionMasterMessage.Request.ISetSystemClientTimeout, messageId?: string) {
     const setSystemClientTimeout = MotionMasterMessage.Request.SetSystemClientTimeout.create(props);
     this.sendRequest({ setSystemClientTimeout }, messageId);
     return EMPTY;
   }
 
+  /**
+   * {@inheritDoc setSystemClientTimeout}
+   */
   async setSystemClientTimeoutAsync(props: MotionMasterMessage.Request.ISetSystemClientTimeout, messageId?: string) {
     return await lastValueFrom(this.setSystemClientTimeout(props, messageId), { defaultValue: undefined });
   }
 
+  /**
+   * Start system identification.
+   *
+   * pre-condition motor and encoder configured (setup wizard), without position and velocity tuning
+   * torque only, used for computing the PID values during the auto tuning and full auto tuning and ctc which uses auto-tuning
+   * error when, fault state, cannot set op mode, state, system failed, chirp profile is generate on master, each point in a cycle (millisecond)
+   * CST sets targets, after the last target value MM sends Quick Stop, failed if fault, everything happens on master, but idea to run chirp on slave
+   * and record data on slave, so that communication doesn't impact the result, MM records velocity and torque and computes, compute how many data is missing warning
+   * error if there are not enough data, missing more than 80% of data points, if between 5%-80% warning, <5% ok, linear interpolation of missing data points
+   * conversion every all velocity to SI, check amplitude of signal no torque, no velocity, or small amplitudes warning, errors 0 amplitudes
+   * identification plant model, check stability of computed model (math only) can result in error, compute and write to plant_model.csv
+   * set parameters integral limits 0x2012:4 0x2012:8, 0x2011:4 Position|Velocity loop integral limit
+   * result plant_model.csv - check what values are and in what unit
+   *
+   * This request will turn motor
+   */
   startSystemIdentification(props: MotionMasterMessage.Request.IStartSystemIdentification & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -933,6 +1247,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc startSystemIdentification}
+   */
   async startSystemIdentificationAsync(props: MotionMasterMessage.Request.IStartSystemIdentification & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<void> {
     const status = await lastValueFrom(this.startSystemIdentification(props, requestTimeout, messageId));
 
@@ -943,6 +1260,15 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed start system identification. ${status.error?.code}: ${status.error?.message} ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Get circulo encoder magnet distance.
+   *
+   * check encoder ordinal (1 or 2)
+   * ring revision
+   * is it based on fw 5 in fw <5 this doesn't exist error in that case
+   * read encoder registers with OS command, registers read 2B and 2F, some values go through math depending on the version of Circulo, port, distance value is computed
+   * @todo check what OS command
+   */
   getCirculoEncoderMagnetDistance(props: MotionMasterMessage.Request.IGetCirculoEncoderMagnetDistance & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -955,6 +1281,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc getCirculoEncoderMagnetDistance}
+   */
   async getCirculoEncoderMagnetDistanceAsync(props: MotionMasterMessage.Request.IGetCirculoEncoderMagnetDistance & DeviceRefObj, requestTimeout: number, messageId?: string): Promise<{ distance: number | null | undefined, encoderOrdinal: number | null | undefined, position: number | null | undefined }> {
     const status = await lastValueFrom(this.getCirculoEncoderMagnetDistance(props, requestTimeout, messageId));
 
@@ -965,6 +1294,39 @@ export class MotionMasterReqResClient {
     throw new Error(`Failed to get circulo encoder magnet distance. ${JSON.stringify(props)}`);
   }
 
+  /**
+   * Start circulo encoder narrow angle calibration procedure.
+   *
+   * check encoder ordinal
+   * check fw version 5
+   * check if SMM, has to be disable safety encoder source type
+   * ignore biss status bit, OS command for encoder to ignore BiSS status bits
+   * initialize velocity profile PV
+   * check software position limits
+   * initialize intern values, feed constant, single turn resolution, si unit, get parameter values, gear ratio, what encoder, port, if gear ratio etc etc
+   * if gear box and si unit velocity not mRPM, and position only encoder, and si unit * feed constant is <10% of gear ratio, error not enough velocity resolution
+   * hardware description file, different values for RPM for different version of Circulo, inner|outer encoder ring, multiturn, not, change profile acc|dec max motor speed etc.
+   * after everything rollback
+   * check if enough turns is possible, if not enough space, error
+   * set default calibration register values
+   * set biss to raw mode, no longer position - raw position
+   * ic house lib is initialized
+   * remove previous files for high resolution data 4kHz, for each iteration, hight res data contains raw data from encoder
+   * OS command configure HRD streaming, automatically sets data from encoder, can only configure how long to record
+   * slave saves data to HRD files
+   * after each iteration which lasts 6 seconds, every iteration is one direction, MM takes data recorded in HRD files and puts that passes that to
+   * master/noniuns track data it takes 32-bit values are both splitted into 2 parts (master nonius), two arrays one master one nonious
+   * that data are passed to iChouse library which give depending on encoder type track master nonius, return some sine offset, cos offset, gain, etc.
+   * that procuderu can have errors: data out of range, motor to slow, bad data, internal error - if error in any iteration the procedure stops
+   * if no error then check if calibration succeeded depending on the values (iterativelly improve values by writing them back to some registers), if not run another iteration
+   * max iteration to run is 13 (up to 2 mins)
+   * treshold is determined by Petr
+   * if iteration is successfull, HRD files are moved after deinitializing (succesfful run),
+   * the result of calibration is setting multiple register values
+   * all parameters are reverted back, motor is rotated back to the starging position, commutation offset measurement (just one OS command) is run again
+   * how many iterations are run are based on results
+   * final itertion is for outputting does nothhing just measures the values
+   */
   startCirculoEncoderNarrowAngleCalibrationProcedure(props: MotionMasterMessage.Request.IStartCirculoEncoderNarrowAngleCalibrationProcedure & DeviceRefObj, requestTimeout: number, messageId?: string) {
     return from(this.resolveDeviceAddress(props)).pipe(
       mergeMap((deviceAddress) => {
@@ -977,6 +1339,9 @@ export class MotionMasterReqResClient {
     );
   }
 
+  /**
+   * {@inheritDoc startCirculoEncoderNarrowAngleCalibrationProcedure}
+   */
   async startCirculoEncoderNarrowAngleCalibrationProcedureAsync(props: MotionMasterMessage.Request.IStartCirculoEncoderNarrowAngleCalibrationProcedure & DeviceRefObj, requestTimeout: number, messageId?: string) {
     const status = await lastValueFrom(this.startCirculoEncoderNarrowAngleCalibrationProcedure(props, requestTimeout, messageId));