motion-master-client 0.0.287 → 0.0.289

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "motion-master-client",
-  "version": "0.0.287",
+  "version": "0.0.289",
   "type": "commonjs",
   "description": "A library and CLI program used for communicating with Motion Master.",
   "dependencies": {
@@ -9,6 +9,7 @@
     "commander": "^11.1.0",
     "cors": "^2.8.5",
     "debug": "^4.3.5",
+    "ecatmod": "^2.2.6",
     "express": "^4.19.2",
     "fast-deep-equal": "^3.1.3",
     "js-untar": "^2.0.0",

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 } 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 } 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 } from './os-command';
 import { IntegroVariant } from './integro-variant';
@@ -847,11 +847,29 @@ export declare class MotionMasterReqResClient {
     resolveDeviceParameterTypeValueKey(deviceRefObj: DeviceRefObj, index: number, subindex: number, typeValueKey?: ParameterTypeValueKey): Observable<ParameterTypeValueKey>;
     resolveDeviceParameterInfoMap(deviceRef: DeviceRef | DeviceRefObj, requestTimeout?: number): Observable<Map<string, DeviceParameterInfo>>;
     /**
-     * Get device parameters.
+     * Retrieves and constructs device parameters with optional ESI (EtherCAT Slave Information) extensions.
+     *
+     * This method resolves the target device, optionally loads and parses an ESI XML file,
+     * gathers device parameter metadata, and then fetches the actual parameter values.
+     * Optionally includes progress updates during value retrieval.
+     *
+     * @param props - An object containing the following properties:
+     * - `deviceId` or other identifying fields from `DeviceRefObj` to resolve the device.
+     * - `loadFromCache` (optional): Whether read from the device or from the cache in Motion Master.
+     * - `sendProgress` (optional): Whether to emit progress updates during parameter value retrieval.
+     * - `extendWithEsi` (optional): If true, attempts to load and parse the ESI XML file to enrich parameters with metadata.
+     * @param requestTimeout - Timeout in milliseconds to apply to the device parameter value retrieval. Defaults to 30,000 ms.
+     *
+     * @returns An Observable emitting an object containing:
+     * - `parameters`: An array of fully built `DeviceParameter` objects.
+     * - `progress`: A percentage (0–100) representing retrieval progress if `sendProgress` is enabled, otherwise 100.
+     *
+     * @throws An error if device parameter values could not be retrieved or are empty.
      */
     getDeviceParameters(props: {
         loadFromCache?: boolean;
         sendProgress?: boolean;
+        extendWithEsi?: boolean;
     } & DeviceRefObj, requestTimeout?: number): Observable<{
         parameters: DeviceParameter[];
         progress: number;
@@ -904,6 +922,37 @@ export declare class MotionMasterReqResClient {
      * Get the system log content and parse it into an array of lines, where each line contains the date, uptime, ID, file, level, and message.
      */
     getSystemLogLines(requestTimeout?: number, messageId?: string): Observable<SystemLogLine[]>;
+    /**
+     * Retrieves the UI configuration from the device's `ui.config.json` file.
+     *
+     * @param deviceRef - Reference to the target device from which to fetch the config.
+     * @param requestTimeout - Optional timeout in milliseconds for the file retrieval request (default is 10,000 ms).
+     * @param messageId - Optional message identifier for tracking or logging purposes.
+     * @returns An Observable emitting the parsed `UiConfig` object from the device, or an empty object if the content is unavailable.
+     */
+    getUiConfig(deviceRef: DeviceRef, requestTimeout?: number, messageId?: string): Observable<UiConfig>;
+    /**
+     * Updates the UI configuration file `ui.config.json` on the device by writing the provided PDO mapping.
+     *
+     * This method retrieves the current UI configuration from the device,
+     * updates its `pdoMapping` property with the provided mapping,
+     * then serializes and writes the updated configuration back to the device file system.
+     *
+     * @param deviceRef - Reference to the target device containing the UI configuration file.
+     * @param pdoMapping - The PDO mapping object to be saved within the UI configuration.
+     * @returns An Observable that emits the status of the file write operation.
+     */
+    writePdoMappingToUiConfigFile(deviceRef: DeviceRef, pdoMapping: UiPdoMapping): Observable<DeviceFileStatus>;
+    /**
+     * Removes the PDO mapping from the UI configuration file `ui.config.json` on the device.
+     *
+     * This method fetches the existing UI configuration, deletes the `pdoMapping` property if present,
+     * then writes the updated configuration back to the device.
+     *
+     * @param deviceRef - Reference to the target device containing the UI configuration file.
+     * @returns An Observable that emits the status of the file write operation.
+     */
+    removePdoMappingFromUiConfigFile(deviceRef: DeviceRef): Observable<DeviceFileStatus>;
     /**
      * Store parameters.
      *

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

@@ -27,6 +27,7 @@ const smm_1 = require("./smm");
 const firmware_1 = require("./firmware");
 const fetch_1 = require("./fetch");
 const circulo_1 = require("./circulo");
+const { xmlToEsi } = require('ecatmod');
 /**
  * This class contains methods for making requests to Motion Master using the injected request/response socket.
  *
@@ -1606,13 +1607,34 @@ class MotionMasterReqResClient {
         }));
     }
     /**
-     * Get device parameters.
+     * Retrieves and constructs device parameters with optional ESI (EtherCAT Slave Information) extensions.
+     *
+     * This method resolves the target device, optionally loads and parses an ESI XML file,
+     * gathers device parameter metadata, and then fetches the actual parameter values.
+     * Optionally includes progress updates during value retrieval.
+     *
+     * @param props - An object containing the following properties:
+     * - `deviceId` or other identifying fields from `DeviceRefObj` to resolve the device.
+     * - `loadFromCache` (optional): Whether read from the device or from the cache in Motion Master.
+     * - `sendProgress` (optional): Whether to emit progress updates during parameter value retrieval.
+     * - `extendWithEsi` (optional): If true, attempts to load and parse the ESI XML file to enrich parameters with metadata.
+     * @param requestTimeout - Timeout in milliseconds to apply to the device parameter value retrieval. Defaults to 30,000 ms.
+     *
+     * @returns An Observable emitting an object containing:
+     * - `parameters`: An array of fully built `DeviceParameter` objects.
+     * - `progress`: A percentage (0–100) representing retrieval progress if `sendProgress` is enabled, otherwise 100.
+     *
+     * @throws An error if device parameter values could not be retrieved or are empty.
      */
     getDeviceParameters(props, requestTimeout = 30000) {
+        const { loadFromCache, sendProgress, extendWithEsi } = props;
         return this.resolveDevice(props).pipe((0, operators_1.mergeMap)((device) => {
-            return this.getDeviceParameterInfo({ deviceAddress: device.deviceAddress }, requestTimeout).pipe((0, operators_1.mergeMap)((deviceParameterInfoStatus) => {
+            return (0, rxjs_1.concat)(extendWithEsi ? this.upload(device.deviceAddress, 0x1018, 0x02) : (0, rxjs_1.of)(undefined), // productCode
+            extendWithEsi ? this.getFile(device.deviceAddress, 'SOMANET_CiA_402.xml') : (0, rxjs_1.of)(undefined), // esiFileContent
+            this.getDeviceParameterInfo({ deviceAddress: device.deviceAddress }, 5000) // deviceParameterInfoStatus
+            ).pipe((0, operators_1.toArray)(), (0, operators_1.mergeMap)((results) => {
                 var _a;
-                const { loadFromCache, sendProgress } = props;
+                const [productCode, esiFileContent, deviceParameterInfoStatus] = results;
                 const parameters = (_a = deviceParameterInfoStatus.parameters) === null || _a === void 0 ? void 0 : _a.map((p) => {
                     var _a, _b;
                     return ({
@@ -1621,6 +1643,11 @@ class MotionMasterReqResClient {
                         loadFromCache,
                     });
                 });
+                let esi = undefined;
+                if (esiFileContent instanceof Uint8Array) {
+                    const xml = new TextDecoder('utf-8').decode(esiFileContent);
+                    esi = xmlToEsi(xml);
+                }
                 return this.getDeviceParameterValues({ deviceAddress: device.deviceAddress, sendProgress, parameters }, requestTimeout).pipe((0, operators_1.map)((deviceParameterValuesStatus) => {
                     var _a, _b;
                     if (!deviceParameterValuesStatus.parameterValues) {
@@ -1631,8 +1658,13 @@ class MotionMasterReqResClient {
                         const index = (_a = value.index) !== null && _a !== void 0 ? _a : 0;
                         const subindex = (_b = value.subindex) !== null && _b !== void 0 ? _b : 0;
                         const id = (0, device_parameter_1.makeDeviceParameterId)(device.id, index, subindex);
-                        return Object.assign(Object.assign(Object.assign({ id }, value), (_c = deviceParameterInfoStatus.parameters) === null || _c === void 0 ? void 0 : _c[i]), { index,
+                        let deviceParameter = Object.assign(Object.assign(Object.assign({ id }, value), (_c = deviceParameterInfoStatus.parameters) === null || _c === void 0 ? void 0 : _c[i]), { index,
                             subindex, value: (0, parameter_1.getParameterValue)(value) });
+                        let esiExtension = {};
+                        if (esi) {
+                            esiExtension = (0, parameter_1.getParameterEsiExtension)(deviceParameter, esi === null || esi === void 0 ? void 0 : esi.value, productCode);
+                        }
+                        return Object.assign(Object.assign({}, deviceParameter), esiExtension);
                     });
                     const progress = sendProgress ? (_b = (_a = deviceParameterValuesStatus === null || deviceParameterValuesStatus === void 0 ? void 0 : deviceParameterValuesStatus.progress) === null || _a === void 0 ? void 0 : _a.percentage) !== null && _b !== void 0 ? _b : 0 : 100;
                     return { parameters: deviceParameters, progress };
@@ -1740,6 +1772,64 @@ class MotionMasterReqResClient {
     getSystemLogLines(requestTimeout = 5000, messageId) {
         return this.getSystemLog(requestTimeout, messageId).pipe((0, operators_1.map)((systemLog) => { var _a; return (0, util_1.parseSystemLogContent)((_a = systemLog.content) !== null && _a !== void 0 ? _a : ''); }));
     }
+    /**
+     * Retrieves the UI configuration from the device's `ui.config.json` file.
+     *
+     * @param deviceRef - Reference to the target device from which to fetch the config.
+     * @param requestTimeout - Optional timeout in milliseconds for the file retrieval request (default is 10,000 ms).
+     * @param messageId - Optional message identifier for tracking or logging purposes.
+     * @returns An Observable emitting the parsed `UiConfig` object from the device, or an empty object if the content is unavailable.
+     */
+    getUiConfig(deviceRef, requestTimeout = 10000, messageId) {
+        return this.getFile(deviceRef, 'ui.config.json', requestTimeout, messageId).pipe((0, operators_1.map)((content) => {
+            if (content) {
+                const buffer = buffer_1.Buffer.from(content);
+                const text = (0, util_1.decodeTextContent)(buffer);
+                return JSON.parse(text);
+            }
+            else {
+                return {};
+            }
+        }));
+    }
+    /**
+     * Updates the UI configuration file `ui.config.json` on the device by writing the provided PDO mapping.
+     *
+     * This method retrieves the current UI configuration from the device,
+     * updates its `pdoMapping` property with the provided mapping,
+     * then serializes and writes the updated configuration back to the device file system.
+     *
+     * @param deviceRef - Reference to the target device containing the UI configuration file.
+     * @param pdoMapping - The PDO mapping object to be saved within the UI configuration.
+     * @returns An Observable that emits the status of the file write operation.
+     */
+    writePdoMappingToUiConfigFile(deviceRef, pdoMapping) {
+        return this.getUiConfig(deviceRef).pipe((0, operators_1.mergeMap)((uiConfig) => {
+            uiConfig.pdoMapping = pdoMapping;
+            const jsonString = JSON.stringify(uiConfig);
+            const content = new TextEncoder().encode(jsonString);
+            return this.setFile(deviceRef, 'ui.config.json', content, true, 10000);
+        }));
+    }
+    /**
+     * Removes the PDO mapping from the UI configuration file `ui.config.json` on the device.
+     *
+     * This method fetches the existing UI configuration, deletes the `pdoMapping` property if present,
+     * then writes the updated configuration back to the device.
+     *
+     * @param deviceRef - Reference to the target device containing the UI configuration file.
+     * @returns An Observable that emits the status of the file write operation.
+     */
+    removePdoMappingFromUiConfigFile(deviceRef) {
+        return this.getUiConfig(deviceRef).pipe((0, operators_1.mergeMap)((uiConfig) => {
+            if ('pdoMapping' in uiConfig) {
+                delete uiConfig.pdoMapping;
+            }
+            const jsonString = JSON.stringify(uiConfig);
+            const content = new TextEncoder().encode(jsonString);
+            return this.setFile(deviceRef, 'ui.config.json', content, true, 10000);
+        }));
+    }
     /**
      * Store parameters.
      *