motion-master-client 0.0.421 → 0.0.422

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

@@ -3367,7 +3367,7 @@ class MotionMasterReqResClient {
         // @ts-ignore
         return this.runOsCommandAndWriteFsBuffer(deviceRef, command, content, commandTimeout, responsePollingInterval).pipe((0, operators_1.last)(), (0, operators_1.map)((response) => {
             if (response.request !== 'succeeded') {
-                throw new Error('Login to SMM for parameter download failed.');
+                throw new Error(`Login to SMM for parameter download failed: ${(0, os_command_1.describeOsCommandFailure)(response)}.`);
             }
         }));
     }
@@ -3395,7 +3395,7 @@ class MotionMasterReqResClient {
         // @ts-ignore
         return this.runOsCommandAndWriteFsBuffer(deviceRef, command, content, commandTimeout, responsePollingInterval).pipe((0, operators_1.last)(), (0, operators_1.map)((response) => {
             if (response.request !== 'succeeded') {
-                throw new Error('Login to SMM for software update failed.');
+                throw new Error(`Login to SMM for software update failed: ${(0, os_command_1.describeOsCommandFailure)(response)}.`);
             }
         }));
     }
@@ -3415,7 +3415,7 @@ class MotionMasterReqResClient {
         const command = (0, os_command_1.createSmmAcyclicHandlerOsCommand)(os_command_1.SmmAcyclicHandlerSubcommandId.LOGOUT);
         return this.runOsCommand(deviceRef, command, commandTimeout, responsePollingInterval).pipe((0, operators_1.last)(), (0, operators_1.map)((response) => {
             if (response.request !== 'succeeded') {
-                throw new Error('Logout from SMM failed.');
+                throw new Error(`Logout from SMM failed: ${(0, os_command_1.describeOsCommandFailure)(response)}.`);
             }
         }));
     }
@@ -3440,25 +3440,84 @@ class MotionMasterReqResClient {
     /**
      * Changes the SMM password for the specified device.
      *
+     * The sequence is: write `<newPassword><oldPassword>` to the fs-buffer and run CHANGE_PASSWORD. If, and only if, the
+     * SMM accepts the change, log out from the SMM, trigger an SMM restart (unless `triggerRestart` is false) and then
+     * wait `rebootDelay` milliseconds before completing, so the next SMM command a caller issues does not land in the
+     * reboot.
+     *
+     * The logout has to come before the restart. When the SMM is restarted while the session is still open, it stores
+     * neither the new nor the old password, although it accepted the change, and only the master password gets in again.
+     * After an accepted change the session is therefore closed; log in again with the new password to continue.
+     *
      * @param deviceRef - A reference to the target device.
      * @param oldPassword - The current SMM password.
-     * @param newPassword - The new password to set for the SMM.
-     * @param commandTimeout - The timeout in milliseconds for the command to complete.
+     * @param newPassword - The new password to set for the SMM, 4 to 24 printable ASCII characters.
+     * @param commandTimeout - The timeout in milliseconds for the CHANGE_PASSWORD command. On firmware below 5.2.0 it also
+     *   covers the FoE write of the fs-buffer, because the buffer is written before the command is issued. If it runs out
+     *   while the SMM is still storing the password, the client gives up, the SMM is not restarted, and the result of the
+     *   change is unknown. Defaults to 12000: the drive gives up on the SMM after 10 s, so do not set it lower, and do not
+     *   retry after a timeout, the SMM may still be running the change.
      * @param responsePollingInterval - The interval in milliseconds between polling for the response.
-     *
-     * @throws {Error} If the password change attempt fails.
+     * @param triggerRestart - Whether to restart the SMM after an accepted change and the logout. Defaults to true. The
+     *   firmware requires a restart after a password change, so pass false only if you restart the SMM yourself (with
+     *   {@link triggerSmmRestart}) before issuing any other SMM command. The logout happens either way, so your restart
+     *   comes after it.
+     * @param rebootDelay - How long to wait after the restart command completes, in milliseconds, before the observable
+     *   completes. Defaults to 3000, the `SMM_REBOOT_DELAY` the firmware test reference uses. Ignored when
+     *   `triggerRestart` is false.
+     *
+     * @throws {Error} If a password is not 1 (old) or 4 (new) to 24 printable ASCII characters, if the SMM rejects the
+     *   change (the SMM is then not restarted and the session stays open), if the logout after an accepted change fails
+     *   (the SMM is then not restarted), or if the restart fails.
      *
      * @remarks
-     * A prior successful login is required before changing the password.
-     * The new password must be at least 4 characters long.
+     * Completion means the SMM accepted the change. It does not prove that the SMM stored the intended password; only a
+     * login with the new password does.
      *
-     * This function sends an acyclic command to update the password. If successful, it triggers an SMM restart.
+     * Rules a caller has to follow, because the SMM and the drive do not enforce them for you:
+     *
+     * - A login for parameter download must be open. A login fails while a session is already open, so log out first:
+     *   use {@link reloginToSmmForParameterDownload}. The SMM closes a session after 5 minutes.
+     * - The OS command object (0x1023) and the fs-buffer are a single slot per device. Nothing else may issue OS commands
+     *   to the same device during the sequence: no second script, no Motion Master Console on the OS Commands page, no
+     *   other tool. Issue SMM functions one at a time and wait for each to complete.
+     * - When the SMM rejects the change, the response does not say why: a wrong old password, a missing or expired
+     *   session and an SMM that is still booting all produce the same "the SMM rejected the request (status 2)".
      */
-    changeSmmPassword(deviceRef, oldPassword, newPassword, commandTimeout = 10000, responsePollingInterval = 500) {
-        const command = (0, os_command_1.createSmmAcyclicHandlerOsCommand)(os_command_1.SmmAcyclicHandlerSubcommandId.CHANGE_PASSWORD);
-        const content = (0, smm_1.packSmmChangePassword)(newPassword, oldPassword);
-        // @ts-ignore
-        return this.runOsCommandAndWriteFsBuffer(deviceRef, command, content, commandTimeout, responsePollingInterval).pipe((0, operators_1.last)(), (0, operators_1.mergeMap)(() => this.triggerSmmRestart(deviceRef)));
+    changeSmmPassword(deviceRef, oldPassword, newPassword, commandTimeout = 12000, responsePollingInterval = 500, triggerRestart = true, rebootDelay = 3000) {
+        return (0, rxjs_1.defer)(() => {
+            (0, smm_1.assertValidSmmPassword)(oldPassword, 'Old password');
+            (0, smm_1.assertValidSmmPassword)(newPassword, 'New password', smm_1.SMM_PASSWORD_MIN_LENGTH);
+            const command = (0, os_command_1.createSmmAcyclicHandlerOsCommand)(os_command_1.SmmAcyclicHandlerSubcommandId.CHANGE_PASSWORD);
+            const content = (0, smm_1.packSmmChangePassword)(newPassword, oldPassword);
+            // @ts-ignore
+            return this.runOsCommandAndWriteFsBuffer(deviceRef, command, content, commandTimeout, responsePollingInterval);
+        }).pipe((0, operators_1.last)(), (0, operators_1.concatMap)((response) => {
+            if (response.request !== 'succeeded') {
+                throw new Error(`Changing SMM password failed: ${(0, os_command_1.describeOsCommandFailure)(response)}. The password was not changed and the SMM was not restarted.`);
+            }
+            // Log out before the restart. A restart while the session is still open makes the SMM store neither the new
+            // nor the old password, although it accepted the change (reproduced on firmware v5.6.6, issue #185).
+            const logout$ = this.logoutFromSmm(deviceRef).pipe((0, operators_1.catchError)((err) => (0, rxjs_1.throwError)(() => {
+                var _a;
+                return new Error(`The SMM accepted the password change, but the logout failed, so the SMM was not restarted. Log out and restart the SMM before using the new password. ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`);
+            })), (0, operators_1.last)(null, undefined));
+            if (!triggerRestart) {
+                return logout$;
+            }
+            return logout$.pipe((0, operators_1.concatMap)(() => this.triggerSmmRestart(deviceRef).pipe((0, operators_1.catchError)((err) => (0, rxjs_1.throwError)(() => { var _a; return new Error(`The SMM accepted the password change, but the restart failed. ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`); })), (0, operators_1.last)(null, undefined))), (0, operators_1.concatMap)(() => (0, rxjs_1.timer)(rebootDelay)));
+        }), (0, operators_1.last)(null, undefined), (0, operators_1.map)(() => undefined));
+    }
+    /**
+     * Runs an SMM sequence and then logs out from the SMM, on completion and on error alike.
+     *
+     * Unlike a `finalize(() => logout.subscribe())`, the logout is part of the returned observable: the result is
+     * delivered only after the logout has finished, so a caller's next SMM command cannot run alongside it on the
+     * device's single OS command slot. A failing logout does not replace the sequence's own result or error.
+     */
+    logoutFromSmmAfter(deviceRef, sequence$) {
+        const logout$ = (0, rxjs_1.defer)(() => this.logoutFromSmm(deviceRef)).pipe((0, operators_1.catchError)(() => rxjs_1.EMPTY), (0, operators_1.filter)(() => false));
+        return (0, rxjs_1.concat)(sequence$.pipe((0, operators_1.catchError)((err) => (0, rxjs_1.concat)(logout$, (0, rxjs_1.throwError)(() => err)))), logout$);
     }
     /**
      * Triggers an SMM restart for the specified device.
@@ -3479,7 +3538,7 @@ class MotionMasterReqResClient {
         const command = (0, os_command_1.createSmmAcyclicHandlerOsCommand)(os_command_1.SmmAcyclicHandlerSubcommandId.TRIGGER_RESTART);
         return this.runOsCommand(deviceRef, command, commandTimeout, responsePollingInterval).pipe((0, operators_1.last)(), (0, operators_1.map)((response) => {
             if (response.request !== 'succeeded') {
-                throw new Error('Triggering SMM restart failed.');
+                throw new Error(`Triggering SMM restart failed: ${(0, os_command_1.describeOsCommandFailure)(response)}.`);
             }
         }));
     }
@@ -3499,7 +3558,7 @@ class MotionMasterReqResClient {
         const command = (0, os_command_1.createSmmAcyclicHandlerOsCommand)(os_command_1.SmmAcyclicHandlerSubcommandId.IO_FAILURE_ACKNOWLEDGE);
         return this.runOsCommand(deviceRef, command, commandTimeout, responsePollingInterval).pipe((0, operators_1.last)(), (0, operators_1.map)((response) => {
             if (response.request !== 'succeeded') {
-                throw new Error('Acknowledging I/O failure on SMM failed.');
+                throw new Error(`Acknowledging I/O failure on SMM failed: ${(0, os_command_1.describeOsCommandFailure)(response)}.`);
             }
         }));
     }
@@ -3516,7 +3575,7 @@ class MotionMasterReqResClient {
         const command = (0, os_command_1.createSmmAcyclicHandlerConfigureSoftwareUpdateOsCommand)(fileSize);
         return this.runOsCommand(deviceRef, command, 10000, 100).pipe((0, operators_1.last)(), (0, operators_1.map)((response) => {
             if (response.request !== 'succeeded') {
-                throw new Error('Configuring SMM software update failed.');
+                throw new Error(`Configuring SMM software update failed: ${(0, os_command_1.describeOsCommandFailure)(response)}.`);
             }
         }));
     }
@@ -3571,7 +3630,7 @@ class MotionMasterReqResClient {
             observables.push((0, rxjs_1.defer)(() => this.runOsCommandAndWriteFsBuffer(deviceRef, transmitSoftwareCommand, fsBufferContent, commandTimeout, responsePollingInterval, false, fsBufferReadWriteTimeout).pipe((0, operators_1.last)(), // Only consider the final response of the command.
             (0, operators_1.map)((response) => {
                 if (response.request !== 'succeeded') {
-                    throw new Error(`Transmitting SMM software chunk ${i + 1}/${n} failed.`);
+                    throw new Error(`Transmitting SMM software chunk ${i + 1}/${n} failed: ${(0, os_command_1.describeOsCommandFailure)(response)}.`);
                 }
             }) // Interpret the response success.
             )));
@@ -3584,7 +3643,7 @@ class MotionMasterReqResClient {
         // @ts-ignore
         this.runOsCommandAndWriteFsBuffer(deviceRef, finalizeSoftwareUpdateCommand, packedCrc).pipe((0, operators_1.last)(), (0, operators_1.map)((response) => {
             if (response.request !== 'succeeded') {
-                throw new Error('Finalizing SMM software update failed.');
+                throw new Error(`Finalizing SMM software update failed: ${(0, os_command_1.describeOsCommandFailure)(response)}.`);
             }
         }))), 
         // Step 7: Trigger a restart so the new software takes effect.
@@ -3862,7 +3921,7 @@ class MotionMasterReqResClient {
             // @ts-ignore
             content, commandTimeout, responsePollingInterval).pipe((0, operators_1.last)(), (0, operators_1.map)((response) => {
                 if (response.request !== 'succeeded') {
-                    throw new Error('Transmitting SMM parameters failed.');
+                    throw new Error(`Transmitting SMM parameters failed: ${(0, os_command_1.describeOsCommandFailure)(response)}.`);
                 }
             }));
         }));
@@ -3925,7 +3984,7 @@ class MotionMasterReqResClient {
             const command = (0, os_command_1.createSmmAcyclicHandlerOsCommand)(os_command_1.SmmAcyclicHandlerSubcommandId.VERIFY_PARAMETERS);
             return this.runOsCommandAndWriteFsBuffer(deviceRef, command, content, commandTimeout, responsePollingInterval).pipe((0, operators_1.last)(), (0, operators_1.map)((response) => {
                 if (response.request !== 'succeeded') {
-                    throw new Error('Verifying SMM parameters failed.');
+                    throw new Error(`Verifying SMM parameters failed: ${(0, os_command_1.describeOsCommandFailure)(response)}.`);
                 }
             }));
         }));
@@ -3990,7 +4049,7 @@ class MotionMasterReqResClient {
         const command = (0, os_command_1.createSmmAcyclicHandlerOsCommand)(os_command_1.SmmAcyclicHandlerSubcommandId.VALIDATE_CONFIGURATION);
         return this.runOsCommandAndWriteFsBuffer(deviceRef, command, content, commandTimeout, responsePollingInterval).pipe((0, operators_1.last)(), (0, operators_1.map)((response) => {
             if (response.request !== 'succeeded') {
-                throw new Error('Validating SMM configuration failed.');
+                throw new Error(`Validating SMM configuration failed: ${(0, os_command_1.describeOsCommandFailure)(response)}.`);
             }
         }));
     }
@@ -4454,7 +4513,7 @@ class MotionMasterReqResClient {
         // Fail lambda to handle errors in a consistent way.
         const fail = (message) => (0, rxjs_1.throwError)(() => new Error(message));
         // Resolve the SMM parameter structure version for getting the correct SMM OD.
-        return this.resolveSmmParameterStructureVersion(deviceRef).pipe((0, operators_1.concatMap)((parameterStructureVersion) => {
+        const sequence$ = this.resolveSmmParameterStructureVersion(deviceRef).pipe((0, operators_1.concatMap)((parameterStructureVersion) => {
             const smmOd = (0, smm_1.resolveSmmOd)(parameterStructureVersion);
             // Group SMM safety parameters by their 'group' property,
             // then for each group, map the SMM OD parameters to the matching
@@ -4509,9 +4568,9 @@ class MotionMasterReqResClient {
                     }));
                 }));
             }));
-        }), (0, operators_1.finalize)(() => {
-            this.logoutFromSmm(deviceRef).subscribe();
         }));
+        // Log out at the end, on success and on failure, before the result is delivered.
+        return this.logoutFromSmmAfter(deviceRef, sequence$);
     }
     /**
      * Executes a forward call by sending the provided data, then parses the JSON response.