@synapticon/motion-master-client 6.0.0-alpha.69 → 6.0.0-alpha.71

package/dist/api-error.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The one place that knows how a failed request from the generated client is shaped.
+ *
+ * `swagger-typescript-api`'s client does not throw an `Error`. On a non-2xx it throws its own
+ * `HttpResponse` object, having parsed the response body into that object's `error` property — and
+ * Motion Master's own error body is `{ "error": "<message>" }`. So the message a user should see
+ * sits at `err.error.error`, two levels down, and reading one level yields the string
+ * `"[object Object]"`.
+ *
+ * That is not a shape any caller should have to know, which is the whole reason this lives here: the
+ * wrapping belongs to the generated client, the generated client belongs to this package, so the
+ * unwrapping belongs here too rather than being rediscovered in every page that catches a request.
+ */
+/**
+ * The human-readable reason a request failed.
+ *
+ * Tries, in order: the server's own message (`{ error }`, at either nesting level), the HTTP status,
+ * a thrown `Error`'s message, and finally `fallback`. The server message comes first because it is
+ * the only one that says anything specific — Motion Master's node layer writes these, and they name
+ * the object, the state, or the grammar that was wrong.
+ *
+ * @param err       Whatever was caught.
+ * @param fallback  Returned when nothing usable can be found.
+ */
+export declare function apiErrorMessage(err: unknown, fallback?: string): string;

package/dist/api-error.js

@@ -0,0 +1,52 @@
+/**
+ * The one place that knows how a failed request from the generated client is shaped.
+ *
+ * `swagger-typescript-api`'s client does not throw an `Error`. On a non-2xx it throws its own
+ * `HttpResponse` object, having parsed the response body into that object's `error` property — and
+ * Motion Master's own error body is `{ "error": "<message>" }`. So the message a user should see
+ * sits at `err.error.error`, two levels down, and reading one level yields the string
+ * `"[object Object]"`.
+ *
+ * That is not a shape any caller should have to know, which is the whole reason this lives here: the
+ * wrapping belongs to the generated client, the generated client belongs to this package, so the
+ * unwrapping belongs here too rather than being rediscovered in every page that catches a request.
+ */
+/**
+ * The human-readable reason a request failed.
+ *
+ * Tries, in order: the server's own message (`{ error }`, at either nesting level), the HTTP status,
+ * a thrown `Error`'s message, and finally `fallback`. The server message comes first because it is
+ * the only one that says anything specific — Motion Master's node layer writes these, and they name
+ * the object, the state, or the grammar that was wrong.
+ *
+ * @param err       Whatever was caught.
+ * @param fallback  Returned when nothing usable can be found.
+ */
+export function apiErrorMessage(err, fallback = 'Unknown error') {
+    if (typeof err === 'object' && err !== null) {
+        const candidate = err;
+        // The generated client's HttpResponse: the parsed body sits in `error`.
+        if (typeof candidate.error === 'object' && candidate.error !== null) {
+            const body = candidate.error;
+            if (typeof body.error === 'string' && body.error !== '') {
+                return body.error;
+            }
+        }
+        // A body handed over directly, or an already-unwrapped one.
+        if (typeof candidate.error === 'string' && candidate.error !== '') {
+            return candidate.error;
+        }
+        // No body to read — a network failure, or a response with no JSON. The status is what is left,
+        // and it is still more use than a generic sentence.
+        if (typeof candidate.status === 'number') {
+            const statusText = typeof candidate.statusText === 'string' && candidate.statusText !== ''
+                ? ` ${candidate.statusText}`
+                : '';
+            return `HTTP ${candidate.status}${statusText}`;
+        }
+    }
+    if (err instanceof Error && err.message !== '') {
+        return err.message;
+    }
+    return fallback;
+}

package/dist/generated/Api.d.ts

@@ -1,4 +1,4 @@
-import { AlStatusCode, BrakeState, Cia402Status, DcSyncStatus, DeviceDiagnostics, DeviceFile, DeviceParameter, EscRegister, EsiParseResult, FirmwarePackageName, FoeErrorCode, GameLoopHealth, HrdRecording, MailboxErrorCode, Monitoring, ObjectDataTypeInfo, OutputStageResult, ParameterCacheEntry, PdoMapping, PdoMappingRequest, ProcedureListing, ProcedureRequest, ProcedureSnapshot, ProcessDataWatchdog, ProcessImageObject, SdoAbortCode, SlaveConfig, SlaveInformationInterface, UserCacheListing } from "./data-contracts.js";
+import { AlStatusCode, BrakeState, Cia402Status, DcSyncStatus, DeviceDiagnostics, DeviceFile, DeviceParameter, EscRegister, EsiParseResult, FirmwareCompatibility, FirmwarePackageName, FoeErrorCode, GameLoopHealth, HardwareDescription, HrdRecording, IntegroVariant, IntegroVariantOption, MailboxErrorCode, Monitoring, ObjectDataTypeInfo, OperationModes, 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> {
     /**
@@ -396,6 +396,52 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
      * @request GET:/api/meta/sdo-abort-codes
      */
     getSdoAbortCodes: (params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<SdoAbortCode[], any>>;
+    /**
+     * @description The register map of the Integro's internal (Kübler) encoder — the reference table for POST /api/devices/{slavePosition}/procedures/kuebler-register-communication, and documentation in its own right. Static: it describes the encoder type, not any connected device, so it needs no bus and no scan. Transcribed from the vendor's own draft table. Each entry carries the width, the access type, whether the encoder actually implements it — seven are documented but not implemented — and the vendor's bit definitions verbatim, which for a bit-field register is the only place its meaning is recorded. `format` says how to read the assembled value, because signedness is not uniform and one register is not a single number at all: `unsigned`, `signed`, `bitField` (the number means nothing on its own), or `signedHalves` — two signed 16-bit values packed into 32 bits, which register 0x3C is the only case of. `readableInOneCommand` is false for the one 64-bit register, since the command's length byte caps at 4 bytes.
+     *
+     * @name GetKueblerRegisters
+     * @summary The Integro internal encoder's register map
+     * @request GET:/api/meta/kuebler-registers
+     */
+    getKueblerRegisters: (params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<{
+        /**
+         * Register address, as OS command 19 carries it.
+         * @example 48
+         */
+        address: number;
+        /**
+         * Width in bits — 8, 16, 32, or 64.
+         * @example 32
+         */
+        bits: number;
+        /**
+         * The vendor's own name for the register.
+         * @example "Absolute position ST"
+         */
+        name: string;
+        /** @example "ro" */
+        access: "ro" | "wo" | "rw";
+        /**
+         * Whether the encoder implements it, per the vendor's draft.
+         * @example true
+         */
+        implemented: boolean;
+        /**
+         * How to read the assembled value.
+         * @example "unsigned"
+         */
+        format: "unsigned" | "signed" | "bitField" | "signedHalves";
+        /**
+         * The vendor's bit definitions, clauses joined with "; ".
+         * @example "Left aligned 32 bit singleturn position"
+         */
+        definition: string;
+        /**
+         * False only for the 64-bit register, which exceeds the command's 4-byte length field.
+         * @example true
+         */
+        readableInOneCommand: boolean;
+    }[], any>>;
     /**
      * @description Returns the static catalogue of CoE mailbox error codes defined in ETG.1000.4, Table 30 ("Error Reply Service Data").  A slave returns one of these when the mailbox layer (below a specific protocol such as CoE/FoE) rejects a transfer; the code is embedded in the error text the mailbox endpoints return.
      *
@@ -616,7 +662,15 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
      */
     getCia402Status: (slavePosition: number, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<Cia402Status, void>>;
     /**
-     * @description Writes the requested operation mode to 0x6060 and returns the resulting control snapshot. The drive reflects the accepted mode in 0x6061 (the modeOfOperation of the response) once it takes effect.
+     * @description Every operation mode the device has, standard and manufacturer-specific, with what the drive says about each. The standard modes are CiA402's (ETG.6010 §6.8.1) and carry the bit of "Supported drive modes" (0x6502) that advertises them, decoded into `supported`. The manufacturer modes are the vendor's own — the negative half of 0x6060 — and are listed only for a device whose vendor this server knows; their `supported` is null, because 0x6502 reserves bits 16-31 for the vendor without defining them, so a drive has no way to advertise one that a master could read. That null means "the drive does not say", not "no". Read this once per device and cache it: it is a static property of the firmware, and the one thing that makes a negative value of 0x6061 nameable rather than "Unknown".
+     *
+     * @name GetOperationModes
+     * @summary List a device's operation modes
+     * @request GET:/api/devices/{slavePosition}/operation-modes
+     */
+    getOperationModes: (slavePosition: number, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<OperationModes, void>>;
+    /**
+     * @description Writes the requested operation mode to 0x6060 and returns the resulting control snapshot. The drive reflects the accepted mode in 0x6061 (the modeOfOperation of the response) once it takes effect. Any value object 0x6060 can hold is accepted, standard or manufacturer-specific — the negative half of that range belongs to the vendor, so a SOMANET's diagnostics (-2) or system identification (-4) go through here like any other. Whether a given drive has the mode is the drive's answer, seen in the modeOfOperation of the response; GET /api/devices/{slavePosition}/operation-modes is what lists them beforehand.
      *
      * @name SetCia402OperationMode
      * @summary Set a device's CiA402 operation mode
@@ -624,13 +678,29 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
      */
     setCia402OperationMode: (slavePosition: number, data: {
         /**
-         * CiA402 operation mode (0x6060 value): 0 NoMode, 1 Profile Position, 3 Profile Velocity, 4 Profile Torque, 6 Homing, 8 Cyclic Sync Position, 9 Cyclic Sync Velocity, 10 Cyclic Sync Torque.
+         * Operation mode to request (the 0x6060 value). Standard modes are 0 NoMode, 1 Profile Position, 2 Velocity, 3 Profile Velocity, 4 Profile Torque, 6 Homing, 7 Interpolated Position, 8 Cyclic Sync Position, 9 Cyclic Sync Velocity, 10 Cyclic Sync Torque, 11 Cyclic Sync Torque with Commutation Angle; negative values are the vendor's.
+         * @min -128
+         * @max 127
          * @example 9
          */
         mode: number;
     }, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<Cia402Status, void>>;
     /**
-     * @description Drives the CiA402 device-control state machine. "enable" walks every intermediate transition to Operation Enabled (clearing a fault first if needed); "disable" goes to Switch On Disabled; "quickStop" triggers a quick stop; "faultReset" clears a latched fault. The device must be exchanging process data for "enable" to make progress. Returns the resulting control snapshot.
+     * @description Walks the CiA402 device-control state machine to the state you name, issuing whatever transitions that takes and re-reading the drive between each — so multi-hop paths are ordinary: Switch On Disabled up to Operation Enabled, Quick Stop Active back down to Ready To Switch On. Starting from Fault begins with a fault reset, and a fault whose cause is still present is reported as such (with the drive's 0x603F error code) rather than as a timeout. Only the five states a master can command are accepted. Not Ready To Switch On, Fault Reaction Active and Fault are entered by the drive itself and are rejected as a bad request. **Asking for Operation Enabled while the drive is in Quick Stop Active leaves that quick stop** (CiA402 transition 16), because naming the destination is an explicit instruction to go there. The "enable" command on the sibling endpoint deliberately does not, so a procedure preparing a drive cannot undo somebody's stop by accident. The device must be exchanging process data for any of this to progress — the statusword has to update between polls, and the firmware refuses Operation Enabled unless master communication is live. Returns the resulting control snapshot.
+     *
+     * @name TransitionToCia402State
+     * @summary Bring a drive to a CiA402 state
+     * @request POST:/api/devices/{slavePosition}/cia402/state
+     */
+    transitionToCia402State: (slavePosition: number, data: {
+        /**
+         * The state to bring the drive to.
+         * @example "OperationEnabled"
+         */
+        state: "SwitchOnDisabled" | "ReadyToSwitchOn" | "SwitchedOn" | "OperationEnabled" | "QuickStopActive";
+    }, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<Cia402Status, void>>;
+    /**
+     * @description Drives the CiA402 device-control state machine. "enable" walks every intermediate transition to Operation Enabled (clearing a fault first if needed); "disable" goes to Switch On Disabled; "quickStop" triggers a quick stop; "faultReset" clears a latched fault. The device must be exchanging process data for "enable" to make progress. Returns the resulting control snapshot. Use POST /api/devices/{slavePosition}/cia402/state to name a destination instead of an action — it reaches states these four cannot, and it is the one that will leave a quick stop. "enable" here deliberately will not.
      *
      * @name RunCia402Command
      * @summary Run a CiA402 state-machine command
@@ -798,9 +868,37 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
      * @summary List the files stored on a device
      * @request GET:/api/devices/{slavePosition}/files
      */
-    listDeviceFiles: (slavePosition: number, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<{
-        files: DeviceFile[];
-    }, void>>;
+    listDeviceFiles: (slavePosition: number, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<DeviceFile[], void>>;
+    /**
+     * @description Reads and decodes the device's `.hardware_description` file over FoE — its product id and revision, serial number, the components it is built from, and the assembly it was packaged into. It is also the only source of the descriptor that decides which firmware belongs on the device, which is what most callers want it for (see `/api/devices/{slavePosition}/firmware-compatibility`). **Readable in BOOT as well as PRE-OP and above.** The bootloader deliberately allows this one file, which is what lets a compatibility check work on a drive a failed install left stranded there — precisely when knowing whether the package was the right one matters most.
+     *
+     * @name GetDeviceHardwareDescription
+     * @summary Read what a device says it is
+     * @request GET:/api/devices/{slavePosition}/hardware-description
+     */
+    getDeviceHardwareDescription: (slavePosition: number, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<HardwareDescription, void>>;
+    /**
+     * @description Reads and decodes the device's `.variant` file over FoE — which features the Integro was licensed with. **A 404 is the ordinary answer for most devices.** Only Integro drives carry this file, so the resource being absent is normal rather than a problem. Its one property that matters beyond inspection is `fieldbusProtocol`, which the hardware description deliberately does not carry and a full firmware descriptor ends with.
+     *
+     * @name GetDeviceIntegroVariant
+     * @summary Read a device's Integro variant file
+     * @request GET:/api/devices/{slavePosition}/variant
+     */
+    getDeviceIntegroVariant: (slavePosition: number, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<IntegroVariant, 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.
+     *
+     * @name CheckDeviceFirmwareCompatibility
+     * @summary Check whether a firmware package belongs on a device
+     * @request GET:/api/devices/{slavePosition}/firmware-compatibility
+     */
+    checkDeviceFirmwareCompatibility: (slavePosition: number, query: {
+        /**
+         * The package filename, with no directory part.
+         * @example "package_SOMANET-Circulo-7_8500-04-2332_motion-drive_v5.6.10.zip"
+         */
+        filename: string;
+    }, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<FirmwareCompatibility, void>>;
     /**
      * @description Sends an FoE read request for `filename` to the device at `slavePosition` and returns the raw file bytes.  FoE is available in Boot, Pre-Op, Safe-Op, and Op states (device-dependent); the caller is responsible for ensuring the device is in a suitable state before calling.  The call blocks until the full file has been received or a per-packet timeout of 700 ms is exceeded.
      *
@@ -885,6 +983,30 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
          */
         filename: string;
     }, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<FirmwarePackageName, void>>;
+    /**
+     * @description Decodes a `.hardware_description` supplied in the request body. No device is involved — the same parse a device read uses, so a file saved from one device can be inspected with no hardware present. Three things fail a parse: content that is not JSON, content with no `device` object, and a device carrying no `id` or no `version`. Everything else is accepted as written. Those three required fields are exactly what a descriptor is built from, which is also what makes this a usable type check — arbitrary JSON is rejected rather than yielding an empty descriptor. The `fileVersion` major is reported but not enforced: a bump means "a new parser is needed", but refusing an unknown one would make a drive flashed with a future file unreadable today.
+     *
+     * @name ParseHardwareDescription
+     * @summary Parse a .hardware_description file
+     * @request POST:/api/hardware-description/parse
+     */
+    parseHardwareDescription: (data: string, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<HardwareDescription, void>>;
+    /**
+     * @description Decodes a `.variant` file supplied in the request body. Binary rather than text, hence a `POST` with bytes like `/api/sii/parse` rather than a query like `/api/firmware-package-name`. Trailing bytes past the last option are accepted: the firmware reads only as many options as the count claims and ignores the rest, so refusing padding would reject a file the drive is happy with.
+     *
+     * @name ParseIntegroVariant
+     * @summary Parse a .variant file
+     * @request POST:/api/integro-variant/parse
+     */
+    parseIntegroVariant: (data: File, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<IntegroVariant, void>>;
+    /**
+     * @description Every option an Integro can be licensed with, in code order. Static data: no device, no bus, no request body. Served so a client can explain a decoded file — or simply show what is available — without carrying a second copy of a table that belongs to the firmware. The codes ascend with real gaps, and the catalogue keeps codes current firmware no longer implements, because files written years ago still carry them.
+     *
+     * @name ListIntegroVariantOptions
+     * @summary The whole Integro variant option catalogue
+     * @request GET:/api/integro-variant/options
+     */
+    listIntegroVariantOptions: (params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<IntegroVariantOption[], any>>;
     /**
      * @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.
      *

package/dist/generated/Api.js

@@ -219,6 +219,19 @@ export class Api extends HttpClient {
         format: "json",
         ...params,
     });
+    /**
+     * @description The register map of the Integro's internal (Kübler) encoder — the reference table for POST /api/devices/{slavePosition}/procedures/kuebler-register-communication, and documentation in its own right. Static: it describes the encoder type, not any connected device, so it needs no bus and no scan. Transcribed from the vendor's own draft table. Each entry carries the width, the access type, whether the encoder actually implements it — seven are documented but not implemented — and the vendor's bit definitions verbatim, which for a bit-field register is the only place its meaning is recorded. `format` says how to read the assembled value, because signedness is not uniform and one register is not a single number at all: `unsigned`, `signed`, `bitField` (the number means nothing on its own), or `signedHalves` — two signed 16-bit values packed into 32 bits, which register 0x3C is the only case of. `readableInOneCommand` is false for the one 64-bit register, since the command's length byte caps at 4 bytes.
+     *
+     * @name GetKueblerRegisters
+     * @summary The Integro internal encoder's register map
+     * @request GET:/api/meta/kuebler-registers
+     */
+    getKueblerRegisters = (params = {}) => this.request({
+        path: `/api/meta/kuebler-registers`,
+        method: "GET",
+        format: "json",
+        ...params,
+    });
     /**
      * @description Returns the static catalogue of CoE mailbox error codes defined in ETG.1000.4, Table 30 ("Error Reply Service Data").  A slave returns one of these when the mailbox layer (below a specific protocol such as CoE/FoE) rejects a transfer; the code is embedded in the error text the mailbox endpoints return.
      *
@@ -413,7 +426,20 @@ export class Api extends HttpClient {
         ...params,
     });
     /**
-     * @description Writes the requested operation mode to 0x6060 and returns the resulting control snapshot. The drive reflects the accepted mode in 0x6061 (the modeOfOperation of the response) once it takes effect.
+     * @description Every operation mode the device has, standard and manufacturer-specific, with what the drive says about each. The standard modes are CiA402's (ETG.6010 §6.8.1) and carry the bit of "Supported drive modes" (0x6502) that advertises them, decoded into `supported`. The manufacturer modes are the vendor's own — the negative half of 0x6060 — and are listed only for a device whose vendor this server knows; their `supported` is null, because 0x6502 reserves bits 16-31 for the vendor without defining them, so a drive has no way to advertise one that a master could read. That null means "the drive does not say", not "no". Read this once per device and cache it: it is a static property of the firmware, and the one thing that makes a negative value of 0x6061 nameable rather than "Unknown".
+     *
+     * @name GetOperationModes
+     * @summary List a device's operation modes
+     * @request GET:/api/devices/{slavePosition}/operation-modes
+     */
+    getOperationModes = (slavePosition, params = {}) => this.request({
+        path: `/api/devices/${slavePosition}/operation-modes`,
+        method: "GET",
+        format: "json",
+        ...params,
+    });
+    /**
+     * @description Writes the requested operation mode to 0x6060 and returns the resulting control snapshot. The drive reflects the accepted mode in 0x6061 (the modeOfOperation of the response) once it takes effect. Any value object 0x6060 can hold is accepted, standard or manufacturer-specific — the negative half of that range belongs to the vendor, so a SOMANET's diagnostics (-2) or system identification (-4) go through here like any other. Whether a given drive has the mode is the drive's answer, seen in the modeOfOperation of the response; GET /api/devices/{slavePosition}/operation-modes is what lists them beforehand.
      *
      * @name SetCia402OperationMode
      * @summary Set a device's CiA402 operation mode
@@ -428,7 +454,22 @@ export class Api extends HttpClient {
         ...params,
     });
     /**
-     * @description Drives the CiA402 device-control state machine. "enable" walks every intermediate transition to Operation Enabled (clearing a fault first if needed); "disable" goes to Switch On Disabled; "quickStop" triggers a quick stop; "faultReset" clears a latched fault. The device must be exchanging process data for "enable" to make progress. Returns the resulting control snapshot.
+     * @description Walks the CiA402 device-control state machine to the state you name, issuing whatever transitions that takes and re-reading the drive between each — so multi-hop paths are ordinary: Switch On Disabled up to Operation Enabled, Quick Stop Active back down to Ready To Switch On. Starting from Fault begins with a fault reset, and a fault whose cause is still present is reported as such (with the drive's 0x603F error code) rather than as a timeout. Only the five states a master can command are accepted. Not Ready To Switch On, Fault Reaction Active and Fault are entered by the drive itself and are rejected as a bad request. **Asking for Operation Enabled while the drive is in Quick Stop Active leaves that quick stop** (CiA402 transition 16), because naming the destination is an explicit instruction to go there. The "enable" command on the sibling endpoint deliberately does not, so a procedure preparing a drive cannot undo somebody's stop by accident. The device must be exchanging process data for any of this to progress — the statusword has to update between polls, and the firmware refuses Operation Enabled unless master communication is live. Returns the resulting control snapshot.
+     *
+     * @name TransitionToCia402State
+     * @summary Bring a drive to a CiA402 state
+     * @request POST:/api/devices/{slavePosition}/cia402/state
+     */
+    transitionToCia402State = (slavePosition, data, params = {}) => this.request({
+        path: `/api/devices/${slavePosition}/cia402/state`,
+        method: "POST",
+        body: data,
+        type: ContentType.Json,
+        format: "json",
+        ...params,
+    });
+    /**
+     * @description Drives the CiA402 device-control state machine. "enable" walks every intermediate transition to Operation Enabled (clearing a fault first if needed); "disable" goes to Switch On Disabled; "quickStop" triggers a quick stop; "faultReset" clears a latched fault. The device must be exchanging process data for "enable" to make progress. Returns the resulting control snapshot. Use POST /api/devices/{slavePosition}/cia402/state to name a destination instead of an action — it reaches states these four cannot, and it is the one that will leave a quick stop. "enable" here deliberately will not.
      *
      * @name RunCia402Command
      * @summary Run a CiA402 state-machine command
@@ -605,6 +646,46 @@ export class Api extends HttpClient {
         format: "json",
         ...params,
     });
+    /**
+     * @description Reads and decodes the device's `.hardware_description` file over FoE — its product id and revision, serial number, the components it is built from, and the assembly it was packaged into. It is also the only source of the descriptor that decides which firmware belongs on the device, which is what most callers want it for (see `/api/devices/{slavePosition}/firmware-compatibility`). **Readable in BOOT as well as PRE-OP and above.** The bootloader deliberately allows this one file, which is what lets a compatibility check work on a drive a failed install left stranded there — precisely when knowing whether the package was the right one matters most.
+     *
+     * @name GetDeviceHardwareDescription
+     * @summary Read what a device says it is
+     * @request GET:/api/devices/{slavePosition}/hardware-description
+     */
+    getDeviceHardwareDescription = (slavePosition, params = {}) => this.request({
+        path: `/api/devices/${slavePosition}/hardware-description`,
+        method: "GET",
+        format: "json",
+        ...params,
+    });
+    /**
+     * @description Reads and decodes the device's `.variant` file over FoE — which features the Integro was licensed with. **A 404 is the ordinary answer for most devices.** Only Integro drives carry this file, so the resource being absent is normal rather than a problem. Its one property that matters beyond inspection is `fieldbusProtocol`, which the hardware description deliberately does not carry and a full firmware descriptor ends with.
+     *
+     * @name GetDeviceIntegroVariant
+     * @summary Read a device's Integro variant file
+     * @request GET:/api/devices/{slavePosition}/variant
+     */
+    getDeviceIntegroVariant = (slavePosition, params = {}) => this.request({
+        path: `/api/devices/${slavePosition}/variant`,
+        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.
+     *
+     * @name CheckDeviceFirmwareCompatibility
+     * @summary Check whether a firmware package belongs on a device
+     * @request GET:/api/devices/{slavePosition}/firmware-compatibility
+     */
+    checkDeviceFirmwareCompatibility = (slavePosition, query, params = {}) => this.request({
+        path: `/api/devices/${slavePosition}/firmware-compatibility`,
+        method: "GET",
+        query: query,
+        format: "json",
+        ...params,
+    });
     /**
      * @description Sends an FoE read request for `filename` to the device at `slavePosition` and returns the raw file bytes.  FoE is available in Boot, Pre-Op, Safe-Op, and Op states (device-dependent); the caller is responsible for ensuring the device is in a suitable state before calling.  The call blocks until the full file has been received or a per-packet timeout of 700 ms is exceeded.
      *
@@ -686,6 +767,48 @@ export class Api extends HttpClient {
         format: "json",
         ...params,
     });
+    /**
+     * @description Decodes a `.hardware_description` supplied in the request body. No device is involved — the same parse a device read uses, so a file saved from one device can be inspected with no hardware present. Three things fail a parse: content that is not JSON, content with no `device` object, and a device carrying no `id` or no `version`. Everything else is accepted as written. Those three required fields are exactly what a descriptor is built from, which is also what makes this a usable type check — arbitrary JSON is rejected rather than yielding an empty descriptor. The `fileVersion` major is reported but not enforced: a bump means "a new parser is needed", but refusing an unknown one would make a drive flashed with a future file unreadable today.
+     *
+     * @name ParseHardwareDescription
+     * @summary Parse a .hardware_description file
+     * @request POST:/api/hardware-description/parse
+     */
+    parseHardwareDescription = (data, params = {}) => this.request({
+        path: `/api/hardware-description/parse`,
+        method: "POST",
+        body: data,
+        type: ContentType.Text,
+        format: "json",
+        ...params,
+    });
+    /**
+     * @description Decodes a `.variant` file supplied in the request body. Binary rather than text, hence a `POST` with bytes like `/api/sii/parse` rather than a query like `/api/firmware-package-name`. Trailing bytes past the last option are accepted: the firmware reads only as many options as the count claims and ignores the rest, so refusing padding would reject a file the drive is happy with.
+     *
+     * @name ParseIntegroVariant
+     * @summary Parse a .variant file
+     * @request POST:/api/integro-variant/parse
+     */
+    parseIntegroVariant = (data, params = {}) => this.request({
+        path: `/api/integro-variant/parse`,
+        method: "POST",
+        body: data,
+        format: "json",
+        ...params,
+    });
+    /**
+     * @description Every option an Integro can be licensed with, in code order. Static data: no device, no bus, no request body. Served so a client can explain a decoded file — or simply show what is available — without carrying a second copy of a table that belongs to the firmware. The codes ascend with real gaps, and the catalogue keeps codes current firmware no longer implements, because files written years ago still carry them.
+     *
+     * @name ListIntegroVariantOptions
+     * @summary The whole Integro variant option catalogue
+     * @request GET:/api/integro-variant/options
+     */
+    listIntegroVariantOptions = (params = {}) => this.request({
+        path: `/api/integro-variant/options`,
+        method: "GET",
+        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.
      *

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

@@ -1,3 +1,4 @@
+type UtilRequiredKeys<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
 /** A CiA402 drive's control snapshot — its state machine, control words, and mode. */
 export interface Cia402Status {
     /**
@@ -26,11 +27,69 @@ export interface Cia402Status {
      */
     modeName: string;
     /**
-     * The setpoint currently commanded for the active mode — target position 0x607A (PP/CSP), velocity 0x60FF (PV/CSV), or torque 0x6071 (PT/CST), widened to INTEGER32. 0 only when the active mode has no linear setpoint (NoMode / Homing).
+     * The setpoint currently commanded for the active mode — target position 0x607A (PP/CSP), velocity 0x60FF (PV/CSV), or torque 0x6071 (PT/CST), widened to INTEGER32. 0 only when the active mode has no linear setpoint (NoMode / Homing / vl / ip).
      * @example 100000
      */
     target: number;
 }
+/** Every operation mode a device has, with what its "Supported drive modes" field (0x6502) says about each. */
+export interface OperationModes {
+    /**
+     * Object 0x6502 verbatim, as an UNSIGNED32.
+     * @example 197549
+     */
+    supportedDriveModes: number;
+    /**
+     * The set bits of 0x6502 from bit 16 upwards, reported as bit numbers and nothing more. The profile leaves their meaning entirely to the vendor, so nothing here can decode them — a SOMANET drive sets bits 16 and 17 and publishes no definition for either.
+     * @example [16,17]
+     */
+    manufacturerBits: number[];
+    /** Every mode, ascending by value — manufacturer modes first, then standard. */
+    modes: OperationMode[];
+}
+/** One operation mode of one device. */
+export interface OperationMode {
+    /**
+     * The value written to 0x6060 / read from 0x6061. Negative for a vendor mode.
+     * @example -2
+     */
+    value: number;
+    /**
+     * PascalCase identifier, matching the modeName of GET /api/devices/{n}/cia402.
+     * @example "Diagnostics"
+     */
+    name: string;
+    /**
+     * The profile's or the vendor's own wording, for a user-facing list.
+     * @example "Diagnostics mode"
+     */
+    label: string;
+    /**
+     * Whether CiA402 or the vendor defines this mode.
+     * @example "manufacturer"
+     */
+    kind: "standard" | "manufacturer";
+    /**
+     * The bit of 0x6502 that advertises this mode. Null for every manufacturer mode, and for NoMode, which is always legal and so has no bit.
+     * @example 7
+     */
+    bit: number | null;
+    /**
+     * The profile's short form (pp, vl, pv, tq, hm, ip, csp, csv, cst, cstca).
+     * @example "csp"
+     */
+    abbreviation: string | null;
+    /**
+     * Whether the drive advertises this mode. Null for every manufacturer mode — 0x6502 has no bit a master could read for one — which means "the drive does not say", not "no".
+     * @example true
+     */
+    supported: boolean | null;
+    /**
+     * Present and true only for a mode the vendor's firmware marks deprecated.
+     * @example true
+     */
+    deprecated?: boolean;
+}
 /** Point-in-time health of the real-time game loop. Times are nanoseconds; rates are hertz. All fields are diagnostic (relaxed reads), not synchronised. */
 export interface GameLoopHealth {
     /**
@@ -583,40 +642,224 @@ export interface FirmwarePackageName {
      */
     hardwareName: string;
     /**
-     * The full firmware descriptor, verbatim.
+     * The hardware this package is built for, verbatim — the string a compatibility check compares.
      * @example "8500-04-2332"
      */
-    firmwareId: string;
+    fullFirmwareDescriptor: string;
     /**
-     * Software name.
+     * Firmware or software name.
      * @example "motion-drive"
      */
-    firmwareName: string;
+    softwareName: string;
     /**
-     * Software version, including the leading `v`.
+     * The firmware or software version, including the leading `v`. Not to be confused with `firmwareVersion`, which is the *hardware* revision inside the descriptor.
      * @example "v5.6.10"
      */
-    firmwareVersion: string;
+    softwareVersion: string;
     /**
-     * Product id from the descriptor.
-     * @example 8500
+     * Firmware id from the descriptor — the hardware product.
+     * @example "8500"
      */
-    productId?: number;
+    firmwareId?: string;
     /**
-     * Product version from the descriptor.
-     * @example 4
+     * Hardware revision from the descriptor. A string, so a leading zero survives: `04` read as a number and printed back would be `4`, and `8500-4` matches no package.
+     * @example "04"
+     */
+    firmwareVersion?: string;
+    /**
+     * Firmware encryption key id from the descriptor. A string because real packages carry non-numeric ones, e.g. `A`.
+     * @example "2332"
+     */
+    keyId?: string;
+    /**
+     * Fieldbus protocol character from the descriptor, hexadecimal. `1` is EtherCAT.
+     * @example "1"
      */
-    productVersion?: number;
+    fieldbusProtocol?: string;
     /**
-     * Firmware encryption key id from the descriptor.
-     * @example 2332
+     * `firmwareId` and `firmwareVersion` joined — the descriptor without the key or fieldbus. Useful for saying *how* a package missed: a matching build descriptor with a different key means right hardware, wrong encryption key.
+     * @example "8500-04"
      */
-    keyId?: number;
+    buildDescriptor?: string;
+}
+/** One item making up a device or assembly. Carries no function beyond recording what has a serial number, so every property can legitimately be empty. */
+export interface HardwareComponent {
+    /** @example "Com EtherCAT" */
+    name: string;
+    /** @example "A.2" */
+    version: string;
+    /** @example "1000-02-0005739-1815" */
+    serialNumber: string;
+}
+/** A device or an assembly. The two are one shape — the specification lists their fields in a single table and they differ only in that `keyId` and `macAddress` are device-only. */
+export interface HardwareProduct {
+    /**
+     * Human-readable description of the hardware.
+     * @example "SOMANET Servo Node 400 EtherCAT"
+     */
+    name: string;
+    /**
+     * Names the product's picture. Empty when the file carries none.
+     * @example "9501-xx"
+     */
+    imageId: string;
     /**
-     * Fieldbus protocol from the descriptor, decoded as hexadecimal. 1 is EtherCAT.
+     * The `firmwareId` — identifies the hardware product.
+     * @example "9501"
+     */
+    id: string;
+    /**
+     * The `firmwareVersion` — revision of that product.
+     * @example "01"
+     */
+    version: string;
+    /**
+     * Firmware encryption key burned to OTP memory. Device only, and empty on hardware whose firmware predates encryption.
+     * @example "4622"
+     */
+    keyId: string;
+    /** @example "9501-01-040595-4023" */
+    serialNumber: string;
+    /**
+     * MAC address of the Ethernet port. Device only.
+     * @example "01-23-45-67-89-AB"
+     */
+    macAddress: string;
+    components: HardwareComponent[];
+    /**
+     * `id` and `version` joined by a dash.
+     * @example "9501-01"
+     */
+    buildDescriptor: string;
+}
+/**
+ * A device's `.hardware_description` file — what the hardware says it is, and the source of the descriptor that decides which firmware belongs on it.
+ *
+ * `device` is never absent, and that is structural rather than a simplification: the file lives *on* the device, so a file without one cannot exist. `assembly` is present only when the device was packaged into a product — an ACTILINK is an assembly with a SOMANET Node device inside it — and when it is, it is what firmware is matched against first.
+ */
+export interface HardwareDescription {
+    /**
+     * Format version of the file itself, semver.
+     * @example "1.2.0"
+     */
+    fileVersion: string;
+    /** A device or an assembly. The two are one shape — the specification lists their fields in a single table and they differ only in that `keyId` and `macAddress` are device-only. */
+    device: HardwareProduct;
+    /** A device or an assembly. The two are one shape — the specification lists their fields in a single table and they differ only in that `keyId` and `macAddress` are device-only. */
+    assembly?: HardwareProduct;
+}
+/** One entry of the Integro runtime-variant option catalogue. Nothing on the server acts on `socVariables` or `incompatibleOptionIds` — the drive enforces them — but they are what make a decoded file legible. */
+export interface IntegroVariantOption {
+    /**
+     * The option code as it appears in the file.
+     * @example 1
+     */
+    id: number;
+    /**
+     * What the option selects.
+     * @example "Fieldbus Protocol"
+     */
+    category: string;
+    /**
+     * Which choice within that category.
+     * @example "EtherCAT"
+     */
+    meaning: string;
+    /**
+     * The drive's own configuration values this option sets. Empty for an option the fieldbus firmware acts on rather than the SoC.
+     * @example ["adc_phase_current_sensor_gain"]
+     */
+    socVariables: string[];
+    /**
+     * Options that cannot be selected alongside this one — the other members of a category that selects exactly one choice. Empty for an independent flag such as "disable DI1".
+     * @example [0,2,3,39]
+     */
+    incompatibleOptionIds: number[];
+    /**
+     * Segments of the part number this option corresponds to. Empty for an option not distinguished in the part number.
+     * @example ["EC"]
+     */
+    mpnSegmentCodes: string[];
+}
+/** 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 decoded `.variant` file: which features a SOMANET Integro was licensed with.
+ *
+ * Only Integro drives carry one. Its layout comes from the firmware that reads it rather than from a specification — there is none — and the one thing on it that matters beyond inspection is `fieldbusProtocol`, which the hardware description deliberately does not carry and a full firmware descriptor ends with.
+ */
+export interface IntegroVariant {
+    /**
+     * Format version; 1 in every file seen so far.
+     * @example 1
+     */
+    fileVersion: number;
+    /** Lowercase hex. Opaque — verification needs the private key and happens on the drive — and reported only so a caller can see whether one is present. */
+    signature: string;
+    /**
+     * Lowercase hex netX chip id this file was issued for.
+     * @example "4e64646c70b286a000000000"
+     */
+    chipId: string;
+    /** @example "9004-02-0000424-2445" */
+    serialNumber: string;
+    /** @example "40:49:8A:01:21:D6" */
+    macAddress: string;
+    /**
+     * Who the device was licensed to.
+     * @example 1
+     */
+    customerId: number;
+    /**
+     * Raw mode value. `passive` (0x51) is the failure state as much as a mode: firmware falls back to it when the file is missing, its signature does not verify, or its chip id belongs to another device.
+     * @example 87
+     */
+    operationMode: number;
+    /** @example "live" */
+    operationModeName: "passive" | "trial" | "production" | "live" | "unknown";
+    /**
+     * The fieldbus the device is licensed for, for the tail of a full firmware descriptor. **EtherCAT wins when several are selected** — real files do carry more than one. Absent when the file selects no fieldbus at all.
      * @example 1
      */
     fieldbusProtocol?: number;
+    /** The option codes, in the order the file lists them — which is not sorted, and is the only record of how the file was written. */
+    options: IntegroVariantFileOption[];
+}
+/** The full firmware descriptors one device accepts firmware under. Two rather than one because the specification says both are compatible and lists both for the user to choose from: the assembly's firmware "should have been customized for the assembly", so it is the one to prefer, while the device package is the generic build for the hardware inside it. */
+export interface FullFirmwareDescriptors {
+    /**
+     * The device's own descriptor. Always present.
+     * @example "9010-02-2423-1"
+     */
+    device: string;
+    /**
+     * The assembly's build descriptor with the **device's** key id — assemblies have no key of their own. Absent when the hardware description carries no assembly.
+     * @example "6000-01-2423-1"
+     */
+    assembly?: string;
+}
+/**
+ * Whether one firmware package belongs on one device.
+ *
+ * **The whole descriptor string is compared, never its decoded parts.** That is what makes the check correct for descriptors outside the numeric convention, and it is how the specification frames the operation — find compatible firmware by searching for the `fullFirmwareDescriptor` string.
+ */
+export interface FirmwareCompatibility {
+    /** @example true */
+    compatible: boolean;
+    /**
+     * Which of the device's descriptors matched. `device` is a match that still has something to say: it is the generic build rather than the one customised for the assembly.
+     * @example "assembly"
+     */
+    match: "none" | "assembly" | "device";
+    /** A SOMANET firmware package filename broken into its fields. The four decoded-descriptor properties are absent — not null — when the full firmware descriptor is not the numeric kind, which the naming specification explicitly allows. */
+    packageName: FirmwarePackageName;
+    /** The full firmware descriptors one device accepts firmware under. Two rather than one because the specification says both are compatible and lists both for the user to choose from: the assembly's firmware "should have been customized for the assembly", so it is the one to prefer, while the device package is the generic build for the hardware inside it. */
+    deviceDescriptors: FullFirmwareDescriptors;
+    /**
+     * One sentence naming the descriptors involved, ready to show a user. Populated for a match as well as a mismatch.
+     * @example "This package is built for 6000-01-2423-1, which is this device's assembly."
+     */
+    explanation: 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 {
@@ -1476,3 +1719,4 @@ export interface EsiParseResult {
     /** 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[];
 }
+export {};

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './generated/http-client.js';
 export * from './generated/data-contracts.js';
 export * from './generated/Api.js';
+export * from './api-error.js';
 export * from './constants.js';
 export * from './web-socket-connection.js';
 export * from './client.js';

package/dist/index.js

@@ -5,6 +5,7 @@
 export * from './generated/http-client.js';
 export * from './generated/data-contracts.js';
 export * from './generated/Api.js';
+export * from './api-error.js';
 export * from './constants.js';
 export * from './web-socket-connection.js';
 export * from './client.js';

package/package.json

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