motion-master-client 0.0.367 → 0.0.369

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

@@ -3350,6 +3350,250 @@ class MotionMasterReqResClient {
         (0, rxjs_1.defer)(() => this.triggerSmmRestart(deviceRef)));
         return (0, rxjs_1.concat)(...observables).pipe((0, operators_1.last)());
     }
+    /**
+     * Resolves whether an automated SMM software update is allowed for the specified device.
+     *
+     * This method evaluates the device and the provided firmware binary against a set of
+     * preconditions required for automated installation. It returns a detailed
+     * {@link SmmAutomatedUpdate} object describing each individual check result, which
+     * can be used to give precise feedback to the user when automation is not possible.
+     *
+     * The automation is only permitted when **all** of the following conditions are met:
+     * - The device is a recognized Somanet product (`isValidProduct`).
+     * - The device belongs to the Circulo product family (`isCirculo`).
+     * - The binary is encrypted (`isBinaryEncrypted`).
+     * - The binary targets one of the supported SMM versions — v1.4 (260) or v2.56 (568) (`isAllowedBinaryVersion`).
+     * - If targeting v2.56, the device SoC firmware version is ≥ 5.5.0 (`canInstallV256`).
+     * - The device is running a legacy SMM firmware below v1.3, i.e. version < 259 (`isDeviceLw1`).
+     *
+     * If the device is not a recognized product, the method returns early with all flags set
+     * to `false` and default zero values to avoid unnecessary device communication.
+     *
+     * @param deviceRef - A reference to the target device.
+     * @param buffer - The SMM firmware binary to be installed, provided as a `Uint8Array`.
+     *                 Its header is parsed to determine the target version and encryption status.
+     *
+     * @returns A promise that resolves to an {@link SmmAutomatedUpdate} object containing:
+     * - `isValidProduct` — Whether the device maps to a known Somanet product.
+     * - `isCirculo` — Whether the device belongs to the Circulo product family.
+     * - `isCirculo7` — Whether the device is a Circulo 7.
+     * - `isCirculo9` — Whether the device is a Circulo 9.
+     * - `isDeviceLw1` — Whether the device SMM firmware is below v1.3 (version < 259).
+     * - `isBinaryEncrypted` — Whether the provided firmware binary is encrypted.
+     * - `isAllowedBinaryVersion` — Whether the binary targets a supported version (v1.4 or v2.56).
+     * - `canInstallV256` — Whether v2.56 can be installed (requires SoC firmware ≥ 5.5.0).
+     * - `isAutomationAllowed` — Whether all preconditions for automated update are satisfied.
+     * - `allowedTargetSmmVersions` — The list of supported target SMM versions: `[260, 568]`.
+     * - `deviceFirmwareVersion` — The SoC firmware version string read from the device (index `0x100a:0`).
+     * - `deviceSmmVersion` — The current SMM firmware version as a raw integer.
+     * - `binaryVersion` — The target SMM version encoded in the binary header.
+     */
+    resolveSmmAutomatedUpdateConditions(deviceRef, buffer) {
+        var _a, _b;
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            const device = yield (0, rxjs_1.lastValueFrom)(this.resolveDevice(deviceRef));
+            const product = (0, product_1.findSomanetProductById)(device === null || device === void 0 ? void 0 : device.serialNumber);
+            const isValidProduct = !!product;
+            // v1.4 (no safe torque), v2.56 (safe torque)
+            const allowedTargetSmmVersions = [260, 568];
+            if (!isValidProduct) {
+                return {
+                    isValidProduct: false,
+                    isDeviceLw1: false,
+                    isCirculo: false,
+                    isCirculo7: false,
+                    isCirculo9: false,
+                    isBinaryEncrypted: false,
+                    isAllowedBinaryVersion: false,
+                    canInstallV256: false,
+                    isAutomationAllowed: false,
+                    allowedTargetSmmVersions,
+                    deviceFirmwareVersion: 'v0.0.0',
+                    deviceSmmVersion: 0,
+                    isV990: false,
+                    isV770: false,
+                    isV771: false,
+                    binaryVersion: 0,
+                    deviceSupportsStreaming: false,
+                };
+            }
+            const deviceSmmVersion = yield (0, rxjs_1.lastValueFrom)(this.readSmmFirmwareVersionAsNumber(deviceRef));
+            const deviceFirmwareVersion = (yield this.upload(deviceRef, 0x100a, 0));
+            const binaryHeader = (0, smm_1.parseSmmBinaryHeaders)(buffer);
+            const binaryInformation = (0, smm_1.getInformationFromSmmFirmwareVersion)(binaryHeader.swVersion);
+            // Allow installation of smm v2.56 only if device SoC firmware version is >=5.5.0
+            const canInstallV256 = binaryHeader.swVersion === 568 ? semver.gte((_a = semver.coerce(deviceFirmwareVersion)) !== null && _a !== void 0 ? _a : '0.0.0', '5.5.0') : true;
+            const isCirculo = product.family === 'Circulo';
+            const isDeviceLw1 = deviceSmmVersion < 259; // <v1.3
+            const isV990 = deviceSmmVersion === 25344;
+            const isV770 = deviceSmmVersion === 19712;
+            const isV771 = deviceSmmVersion === 19713;
+            const isBinaryEncrypted = binaryInformation.isEncrypted;
+            const isAllowedBinaryVersion = allowedTargetSmmVersions.includes(binaryInformation.version);
+            const isCirculo7 = isCirculo && product.group === 'Circulo 7';
+            const isCirculo9 = isCirculo && product.group === 'Circulo 9';
+            const deviceSupportsStreaming = semver.gte((_b = semver.coerce(deviceFirmwareVersion)) !== null && _b !== void 0 ? _b : '0.0.0', '5.2.0');
+            const isAutomationAllowed = isCirculo &&
+                isBinaryEncrypted &&
+                isAllowedBinaryVersion &&
+                canInstallV256 &&
+                (isDeviceLw1 || isV990 || isV770 || isV771); // Allow automation for devices on legacy firmware (lw1) or already on one of the intermediate versions (v99.0, v77.0, v77.1)
+            return {
+                isValidProduct,
+                isDeviceLw1,
+                isCirculo,
+                isCirculo7,
+                isCirculo9,
+                isBinaryEncrypted,
+                isAllowedBinaryVersion,
+                canInstallV256,
+                isAutomationAllowed,
+                allowedTargetSmmVersions,
+                deviceFirmwareVersion,
+                deviceSmmVersion,
+                isV990,
+                isV770,
+                isV771,
+                binaryVersion: binaryInformation.version,
+                deviceSupportsStreaming,
+            };
+        });
+    }
+    /**
+     * Performs an automated, multi-step SMM software update to an encrypted firmware version on a Circulo device.
+     *
+     * Before installing the target binary, this method evaluates the device state by calling
+     * {@link resolveSmmAutomatedUpdateConditions}. Based on the result, it determines which
+     * sequence of intermediate firmware versions must be installed first to transition the device
+     * from unencrypted to encrypted firmware.
+     *
+     * The installation sequence depends on the current SMM version and device group:
+     * - **Legacy (< v1.3) + Circulo 7**: v99.0 → v77.0 → target
+     * - **Legacy (< v1.3) + Circulo 9**: v99.0 → v77.1 → target
+     * - **v99.0 + Circulo 7**: v77.0 → target
+     * - **v99.0 + Circulo 9**: v77.1 → target
+     * - **v77.0 or v77.1**: target only
+     *
+     * If the device does not support streaming, `commandTimeout` is automatically extended to 420,000 ms.
+     *
+     * @param deviceRef - Reference to the target device.
+     * @param username - Username used for SMM authentication.
+     * @param password - Password used for SMM authentication.
+     * @param buffer - The target encrypted firmware binary as a `Uint8Array`.
+     * @param crc - CRC32 checksum of the target firmware binary for integrity verification.
+     * @param chunkSize - (Optional) Size of each data chunk transmitted per step, in bytes. Defaults to 1000.
+     * @param commandTimeout - (Optional) Timeout for each OS command in ms. Automatically overridden to 420,000 ms
+     *                         if the device does not support streaming. Defaults to 30,000 ms.
+     * @param responsePollingInterval - (Optional) Polling interval for command responses in ms. Defaults to 1000 ms.
+     * @param fsBufferReadWriteTimeout - (Optional) Timeout for fs-buffer read/write operations in ms. Defaults to 120,000 ms.
+     *
+     * @returns An `Observable<void>` that completes when the full installation sequence finishes successfully.
+     *
+     * @throws {Error} With message `'Unknown product. Cannot perform SMM software update.'` if the device
+     *                 serial number does not map to a known Somanet product.
+     * @throws {Error} With a descriptive message listing unmet preconditions if automation is not allowed —
+     *                 e.g. the device is not a Circulo, the binary is not encrypted, the target version is
+     *                 unsupported, the SoC firmware is below v5.5.0 (for SMM v2.56), or the device is
+     *                 already on SMM v1.3+.
+     * @throws {Error} If any individual firmware installation step fails during execution.
+     */
+    updateSmmSoftwareToEncrypted(deviceRef, username, password, buffer, crc, chunkSize = 1000, commandTimeout = 30000, responsePollingInterval = 1000, fsBufferReadWriteTimeout = 120000) {
+        return new rxjs_1.Observable((subscriber) => {
+            (() => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                /**
+                 * We must wrap the whole anonymous function body in try/catch so the subscriber (in `catch`)
+                 * knows when the error happens. Otherwise, the application will "explode" when the error occurs.
+                 *
+                 * Observable function is synchronous. When the error occurs, it will handle it via `error: (err) => {}`
+                 * function. Here, that is not the case. The anonymous function is asynchronous and will update the
+                 * subscriber only when we tell it to do so via `subscriber.<method>`. Error handling from the outside
+                 * will not pick-up the errors from here as this is "fire-and-forget" type of function.
+                 *
+                 * @example
+                 *
+                 * ```typescript
+                 * asyncHandler(async (req, res, next) => {
+                 *  somePromiseThatRejects().then(...)   // ← no await, no .catch()
+                 *  // or a setTimeout, event emitter, etc.
+                 *
+                 *  // handler finishes immediately
+                  })
+                 */
+                try {
+                    const automatedInstall = yield this.resolveSmmAutomatedUpdateConditions(deviceRef, buffer);
+                    if (!automatedInstall.isValidProduct) {
+                        subscriber.error(new Error('Unknown product. Cannot perform SMM software update.'));
+                        return;
+                    }
+                    let observables = [];
+                    if (automatedInstall.isAutomationAllowed) {
+                        const v990crc = 0xd1a3bb72;
+                        const v990Buffer = yield Promise.resolve().then(() => tslib_1.__importStar(require('./smm/40701_DEBUG_Update_V99.0'))).then((m) => Uint8Array.from(atob(m.smmBinaryV990), (c, _) => { var _a; return (_a = c.codePointAt(0)) !== null && _a !== void 0 ? _a : 0; }));
+                        const v770crc = 0xe290a20a;
+                        const v770Buffer = yield Promise.resolve().then(() => tslib_1.__importStar(require('./smm/40701_DEBUG_Update_V77.0'))).then((m) => Uint8Array.from(atob(m.smmBinaryV770), (c, _) => { var _a; return (_a = c.codePointAt(0)) !== null && _a !== void 0 ? _a : 0; }));
+                        const v771crc = 0xa4a11125;
+                        const v771Buffer = yield Promise.resolve().then(() => tslib_1.__importStar(require('./smm/40701_DEBUG_Update_V77.1'))).then((m) => Uint8Array.from(atob(m.smmBinaryV771), (c, _) => { var _a; return (_a = c.codePointAt(0)) !== null && _a !== void 0 ? _a : 0; }));
+                        const v990$ = (0, rxjs_1.defer)(() => this.updateSmmSoftware(deviceRef, username, password, new Uint8Array(v990Buffer), v990crc, chunkSize, commandTimeout, responsePollingInterval, fsBufferReadWriteTimeout));
+                        const v770$ = (0, rxjs_1.defer)(() => this.updateSmmSoftware(deviceRef, username, password, new Uint8Array(v770Buffer), v770crc, chunkSize, commandTimeout, responsePollingInterval, fsBufferReadWriteTimeout));
+                        const v771$ = (0, rxjs_1.defer)(() => this.updateSmmSoftware(deviceRef, username, password, new Uint8Array(v771Buffer), v771crc, chunkSize, commandTimeout, responsePollingInterval, fsBufferReadWriteTimeout));
+                        const userVersion$ = (0, rxjs_1.defer)(() => this.updateSmmSoftware(deviceRef, username, password, buffer, crc, chunkSize, commandTimeout, responsePollingInterval, fsBufferReadWriteTimeout));
+                        if (automatedInstall.isDeviceLw1) {
+                            if (automatedInstall.isCirculo7) {
+                                observables = [v990$, v770$, userVersion$];
+                            }
+                            else if (automatedInstall.isCirculo9) {
+                                observables = [v990$, v771$, userVersion$];
+                            }
+                        }
+                        else if (automatedInstall.isV990) {
+                            if (automatedInstall.isCirculo7) {
+                                observables = [v770$, userVersion$];
+                            }
+                            else if (automatedInstall.isCirculo9) {
+                                observables = [v771$, userVersion$];
+                            }
+                        }
+                        else if (automatedInstall.isV770 || automatedInstall.isV771) {
+                            observables = [userVersion$];
+                        }
+                        (0, rxjs_1.concat)(...observables).subscribe({
+                            next: () => {
+                                subscriber.next();
+                            },
+                            error: (err) => {
+                                subscriber.error(err);
+                            },
+                            complete: () => {
+                                subscriber.complete();
+                            },
+                        });
+                    }
+                    else {
+                        const reasons = [];
+                        if (!automatedInstall.isCirculo) {
+                            reasons.push('The device is not part of the Circulo family.');
+                        }
+                        if (!automatedInstall.isDeviceLw1) {
+                            reasons.push('The device SMM software version is not lower than 1.3.');
+                        }
+                        if (!automatedInstall.isBinaryEncrypted) {
+                            reasons.push('The SMM binary is not encrypted.');
+                        }
+                        if (!automatedInstall.isAllowedBinaryVersion) {
+                            reasons.push('The target SMM software version is not supported for encrypted update.');
+                        }
+                        if (!automatedInstall.canInstallV256) {
+                            reasons.push('The device firmware must be minimum v5.5.0 for installing SMM v2.56.');
+                        }
+                        subscriber.error(new Error(`The following conditions are not met for SMM software automated update: ${reasons.join(' ')}`));
+                    }
+                }
+                catch (err) {
+                    subscriber.error(err);
+                }
+            }))();
+        });
+    }
     /**
      * Transmits SMM parameters to the specified device.
      *
@@ -4317,6 +4561,7 @@ class MotionMasterReqResClient {
      *   `OPERATION ENABLED` state before executing steps.
      * - Restores the brake state and transitions the device to
      *   `SWITCH_ON_DISABLED` after completion, error, or cancellation.
+     * - Certain steps may temporarily release or engage the brake as needed during execution.
      *
      * Cancellation
      * - Unsubscribing from the returned observable cancels further step execution.
@@ -4338,36 +4583,13 @@ class MotionMasterReqResClient {
      * 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;
+            let measurementMethod = 0;
             // Throws if cancellation was requested
             const checkCancelled = () => {
                 if (isCancelled) {
@@ -4391,17 +4613,80 @@ class MotionMasterReqResClient {
                 }
                 try {
                     // Read brake configuration from device
-                    [brakeReleaseStrategy, brakeStatusInit, brakePullTime] = (yield this.uploadMany([
+                    [brakeReleaseStrategy, brakeStatusInit, brakePullTime, measurementMethod] = (yield this.uploadMany([
                         [deviceRef, 0x2004, 4],
                         [deviceRef, 0x2004, 7],
                         [deviceRef, 0x2004, 3],
+                        [deviceRef, 0x2009, 3],
                     ]));
                     checkCancelled();
-                    // Temporarily release brake if required
-                    if (brakeReleaseStrategy > 0) {
-                        yield this.download(deviceRef, 0x2004, 7, 2);
-                        yield (0, util_1.resolveAfter)(brakePullTime + 500);
-                    }
+                    const engageBrake = () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                        if (brakeReleaseStrategy > 0) {
+                            yield this.download(deviceRef, 0x2004, 7, 1);
+                            yield (0, util_1.resolveAfter)(brakePullTime + 250);
+                        }
+                    });
+                    const releaseBrake = () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                        if (brakeReleaseStrategy > 0) {
+                            yield this.download(deviceRef, 0x2004, 7, 2);
+                            yield (0, util_1.resolveAfter)(brakePullTime + 250);
+                        }
+                    });
+                    // Mapping of step IDs to their corresponding execution functions and result value keys
+                    const stepCommand = {
+                        openPhaseDetection: {
+                            execute: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                                const response = yield (0, rxjs_1.lastValueFrom)(this.runOpenPhaseDetectionOsCommand(deviceRef));
+                                return response;
+                            }),
+                            valueKey: 'phaseOpened',
+                        },
+                        phaseResistanceMeasurement: {
+                            execute: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                                const response = yield (0, rxjs_1.lastValueFrom)(this.runPhaseResistanceMeasurementOsCommand(deviceRef));
+                                return response;
+                            }),
+                            valueKey: 'phaseResistance',
+                        },
+                        phaseInductanceMeasurement: {
+                            execute: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                                const response = yield (0, rxjs_1.lastValueFrom)(this.runPhaseInductanceMeasurementOsCommand(deviceRef));
+                                return response;
+                            }),
+                            valueKey: 'phaseInductance',
+                        },
+                        polePairDetection: {
+                            execute: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                                yield releaseBrake();
+                                const response = yield (0, rxjs_1.lastValueFrom)(this.runPolePairDetectionOsCommand(deviceRef));
+                                yield engageBrake();
+                                return response;
+                            }),
+                            valueKey: 'numberOfPolePairs',
+                        },
+                        motorPhaseOrderDetection: {
+                            execute: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                                yield releaseBrake();
+                                const response = yield (0, rxjs_1.lastValueFrom)(this.runMotorPhaseOrderDetectionOsCommand(deviceRef));
+                                yield engageBrake();
+                                return response;
+                            }),
+                            valueKey: 'motorPhaseOrder',
+                        },
+                        commutationOffsetMeasurement: {
+                            execute: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
+                                if (measurementMethod != 2) {
+                                    yield releaseBrake();
+                                }
+                                const response = yield (0, rxjs_1.lastValueFrom)(this.runCommutationOffsetMeasurementOsCommand(deviceRef));
+                                if (measurementMethod !== 2) {
+                                    yield engageBrake();
+                                }
+                                return response;
+                            }),
+                            valueKey: 'commutationAngleOffset',
+                        },
+                    };
                     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));
@@ -4425,7 +4710,7 @@ class MotionMasterReqResClient {
                         step.status = 'running';
                         subscriber.next(structuredClone(steps));
                         // Execute diagnostic command
-                        const response = yield (0, rxjs_1.lastValueFrom)(command.execute());
+                        const response = yield command.execute();
                         checkCancelled();
                         if (response.request === 'succeeded') {
                             // Mark success and store result value