@synapticon/motion-master-client 6.0.0-alpha.84 → 6.0.0-alpha.85

package/dist/eni.d.ts

@@ -0,0 +1,197 @@
+export interface EniExport {
+    xml: string;
+    warnings: number;
+}
+export declare function fetchEni(baseUrl: string, options?: {
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<EniExport>;
+export interface EniBytes {
+    hex: string;
+    bytes: number;
+}
+export interface EniRegisterAnnotation {
+    name: string;
+    description: string;
+    instance?: number;
+    decoded?: Record<string, number | boolean | string>;
+    requestsState?: string;
+    waitsForState?: string;
+}
+export interface EniInitCmd {
+    transitions?: string[];
+    states?: string[];
+    inputOffs?: number;
+    outputOffs?: number;
+    cmd: number;
+    cmdName: string;
+    beforeSlave?: boolean;
+    comment?: string;
+    requires?: string;
+    adp?: number;
+    ado?: number;
+    addr?: number;
+    data?: EniBytes;
+    dataLength?: number;
+    cnt?: number;
+    retries?: number;
+    timeoutMs?: number;
+    validate?: {
+        data: EniBytes;
+        dataMask?: EniBytes;
+        timeoutMs: number;
+    };
+    register?: EniRegisterAnnotation;
+}
+export interface EniCoeCmd {
+    transitions: string[];
+    timeoutMs: number;
+    ccs: number;
+    ccsName: 'download' | 'upload';
+    index: number;
+    subindex: number;
+    comment?: string;
+    data?: EniBytes;
+    disabled?: boolean;
+}
+export interface EniPdoEntry {
+    index: number;
+    subindex: number;
+    bitLen: number;
+    name?: string;
+    dataType?: string;
+    comment?: string;
+}
+export interface EniPdo {
+    index: number;
+    name: string;
+    syncManager?: number;
+    fixed?: boolean;
+    mandatory?: boolean;
+    entries: EniPdoEntry[];
+}
+export interface EniSyncManager {
+    index: number;
+    type: string;
+    startAddress: number;
+    controlByte: number;
+    enable: boolean;
+    minSize?: number;
+    maxSize?: number;
+    defaultSize?: number;
+    watchdog?: number;
+}
+export interface EniMailboxWindow {
+    start: number;
+    length: number;
+    pollTime?: number;
+    statusBitAddr?: number;
+}
+export interface EniSlave {
+    info: {
+        name: string;
+        physAddr: number;
+        autoIncAddr: number;
+        physics: string;
+        vendorId: number;
+        productCode: number;
+        revisionNo: number;
+        serialNo: number;
+    };
+    processData?: {
+        send?: {
+            bitStart: number;
+            bitLength: number;
+        };
+        recv?: {
+            bitStart: number;
+            bitLength: number;
+        };
+        syncManagers: EniSyncManager[];
+        rxPdos?: EniPdo[];
+        txPdos?: EniPdo[];
+    };
+    mailbox?: {
+        send: EniMailboxWindow;
+        recv: EniMailboxWindow;
+        bootstrap?: {
+            send: EniMailboxWindow;
+            recv: EniMailboxWindow;
+        };
+        protocols: string[];
+        coeInitCmds: EniCoeCmd[];
+    };
+    initCmds: EniInitCmd[];
+    previousPorts?: {
+        port: string;
+        selected: boolean;
+        physAddr?: number;
+        deviceId?: number;
+    }[];
+    dc?: {
+        potentialReferenceClock?: boolean;
+        referenceClock?: boolean;
+        cycleTime0Ns?: number;
+        cycleTime1Ns?: number;
+        shiftTimeNs?: number;
+    };
+}
+export interface EniVariable {
+    name: string;
+    bitSize: number;
+    bitOffs: number;
+    comment?: string;
+    dataType?: string;
+}
+export interface EniNetwork {
+    master: {
+        name: string;
+        destination: string;
+        source: string;
+        etherType?: number;
+        mailboxStates?: {
+            startAddr: number;
+            count: number;
+        };
+        eoe?: {
+            maxPorts: number;
+            maxFrames: number;
+            maxMacs: number;
+        };
+        initCmds: EniInitCmd[];
+    };
+    slaves: EniSlave[];
+    cyclic?: {
+        comment?: string;
+        taskId?: string;
+        cycleTimeUs?: number;
+        priority?: number;
+        frames: {
+            comment?: string;
+            cmds: EniInitCmd[];
+        }[];
+    };
+    processImage?: {
+        inputs?: {
+            byteSize: number;
+            variables: EniVariable[];
+        };
+        outputs?: {
+            byteSize: number;
+            variables: EniVariable[];
+        };
+    };
+}
+export interface EniParseResult {
+    network: EniNetwork;
+    warnings: string[];
+    summary: {
+        devices: number;
+        datagrams: number;
+        coeTransfers: number;
+    };
+}
+export declare function parseEni(baseUrl: string, xml: string, options?: {
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<EniParseResult>;

package/dist/eni.js

@@ -0,0 +1,61 @@
+// EtherCAT Network Information (ENI) export.
+//
+// The generated client types `GET /api/eni` as a `File`, which is what swagger-typescript-api makes
+// of a binary response. An ENI is text, and what a caller wants is the document plus the warning
+// count that came with it, so this wraps the call.
+/// Exports the bus as an ENI document (`GET /api/eni`). `baseUrl` is the HTTP API origin (e.g.
+/// `https://host:61447`). Throws on a non-OK response, with the response body's `error` message
+/// when there is one — a bus that has not reached SAFE-OP or OP answers 409, because before that
+/// there is no mapping to describe. Pass `fetch` to inject an implementation (Node, request
+/// logging).
+export async function fetchEni(baseUrl, options = {}) {
+    const doFetch = options.fetch ?? fetch;
+    const res = await doFetch(`${baseUrl.replace(/\/+$/, '')}/api/eni`, {
+        headers: { Accept: 'application/xml' },
+        signal: options.signal,
+    });
+    if (!res.ok) {
+        let message = `HTTP ${res.status}`;
+        try {
+            const body = (await res.json());
+            if (body?.error) {
+                message = body.error;
+            }
+        }
+        catch {
+            // Non-JSON error body — keep the status message.
+        }
+        throw new Error(message);
+    }
+    const warnings = Number.parseInt(res.headers.get('X-Eni-Warnings') ?? '0', 10);
+    return {
+        xml: await res.text(),
+        warnings: Number.isFinite(warnings) ? warnings : 0,
+    };
+}
+/// Parses an ENI document (`POST /api/eni/parse`). `baseUrl` is the HTTP API origin. The document
+/// need not have come from this server — reading one another tool wrote is the point. Throws on a
+/// non-OK response, with the server's `error` message when there is one.
+export async function parseEni(baseUrl, xml, options = {}) {
+    const doFetch = options.fetch ?? fetch;
+    const res = await doFetch(`${baseUrl.replace(/\/+$/, '')}/api/eni/parse`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/xml' },
+        body: xml,
+        signal: options.signal,
+    });
+    if (!res.ok) {
+        let message = `HTTP ${res.status}`;
+        try {
+            const body = (await res.json());
+            if (body?.error) {
+                message = body.error;
+            }
+        }
+        catch {
+            // Non-JSON error body — keep the status message.
+        }
+        throw new Error(message);
+    }
+    return (await res.json());
+}

package/dist/generated/Api.d.ts

@@ -1122,6 +1122,27 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
      * @request GET:/api/integro-variant/options
      */
     listIntegroVariantOptions: (params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<IntegroVariantOption[], any>>;
+    /**
+     * @description Decodes an ENI document supplied in the request body. No device is involved, and that is the point: the useful case is reading a configuration somebody else's tool wrote — acontis EC-Engineer, TwinCAT — rather than the one this master exports from `GET /api/eni`. **An ENI is a script, not a description.** Every configuration step in it is an EtherCAT datagram or a CoE download tagged with the AL-state transition it belongs to, so a listing of the raw elements would show `FPWR to 2064, data 0018060064000100` and leave the reading undone. Each datagram therefore carries a `register` object naming what its `ado` selects, with the instance for a repeating block, and `decoded` fields where the payload is a sync-manager or FMMU register block. A write to AL Control reports `requestsState`, and the read that follows it reports `waitsForState`. Every enumeration is spelled out beside its value — `cmd` 5 with `cmdName` `FPWR`, transitions as `IP`/`PS`/`SO` — and every payload carries its hex beside its byte count, because the reader of this JSON is a person rather than a master. Tolerant by design. Only three things fail: XML that will not parse, a root that is not `EtherCATConfig`, and a missing `Config`. Anything else costs that value and a line in `warnings`, including an element this model has no room for. The sample documents ETG itself ships need that tolerance: two of them omit elements their own schema marks mandatory, and a previous port of `A` is spec-legal while ENI Schema 1.7 enumerates only `B`, `C` and `D`.
+     *
+     * @name ParseEni
+     * @summary Parse an EtherCAT Network Information (ENI) file
+     * @request POST:/api/eni/parse
+     */
+    parseEni: (data: string, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<{
+        /** The master, every device, the cyclic frame and the process image, keyed by the model's own field names. */
+        network: object;
+        /** One line per element seen and not modelled, or per value that would not decode. Each names a place in the document. */
+        warnings: string[];
+        summary: {
+            /** Devices in the document */
+            devices: number;
+            /** EtherCAT init commands, master and devices together */
+            datagrams: number;
+            /** CoE init commands, which live under a device's mailbox */
+            coeTransfers: number;
+        };
+    }, 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.
      *
@@ -1490,6 +1511,22 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
      * @request GET:/api/bus-config
      */
     getBusConfig: (params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<SlaveConfig[], any>>;
+    /**
+     * @description Returns the bus as an ENI document, the vendor-neutral configuration a third-party master (acontis EC-Master, TwinCAT, CODESYS) replays to bring the same bus up. Where an ESI file describes one device family, an ENI describes one assembled network, and it is imperative rather than declarative: every configuration step is an EtherCAT datagram or a CoE download tagged with the AL-state transition it belongs to. The document carries each device's identity and addresses, its Sync Manager and FMMU register writes, its mailbox windows, its PDO assignment as CoE downloads, the AL-state walk with a read that holds the master until the device arrives, the cyclic frame, and the named process image. Conforms to ENI Schema 1.7 (ETG.2100). The bus must be configured. FMMUs and logical addresses come into being at the SAFE-OP transition, so a bus in PRE-OP has no mapping to describe and the call returns 409. **This drives the bus.** Each device's SII is read for its port layout and bootstrap mailbox, and its PDO assignment is read over CoE, so the call costs one EEPROM read and a short burst of SDO uploads per device. It is an export action, not an accessor. Distributed clocks are left out, so the generated configuration runs in free-run — which is how Motion Master runs the bus itself. The `DC` element needs an `AssignActivate` word, and a SOMANET drive does not carry the SII category that holds one. `X-Eni-Warnings` counts the parts that were asked for and not answered; each is also logged. A warning costs one optional element, never the document: a device whose SII will not read keeps every init command.
+     *
+     * @name ExportEni
+     * @summary Export the bus as an EtherCAT Network Information (ENI) file
+     * @request GET:/api/eni
+     */
+    exportEni: (params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<File, {
+        /** Human-readable reason the export could not be produced */
+        error: string;
+    } | {
+        /** The field that could not be written */
+        error: string;
+    } | {
+        error: string;
+    }>>;
     /**
      * @description Returns every registered monitoring as a resource — its configuration plus, per parameter, how its value is sourced, and the current buffer fill.
      *

package/dist/generated/Api.js

@@ -875,6 +875,20 @@ export class Api extends HttpClient {
         format: "json",
         ...params,
     });
+    /**
+     * @description Decodes an ENI document supplied in the request body. No device is involved, and that is the point: the useful case is reading a configuration somebody else's tool wrote — acontis EC-Engineer, TwinCAT — rather than the one this master exports from `GET /api/eni`. **An ENI is a script, not a description.** Every configuration step in it is an EtherCAT datagram or a CoE download tagged with the AL-state transition it belongs to, so a listing of the raw elements would show `FPWR to 2064, data 0018060064000100` and leave the reading undone. Each datagram therefore carries a `register` object naming what its `ado` selects, with the instance for a repeating block, and `decoded` fields where the payload is a sync-manager or FMMU register block. A write to AL Control reports `requestsState`, and the read that follows it reports `waitsForState`. Every enumeration is spelled out beside its value — `cmd` 5 with `cmdName` `FPWR`, transitions as `IP`/`PS`/`SO` — and every payload carries its hex beside its byte count, because the reader of this JSON is a person rather than a master. Tolerant by design. Only three things fail: XML that will not parse, a root that is not `EtherCATConfig`, and a missing `Config`. Anything else costs that value and a line in `warnings`, including an element this model has no room for. The sample documents ETG itself ships need that tolerance: two of them omit elements their own schema marks mandatory, and a previous port of `A` is spec-legal while ENI Schema 1.7 enumerates only `B`, `C` and `D`.
+     *
+     * @name ParseEni
+     * @summary Parse an EtherCAT Network Information (ENI) file
+     * @request POST:/api/eni/parse
+     */
+    parseEni = (data, params = {}) => this.request({
+        path: `/api/eni/parse`,
+        method: "POST",
+        body: data,
+        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.
      *
@@ -1054,6 +1068,18 @@ export class Api extends HttpClient {
         format: "json",
         ...params,
     });
+    /**
+     * @description Returns the bus as an ENI document, the vendor-neutral configuration a third-party master (acontis EC-Master, TwinCAT, CODESYS) replays to bring the same bus up. Where an ESI file describes one device family, an ENI describes one assembled network, and it is imperative rather than declarative: every configuration step is an EtherCAT datagram or a CoE download tagged with the AL-state transition it belongs to. The document carries each device's identity and addresses, its Sync Manager and FMMU register writes, its mailbox windows, its PDO assignment as CoE downloads, the AL-state walk with a read that holds the master until the device arrives, the cyclic frame, and the named process image. Conforms to ENI Schema 1.7 (ETG.2100). The bus must be configured. FMMUs and logical addresses come into being at the SAFE-OP transition, so a bus in PRE-OP has no mapping to describe and the call returns 409. **This drives the bus.** Each device's SII is read for its port layout and bootstrap mailbox, and its PDO assignment is read over CoE, so the call costs one EEPROM read and a short burst of SDO uploads per device. It is an export action, not an accessor. Distributed clocks are left out, so the generated configuration runs in free-run — which is how Motion Master runs the bus itself. The `DC` element needs an `AssignActivate` word, and a SOMANET drive does not carry the SII category that holds one. `X-Eni-Warnings` counts the parts that were asked for and not answered; each is also logged. A warning costs one optional element, never the document: a device whose SII will not read keeps every init command.
+     *
+     * @name ExportEni
+     * @summary Export the bus as an EtherCAT Network Information (ENI) file
+     * @request GET:/api/eni
+     */
+    exportEni = (params = {}) => this.request({
+        path: `/api/eni`,
+        method: "GET",
+        ...params,
+    });
     /**
      * @description Returns every registered monitoring as a resource — its configuration plus, per parameter, how its value is sourced, and the current buffer fill.
      *

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './constants.js';
 export * from './web-socket-connection.js';
 export * from './client.js';
 export * from './lan.js';
+export * from './eni.js';
 export * from './hex.js';
 export * from './sdo.js';
 export * from './mmpd.js';

package/dist/index.js

@@ -10,9 +10,10 @@ export * from './constants.js';
 export * from './web-socket-connection.js';
 export * from './client.js';
 // Pure, framework-agnostic helpers (no DOM/React): hex formatting, CoE SDO value
-// encode/decode, SOMANET file-list parsing, and the LAN hostname mapping that lets a browser
-// reach a server on another machine under a name the bundled certificate covers.
+// encode/decode, SOMANET file-list parsing, the ENI export, and the LAN hostname mapping that lets
+// a browser reach a server on another machine under a name the bundled certificate covers.
 export * from './lan.js';
+export * from './eni.js';
 export * from './hex.js';
 export * from './sdo.js';
 export * from './mmpd.js';

package/package.json

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