@synapticon/motion-master-client 6.0.0-alpha.63 → 6.0.0-alpha.65

package/dist/generated/Api.d.ts

@@ -1,4 +1,4 @@
-import { AlStatusCode, Cia402Status, DcSyncStatus, DeviceDiagnostics, DeviceParameter, EscRegister, EsiParseResult, FoeErrorCode, GameLoopHealth, MailboxErrorCode, Monitoring, ObjectDataTypeInfo, OutputStageResult, ParameterCacheEntry, PdoMapping, PdoMappingRequest, ProcessDataWatchdog, ProcessImageObject, SdoAbortCode, SlaveConfig, SlaveInformationInterface, UserCacheListing } 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).
      *

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).
      *

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

@@ -344,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)

package/package.json

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