motion-master-client 0.0.423 → 0.0.424

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

@@ -3365,21 +3365,27 @@ class MotionMasterReqResClient {
      * attempt will fail unless the user logs out beforehand.
      *
      * @param deviceRef - The reference to the device to which the login command will be sent.
-     * @param username - The optional username used for logging in to the SMM. If not provided, it will be treated as an empty string.
-     * @param password - The password used for logging in to the SMM.
+     * @param username - The name of the user who logs in, 4 to 24 printable ASCII characters. It tells who configured
+     *   the SMM, so pass the real user's name.
+     * @param password - The password used for logging in to the SMM, 1 to 24 printable ASCII characters.
      * @param commandTimeout - The timeout in milliseconds for the command to complete.
      * @param responsePollingInterval - The interval in milliseconds between polling for the response.
      *
-     * @throws {Error} If the login attempt fails.
+     * @throws {Error} If the username or the password is not valid, in which case nothing is sent, or if the login
+     *   attempt fails.
      *
      * @remarks
      * If the device is already logged in, the next login attempt will fail unless the user logs out first.
      */
     loginToSmmForParameterDownload(deviceRef, username, password, commandTimeout = 5000, responsePollingInterval = 500) {
-        const command = (0, os_command_1.createSmmAcyclicHandlerOsCommand)(os_command_1.SmmAcyclicHandlerSubcommandId.PARAMETER_DOWNLOAD_LOGIN);
-        const content = (0, smm_1.packSmmCredentials)(username, password);
-        // @ts-ignore
-        return this.runOsCommandAndWriteFsBuffer(deviceRef, command, content, commandTimeout, responsePollingInterval).pipe((0, operators_1.last)(), (0, operators_1.map)((response) => {
+        return (0, rxjs_1.defer)(() => {
+            (0, smm_1.assertValidSmmCredential)(username, 'Username', smm_1.SMM_USERNAME_MIN_LENGTH);
+            (0, smm_1.assertValidSmmCredential)(password, 'Password');
+            const command = (0, os_command_1.createSmmAcyclicHandlerOsCommand)(os_command_1.SmmAcyclicHandlerSubcommandId.PARAMETER_DOWNLOAD_LOGIN);
+            const content = (0, smm_1.packSmmCredentials)(username, password);
+            // @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: ${(0, os_command_1.describeOsCommandFailure)(response)}.`);
             }
@@ -3393,21 +3399,27 @@ class MotionMasterReqResClient {
      * attempt will fail unless the user logs out beforehand.
      *
      * @param deviceRef - The reference to the device to which the login command will be sent.
-     * @param username - The optional username used for logging in to the SMM. If not provided, it will be treated as an empty string.
-     * @param password - The password used for logging in to the SMM.
+     * @param username - The name of the user who logs in, 4 to 24 printable ASCII characters. It tells who configured
+     *   the SMM, so pass the real user's name.
+     * @param password - The password used for logging in to the SMM, 1 to 24 printable ASCII characters.
      * @param commandTimeout - The timeout in milliseconds for the command to complete.
      * @param responsePollingInterval - The interval in milliseconds between polling for the response.
      *
-     * @throws {Error} If the login attempt fails.
+     * @throws {Error} If the username or the password is not valid, in which case nothing is sent, or if the login
+     *   attempt fails.
      *
      * @remarks
      * If the device is already logged in, the next login attempt will fail unless the user logs out first.
      */
     loginToSmmForSoftwareUpdate(deviceRef, username, password, commandTimeout = 10000, responsePollingInterval = 500) {
-        const command = (0, os_command_1.createSmmAcyclicHandlerOsCommand)(os_command_1.SmmAcyclicHandlerSubcommandId.SOFTWARE_UPDATE_LOGIN);
-        const content = (0, smm_1.packSmmCredentials)(username, password);
-        // @ts-ignore
-        return this.runOsCommandAndWriteFsBuffer(deviceRef, command, content, commandTimeout, responsePollingInterval).pipe((0, operators_1.last)(), (0, operators_1.map)((response) => {
+        return (0, rxjs_1.defer)(() => {
+            (0, smm_1.assertValidSmmCredential)(username, 'Username', smm_1.SMM_USERNAME_MIN_LENGTH);
+            (0, smm_1.assertValidSmmCredential)(password, 'Password');
+            const command = (0, os_command_1.createSmmAcyclicHandlerOsCommand)(os_command_1.SmmAcyclicHandlerSubcommandId.SOFTWARE_UPDATE_LOGIN);
+            const content = (0, smm_1.packSmmCredentials)(username, password);
+            // @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: ${(0, os_command_1.describeOsCommandFailure)(response)}.`);
             }
@@ -3455,38 +3467,46 @@ 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.
+     * SMM accepts the change, log in for parameter download with the new password until the SMM accepts the login. The
+     * SMM is not restarted, because it does not need a restart to use a new password.
      *
-     * 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.
+     * The SMM acknowledges CHANGE_PASSWORD before it stores the new password. It writes the password to its EEPROM in the
+     * background, refuses every login while the write runs, and closes the session itself when the write is done. A
+     * restart during the write leaves a stored password that the SMM discards at boot, so neither the new nor the old
+     * password logs in and only the master password gets in again. A logout does not wait for the write either. The
+     * first login that the SMM accepts with the new password is therefore the proof that the write is done and that the
+     * SMM stored the intended password.
+     *
+     * After the call, a session for parameter download is open, logged in with the new password, so a caller can go on
+     * with SMM commands without a new login. Log out with {@link logoutFromSmm} when done.
      *
      * @param deviceRef - A reference to the target device.
+     * @param username - The name of the logged-in user, 4 to 24 printable ASCII characters, for the login with the new
+     *   password. Pass the same name the user logged in with: it tells who configured the SMM.
      * @param oldPassword - The current SMM password.
      * @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.
+     *   covers the FoE write of the fs-buffer, because the buffer is written before the command is issued. Defaults to
+     *   12000: the drive gives up on the SMM after 10 s, so do not set it lower. If it runs out, the result of the change
+     *   is unknown. Do not retry after a timeout, because the SMM may still be running the change.
      * @param responsePollingInterval - The interval in milliseconds between polling for the response.
-     * @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.
+     * @param verifyTimeout - How long to keep trying the login with the new password, in milliseconds, counted from the
+     *   accepted change. Defaults to 10000.
+     * @param verifyInterval - The pause in milliseconds between two login attempts with the new password. Defaults to
+     *   500.
+     *
+     * @throws {Error} If the username is not 4, or a password not 1 (old) or 4 (new), to 24 printable ASCII characters
+     *   (nothing is sent then), if the SMM rejects the change (the session then stays open), or if the SMM does not
+     *   accept a login with the new password within `verifyTimeout`.
      *
      * @remarks
-     * 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.
+     * Completion means the SMM accepted a login with the new password, so the new password is stored.
+     *
+     * When the SMM does not accept the new password within `verifyTimeout`, the stored password is unknown. Do not run
+     * the change again. Try to log in with the new password, then with the old one.
+     *
+     * Do not restart the SMM, and do not power the device off, until the call completes. Either one during the write
+     * leaves a stored password that the SMM discards.
      *
      * Rules a caller has to follow, because the SMM and the drive do not enforce them for you:
      *
@@ -3498,28 +3518,32 @@ class MotionMasterReqResClient {
      * - 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 = 12000, responsePollingInterval = 500, triggerRestart = true, rebootDelay = 3000) {
+    changeSmmPassword(deviceRef, username, oldPassword, newPassword, commandTimeout = 12000, responsePollingInterval = 500, verifyTimeout = 10000, verifyInterval = 500) {
         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);
+            (0, smm_1.assertValidSmmCredential)(username, 'Username', smm_1.SMM_USERNAME_MIN_LENGTH);
+            (0, smm_1.assertValidSmmCredential)(oldPassword, 'Old password');
+            (0, smm_1.assertValidSmmCredential)(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$;
+                throw new Error(`Changing SMM password failed: ${(0, os_command_1.describeOsCommandFailure)(response)}. The password was not changed.`);
             }
-            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)));
+            // The SMM acknowledges the change before it writes the password to its EEPROM, and refuses logins until the
+            // write is done. A restart during the write makes the SMM discard the stored password (issue #185), so the
+            // first accepted login with the new password is what ends the write, not a logout or a delay. That login's
+            // session stays open for the caller.
+            const deadline = Date.now() + verifyTimeout;
+            return (0, rxjs_1.defer)(() => this.loginToSmmForParameterDownload(deviceRef, username, newPassword, undefined, responsePollingInterval)).pipe((0, operators_1.retry)({
+                delay: (err) => Date.now() + verifyInterval < deadline
+                    ? (0, rxjs_1.timer)(verifyInterval)
+                    : (0, rxjs_1.throwError)(() => {
+                        var _a;
+                        return new Error(`The SMM accepted the password change, but did not accept a login with the new password within ${verifyTimeout} ms, so the stored password is unknown. Do not change the password again; try to log in with the new password, then with the old one. ${(_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.last)(null, undefined), (0, operators_1.map)(() => undefined));
     }
     /**