motion-master-client 0.0.363 → 0.0.367

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

@@ -30,6 +30,7 @@ const circulo_1 = require("./circulo");
 const encoder_1 = require("./encoder");
 const pdo_1 = require("./pdo");
 const integro_1 = require("./integro");
+const offset_detection_1 = require("./offset-detection");
 const { xmlToEsi } = require('ecatmod');
 /**
  * This class contains methods for making requests to Motion Master using the injected request/response socket.
@@ -1199,6 +1200,14 @@ class MotionMasterReqResClient {
         this.socket.send(message);
         return id;
     }
+    /**
+     * Get device SII.
+     */
+    getDeviceSii(props, requestTimeout, messageId) {
+        const getDeviceSii = types_1.MotionMasterMessage.Request.GetDeviceSii.create(props);
+        const id = this.sendRequest({ getDeviceSii }, messageId);
+        return this.socket.message$.pipe((0, operators_2.transformMotionMasterMessageToStatus)('deviceSii', requestTimeout, id));
+    }
     //
     // Helpers
     //
@@ -2747,7 +2756,24 @@ class MotionMasterReqResClient {
      * @todo Document this method and consider removing the void return type.
      */
     runPhaseResistanceMeasurement(deviceRef) {
-        return (0, rxjs_1.concat)(this.setModesOfOperation(deviceRef, cia402_1.ModesOfOperation.DIAGNOSTICS_MODE), this.transitionToCia402State(deviceRef, cia402_1.Cia402State.OPERATION_ENABLED), this.runPhaseResistanceMeasurementOsCommand(deviceRef));
+        return (0, rxjs_1.concat)(this.setModesOfOperationAndTransitionToCia402State(deviceRef, cia402_1.ModesOfOperation.DIAGNOSTICS_MODE, cia402_1.Cia402State.OPERATION_ENABLED), this.runPhaseResistanceMeasurementOsCommand(deviceRef));
+    }
+    /**
+     * Sets the device mode of operation and then transitions the device
+     * to the specified CiA 402 state.
+     *
+     * The operations are executed sequentially:
+     * 1. The mode of operation is written to the device.
+     * 2. The device is transitioned to the requested CiA 402 state.
+     *
+     * @param deviceRef - Reference to the target device.
+     * @param modesOfOperation - Desired CiA 402 mode of operation.
+     * @param cia402State - Target CiA 402 state to transition to.
+     *
+     * @returns Observable that completes when both operations finish.
+     */
+    setModesOfOperationAndTransitionToCia402State(deviceRef, modesOfOperation, cia402State) {
+        return (0, rxjs_1.concat)(this.setModesOfOperation(deviceRef, modesOfOperation), this.transitionToCia402State(deviceRef, cia402State));
     }
     /**
      * Installs the Integro Encoder Firmware by performing the following steps:
@@ -2772,7 +2798,7 @@ class MotionMasterReqResClient {
     /**
      * @link https://www.wrike.com/open.htm?id=1375749957
      *
-     * @todo: Verify if the device is an Actilink S device and check the corresponding variant file.
+     * @todo: Verify if the device is an ACTILINK-S device and check the corresponding variant file.
      */
     isIntegroWithMultiturnEncoder(deviceRef) {
         var _a;
@@ -2808,10 +2834,10 @@ class MotionMasterReqResClient {
         return tslib_1.__awaiter(this, void 0, void 0, function* () {
             // Create a default UI features configuration object.
             const uiFeaturesConfig = { setupWizard: 'default' };
-            // Check if the device is an Actilink S device.
-            // If the device is an Actilink S device, the setup wizard should be set to 'actilink'.
+            // Check if the device is an ACTILINK-S device.
+            // If the device is an ACTILINK-S device, the setup wizard should be set to 'actilink'.
             const hardwareDescription = yield (0, rxjs_1.lastValueFrom)(this.getHardwareDescription(deviceRef));
-            if ((hardwareDescription === null || hardwareDescription === void 0 ? void 0 : hardwareDescription.assembly) && (0, product_1.isSomanetProductIdInRange)((_a = hardwareDescription.assembly) === null || _a === void 0 ? void 0 : _a.id, 'Actilink S')) {
+            if ((hardwareDescription === null || hardwareDescription === void 0 ? void 0 : hardwareDescription.assembly) && (0, product_1.isSomanetProductIdInRange)((_a = hardwareDescription.assembly) === null || _a === void 0 ? void 0 : _a.id, 'ACTILINK-S')) {
                 uiFeaturesConfig.setupWizard = 'actilink';
             }
             // Read the parameters from the assembly configuration file.
@@ -4276,6 +4302,201 @@ class MotionMasterReqResClient {
     getUiConfigOrDefaultPdoMapping(deviceRef) {
         return this.getUiConfig(deviceRef).pipe((0, operators_1.map)((uiConfig) => { var _a; return (_a = uiConfig.pdoMapping) !== null && _a !== void 0 ? _a : device_parameter_1.uiConfigWithDefaultPdoMapping.pdoMapping; }));
     }
+    /**
+     * Runs the offset detection procedure for the given device and emits step-wise progress updates.
+     *
+     * The procedure executes a sequence of diagnostic steps sequentially and reports their state
+     * (`idle`, `running`, `succeeded`, `failed`) via an observable stream.
+     *
+     * Behavior
+     * - If `stepIds` is provided, only those steps are executed (in order).
+     * - If `stepIds` is empty, all available offset detection steps are executed.
+     * - Automatically inserts `motorPhaseOrderDetection` if required by
+     *   `commutationOffsetMeasurement`.
+     * - Transitions the device into diagnostics mode and ensures it is in
+     *   `OPERATION ENABLED` state before executing steps.
+     * - Restores the brake state and transitions the device to
+     *   `SWITCH_ON_DISABLED` after completion, error, or cancellation.
+     *
+     * Cancellation
+     * - Unsubscribing from the returned observable cancels further step execution.
+     * - Cancellation stops the sequence cooperatively (in-progress async operations may still complete).
+     * - Cancellation is treated as an error internally.
+     *
+     * Error Handling
+     * - Emits an error if the device is not in the required CIA402 state.
+     * - Emits an error if any step fails.
+     * - Emits an error if step dependencies are violated.
+     * - Cleanup operations (brake restore and state transition) are always attempted in `finally`.
+     *
+     * @param deviceRef - Reference to the target device.
+     * @param stepIds - Optional list of step IDs to execute. If omitted or empty, all steps are executed.
+     * @returns An observable that emits the progress and final state of each offset detection step.
+     *
+     * @remarks
+     * Each emission contains a cloned snapshot of all steps to allow safe external consumption
+     * without mutation side effects.
+     */
+    runOffsetDetection(deviceRef, stepIds = []) {
+        // Mapping of step IDs to their corresponding execution functions and result value keys
+        const stepCommand = {
+            openPhaseDetection: { execute: () => this.runOpenPhaseDetectionOsCommand(deviceRef), valueKey: 'phaseOpened' },
+            phaseResistanceMeasurement: {
+                execute: () => this.runPhaseResistanceMeasurementOsCommand(deviceRef),
+                valueKey: 'phaseResistance',
+            },
+            phaseInductanceMeasurement: {
+                execute: () => this.runPhaseInductanceMeasurementOsCommand(deviceRef),
+                valueKey: 'phaseInductance',
+            },
+            polePairDetection: {
+                execute: () => this.runPolePairDetectionOsCommand(deviceRef),
+                valueKey: 'numberOfPolePairs',
+            },
+            motorPhaseOrderDetection: {
+                execute: () => this.runMotorPhaseOrderDetectionOsCommand(deviceRef),
+                valueKey: 'motorPhaseOrder',
+            },
+            commutationOffsetMeasurement: {
+                execute: () => this.runCommutationOffsetMeasurementOsCommand(deviceRef),
+                valueKey: 'commutationAngleOffset',
+            },
+        };
+        return new rxjs_1.Observable((subscriber) => {
+            let isCancelled = false;
+            // Brake-related state restored in finally block
+            let brakeReleaseStrategy = 0;
+            let brakeStatusInit = 0;
+            let brakePullTime = 0;
+            // Throws if cancellation was requested
+            const checkCancelled = () => {
+                if (isCancelled) {
+                    throw new Error('Offset detection procedure was cancelled.');
+                }
+            };
+            const runInternal = () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                // Determine active steps (either provided subset or all steps)
+                let activeStepIds = stepIds.length > 0 ? [...stepIds] : offset_detection_1.offsetDetectionSteps.map((s) => s.id);
+                // Ensure motor phase order detection is included if required by commutation step
+                const needsMotorPhaseOrderDetection = activeStepIds.includes('commutationOffsetMeasurement');
+                const hasMotorPhaseOrderDetection = activeStepIds.includes('motorPhaseOrderDetection');
+                if (needsMotorPhaseOrderDetection && !hasMotorPhaseOrderDetection) {
+                    const idx = activeStepIds.indexOf('commutationOffsetMeasurement');
+                    activeStepIds.splice(idx, 0, 'motorPhaseOrderDetection');
+                }
+                // Initial step snapshot with all steps in 'idle' state
+                const steps = structuredClone(offset_detection_1.offsetDetectionSteps);
+                if (!isCancelled) {
+                    subscriber.next(steps);
+                }
+                try {
+                    // Read brake configuration from device
+                    [brakeReleaseStrategy, brakeStatusInit, brakePullTime] = (yield this.uploadMany([
+                        [deviceRef, 0x2004, 4],
+                        [deviceRef, 0x2004, 7],
+                        [deviceRef, 0x2004, 3],
+                    ]));
+                    checkCancelled();
+                    // Temporarily release brake if required
+                    if (brakeReleaseStrategy > 0) {
+                        yield this.download(deviceRef, 0x2004, 7, 2);
+                        yield (0, util_1.resolveAfter)(brakePullTime + 500);
+                    }
+                    checkCancelled();
+                    // Switch device into diagnostics mode and ensure OPERATION ENABLED state
+                    yield (0, rxjs_1.lastValueFrom)(this.setModesOfOperationAndTransitionToCia402State(deviceRef, cia402_1.ModesOfOperation.DIAGNOSTICS_MODE, cia402_1.Cia402State.OPERATION_ENABLED));
+                    // Execute each selected diagnostic step sequentially and emit progress updates
+                    for (const id of activeStepIds) {
+                        checkCancelled();
+                        // Verify device state before each step to ensure it is still in OPERATION ENABLED
+                        const cia402state = yield (0, rxjs_1.lastValueFrom)(this.getCia402State(deviceRef));
+                        if (cia402state !== cia402_1.Cia402State.OPERATION_ENABLED) {
+                            subscriber.error(new Error('Device is not in the expected state for running diagnostics. Please ensure the device is in OPERATION ENABLED state.'));
+                            return;
+                        }
+                        checkCancelled();
+                        const step = steps.find((s) => s.id === id);
+                        const command = stepCommand[id];
+                        // Validate configuration consistency
+                        if (!step || !command) {
+                            throw new Error(`Invalid diagnostic configuration for: "${id}"`);
+                        }
+                        // Mark step as running and emit progress
+                        step.status = 'running';
+                        subscriber.next(structuredClone(steps));
+                        // Execute diagnostic command
+                        const response = yield (0, rxjs_1.lastValueFrom)(command.execute());
+                        checkCancelled();
+                        if (response.request === 'succeeded') {
+                            // Mark success and store result value
+                            step.status = 'succeeded';
+                            step.value = response[command.valueKey];
+                        }
+                        else {
+                            // Mark failure and store error details
+                            step.status = 'failed';
+                            step.error = `${response.errorCode}: ${response.errorDescription} (${response.errorName})`;
+                            // Special validation: enforce dependency between steps
+                            const nextStepId = activeStepIds[activeStepIds.indexOf(id) + 1];
+                            if (id === 'motorPhaseOrderDetection' && nextStepId === 'commutationOffsetMeasurement') {
+                                subscriber.next(structuredClone(steps));
+                                subscriber.error(new Error('Commutation Offset Measurement cannot be performed until Motor Phase Order Detection has successfully completed.'));
+                                return;
+                            }
+                        }
+                        // Emit updated progress after each step
+                        if (!isCancelled) {
+                            subscriber.next(structuredClone(steps));
+                        }
+                    }
+                    // Complete observable if not cancelled
+                    if (!isCancelled) {
+                        subscriber.complete();
+                    }
+                }
+                catch (error) {
+                    // Emit error unless cancellation occurred
+                    if (!isCancelled) {
+                        // Mark all running steps as failed on error
+                        steps.forEach((s) => {
+                            if (s.status === 'running') {
+                                s.status = 'failed';
+                            }
+                        });
+                        // Emit final step states before error
+                        subscriber.next(structuredClone(steps));
+                        subscriber.error(error instanceof Error ? error : new Error(String(error)));
+                    }
+                    else {
+                        console.warn('Offset detection procedure was cancelled.');
+                    }
+                }
+                finally {
+                    // Always restore brake state if it was modified
+                    if (brakeReleaseStrategy > 0) {
+                        try {
+                            yield this.download(deviceRef, 0x2004, 7, brakeStatusInit);
+                        }
+                        catch (error) {
+                            console.error(`Failed to restore brake state (${brakeStatusInit}) after offset detection procedure: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                    // Always attempt to return device to a safe state
+                    try {
+                        yield this.transitionToCia402State(deviceRef, cia402_1.Cia402State.SWITCH_ON_DISABLED);
+                    }
+                    catch (error) {
+                        console.error(`Failed to transition device to Switch on Disabled state after offset detection procedure: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+            });
+            runInternal();
+            // Cancellation handler from observable unsubscribe
+            return () => {
+                isCancelled = true;
+            };
+        });
+    }
 }
 exports.MotionMasterReqResClient = MotionMasterReqResClient;
 /**