motion-master-client 0.0.422 → 0.0.423

package/src/lib/motion-master-req-res-client.d.ts

@@ -6,7 +6,7 @@ import { HardwareDescription, StackInfo } from './hardware-description';
 import { MotionMasterReqResSocket } from './motion-master-req-res-socket';
 import { UIFeaturesConfig } from './parameter';
 import { SystemLogLine } from './system-log-line';
-import { MotionMasterMessage, ParameterValueType, ParameterTypeValue, DeviceParameterValuesStatus, ParameterTypeValueKey, DeviceRefObj, DeviceRef, FullAutoTuningStatus, SystemVersionStatus, DeviceInfoStatus, DeviceParameterInfoStatus, GetDeviceParameterInfoRequest, GetDeviceParameterValuesRequest, GetMultiDeviceParameterValuesRequest, MultiDeviceParameterValuesStatus, SetDeviceParameterValuesRequest, SetMultiDeviceParameterValuesRequest, GetDeviceFileListRequest, DeviceFileListStatus, GetDeviceFileRequest, DeviceFileStatus, SetDeviceFileRequest, DeleteDeviceFileRequest, ResetDeviceFaultRequest, DeviceFaultResetStatus, StopDeviceRequest, DeviceStopStatus, StartDeviceFirmwareInstallationRequest, DeviceFirmwareInstallationStatus, GetDeviceLogRequest, DeviceLogStatus, StartCoggingTorqueRecordingRequest, CoggingTorqueRecordingStatus, GetCoggingTorqueDataRequest, CoggingTorqueDataStatus, StartOffsetDetectionRequest, OffsetDetectionStatus, StartPlantModelIdentificationRequest, PlantIdentificationStatus, ComputeAutoTuningGainsRequest, AutoTuningStatus, SetMotionControllerParametersRequest, MotionControllerStatus, EnableMotionControllerRequest, SetSignalGeneratorParametersRequest, SignalGeneratorStatus, StopSignalGeneratorRequest, StartMonitoringDeviceParameterValuesRequest, MonitoringParameterValuesStatus, StopMonitoringDeviceParameterValuesRequest, GetEthercatNetworkStateRequest, EthercatNetworkStateStatus, SetEthercatNetworkStateRequest, StartNarrowAngleCalibrationRequest, NarrowAngleCalibrationStatus, SetSystemClientTimeoutRequest, StartSystemIdentificationRequest, SystemIdentificationStatus, CirculoEncoderMagnetDistanceStatus, StartCirculoEncoderNarrowAngleCalibrationProcedureRequest, CirculoEncoderNarrowAngleCalibrationProcedureStatus, GetDeviceCiA402StateRequest, DeviceCiA402StateStatus, SetDeviceCiA402StateRequest, SystemLogStatus, StartDeviceSiiRestoreRequest, DeviceSiiRestoreStatus, StartOpenLoopFieldControlRequest, OpenLoopFieldControlStatus, ComputeFullAutoTuningGainsRequest, StartFullAutoTuningRequest, StopFullAutoTuningRequest, StartCirculoEncoderConfigurationRequest, CirculoEncoderConfigurationStatus, StopCirculoEncoderNarrowAngleCalibrationProcedureRequest, StartOsCommandRequest, OsCommandStatus, RestoreDefaultParametersType, DeviceParameterAddressValue, DeviceParameterIds, DeviceParameterInfo, RequestStatusMessage, UiPdoMapping, UiConfig, ExecuteForwardCallRequest, ForwardCallStatus, PlantModel, NotchFilter, LoadConfigStrategy, SystemInformationStatus, SetPdoModeRequest, PdoModeStatus, GetDeviceSiiRequest, DeviceSiiStatus, SmmAutomatedUpdate } from './types';
+import { MotionMasterMessage, ParameterValueType, ParameterTypeValue, DeviceParameterValuesStatus, ParameterTypeValueKey, DeviceRefObj, DeviceRef, FullAutoTuningStatus, SystemVersionStatus, DeviceInfoStatus, DeviceParameterInfoStatus, GetDeviceParameterInfoRequest, GetDeviceParameterValuesRequest, GetMultiDeviceParameterValuesRequest, MultiDeviceParameterValuesStatus, SetDeviceParameterValuesRequest, SetMultiDeviceParameterValuesRequest, GetDeviceFileListRequest, DeviceFileListStatus, GetDeviceFileRequest, DeviceFileStatus, SetDeviceFileRequest, DeleteDeviceFileRequest, ResetDeviceFaultRequest, DeviceFaultResetStatus, StopDeviceRequest, DeviceStopStatus, StartDeviceFirmwareInstallationRequest, DeviceFirmwareInstallationStatus, GetDeviceLogRequest, DeviceLogStatus, StartCoggingTorqueRecordingRequest, CoggingTorqueRecordingStatus, GetCoggingTorqueDataRequest, CoggingTorqueDataStatus, StartOffsetDetectionRequest, OffsetDetectionStatus, StartPlantModelIdentificationRequest, PlantIdentificationStatus, ComputeAutoTuningGainsRequest, AutoTuningStatus, SetMotionControllerParametersRequest, MotionControllerStatus, EnableMotionControllerRequest, SetSignalGeneratorParametersRequest, SignalGeneratorStatus, StopSignalGeneratorRequest, StartMonitoringDeviceParameterValuesRequest, MonitoringParameterValuesStatus, StopMonitoringDeviceParameterValuesRequest, GetEthercatNetworkStateRequest, EthercatNetworkStateStatus, SetEthercatNetworkStateRequest, StartNarrowAngleCalibrationRequest, NarrowAngleCalibrationStatus, SetSystemClientTimeoutRequest, StartSystemIdentificationRequest, SystemIdentificationStatus, CirculoEncoderMagnetDistanceStatus, StartCirculoEncoderNarrowAngleCalibrationProcedureRequest, CirculoEncoderNarrowAngleCalibrationProcedureStatus, GetDeviceCiA402StateRequest, DeviceCiA402StateStatus, SetDeviceCiA402StateRequest, SystemLogStatus, StartDeviceSiiRestoreRequest, DeviceSiiRestoreStatus, StartOpenLoopFieldControlRequest, OpenLoopFieldControlStatus, ComputeFullAutoTuningGainsRequest, StartFullAutoTuningRequest, StopFullAutoTuningRequest, StartCirculoEncoderConfigurationRequest, CirculoEncoderConfigurationStatus, StopCirculoEncoderNarrowAngleCalibrationProcedureRequest, StartOsCommandRequest, OsCommandStatus, RestoreDefaultParametersType, DeviceParameterAddressValue, DeviceParameterIds, DeviceParameterInfo, RequestStatusMessage, UiPdoMapping, UiConfig, ExecuteForwardCallRequest, ForwardCallStatus, PlantModel, NotchFilter, LoadConfigStrategy, SystemInformationStatus, SetPdoModeRequest, PdoModeStatus, GetDeviceSiiRequest, DeviceSiiStatus, SmmAutomatedUpdate, SmmAutomatedUpdateProgress, SmmSoftwareUpdateProgress } from './types';
 import { Cia402State, ModesOfOperation } from './cia402';
 import { EncoderRegisterCommunicationOsCommandResponse, MotorPhaseOrderDetectionOsCommandResponse, OpenPhaseDetectionOsCommandResponse, OsCommandMode, OsCommandResponse, PhaseResistanceMeasurementOsCommandResponse, PhaseInductanceMeasurementOsCommandResponse, PolePairDetectionOsCommandResponse, CommutationOffsetMeasurementOsCommandResponse, IcMuCalibrationModeOsCommandResponse, OpenLoopFieldModeOsCommandResponse, HrdStreamingOsCommandResponse, TorqueConstantMeasurementOsCommandResponse, SkippedCyclesCounterOsCommandResponse, IgnoreBissStatusBitsOsCommandResponse, SystemIdentificationOsCommandResponse, KublerEncoderCommandOsCommandResponse, UseInternalEncoderVelocityOsCommandResponse, KublerEncoderRegisterCommunicationOsCommandResponse, SmmAcyclicHandlerOsCommandResponse, HrdStreamingOsCommandAction, HrdStreamingOsCommandDataIndex, SmmAcyclicHandlerLoadParametersForVerificationOsCommandResponse, ChirpSignalOptions, OsCommandAbortResult } from './os-command';
 import { IntegroVariant } from './integro-variant';
@@ -238,9 +238,25 @@ export declare class MotionMasterReqResClient {
      *
      * If the requested file content is empty, Motion Master will return a not found error. This is subject to change now that Motion Master reads the file error codes.
      *
-     * SOMANET_CiA_402.xml and SOMANET_CiA_402.xml.zip files are stored in IndexedDB for faster access.
+     * The ESI file ("SOMANET_CiA_402.xml" or "SOMANET_CiA_402.xml.zip") is never read from the device, see {@link getEsiFromIndexedDB}.
      */
     getDeviceFile(props: GetDeviceFileRequest, requestTimeout: number, messageId?: string): Observable<DeviceFileStatus>;
+    /**
+     * Returns the ESI file cached in IndexedDB under the firmware version the device reports in 0x100A:00.
+     *
+     * The ESI file is never read from the device. Firmware installation no longer writes it to the device (see
+     * {@link installFirmwareAndCacheEsi}), and Motion Master does not remove a skipped file, so the file on the device may
+     * belong to an older firmware. Neither the file nor its ESI revision tells which firmware it belongs to.
+     * Caching it under the installed version would hide the correct ESI file for good.
+     *
+     * The ESI file gets into IndexedDB only from a firmware package: at firmware installation, see
+     * {@link cacheEsiFromFirmwarePackage}, or when a user loads it from a package in OBLAC Drives.
+     *
+     * Returns a failed status with the NOT_FOUND error code when the ESI file is not cached for the installed firmware,
+     * or when there is no IndexedDB, as outside the browser. Returns a failed status with the FAILED error code when the
+     * firmware version or IndexedDB can't be read.
+     */
+    private getEsiFromIndexedDB;
     private getDeviceFileUsingResolvedDeviceAddress;
     /**
      * Fixing a production screw-up that affects a very important customer. Added on February 29th, 2024.
@@ -315,8 +331,7 @@ export declare class MotionMasterReqResClient {
      * Extracts the ESI file (SOMANET_CiA_402.xml) from a firmware package and stores its unzipped content in
      * IndexedDB, keyed by the given firmware version.
      *
-     * This is the install-time counterpart to the read-time caching in {@link getDeviceFile}: once the ESI is
-     * cached here, OBLAC can resolve it from IndexedDB without reading it back from the drive. This is what
+     * IndexedDB is the only source of the ESI file: {@link getDeviceFile} never reads it from the drive. This is what
      * allows the ESI file (SOMANET_CiA_402.xml.zip) to be skipped during firmware installation, which avoids
      * slow and unreliable FoE transfers and works around devices (e.g. NetX) that reject writing that file.
      *
@@ -337,17 +352,18 @@ export declare class MotionMasterReqResClient {
      *   user-overridable: when `props.skipFiles` is provided it is passed through unchanged, so a caller can choose to
      *   still write the ESI by omitting it from that list.
      * - Extracts the ESI from the package and stores it in IndexedDB keyed by firmware version (see
-     *   {@link cacheEsiFromFirmwarePackage}) *before* the installation starts, so it can be resolved locally by
-     *   {@link getDeviceFile}. It must be cached up front because, with the ESI skipped on the drive, Motion Master
-     *   will try to read it back right after installation. This caching happens regardless of whether the ESI is
-     *   also written to the drive. A caching failure is logged but does not prevent installation.
+     *   {@link cacheEsiFromFirmwarePackage}) *before* the installation starts, so {@link getDeviceFile} can return it
+     *   as soon as the installation ends. IndexedDB is the only source of the ESI file: {@link getDeviceFile} never
+     *   reads it from the drive, even when the ESI is also written there. A caching failure is logged but does not
+     *   prevent installation; the ESI file is then not found until a user loads it from the package (Load ESI in
+     *   OBLAC Drives).
      *
      * @param firmwareVersion - The firmware version to key the cached ESI by; this must match the value reported by
      *                          the device parameter 0x100a:00 after installation, which {@link getDeviceFile} uses.
      *                          For OBLAC firmware packages this is the version encoded in the package filename, see
      *                          {@link extractFirmwareVersionFromFirmwarePackageFilename}. When it cannot be determined
      *                          (e.g. an arbitrary package with an unrecognized filename), pass an empty value to skip
-     *                          caching; the read path then falls back to the online source.
+     *                          caching; the ESI file is then not found unless it was cached before.
      */
     installFirmwareAndCacheEsi(firmwareVersion: string | undefined, props: StartDeviceFirmwareInstallationRequest, requestTimeout: number, messageId?: string): Observable<DeviceFirmwareInstallationStatus>;
     /**
@@ -1871,6 +1887,34 @@ export declare class MotionMasterReqResClient {
      * The commands execute only when subscribed to, ensuring a strict sequence.
      */
     updateSmmSoftware(deviceRef: DeviceRef, username: string, password: string, buffer: Uint8Array, crc: number, chunkSize?: number, commandTimeout?: number, responsePollingInterval?: number, fsBufferReadWriteTimeout?: number): Observable<void>;
+    /**
+     * Performs a complete SMM software update like {@link updateSmmSoftware}, reporting progress as it goes.
+     *
+     * A {@link SmmSoftwareUpdateProgress} value is emitted when each stage starts, once per transmitted chunk,
+     * and a final `done` value after the SMM restart has been triggered. Use it to show the user what the
+     * update is doing; transmitting a large software file can take many minutes.
+     *
+     * Parameters are the same as for {@link updateSmmSoftware}.
+     *
+     * @throws {Error} If `buffer` is empty or `chunkSize` is not a positive integer. Nothing is sent to the device then.
+     * @throws {Error} If any step in the software update process fails.
+     */
+    updateSmmSoftwareWithProgress(deviceRef: DeviceRef, username: string, password: string, buffer: Uint8Array, crc: number, chunkSize?: number, commandTimeout?: number, responsePollingInterval?: number, fsBufferReadWriteTimeout?: number): Observable<SmmSoftwareUpdateProgress>;
+    /**
+     * Waits until the SMM reports the expected software version.
+     *
+     * After an SMM software update the SMM restarts and boots the new software, which can take around 30 s.
+     * Reads may fail or return the previous version during that time, so the version is polled until it
+     * matches or the timeout expires.
+     *
+     * @param deviceRef - Reference to the target device.
+     * @param expectedVersion - The expected SMM software version, bitwise encoded (e.g. 25344 for v99.0).
+     * @param timeout - (Optional) How long to wait, in ms. Defaults to 90,000 ms.
+     * @param pollingInterval - (Optional) Delay between reads, in ms. Defaults to 2000 ms.
+     *
+     * @throws {Error} If the SMM does not report the expected version within `timeout`.
+     */
+    waitForSmmFirmwareVersion(deviceRef: DeviceRef, expectedVersion: number, timeout?: number, pollingInterval?: number): Observable<void>;
     /**
      * Resolves whether an automated SMM software update is allowed for the specified device.
      *
@@ -1881,7 +1925,8 @@ export declare class MotionMasterReqResClient {
      *
      * 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 device belongs to the Circulo product family (`isCirculo`). ACTILINK-JD / JD Duo devices are judged
+     *   by the underlying Circulo from their hardware description, see {@link resolveEncoderProductId}.
      * - 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`).
@@ -1896,7 +1941,7 @@ export declare class MotionMasterReqResClient {
      *
      * @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.
+     * - `isCirculo` — Whether the device is a Circulo or a Circulo-based ACTILINK-JD / JD Duo.
      * - `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).
@@ -1911,7 +1956,8 @@ export declare class MotionMasterReqResClient {
      */
     resolveSmmAutomatedUpdateConditions(deviceRef: DeviceRef, buffer: Uint8Array): Promise<SmmAutomatedUpdate>;
     /**
-     * Performs an automated, multi-step SMM software update to an encrypted firmware version on a Circulo device.
+     * Performs an automated, multi-step SMM software update to an encrypted firmware version on a Circulo device,
+     * or a Circulo-based ACTILINK-JD / JD Duo (judged by the underlying Circulo).
      *
      * Before installing the target binary, this method evaluates the device state by calling
      * {@link resolveSmmAutomatedUpdateConditions}. Based on the result, it determines which
@@ -1925,20 +1971,29 @@ export declare class MotionMasterReqResClient {
      * - **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.
+     * After each installation the SMM restarts. The next step starts only once the SMM reports the
+     * version that was just installed (see {@link waitForSmmFirmwareVersion}), so a failed or
+     * unfinished installation stops the sequence with an error instead of continuing blindly.
+     *
+     * Transfer settings that are not given are resolved from the device firmware with
+     * {@link resolveSmmSoftwareUpdateTimings}. On firmware without fs-buffer streaming (< v5.2.0),
+     * `chunkSize` is always 1000 and `commandTimeout` is at least 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 chunkSize - (Optional) Size of each data chunk transmitted per step, in bytes.
+     *                    Defaults to 1,000,000 with streaming (one command per file) and 1000 without.
+     * @param commandTimeout - (Optional) Timeout for each OS command in ms.
+     *                         Defaults to 180,000 ms with streaming and 420,000 ms without.
      * @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.
+     * @param fsBufferReadWriteTimeout - (Optional) Timeout for fs-buffer read/write operations in ms.
+     *                                   Defaults to 150,000 ms with streaming and 5000 ms without.
      *
-     * @returns An `Observable<void>` that completes when the full installation sequence finishes successfully.
+     * @returns An `Observable` of {@link SmmAutomatedUpdateProgress} that reports each step and stage,
+     *          and 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.
@@ -1946,9 +2001,9 @@ export declare class MotionMasterReqResClient {
      *                 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.
+     * @throws {Error} If any installation step fails, or the SMM does not report the installed version afterwards.
      */
-    updateSmmSoftwareToEncrypted(deviceRef: DeviceRef, username: string, password: string, buffer: Uint8Array, crc: number, chunkSize?: number, commandTimeout?: number, responsePollingInterval?: number, fsBufferReadWriteTimeout?: number): Observable<void>;
+    updateSmmSoftwareToEncrypted(deviceRef: DeviceRef, username: string, password: string, buffer: Uint8Array, crc: number, chunkSize?: number, commandTimeout?: number, responsePollingInterval?: number, fsBufferReadWriteTimeout?: number): Observable<SmmAutomatedUpdateProgress>;
     /**
      * Transmits SMM parameters to the specified device.
      *