@synapticon/motion-master-client 6.0.0-alpha.62 → 6.0.0-alpha.64

package/dist/generated/Api.d.ts

@@ -1,4 +1,4 @@
-import { AlStatusCode, Cia402Status, DcSyncStatus, DeviceDiagnostics, DeviceParameter, EscRegister, FoeErrorCode, GameLoopHealth, MailboxErrorCode, Monitoring, ObjectDataTypeInfo, OutputStageResult, ParameterCacheEntry, PdoMapping, PdoMappingRequest, ProcessDataWatchdog, ProcessImageObject, SdoAbortCode, SlaveConfig, SlaveInformationInterface } from "./data-contracts.js";
+import { AlStatusCode, BrakeState, Cia402Status, DcSyncStatus, DeviceDiagnostics, DeviceParameter, EscRegister, EsiParseResult, FoeErrorCode, GameLoopHealth, MailboxErrorCode, Monitoring, ObjectDataTypeInfo, OutputStageResult, ParameterCacheEntry, 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> {
     /**
@@ -662,6 +662,78 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
          */
         value: number;
     }, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<void, void>>;
+    /**
+     * @description Returns every procedure available on the device, each with its descriptor and the state of its current or last run. One request is enough to render a whole per-device procedures view: the descriptor carries the title, description and caveats to display, and the snapshot says whether anything is running or how the last run went. The list is per device, not global — a procedure is offered only where it applies, so a third-party slave reports an empty list rather than controls that could only ever fail. A procedure that has never run reports an idle snapshot (`status` `idle`, `runCount` 0, every step `idle`), so every entry has the same shape.
+     *
+     * @name ListProcedures
+     * @summary List the procedures a device supports
+     * @request GET:/api/devices/{slavePosition}/procedures
+     */
+    listProcedures: (slavePosition: number, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<ProcedureListing[], void>>;
+    /**
+     * @description Starts the named procedure and returns as soon as the run is under way — this does **not** wait for it to finish. Poll `GET` on the same path for its outcome, or `DELETE` to cancel it. The request body carries the procedure's parameters; which fields it accepts (and whether it needs any at all) is per procedure, so consult the descriptor from `GET /api/devices/{slavePosition}/procedures`. A procedure that takes no parameters may be started with no body. Only one procedure may run on a device at a time; a second start is refused with 409 while the first is in flight. Most procedures require an active mailbox, so the device must be in PRE-OP, SAFE-OP or OP. A run the drive answers with an error is not a failure of *this* request — it is reported in the snapshot as a failed run.
+     *
+     * @name StartProcedure
+     * @summary Start a procedure on a device
+     * @request POST:/api/devices/{slavePosition}/procedures/{procedureName}
+     */
+    startProcedure: (slavePosition: number, procedureName: string, data?: ProcedureRequest, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<ProcedureSnapshot, void>>;
+    /**
+     * @description Returns the current run, or the last one to have finished. This is the whole progress surface — there is no push channel — and polling it is lossless: every finished step keeps its terminal status and value, so a step that both starts and completes between two polls is still reported as succeeded. A polling loop is `while status == "running"`. A procedure that has never run is not an absence: it reports an idle snapshot built from the procedure's step template, so a client renders one shape and needs no empty-state branch. The snapshot is retained after a run ends, so a client that reconnects (or a user returning to a page) sees how the last run went. It is dropped when the device set is rebuilt by a scan or reset, because bus positions may then name different hardware.
+     *
+     * @name GetProcedure
+     * @summary Read the state of a procedure on a device
+     * @request GET:/api/devices/{slavePosition}/procedures/{procedureName}
+     */
+    getProcedure: (slavePosition: number, procedureName: string, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<ProcedureSnapshot, void>>;
+    /**
+     * @description Asks the running procedure to stop and returns immediately. Where the procedure is waiting on the drive it also tells the drive to abort (for an OS command, 0x1024 = 3), so a run that is waiting stops when asked rather than carrying on to completion. The run then finishes with status `cancelled`. This cancels the *run*, not the record: the snapshot remains and reports how far it got.
+     *
+     * @name CancelProcedure
+     * @summary Cancel a running procedure on a device
+     * @request DELETE:/api/devices/{slavePosition}/procedures/{procedureName}
+     */
+    cancelProcedure: (slavePosition: number, procedureName: string, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<void, void>>;
+    /**
+     * @description Reports the brake objects (0x2004) that decide what a release or engage will do: its current state, the release strategy, the pull time and the pull/hold voltages. Read this before commanding the brake. `softwareControllable` is false when the release strategy is `manualOutputVoltage`, meaning the firmware does not drive the brake at all and both commands below are no-ops. `releaseMovesShaft` is true for a pin brake, whose release procedure turns the motor to lift the load off the pin.
+     *
+     * @name GetBrake
+     * @summary Read a drive's brake configuration and state
+     * @request GET:/api/devices/{slavePosition}/brake
+     */
+    getBrake: (slavePosition: number, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<BrakeState, void>>;
+    /**
+     * @description Writes "disengaged" to the brake state object (0x2004:07) and waits the drive's pull time (0x2004:03) plus `settle` before answering, because the firmware blocks motion — and motion-related OS commands — until the pull time expires. Answers with the brake state read back. **The release only actually happens while the drive is in OP ENABLED.** In any other state the write merely energises the brake output (phase D). Note also that entering OP ENABLED releases the brake automatically in normal operation but **not** in diagnostics mode, where the master owns the brake — which is why a diagnostics procedure has to call this. **On a pin brake this moves the shaft**: the controller raises current progressively until the load has lifted off the pin by the minimum displacement (0x2004:08), reversing direction if it reaches the current ceiling (0x2004:09, a percentage of rated current) first. Check `releaseMovesShaft` on `GET .../brake`. Brake release is open-loop — nothing confirms the brake let go — so the wait is the only margin there is. A brake whose release strategy is `manualOutputVoltage` is left alone and the returned state says so; that is not an error. **A released brake stays released**: nothing re-engages it for you, so on a vertical or loaded axis engage it again when you are done.
+     *
+     * @name ReleaseBrake
+     * @summary Release (disengage) a drive's brake
+     * @request POST:/api/devices/{slavePosition}/brake/release
+     */
+    releaseBrake: (slavePosition: number, query?: {
+        /**
+         * Extra wait in milliseconds on top of the drive's pull time. Size it for the machine — release is open-loop, so this is the only margin between "commanded" and "assumed released".
+         * @min 0
+         * @default 50
+         * @example 50
+         */
+        settle?: number;
+    }, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<BrakeState, void>>;
+    /**
+     * @description Writes "engaged" to the brake state object (0x2004:07) and waits `settle` before answering with the brake state read back. There is no pull time on the way in — a brake is spring-engaged, so engaging it is the removal of voltage — so the wait is only `settle`. As with release, a brake whose release strategy is `manualOutputVoltage` is left alone and the returned state says so.
+     *
+     * @name EngageBrake
+     * @summary Engage a drive's brake
+     * @request POST:/api/devices/{slavePosition}/brake/engage
+     */
+    engageBrake: (slavePosition: number, query?: {
+        /**
+         * How long to wait in milliseconds after commanding the brake before answering.
+         * @min 0
+         * @default 50
+         * @example 50
+         */
+        settle?: number;
+    }, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<BrakeState, void>>;
     /**
      * @description Commands the device to persist its current parameters (the generic CANopen "store parameters" object 0x1010:01) and waits for confirmation. The server writes the ASCII "save" signature, waits a fixed settle (~1 s) for the drive to begin the flash write, then polls 0x1010:01 until it reads back 1 ("save completed"). Because a store in progress can leave the mailbox briefly unresponsive, a poll that does not yet confirm — a value mismatch or a transient read error alike — is retried up to `retries` more times, `interval` apart. The call blocks until the store is confirmed or the retry budget is exhausted (up to a few seconds); the device's mailbox must be active (PRE-OP/SAFE-OP/OP).
      *
@@ -827,6 +899,17 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
      * @request POST:/api/sii/parse
      */
     parseSii: (data: File, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<SlaveInformationInterface, void>>;
+    /**
+     * @description Decodes a vendor's ESI XML supplied in the request body. No device is involved — the Tools page uses this to inspect an ESI with no hardware present, which is the only way to see object descriptions, enum option labels, engineering units and min/max bounds: the CoE SDO-Information service reports none of them. The response carries the vendor, every module, and **every device with its own assembled `entries` table** — one row per addressable `(index, subindex)`, merged from the device's own dictionary plus the dictionaries of the modules its slots reference, with each row recording in `source` where it came from. Object-level annotation (an object's description and raw properties) is attached to **subindex 0 only** — that row *is* the object — rather than repeated onto every subindex. A RECORD member still carries its own description on its own row; an ARRAY element carries none, because the ESI describes an array once rather than per element. To read an object's text for any subindex, look at subindex 0 of the same index. Where a slot offers mutually exclusive module variants the merge necessarily collides; it is resolved last-wins and reported in that device's `warnings`. Pass `modules` to model one concrete configuration instead.
+     *
+     * @name ParseEsi
+     * @summary Parse an EtherCAT Slave Information (ESI) file
+     * @request POST:/api/esi/parse
+     */
+    parseEsi: (data: string, query?: {
+        /** Comma-separated `ModuleIdent` values (hexadecimal or decimal) restricting the merge, applied to every device by intersection with the idents that device's slots actually reference. Omit to merge every module each device references. */
+        modules?: string;
+    }, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<EsiParseResult, void>>;
     /**
      * @description Reads live link-quality and watchdog diagnostics from each slave's EtherCAT Slave Controller (DL Status 0x0110, error-counter block 0x0300–0x0313, watchdog block 0x0440–0x0443) via FPRD. Counters are 8-bit, saturate at 255, and are cleared only by a power cycle or explicit write — poll this endpoint and watch for a rising delta rather than an absolute value. The per-port counters localise a degrading link to a specific cable/connector; the watchdog counters distinguish a slave that stopped receiving process data from a master-side problem. Omit `positions` to query all discovered devices. Returns 500 for transports without an ESC (e.g. SPoE).
      *
@@ -1120,7 +1203,7 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
         error: string;
     }>>;
     /**
-     * @description Serialises the process-data recorder's current span — every cycle from the oldest still in the ring up to the newest at the instant of the call — to a `.mmpd` file and returns its path. Each cycle's full raw input and output images, sequence, and epoch-nanosecond timestamp are written, with the process image (per-device identity and PDO object layout, including object names and data types where the object dictionary has been enumerated) embedded as a header, so the file decodes fully offline with no running Motion Master and no live bus. Works in any state: while devices are exchanging (SAFE-OP/OP) it captures tail→head at that moment and ignores cycles recorded afterwards; after the bus has left the exchange states it uses the most recent retained image layout. The file is written under the configured `recorder.dumpDir` (default: a `motion-master` subdirectory of the OS temporary directory), created if absent. Motion Master binds 127.0.0.1, so the file is on the caller's own machine — only the path is returned (there is no download, list, or delete endpoint).
+     * @description Serialises the process-data recorder's current span — every cycle from the oldest still in the ring up to the newest at the instant of the call — to a `.mmpd` file and returns its path. Each cycle's full raw input and output images, sequence, and epoch-nanosecond timestamp are written, with the process image (per-device identity and PDO object layout, including object names and data types where the object dictionary has been enumerated) embedded as a header, so the file decodes fully offline with no running Motion Master and no live bus. Works in any state: while devices are exchanging (SAFE-OP/OP) it captures tail→head at that moment and ignores cycles recorded afterwards; after the bus has left the exchange states it uses the most recent retained image layout. The file is written under the configured `recorder.dumpDir`, created if absent; by default that is a `dumps` subdirectory of the user-cache root, so the written file is also reachable through the `/api/user-cache` endpoints — list it, download it, or delete it there. Only the path is returned here. (Setting an explicit `recorder.dumpDir` outside the cache root opts out of that; the file is then only reachable from a shell on the server.)
      *
      * @name DumpProcessData
      * @summary Dump the recorder ring to a binary .mmpd file
@@ -1221,17 +1304,17 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
     /**
      * @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.
      *
-     * @name ListParameterCaches
+     * @name ListParameterCacheEntries
      * @summary List on-disk parameter caches
-     * @request GET:/api/parameter-caches
+     * @request GET:/api/parameter-cache
      */
-    listParameterCaches: (params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<ParameterCacheEntry[], any>>;
+    listParameterCacheEntries: (params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<ParameterCacheEntry[], any>>;
     /**
      * @description Returns the raw JSON cache file for the given id, verbatim, so it can be saved or inspected offline.
      *
      * @name GetParameterCache
      * @summary Download a parameter-cache file
-     * @request GET:/api/parameter-caches/{id}
+     * @request GET:/api/parameter-cache/{id}
      */
     getParameterCache: (id: string, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<object, void>>;
     /**
@@ -1239,7 +1322,50 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
      *
      * @name DeleteParameterCache
      * @summary Delete a parameter-cache file
-     * @request DELETE:/api/parameter-caches/{id}
+     * @request DELETE:/api/parameter-cache/{id}
      */
     deleteParameterCache: (id: string, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<void, void>>;
+    /**
+     * @description Returns every file in Motion Master's per-user cache directory, flattened: one entry per file with its full path relative to the cache root, whatever the nesting. Directories have no entries of their own. Independent of the bus — works whether or not a driver is initialised. The cache is a plain file store for data that should outlive a restart. The store itself neither validates nor interprets an upload — `PUT` accepts any bytes at any valid path, and putting a file here does not, on its own, make Motion Master do anything with it; the client chooses the paths. That is separate from whether a *feature* reads a given file, and several do: `parameters/` (the on-disk object-dictionary cache) and `dumps/` (`.mmpd` recorder dumps) are written and consumed by those features, with more to follow. Their files appear in this listing alongside everything else, so a client must not assume every entry was uploaded through this API, nor that deleting one is inconsequential.
+     *
+     * @name ListUserCacheFiles
+     * @summary List the files in the user cache
+     * @request GET:/api/user-cache
+     */
+    listUserCacheFiles: (params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<UserCacheListing, void>>;
+    /**
+     * @description Returns the file verbatim, always as `application/octet-stream` and always with `Content-Disposition: attachment`, `X-Content-Type-Options: nosniff` and a `default-src 'none'; sandbox` CSP. The bytes are whatever a user uploaded, served from the API's own origin, so a browser must never *render* them — a rendered upload would be stored XSS against the origin that controls the drives, which CORS cannot help with. No extension is trusted to name a content type, and the attachment carries no `filename` (the path is user-controlled and must not reach a response header). Clients read the bytes and name the saved file themselves.
+     *
+     * @name GetUserCacheFile
+     * @summary Download a user-cache file
+     * @request GET:/api/user-cache/{path}
+     */
+    getUserCacheFile: (path: string, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<Blob, void>>;
+    /**
+     * @description Writes the request body to the given path, creating parent directories as needed and replacing any existing file. The write is atomic — a concurrent reader sees either the old contents or the new one, never a partial file. The body is taken as raw bytes whatever its content type.
+     *
+     * @name PutUserCacheFile
+     * @summary Upload a user-cache file
+     * @request PUT:/api/user-cache/{path}
+     */
+    putUserCacheFile: (path: string, data: File, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<{
+        /**
+         * The path written, relative to the cache root.
+         * @example "configs/machine-a.json"
+         */
+        path: string;
+        /**
+         * Bytes written.
+         * @example 20480
+         */
+        size: number;
+    }, void>>;
+    /**
+     * @description Removes a file, or a directory and everything under it. Directories left empty between the removed path and the cache root are pruned, so no husks remain.
+     *
+     * @name DeleteUserCacheFile
+     * @summary Delete a user-cache file or directory
+     * @request DELETE:/api/user-cache/{path}
+     */
+    deleteUserCacheFile: (path: string, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<void, void>>;
 }

package/dist/generated/Api.js

@@ -456,6 +456,100 @@ export class Api extends HttpClient {
         type: ContentType.Json,
         ...params,
     });
+    /**
+     * @description Returns every procedure available on the device, each with its descriptor and the state of its current or last run. One request is enough to render a whole per-device procedures view: the descriptor carries the title, description and caveats to display, and the snapshot says whether anything is running or how the last run went. The list is per device, not global — a procedure is offered only where it applies, so a third-party slave reports an empty list rather than controls that could only ever fail. A procedure that has never run reports an idle snapshot (`status` `idle`, `runCount` 0, every step `idle`), so every entry has the same shape.
+     *
+     * @name ListProcedures
+     * @summary List the procedures a device supports
+     * @request GET:/api/devices/{slavePosition}/procedures
+     */
+    listProcedures = (slavePosition, params = {}) => this.request({
+        path: `/api/devices/${slavePosition}/procedures`,
+        method: "GET",
+        format: "json",
+        ...params,
+    });
+    /**
+     * @description Starts the named procedure and returns as soon as the run is under way — this does **not** wait for it to finish. Poll `GET` on the same path for its outcome, or `DELETE` to cancel it. The request body carries the procedure's parameters; which fields it accepts (and whether it needs any at all) is per procedure, so consult the descriptor from `GET /api/devices/{slavePosition}/procedures`. A procedure that takes no parameters may be started with no body. Only one procedure may run on a device at a time; a second start is refused with 409 while the first is in flight. Most procedures require an active mailbox, so the device must be in PRE-OP, SAFE-OP or OP. A run the drive answers with an error is not a failure of *this* request — it is reported in the snapshot as a failed run.
+     *
+     * @name StartProcedure
+     * @summary Start a procedure on a device
+     * @request POST:/api/devices/{slavePosition}/procedures/{procedureName}
+     */
+    startProcedure = (slavePosition, procedureName, data, params = {}) => this.request({
+        path: `/api/devices/${slavePosition}/procedures/${procedureName}`,
+        method: "POST",
+        body: data,
+        type: ContentType.Json,
+        format: "json",
+        ...params,
+    });
+    /**
+     * @description Returns the current run, or the last one to have finished. This is the whole progress surface — there is no push channel — and polling it is lossless: every finished step keeps its terminal status and value, so a step that both starts and completes between two polls is still reported as succeeded. A polling loop is `while status == "running"`. A procedure that has never run is not an absence: it reports an idle snapshot built from the procedure's step template, so a client renders one shape and needs no empty-state branch. The snapshot is retained after a run ends, so a client that reconnects (or a user returning to a page) sees how the last run went. It is dropped when the device set is rebuilt by a scan or reset, because bus positions may then name different hardware.
+     *
+     * @name GetProcedure
+     * @summary Read the state of a procedure on a device
+     * @request GET:/api/devices/{slavePosition}/procedures/{procedureName}
+     */
+    getProcedure = (slavePosition, procedureName, params = {}) => this.request({
+        path: `/api/devices/${slavePosition}/procedures/${procedureName}`,
+        method: "GET",
+        format: "json",
+        ...params,
+    });
+    /**
+     * @description Asks the running procedure to stop and returns immediately. Where the procedure is waiting on the drive it also tells the drive to abort (for an OS command, 0x1024 = 3), so a run that is waiting stops when asked rather than carrying on to completion. The run then finishes with status `cancelled`. This cancels the *run*, not the record: the snapshot remains and reports how far it got.
+     *
+     * @name CancelProcedure
+     * @summary Cancel a running procedure on a device
+     * @request DELETE:/api/devices/{slavePosition}/procedures/{procedureName}
+     */
+    cancelProcedure = (slavePosition, procedureName, params = {}) => this.request({
+        path: `/api/devices/${slavePosition}/procedures/${procedureName}`,
+        method: "DELETE",
+        ...params,
+    });
+    /**
+     * @description Reports the brake objects (0x2004) that decide what a release or engage will do: its current state, the release strategy, the pull time and the pull/hold voltages. Read this before commanding the brake. `softwareControllable` is false when the release strategy is `manualOutputVoltage`, meaning the firmware does not drive the brake at all and both commands below are no-ops. `releaseMovesShaft` is true for a pin brake, whose release procedure turns the motor to lift the load off the pin.
+     *
+     * @name GetBrake
+     * @summary Read a drive's brake configuration and state
+     * @request GET:/api/devices/{slavePosition}/brake
+     */
+    getBrake = (slavePosition, params = {}) => this.request({
+        path: `/api/devices/${slavePosition}/brake`,
+        method: "GET",
+        format: "json",
+        ...params,
+    });
+    /**
+     * @description Writes "disengaged" to the brake state object (0x2004:07) and waits the drive's pull time (0x2004:03) plus `settle` before answering, because the firmware blocks motion — and motion-related OS commands — until the pull time expires. Answers with the brake state read back. **The release only actually happens while the drive is in OP ENABLED.** In any other state the write merely energises the brake output (phase D). Note also that entering OP ENABLED releases the brake automatically in normal operation but **not** in diagnostics mode, where the master owns the brake — which is why a diagnostics procedure has to call this. **On a pin brake this moves the shaft**: the controller raises current progressively until the load has lifted off the pin by the minimum displacement (0x2004:08), reversing direction if it reaches the current ceiling (0x2004:09, a percentage of rated current) first. Check `releaseMovesShaft` on `GET .../brake`. Brake release is open-loop — nothing confirms the brake let go — so the wait is the only margin there is. A brake whose release strategy is `manualOutputVoltage` is left alone and the returned state says so; that is not an error. **A released brake stays released**: nothing re-engages it for you, so on a vertical or loaded axis engage it again when you are done.
+     *
+     * @name ReleaseBrake
+     * @summary Release (disengage) a drive's brake
+     * @request POST:/api/devices/{slavePosition}/brake/release
+     */
+    releaseBrake = (slavePosition, query, params = {}) => this.request({
+        path: `/api/devices/${slavePosition}/brake/release`,
+        method: "POST",
+        query: query,
+        format: "json",
+        ...params,
+    });
+    /**
+     * @description Writes "engaged" to the brake state object (0x2004:07) and waits `settle` before answering with the brake state read back. There is no pull time on the way in — a brake is spring-engaged, so engaging it is the removal of voltage — so the wait is only `settle`. As with release, a brake whose release strategy is `manualOutputVoltage` is left alone and the returned state says so.
+     *
+     * @name EngageBrake
+     * @summary Engage a drive's brake
+     * @request POST:/api/devices/{slavePosition}/brake/engage
+     */
+    engageBrake = (slavePosition, query, params = {}) => this.request({
+        path: `/api/devices/${slavePosition}/brake/engage`,
+        method: "POST",
+        query: query,
+        format: "json",
+        ...params,
+    });
     /**
      * @description Commands the device to persist its current parameters (the generic CANopen "store parameters" object 0x1010:01) and waits for confirmation. The server writes the ASCII "save" signature, waits a fixed settle (~1 s) for the drive to begin the flash write, then polls 0x1010:01 until it reads back 1 ("save completed"). Because a store in progress can leave the mailbox briefly unresponsive, a poll that does not yet confirm — a value mismatch or a transient read error alike — is retried up to `retries` more times, `interval` apart. The call blocks until the store is confirmed or the retry budget is exhausted (up to a few seconds); the device's mailbox must be active (PRE-OP/SAFE-OP/OP).
      *
@@ -577,6 +671,21 @@ export class Api extends HttpClient {
         format: "json",
         ...params,
     });
+    /**
+     * @description Decodes a vendor's ESI XML supplied in the request body. No device is involved — the Tools page uses this to inspect an ESI with no hardware present, which is the only way to see object descriptions, enum option labels, engineering units and min/max bounds: the CoE SDO-Information service reports none of them. The response carries the vendor, every module, and **every device with its own assembled `entries` table** — one row per addressable `(index, subindex)`, merged from the device's own dictionary plus the dictionaries of the modules its slots reference, with each row recording in `source` where it came from. Object-level annotation (an object's description and raw properties) is attached to **subindex 0 only** — that row *is* the object — rather than repeated onto every subindex. A RECORD member still carries its own description on its own row; an ARRAY element carries none, because the ESI describes an array once rather than per element. To read an object's text for any subindex, look at subindex 0 of the same index. Where a slot offers mutually exclusive module variants the merge necessarily collides; it is resolved last-wins and reported in that device's `warnings`. Pass `modules` to model one concrete configuration instead.
+     *
+     * @name ParseEsi
+     * @summary Parse an EtherCAT Slave Information (ESI) file
+     * @request POST:/api/esi/parse
+     */
+    parseEsi = (data, query, params = {}) => this.request({
+        path: `/api/esi/parse`,
+        method: "POST",
+        query: query,
+        body: data,
+        format: "json",
+        ...params,
+    });
     /**
      * @description Reads live link-quality and watchdog diagnostics from each slave's EtherCAT Slave Controller (DL Status 0x0110, error-counter block 0x0300–0x0313, watchdog block 0x0440–0x0443) via FPRD. Counters are 8-bit, saturate at 255, and are cleared only by a power cycle or explicit write — poll this endpoint and watch for a rising delta rather than an absolute value. The per-port counters localise a degrading link to a specific cable/connector; the watchdog counters distinguish a slave that stopped receiving process data from a master-side problem. Omit `positions` to query all discovered devices. Returns 500 for transports without an ESC (e.g. SPoE).
      *
@@ -701,7 +810,7 @@ export class Api extends HttpClient {
         ...params,
     });
     /**
-     * @description Serialises the process-data recorder's current span — every cycle from the oldest still in the ring up to the newest at the instant of the call — to a `.mmpd` file and returns its path. Each cycle's full raw input and output images, sequence, and epoch-nanosecond timestamp are written, with the process image (per-device identity and PDO object layout, including object names and data types where the object dictionary has been enumerated) embedded as a header, so the file decodes fully offline with no running Motion Master and no live bus. Works in any state: while devices are exchanging (SAFE-OP/OP) it captures tail→head at that moment and ignores cycles recorded afterwards; after the bus has left the exchange states it uses the most recent retained image layout. The file is written under the configured `recorder.dumpDir` (default: a `motion-master` subdirectory of the OS temporary directory), created if absent. Motion Master binds 127.0.0.1, so the file is on the caller's own machine — only the path is returned (there is no download, list, or delete endpoint).
+     * @description Serialises the process-data recorder's current span — every cycle from the oldest still in the ring up to the newest at the instant of the call — to a `.mmpd` file and returns its path. Each cycle's full raw input and output images, sequence, and epoch-nanosecond timestamp are written, with the process image (per-device identity and PDO object layout, including object names and data types where the object dictionary has been enumerated) embedded as a header, so the file decodes fully offline with no running Motion Master and no live bus. Works in any state: while devices are exchanging (SAFE-OP/OP) it captures tail→head at that moment and ignores cycles recorded afterwards; after the bus has left the exchange states it uses the most recent retained image layout. The file is written under the configured `recorder.dumpDir`, created if absent; by default that is a `dumps` subdirectory of the user-cache root, so the written file is also reachable through the `/api/user-cache` endpoints — list it, download it, or delete it there. Only the path is returned here. (Setting an explicit `recorder.dumpDir` outside the cache root opts out of that; the file is then only reachable from a shell on the server.)
      *
      * @name DumpProcessData
      * @summary Dump the recorder ring to a binary .mmpd file
@@ -797,12 +906,12 @@ export class Api extends HttpClient {
     /**
      * @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.
      *
-     * @name ListParameterCaches
+     * @name ListParameterCacheEntries
      * @summary List on-disk parameter caches
-     * @request GET:/api/parameter-caches
+     * @request GET:/api/parameter-cache
      */
-    listParameterCaches = (params = {}) => this.request({
-        path: `/api/parameter-caches`,
+    listParameterCacheEntries = (params = {}) => this.request({
+        path: `/api/parameter-cache`,
         method: "GET",
         format: "json",
         ...params,
@@ -812,10 +921,10 @@ export class Api extends HttpClient {
      *
      * @name GetParameterCache
      * @summary Download a parameter-cache file
-     * @request GET:/api/parameter-caches/{id}
+     * @request GET:/api/parameter-cache/{id}
      */
     getParameterCache = (id, params = {}) => this.request({
-        path: `/api/parameter-caches/${id}`,
+        path: `/api/parameter-cache/${id}`,
         method: "GET",
         format: "json",
         ...params,
@@ -825,10 +934,61 @@ export class Api extends HttpClient {
      *
      * @name DeleteParameterCache
      * @summary Delete a parameter-cache file
-     * @request DELETE:/api/parameter-caches/{id}
+     * @request DELETE:/api/parameter-cache/{id}
      */
     deleteParameterCache = (id, params = {}) => this.request({
-        path: `/api/parameter-caches/${id}`,
+        path: `/api/parameter-cache/${id}`,
+        method: "DELETE",
+        ...params,
+    });
+    /**
+     * @description Returns every file in Motion Master's per-user cache directory, flattened: one entry per file with its full path relative to the cache root, whatever the nesting. Directories have no entries of their own. Independent of the bus — works whether or not a driver is initialised. The cache is a plain file store for data that should outlive a restart. The store itself neither validates nor interprets an upload — `PUT` accepts any bytes at any valid path, and putting a file here does not, on its own, make Motion Master do anything with it; the client chooses the paths. That is separate from whether a *feature* reads a given file, and several do: `parameters/` (the on-disk object-dictionary cache) and `dumps/` (`.mmpd` recorder dumps) are written and consumed by those features, with more to follow. Their files appear in this listing alongside everything else, so a client must not assume every entry was uploaded through this API, nor that deleting one is inconsequential.
+     *
+     * @name ListUserCacheFiles
+     * @summary List the files in the user cache
+     * @request GET:/api/user-cache
+     */
+    listUserCacheFiles = (params = {}) => this.request({
+        path: `/api/user-cache`,
+        method: "GET",
+        format: "json",
+        ...params,
+    });
+    /**
+     * @description Returns the file verbatim, always as `application/octet-stream` and always with `Content-Disposition: attachment`, `X-Content-Type-Options: nosniff` and a `default-src 'none'; sandbox` CSP. The bytes are whatever a user uploaded, served from the API's own origin, so a browser must never *render* them — a rendered upload would be stored XSS against the origin that controls the drives, which CORS cannot help with. No extension is trusted to name a content type, and the attachment carries no `filename` (the path is user-controlled and must not reach a response header). Clients read the bytes and name the saved file themselves.
+     *
+     * @name GetUserCacheFile
+     * @summary Download a user-cache file
+     * @request GET:/api/user-cache/{path}
+     */
+    getUserCacheFile = (path, params = {}) => this.request({
+        path: `/api/user-cache/${path}`,
+        method: "GET",
+        ...params,
+    });
+    /**
+     * @description Writes the request body to the given path, creating parent directories as needed and replacing any existing file. The write is atomic — a concurrent reader sees either the old contents or the new one, never a partial file. The body is taken as raw bytes whatever its content type.
+     *
+     * @name PutUserCacheFile
+     * @summary Upload a user-cache file
+     * @request PUT:/api/user-cache/{path}
+     */
+    putUserCacheFile = (path, data, params = {}) => this.request({
+        path: `/api/user-cache/${path}`,
+        method: "PUT",
+        body: data,
+        format: "json",
+        ...params,
+    });
+    /**
+     * @description Removes a file, or a directory and everything under it. Directories left empty between the removed path and the cache root are pruned, so no husks remain.
+     *
+     * @name DeleteUserCacheFile
+     * @summary Delete a user-cache file or directory
+     * @request DELETE:/api/user-cache/{path}
+     */
+    deleteUserCacheFile = (path, params = {}) => this.request({
+        path: `/api/user-cache/${path}`,
         method: "DELETE",
         ...params,
     });

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

@@ -106,6 +106,33 @@ export interface GameLoopHealth {
      */
     timestampUs: number;
 }
+/** The user cache's location on disk plus every file it holds. */
+export interface UserCacheListing {
+    /**
+     * Absolute path of the cache directory on the server's filesystem. Platform-dependent (and overridable via the `userCache.directory` config key), so it is reported rather than assumed — show it to the user so they can find the files themselves.
+     * @example "/home/user/.cache/motion-master"
+     */
+    root: string;
+    files: UserCacheFile[];
+}
+/** One file in the user cache. */
+export interface UserCacheFile {
+    /**
+     * Path relative to the cache root, always with `/` separators. Use it verbatim in the download/upload/delete endpoints.
+     * @example "configs/machine-a.json"
+     */
+    path: string;
+    /**
+     * File size in bytes.
+     * @example 20480
+     */
+    size: number;
+    /**
+     * Last-write time, in milliseconds since the Unix epoch.
+     * @example 1783968687738
+     */
+    modifiedMs: number;
+}
 /** Summary of one on-disk parameter-cache file (its identity, size, and count). */
 export interface ParameterCacheEntry {
     /**
@@ -317,6 +344,155 @@ export interface ProcessImageObject {
      */
     bitLength: number;
 }
+/** One step of a procedure. `id` is stable across runs, so a client keys its label and its value formatting off it. A step never reports cancellation: cancelling stops the procedure, leaving the step it was on `running` and the rest `idle`, which records how far it got. */
+export interface ProgressStep {
+    /**
+     * Stable identifier of the step within its procedure.
+     * @example "command"
+     */
+    id: string;
+    /** @example "succeeded" */
+    status: "idle" | "running" | "succeeded" | "failed";
+    /**
+     * What the step produced, if anything — shape is per procedure. Absent when the step produced nothing. For `os-command` it is an object with `status`, `data`, and `errorCode` when the drive sent one.
+     * @example {"status":1,"data":[1,2,3,4,5,6]}
+     */
+    value?: any;
+    /** Why the step failed. Absent unless it did. */
+    error?: string;
+}
+/** The complete state of a procedure on one device — an accumulating snapshot rather than an event, which is what makes polling lossless. */
+export interface ProcedureSnapshot {
+    /**
+     * The one field a polling loop checks. `cancelled` is distinct from `failed` on purpose: "I stopped it" and "the drive could not do it" are different outcomes.
+     * @example "succeeded"
+     */
+    status: "idle" | "running" | "succeeded" | "failed" | "cancelled";
+    /**
+     * How many runs have been accepted on this device since the last scan or reset; a rejected start does not count. Doubles as a generation counter — with no run id, a changed `runCount` is how a poller can tell one run from the next.
+     * @example 3
+     */
+    runCount: number;
+    /**
+     * Epoch milliseconds the run began. Absent when never run.
+     * @format int64
+     * @example 1735821000123
+     */
+    startedAt?: number;
+    /**
+     * Epoch milliseconds the run ended. Absent while running.
+     * @format int64
+     * @example 1735821042456
+     */
+    finishedAt?: number;
+    /** The procedure's ordered steps, always the full template. */
+    steps: ProgressStep[];
+    /** Why the run failed when no step captured it — a failure belonging to no step, such as the device not being the kind the procedure needs. Absent otherwise. */
+    error?: string;
+}
+/** A drive's brake configuration and current state — the parts of object 0x2004 that decide what commanding the brake will actually do. Returned by every brake endpoint, so the outcome of a release or engage arrives in the same shape as a plain read. */
+export interface BrakeState {
+    /**
+     * Brake state (0x2004:07). A brake is spring-engaged, so `engaged` is also its powered-off state.
+     * @example "engaged"
+     */
+    status: "notConfigured" | "engaged" | "disengaged";
+    /**
+     * How the brake is driven (0x2004:04). `manualOutputVoltage` means the firmware does not drive it — the brake is a raw output voltage (0x2004:10) instead.
+     * @example "clutch"
+     */
+    releaseStrategy: "manualOutputVoltage" | "clutch" | "pin";
+    /**
+     * How long the pull voltage is applied to release the brake (0x2004:03). The firmware blocks motion, and motion-related OS commands, until this expires.
+     * @example 120
+     */
+    pullTimeMs: number;
+    /**
+     * Voltage that disengages the brake, in millivolts (0x2004:01).
+     * @example 24000
+     */
+    pullVoltageMv: number;
+    /**
+     * Lower voltage that keeps it disengaged once released, in millivolts (0x2004:02).
+     * @example 12000
+     */
+    holdVoltageMv: number;
+    /**
+     * Whether commanding the brake does anything at all — false for `manualOutputVoltage`. Derived from the release strategy and served so a client need not encode that rule.
+     * @example true
+     */
+    softwareControllable: boolean;
+    /**
+     * Whether releasing this brake turns the motor. True only for a pin brake, whose release raises current progressively to lift the load off the pin.
+     * @example false
+     */
+    releaseMovesShaft: boolean;
+}
+/** What a procedure *is*, independent of any run — everything needed to render a control for it. The text is served rather than held per client, because the house rule that every action carries a description and its caveats means it has to exist somewhere, and duplicating it in each client is how it goes stale. */
+export interface ProcedureDescriptor {
+    /**
+     * Identifier: the `procedureName` path segment, and the key its snapshot is retained under.
+     * @example "os-command"
+     */
+    name: string;
+    /**
+     * Short human-readable name.
+     * @example "OS command"
+     */
+    title: string;
+    /** What the procedure does. */
+    description: string;
+    /** What a user must know before running it. May be empty. */
+    caveats: string[];
+    /**
+     * True if running it can move the shaft.
+     * @example true
+     */
+    movesMotor: boolean;
+    /**
+     * True if the drive must be enabled before it will run.
+     * @example false
+     */
+    requiresEnabled: boolean;
+    /**
+     * The ordered step ids the procedure reports against — bare ids, because a template's per-step status is always idle and says nothing. Live status for the same ids is in the snapshot's `steps`.
+     * @example ["command"]
+     */
+    steps: string[];
+}
+/** One procedure paired with how its last run on this device went — an entry of `GET /api/devices/{slavePosition}/procedures`. The pairing is what lets a page render in a single request instead of one per procedure. */
+export interface ProcedureListing {
+    /** What a procedure *is*, independent of any run — everything needed to render a control for it. The text is served rather than held per client, because the house rule that every action carries a description and its caveats means it has to exist somewhere, and duplicating it in each client is how it goes stale. */
+    descriptor: ProcedureDescriptor;
+    /** The complete state of a procedure on one device — an accumulating snapshot rather than an event, which is what makes polling lossless. */
+    snapshot: ProcedureSnapshot;
+}
+/** A procedure's parameters. Which fields apply is per procedure — consult its descriptor — so this schema is open, and a procedure that takes none may be started with no body at all. The properties below are those of `os-command`, where `command` is required. */
+export interface ProcedureRequest {
+    /**
+     * `os-command` only, and required for it: the eight request bytes. Byte 0 is the OS command ID; bytes 1-7 are that command's parameters.
+     * @maxItems 8
+     * @minItems 8
+     * @example [8,0,0,0,0,0,0,0]
+     */
+    command?: number[];
+    /**
+     * Ceiling on the whole command. Not a liveness check — the drive fails a command no service acknowledges within 5 s on its own — so size it for the command being run. Hitting it aborts the command on the drive.
+     * @min 1
+     * @max 600000
+     * @default 1000
+     * @example 30000
+     */
+    timeoutMs?: number;
+    /**
+     * How often the server reads the drive's response object while waiting.
+     * @min 1
+     * @max 1000
+     * @default 10
+     */
+    pollIntervalMs?: number;
+    [key: string]: any;
+}
 export interface OutputStageResult {
     /**
      * 1-based bus position of the owning device (echoes the request)
@@ -939,3 +1115,129 @@ export interface SiiPdo {
         flags?: number;
     }[];
 }
+/** One addressable `(index, subindex)` of a device's object dictionary, assembled from the ESI. `defaultData`/`minData`/`maxData` are **raw little-endian bytes** as uppercase hexBinary, the same spelling the ESI itself uses — the first byte is the least significant, so `92010200` is `0x00020192`. Decode them with `dataType`; a byte-wise comparison of `minData` against `maxData` is wrong when `isSigned`. */
+export interface EsiEntry {
+    /** Effective CoE index */
+    index: number;
+    subindex: number;
+    /** Index as written in the source dictionary; omitted when unrelocated */
+    rawIndex?: number;
+    /** The parent object's name — identical across all its subindices */
+    objectName: string;
+    /** This subindex's own name */
+    entryName: string;
+    /** The ESI's display-name override, else `entryName` */
+    displayName: string;
+    objectCode: "VAR" | "ARRAY" | "RECORD";
+    /** The CoE object code (ETG.1000.6 §5) — 7, 8 or 9 */
+    objectCodeValue?: number;
+    /** Highest subindex; omitted for a VAR */
+    numberOfEntries?: number;
+    /**
+     * ESI/IEC 61131-3 type name, e.g. `UDINT`, `STRING(50)`
+     * @example "UDINT"
+     */
+    dataTypeName: string;
+    /**
+     * ETG.1020 code, matching `DeviceParameter.dataType`; 0 if unresolved
+     * @example 7
+     */
+    dataType: number;
+    isSigned: boolean;
+    bitSize: number;
+    /** Offset within the object's complete-access image */
+    bitOffset: number;
+    /** Uppercase hexBinary */
+    defaultData?: string;
+    minData?: string;
+    maxData?: string;
+    /** Packed ETG.1004 notation value */
+    unit?: number;
+    /** @example "mV" */
+    unitSymbol?: string;
+    access: {
+        mode: "ro" | "rw" | "wo";
+        readRestrictions?: "PreOP" | "PreOP_SafeOP" | "PreOP_OP" | "SafeOP" | "SafeOP_OP" | "OP";
+        writeRestrictions?: "PreOP" | "PreOP_SafeOP" | "PreOP_OP" | "SafeOP" | "SafeOP_OP" | "OP";
+    };
+    /** Mandatory, optional or conditional */
+    category: "m" | "o" | "c";
+    /** Empty when not mappable; `t` TxPDO, `r` RxPDO */
+    pdoMapping: "" | "t" | "r" | "tr";
+    safetyMapping?: "si" | "so" | "sio" | "sp";
+    sdoAccess: "SubIndexAccess" | "CompleteAccess";
+    backup: boolean;
+    setting: boolean;
+    /** SoE IDN */
+    attribute?: number;
+    /** ETG.1000.6 ObjAccess bitfield synthesised from the flags — bits 0-2 read in PreOP/SafeOP/OP, 3-5 write, 6 RxPDO-mappable, 7 TxPDO-mappable, 8 backup, 9 setting. Matches `DeviceParameter.access`. */
+    objAccess: number;
+    /** This row's description (HTML), decoded from `properties`. On subindex 0 it is the object's; on a RECORD member it is that member's; an ARRAY element has none. */
+    description?: string;
+    /** Enum labels, from `<EnumInfo>` and/or an `options` property */
+    options?: {
+        label: string;
+        value: number;
+    }[];
+    /** Raw `<Property>` annotations as written, for whatever this row describes. This is the ESI's generic extension mechanism; `description` and `options` above are conveniences decoded from the two conventional names, so a vendor using other names still has its data here. **Subindex 0 carries the object's own annotation** (stored once, not repeated onto every subindex); other rows carry only what that entry itself declares. */
+    properties?: EsiProperties;
+    /** Which dictionary this entry came from. The module's *name* is not repeated here — resolve `moduleIdent` against the top-level `modules` list. */
+    source: {
+        kind: "device" | "module";
+        moduleIdent?: number;
+        /** Zero-based slot number */
+        slot?: number;
+        /** Slot offset applied to `rawIndex` */
+        indexOffset?: number;
+    };
+}
+/** Raw `<Property>` annotations as written, for whatever this row describes. This is the ESI's generic extension mechanism; `description` and `options` above are conveniences decoded from the two conventional names, so a vendor using other names still has its data here. **Subindex 0 carries the object's own annotation** (stored once, not repeated onto every subindex); other rows carry only what that entry itself declares. */
+export type EsiProperties = {
+    name: string;
+    value: string;
+}[];
+export interface EsiDeviceSummary {
+    /** Zero-based position in the file */
+    ordinal: number;
+    /** @example "SOMANET Node" */
+    type: string;
+    name: string;
+    productCode?: number;
+    revisionNo?: number;
+    /** @example 402 */
+    profileNo?: number;
+    groupType: string;
+    /** Objects in the device's own dictionary, before any module merge */
+    objectCount: number;
+    rxPdoCount?: number;
+    txPdoCount?: number;
+    /** Every `ModuleIdent` the device's slots reference, in slot order */
+    moduleIdents: number[];
+    /** The parsed `<Slots>` block */
+    slots?: object;
+    /** This device's flat, slot-merged object dictionary */
+    entries?: EsiEntry[];
+    /** Problems found while assembling *this device* — a value whose byte length disagrees with its declared width, an unresolvable type, a module collision. Distinct from the top-level `warnings`, which are about the document; a different `modules` selection would produce a different list here. */
+    warnings?: string[];
+}
+/** A parsed ESI. Every device carries its own assembled `entries` table. */
+export interface EsiParseResult {
+    /** The `EtherCATInfo/@Version` attribute */
+    version?: string;
+    vendor: {
+        /** @example 8914 */
+        id: number;
+        name: string;
+        url?: string;
+    };
+    devices: EsiDeviceSummary[];
+    modules: {
+        moduleIdent: number;
+        /** @example "CiA402 Dictionary" */
+        type: string;
+        name: string;
+        objectCount?: number;
+    }[];
+    /** Recoverable problems in the document itself — a skipped malformed object, an unparsable value. A file with warnings still parses. Per-device assembly problems are reported on the device instead. */
+    warnings?: string[];
+}

package/package.json

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