@synapticon/motion-master-client 6.0.0-alpha.110 → 6.0.0-alpha.112

package/dist/generated/Api.d.ts

@@ -1,4 +1,4 @@
-import { AlStatusCode, AutoTuningError, AutoTuningRunRequest, AutoTuningRunResponse, AutoTuningStatus, BrakeState, CaptureSummary, Cia402Status, DcSyncStatus, DeviceDiagnostics, DeviceFile, DeviceParameter, Encoders, EscRegister, EsiParseResult, FirmwareCompatibility, FirmwarePackageName, FoeErrorCode, GameLoopHealth, HardwareDescription, HrdRecording, IntegroVariant, IntegroVariantOption, MailboxErrorCode, Monitoring, ObjectDataTypeInfo, OperationModes, OutputStageResult, ParameterCacheEntry, ParameterValue, PdoMapping, PdoMappingRequest, ProcedureListing, ProcedureRequest, ProcedureSnapshot, ProcessDataWatchdog, ProcessImageObject, SdoAbortCode, SlaveConfig, SlaveInformationInterface, UserCacheListing } from "./data-contracts.js";
+import { AlStatusCode, AutoTuningError, AutoTuningRunRequest, AutoTuningRunResponse, AutoTuningStatus, BrakeState, CaptureSummary, Cia402Status, DcSyncStatus, DeviceDiagnostics, DeviceFile, DeviceParameter, Encoders, EscRegister, EsiParseResult, FirmwareCompatibility, FirmwarePackageName, FoeErrorCode, GameLoopHealth, HardwareDescription, HrdRecording, IdentifiedPlantModel, IntegroVariant, IntegroVariantOption, MailboxErrorCode, Monitoring, ObjectDataTypeInfo, OperationModes, OutputStageResult, ParameterCacheEntry, ParameterValue, PdoMapping, PdoMappingRequest, ProcedureListing, ProcedureRequest, ProcedureSnapshot, ProcessDataWatchdog, ProcessImageObject, SdoAbortCode, SlaveConfig, SlaveInformationInterface, UserCacheListing } from "./data-contracts.js";
 import { HttpClient, RequestParams } from "./http-client.js";
 export declare class Api<SecurityDataType = unknown> extends HttpClient<SecurityDataType> {
     /**
@@ -1112,6 +1112,14 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
      * @request GET:/api/devices/{slavePosition}/variant
      */
     getDeviceIntegroVariant: (slavePosition: number, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<IntegroVariant, void>>;
+    /**
+     * @description Reads and decodes the drive's `plant_model.csv` over FoE: the transfer function from torque in Nm to velocity in rad/s that the `plant-identification` procedure fitted, and the chirp it was identified with. Controller and notch filter auto-tuning compute from this model. **A 404 is the answer for a drive that was never identified.** The file is written by the procedure and by nothing else, so its absence is a state rather than a problem. The Bode data is not in the file; it is in the result of the run that produced the model.
+     *
+     * @name GetDevicePlantModel
+     * @summary Read the plant model stored on a drive
+     * @request GET:/api/devices/{slavePosition}/plant-model
+     */
+    getDevicePlantModel: (slavePosition: number, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<IdentifiedPlantModel, void>>;
     /**
      * @description Reads the device's `.hardware_description` and `.variant`, assembles the full firmware descriptors it accepts, and compares them against the descriptor in `filename`. **A mismatch is a `200` carrying `compatible: false`**, not an error status: the client asked a question and got an answer, and the body names both descriptors so it can say which hardware the package was for. A `4xx` means the question could not be asked — the filename is not a package name, or the hardware description could not be read. **Nothing acts on the answer.** The firmware installation procedure writes whatever it is given, on purpose, so this exists to tell a user before they start.
      *
@@ -1508,6 +1516,90 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
          */
         error: string;
     }>>;
+    /**
+     * @description Commands one or more devices to INIT and then up to `target` one EtherCAT Application Layer state at a time: PRE-OP, SAFE-OP, OP. A `target` of BOOT is INIT and then BOOT. Each step blocks until every targeted device arrives or the timeout elapses, and the walk stops at the first step a device does not reach. `step` is the last state commanded, and `devices` holds the settled state of every targeted device after it, each with a `reached` flag. `ok` is true only when `step` is `target` and every device reached it. A restart drops every targeted device out of process data exchange, so a drive that was enabled is disabled, and a monitoring reports null for it until it exchanges again. The body is optional: no body restarts every discovered device to OP (8). State values are the standard AL state register encodings from ETG.1000.6: 1 (Init), 2 (PreOp), 3 (Boot), 4 (SafeOp), 8 (Op).
+     *
+     * @name RestartDevices
+     * @summary Restart devices through INIT up to an AL state
+     * @request POST:/api/devices/restart
+     */
+    restartDevices: (data?: {
+        /**
+         * 1-based slave positions to restart. Omit or pass an empty array to restart all discovered devices.
+         * @example [1,2]
+         */
+        positions?: number[];
+        /**
+         * The EtherCAT AL state to end in (ETG.1000.6 AL control register encoding): 1 = Init, 2 = PreOp, 3 = Boot, 4 = SafeOp, 8 = Op.
+         * @default 8
+         * @example 8
+         */
+        target?: 1 | 2 | 3 | 4 | 8;
+        /**
+         * Maximum time to wait for all devices, in milliseconds, for each step
+         * @default 5000
+         * @example 5000
+         */
+        timeout?: number;
+    }, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<{
+        /**
+         * True only when every targeted device reached `target`.
+         * @example true
+         */
+        ok: boolean;
+        /**
+         * The last AL state the restart commanded. It is `target` when every device arrived, and the state a device fell short of otherwise.
+         * @example 8
+         */
+        step: 1 | 2 | 3 | 4 | 8;
+        /** Settled state of each targeted device, in the order targeted. */
+        devices: {
+            /**
+             * 1-based position on the fieldbus
+             * @example 1
+             */
+            slavePosition: number;
+            /**
+             * Raw AL Status register value (ETG.1000.6 §6.4.1). Bits 3:0 encode the state; bit 4 is the error indicator.
+             * @example 2
+             */
+            alStatus: number;
+            /**
+             * Current AL state decoded from alStatus (ETG.1000.6 encoding): 1 = Init, 2 = PreOp, 3 = Boot, 4 = SafeOp, 8 = Op. 0 when the device does not answer (see `reachability`).
+             * @example 2
+             */
+            alState: 0 | 1 | 2 | 3 | 4 | 8;
+            /**
+             * True when the AL Status error indicator bit (bit 4) is set
+             * @example false
+             */
+            error: boolean;
+            /**
+             * AL Status Code register (ETG.1000.6 §6.4.1). Non-zero when error is true; identifies the error cause (e.g. 0x0014 = No valid firmware).
+             * @example 0
+             */
+            alStatusCode: number;
+            /**
+             * Whether the device answers at the station address the master gave it. `addressLost`: nothing answers at that address, but a device answers at its wire position. A reset, such as a power cycle, clears the address. Run `POST /api/scan` to command it again. `notAnswering`: nothing answers at that address or at its wire position. Check the cabling and the power. If devices were removed from the chain, run a scan. The wire position is checked by position only, so after a change to the chain the device that answers there can be a different one. When the value is not `answering`, the state of the device is unknown, and `alStatus`, `alState` and `alStatusCode` are 0.
+             * @example "answering"
+             */
+            reachability: "answering" | "addressLost" | "notAnswering";
+            /**
+             * True when this device reached `step` (error clear and alState equal to `step`).
+             * @example true
+             */
+            reached: boolean;
+        }[];
+    }, void | {
+        /** Why the driver refuses state changes */
+        error: string;
+    } | {
+        /**
+         * Human-readable error message from the driver
+         * @example "FPRD slave 1: wkc=0"
+         */
+        error: string;
+    }>>;
     /**
      * No description
      *
@@ -1817,7 +1909,7 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
      */
     deleteMonitoring: (topic: string, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<void, void>>;
     /**
-     * @description Returns one entry per cached parameter-definition file on disk, keyed by device identity (vendor, product, revision). The cache stores only the object-dictionary *definitions* (not live values), so a scan of previously-seen hardware can skip the slow SDO enumeration. Independent of the bus — works whether or not a driver is initialised.
+     * @description Returns one entry per cached parameter-definition file on disk, keyed by vendor ID, product code and firmware version (object 0x100A). A device without 0x100A is not cached. The cache stores only the object-dictionary *definitions* (not live values), so a scan of previously-seen hardware can skip the slow SDO enumeration. Independent of the bus — works whether or not a driver is initialised.
      *
      * @name ListParameterCacheEntries
      * @summary List on-disk parameter caches
@@ -1833,7 +1925,7 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
      */
     getParameterCache: (id: string, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<object, void>>;
     /**
-     * @description Removes one cached file from disk. The next scan of that hardware re-enumerates it. Useful when a vendor reused a revision across an object-dictionary change.
+     * @description Removes one cached file from disk. The next scan of that hardware re-enumerates it. Useful when a firmware changed its object dictionary and kept its version string.
      *
      * @name DeleteParameterCache
      * @summary Delete a parameter-cache file

package/dist/generated/Api.js

@@ -765,6 +765,19 @@ export class Api extends HttpClient {
         format: "json",
         ...params,
     });
+    /**
+     * @description Reads and decodes the drive's `plant_model.csv` over FoE: the transfer function from torque in Nm to velocity in rad/s that the `plant-identification` procedure fitted, and the chirp it was identified with. Controller and notch filter auto-tuning compute from this model. **A 404 is the answer for a drive that was never identified.** The file is written by the procedure and by nothing else, so its absence is a state rather than a problem. The Bode data is not in the file; it is in the result of the run that produced the model.
+     *
+     * @name GetDevicePlantModel
+     * @summary Read the plant model stored on a drive
+     * @request GET:/api/devices/{slavePosition}/plant-model
+     */
+    getDevicePlantModel = (slavePosition, params = {}) => this.request({
+        path: `/api/devices/${slavePosition}/plant-model`,
+        method: "GET",
+        format: "json",
+        ...params,
+    });
     /**
      * @description Reads the device's `.hardware_description` and `.variant`, assembles the full firmware descriptors it accepts, and compares them against the descriptor in `filename`. **A mismatch is a `200` carrying `compatible: false`**, not an error status: the client asked a question and got an answer, and the body names both descriptors so it can say which hardware the package was for. A `4xx` means the question could not be asked — the filename is not a package name, or the hardware description could not be read. **Nothing acts on the answer.** The firmware installation procedure writes whatever it is given, on purpose, so this exists to tell a user before they start.
      *
@@ -1029,6 +1042,21 @@ export class Api extends HttpClient {
         format: "json",
         ...params,
     });
+    /**
+     * @description Commands one or more devices to INIT and then up to `target` one EtherCAT Application Layer state at a time: PRE-OP, SAFE-OP, OP. A `target` of BOOT is INIT and then BOOT. Each step blocks until every targeted device arrives or the timeout elapses, and the walk stops at the first step a device does not reach. `step` is the last state commanded, and `devices` holds the settled state of every targeted device after it, each with a `reached` flag. `ok` is true only when `step` is `target` and every device reached it. A restart drops every targeted device out of process data exchange, so a drive that was enabled is disabled, and a monitoring reports null for it until it exchanges again. The body is optional: no body restarts every discovered device to OP (8). State values are the standard AL state register encodings from ETG.1000.6: 1 (Init), 2 (PreOp), 3 (Boot), 4 (SafeOp), 8 (Op).
+     *
+     * @name RestartDevices
+     * @summary Restart devices through INIT up to an AL state
+     * @request POST:/api/devices/restart
+     */
+    restartDevices = (data, params = {}) => this.request({
+        path: `/api/devices/restart`,
+        method: "POST",
+        body: data,
+        type: ContentType.Json,
+        format: "json",
+        ...params,
+    });
     /**
      * No description
      *
@@ -1202,7 +1230,7 @@ export class Api extends HttpClient {
         ...params,
     });
     /**
-     * @description Returns one entry per cached parameter-definition file on disk, keyed by device identity (vendor, product, revision). The cache stores only the object-dictionary *definitions* (not live values), so a scan of previously-seen hardware can skip the slow SDO enumeration. Independent of the bus — works whether or not a driver is initialised.
+     * @description Returns one entry per cached parameter-definition file on disk, keyed by vendor ID, product code and firmware version (object 0x100A). A device without 0x100A is not cached. The cache stores only the object-dictionary *definitions* (not live values), so a scan of previously-seen hardware can skip the slow SDO enumeration. Independent of the bus — works whether or not a driver is initialised.
      *
      * @name ListParameterCacheEntries
      * @summary List on-disk parameter caches
@@ -1228,7 +1256,7 @@ export class Api extends HttpClient {
         ...params,
     });
     /**
-     * @description Removes one cached file from disk. The next scan of that hardware re-enumerates it. Useful when a vendor reused a revision across an object-dictionary change.
+     * @description Removes one cached file from disk. The next scan of that hardware re-enumerates it. Useful when a firmware changed its object dictionary and kept its version string.
      *
      * @name DeleteParameterCache
      * @summary Delete a parameter-cache file

package/dist/generated/data-contracts.d.ts

@@ -232,8 +232,8 @@ export interface UserCacheFile {
 /** Summary of one on-disk parameter-cache file (its identity, size, and count). */
 export interface ParameterCacheEntry {
     /**
-     * Opaque key addressing this cache file in the download/delete endpoints ("<vendor>-<product>-<revision>"). Use it verbatim — do not construct it client-side.
-     * @example "000022d2-00000201-0000000a"
+     * Opaque key addressing this cache file in the download/delete endpoints ("<vendor>-<product>-<version>", the version reduced to URL-safe characters). Use it verbatim — do not construct it client-side.
+     * @example "000022d2-00000201-v5.6.6"
      */
     id: string;
     /**
@@ -247,10 +247,10 @@ export interface ParameterCacheEntry {
      */
     productCode: number;
     /**
-     * Revision number.
-     * @example 10
+     * The device's firmware version (0x100A) the file was written for, in full.
+     * @example "v5.6.6"
      */
-    revisionNumber: number;
+    firmwareVersion: string;
     /**
      * Number of cached parameter definitions in the file.
      * @example 312
@@ -878,6 +878,36 @@ export interface IntegroVariantOption {
 }
 /** One option code from a decoded file, expanded into its catalogue entry. Everything but `id` is absent for a code the catalogue does not name, so "we do not know what this is" is missing properties rather than the string `unknown`. */
 export type IntegroVariantFileOption = UtilRequiredKeys<IntegroVariantOption, "id">;
+/**
+ * A plant model as plant identification stored it on the drive: the transfer function from torque in Nm to velocity in rad/s, coefficients highest order first and normalised so that the numerator's last coefficient is 1, and the chirp it was identified with. The last two denominator coefficients are the effective inertia and the effective viscous friction of the reduced model, which is how auto-tuning reads them.
+ * @example {"numerator":[1],"denominator":[0.000123,0.0456],"inertia":0.000123,"friction":0.0456,"chirp":{"startFrequencyHz":1,"endFrequencyHz":100,"amplitudePermil":300,"durationMs":3000,"signalType":"logarithmic"}}
+ */
+export interface IdentifiedPlantModel {
+    numerator: number[];
+    denominator: number[];
+    /**
+     * The denominator coefficient before the last; null when there are fewer than two
+     * @format double
+     */
+    inertia: number | null;
+    /**
+     * The last denominator coefficient; null when the denominator is empty
+     * @format double
+     */
+    friction: number | null;
+    /** What excited the plant. A file written without a chirp row reads back with zeros and the logarithmic type. */
+    chirp: {
+        /** @format double */
+        startFrequencyHz: number;
+        /** @format double */
+        endFrequencyHz: number;
+        /** Peak excitation, in per mille of rated torque */
+        amplitudePermil: number;
+        /** How long the sweep took */
+        durationMs: number;
+        signalType: "logarithmic" | "linear";
+    };
+}
 /**
  * A decoded `.variant` file: which features a SOMANET Integro was licensed with.
  *
@@ -988,7 +1018,7 @@ export interface ProcedureRequest {
      */
     pollIntervalMs?: number;
     /**
-     * `os-command` only: whether the command moves bulk data through the drive's fs-buffer, and which way. Most commands move none. The transfer runs while the command runs, because the drive holds the command in progress until all the data has moved, and it needs firmware 5.2 or newer. Setting a direction for a command that moves no bulk data leaves the server waiting for a transfer the drive will never start.
+     * `os-command` only: whether the command moves bulk data through the drive's fs-buffer, and which way. Most commands move none. A write runs while the command runs, because the command reads its input as it arrives, and it needs firmware 5.2 or newer. A read runs after the command succeeds, because the command completes when its whole output is in the fs-buffer. No read runs after a failure. An output larger than the 2024-byte fs-buffer cannot be read: the command waits for the master to empty it and runs into its timeout. Setting a direction for a command that moves no bulk data makes the transfer wait for an answer the drive never sends.
      * @default "none"
      * @example "read"
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapticon/motion-master-client",
-  "version": "6.0.0-alpha.110",
+  "version": "6.0.0-alpha.112",
   "description": "Isomorphic TypeScript client for Motion Master: the generated HTTP API client, the WebSocket connection, and helpers.",
   "license": "MIT",
   "repository": {