motion-master-client 0.0.423 → 0.0.425

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.`);
+                throw new Error(`Changing SMM password failed: ${(0, os_command_1.describeOsCommandFailure)(response)}. The password was not changed.`);
             }
-            // 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)));
+            // 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));
     }
     /**
@@ -4361,15 +4385,85 @@ class MotionMasterReqResClient {
      * It sends a series of commands to the device to read the registers and returns the responses as an array.
      * It was added as part of a fix for the EEPROM issue in Circulo integrated encoders.
      *
+     * A register read completes on the drive within a few tens of milliseconds, so the response is polled every
+     * 50 ms rather than at the 1000 ms default for OS commands. The first poll usually comes before the read has
+     * completed; at 1000 ms each of those reads then waits a full second, and the 33 registers take about 30 s
+     * instead of 1 to 2 s (measured on a Circulo 7 Safe Motion).
+     *
+     * The registers are read through the encoder configured in 0x2110 (encoder 1) or 0x2112 (encoder 2). When its
+     * sensor port (subindex 1) is 0, no encoder is configured: no OS command is sent, and the observable fails at
+     * once. Otherwise the firmware times out each read after 5 s and then refuses further OS commands.
+     *
      * @param deviceRef - The reference to the device to which the command will be sent.
      * @param encoderOrdinal - The ordinal number of the encoder.
      * @param commandTimeout - The timeout in milliseconds for the command to complete.
+     * @param responsePollingInterval - How often, in milliseconds, the response of each register read is polled.
      * @returns An observable that emits an array of `EncoderRegisterCommunicationOsCommandResponse` objects.
+     * @throws Error when the encoder is not configured.
      */
-    readCirculoIntegratedEncoderKeyConfigurationRegisters(deviceRef, encoderOrdinal, commandTimeout = 5000) {
+    readCirculoIntegratedEncoderKeyConfigurationRegisters(deviceRef, encoderOrdinal, commandTimeout = 5000, responsePollingInterval = 50) {
         const registerAddresses = circulo_1.circuloIntegratedEncoderKeyConfigurationRegisterAddresses.map((addr) => addr.ram);
-        const defferedOsCommands = registerAddresses.map((registerAddress) => (0, rxjs_1.defer)(() => this.runEncoderRegisterCommunicationOsCommand(deviceRef, encoderOrdinal, 0, 0, registerAddress, undefined, commandTimeout).pipe((0, operators_1.last)())));
-        return (0, rxjs_1.concat)(...defferedOsCommands).pipe((0, operators_1.toArray)());
+        const defferedOsCommands = registerAddresses.map((registerAddress) => (0, rxjs_1.defer)(() => this.runEncoderRegisterCommunicationOsCommand(deviceRef, encoderOrdinal, 0, 0, registerAddress, undefined, commandTimeout, responsePollingInterval).pipe((0, operators_1.last)())));
+        const configurationIndex = { 1: 0x2110, 2: 0x2112 }[encoderOrdinal];
+        if (configurationIndex === undefined) {
+            return (0, rxjs_1.concat)(...defferedOsCommands).pipe((0, operators_1.toArray)());
+        }
+        return (0, rxjs_1.defer)(() => this.upload(deviceRef, configurationIndex, 1)).pipe((0, operators_1.mergeMap)((sensorPort) => {
+            if (sensorPort === 0) {
+                const index = `0x${configurationIndex.toString(16).toUpperCase()}`;
+                return (0, rxjs_1.throwError)(() => new Error(`Encoder ${encoderOrdinal} is not configured: its sensor port (${index}:01) is 0. Configure the ` +
+                    'integrated encoder before reading its registers.'));
+            }
+            return (0, rxjs_1.concat)(...defferedOsCommands).pipe((0, operators_1.toArray)());
+        }));
+    }
+    /**
+     * Reads the key configuration registers of a Circulo integrated encoder, `HARD_REV` (register 0x74) and the
+     * amplitude control gain (registers 0x2B and 0x2F), and builds its report: the chip revision, health monitoring,
+     * the Nonius track offset table and every register with the raw values of its fields. See
+     * {@link buildCirculoIntegratedEncoderReport}.
+     *
+     * The device serial number is resolved alongside; when it can't be, the report says it is unknown.
+     *
+     * @param deviceRef - The reference to the device.
+     * @param encoderOrdinal - The ordinal number of the encoder, 1 or 2.
+     * @param commandTimeout - The timeout in milliseconds for each register read.
+     * @param responsePollingInterval - How often, in milliseconds, the response of each register read is polled.
+     * @returns An observable that emits the report and completes.
+     * @throws Error when a register read returns no value, so the report never shows a value it didn't read.
+     */
+    getCirculoIntegratedEncoderReport(deviceRef, encoderOrdinal, commandTimeout = 5000, responsePollingInterval = 50) {
+        const valueOf = (response, ram) => {
+            if (response.registerValue === undefined) {
+                const reason = [response.request, response.errorCode, response.errorName, response.errorDescription]
+                    .filter((part) => part !== undefined && part !== '')
+                    .join(', ');
+                throw new Error(`Register 0x${ram.toString(16).padStart(2, '0')} returned no value (${reason}).`);
+            }
+            return response.registerValue;
+        };
+        const readRegister = (ram) => (0, rxjs_1.defer)(() => this.runEncoderRegisterCommunicationOsCommand(deviceRef, encoderOrdinal, 0, 0, ram, undefined, commandTimeout, responsePollingInterval).pipe((0, operators_1.last)()));
+        const extraRegisters = [
+            circulo_1.icMuHardRevRegister,
+            ...circulo_1.circuloIntegratedEncoderAmplitudeControlRegisters.map((r) => r.ram),
+        ];
+        const deviceSerialNumber$ = this.resolveDevice(deviceRef).pipe((0, operators_1.map)((device) => device.id), (0, operators_1.catchError)(() => (0, rxjs_1.of)(undefined)));
+        // The OS command channel runs one command at a time, so HARD_REV and the amplitude control registers are read
+        // after the key configuration registers, not alongside.
+        return (0, rxjs_1.forkJoin)([
+            (0, rxjs_1.concat)(this.readCirculoIntegratedEncoderKeyConfigurationRegisters(deviceRef, encoderOrdinal, commandTimeout, responsePollingInterval), (0, rxjs_1.concat)(...extraRegisters.map(readRegister)).pipe((0, operators_1.toArray)())).pipe((0, operators_1.toArray)()),
+            deviceSerialNumber$,
+        ]).pipe((0, operators_1.map)(([[responses, extraResponses], deviceSerialNumber]) => {
+            const values = responses.map((response, i) => valueOf(response, circulo_1.circuloIntegratedEncoderKeyConfigurationRegisterAddresses[i].ram));
+            const [hardRev, ...amplitudeControlValues] = extraResponses.map((response, i) => valueOf(response, extraRegisters[i]));
+            return (0, circulo_1.buildCirculoIntegratedEncoderReport)(values, {
+                encoderOrdinal,
+                deviceSerialNumber,
+                readAt: new Date(),
+                hardRev,
+                amplitudeControlValues,
+            });
+        }));
     }
     /**
      * Writes the integrated encoder configuration to a binary file on the device.
@@ -5019,7 +5113,9 @@ class MotionMasterReqResClient {
                         },
                         commutationOffsetMeasurement: {
                             execute: () => tslib_1.__awaiter(this, void 0, void 0, function* () {
-                                measurementMethod === 2 ? yield this.engageBrake(deviceRef, brakeEngageWaitMs) : yield this.releaseBrake(deviceRef, brakeReleaseWaitMs);
+                                measurementMethod === 2
+                                    ? yield this.engageBrake(deviceRef, brakeEngageWaitMs)
+                                    : yield this.releaseBrake(deviceRef, brakeReleaseWaitMs);
                                 return yield (0, rxjs_1.lastValueFrom)(this.runCommutationOffsetMeasurementOsCommand(deviceRef));
                             }),
                             valueKey: 'commutationAngleOffset',