@synapticon/motion-master-client 6.0.0-alpha.97 → 6.0.0-alpha.99

package/dist/generated/Api.d.ts

@@ -1,4 +1,4 @@
-import { AlStatusCode, AutoTuningError, AutoTuningRunRequest, AutoTuningRunResponse, AutoTuningStatus, BrakeState, Cia402Status, DcSyncStatus, DeviceDiagnostics, DeviceFile, DeviceParameter, Encoders, EscRegister, EsiParseResult, FirmwareCompatibility, FirmwarePackageName, FoeErrorCode, GameLoopHealth, HardwareDescription, HrdRecording, IntegroVariant, IntegroVariantOption, MailboxErrorCode, Monitoring, ObjectDataTypeInfo, OperationModes, OutputStageResult, ParameterCacheEntry, ParameterValue, PdoMapping, PdoMappingRequest, ProcedureListing, ProcedureRequest, ProcedureSnapshot, ProcessDataWatchdog, ProcessImageObject, SdoAbortCode, SlaveConfig, SlaveInformationInterface, UserCacheListing } from "./data-contracts.js";
+import { AlStatusCode, AutoTuningError, AutoTuningRunRequest, AutoTuningRunResponse, AutoTuningStatus, BrakeState, CaptureSummary, Cia402Status, DcSyncStatus, DeviceDiagnostics, DeviceFile, DeviceParameter, Encoders, EscRegister, EsiParseResult, FirmwareCompatibility, FirmwarePackageName, FoeErrorCode, GameLoopHealth, HardwareDescription, HrdRecording, IntegroVariant, IntegroVariantOption, MailboxErrorCode, Monitoring, ObjectDataTypeInfo, OperationModes, OutputStageResult, ParameterCacheEntry, ParameterValue, PdoMapping, PdoMappingRequest, ProcedureListing, ProcedureRequest, ProcedureSnapshot, ProcessDataWatchdog, ProcessImageObject, SdoAbortCode, SlaveConfig, SlaveInformationInterface, UserCacheListing } from "./data-contracts.js";
 import { HttpClient, RequestParams } from "./http-client.js";
 export declare class Api<SecurityDataType = unknown> extends HttpClient<SecurityDataType> {
     /**
@@ -307,6 +307,17 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
          * @example false
          */
         parametersUnavailable: boolean;
+        /**
+         * The low byte of ESC register 0x0000, which names the slave controller family: 0x85 is a netX (Integro), 0xC0 the controller of a Circulo, 0x90 a TI PRU-ICSS (Jasper). Null when the register could not be read at the scan, and over SPoE.
+         * @format int32
+         * @example 192
+         */
+        escType?: number | null;
+        /**
+         * Whether Motion Master writes each mailbox request to this device once and never sends it again. True for a Synapticon or Sensodrive device whose ESC type is not 0x85, because its EtherCAT stack locks its receive mailbox when it gets one request twice. False for a netX, which discards a repeat, and for every other vendor, where a write with no frame back is sent again.
+         * @example true
+         */
+        mailboxWriteOnce?: boolean;
         /**
          * Whether the device has an EtherCAT Slave Controller: SII, ESC registers, distributed clocks and the ESC diagnostics. False over SPoE, where those endpoints answer 409.
          * @example true
@@ -1320,6 +1331,54 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
          */
         error: string;
     }>>;
+    /**
+     * @description Runs the capture program `motion-master-capture`, which ships beside the server binary, on the adapter the bus is on, waits for it to exit, and answers the summary. The program records every EtherCAT frame that leaves or enters the adapter with a kernel timestamp and writes them as a pcap file under `captures/` in the user cache, so the file is listed, downloaded and deleted through the `/api/user-cache` routes and opens in Wireshark. The summary matches each frame the master sent to the frame that came back for it, by the index and the header of its first datagram, and reports per kind of frame how late the returns were. The cyclic process-data frame is one kind; mailbox and register datagrams, the control plane, are the other. The bands are the three waits the driver uses, 2 ms, 20 ms and 100 ms, and they are cumulative: a frame later than 100 ms counts in all three. A frame sent again with the same index and header while its first copy had no answer counts once, as `resent`, and its return is timed from the first copy. The time is the kernel's, taken at the boundary to the NIC driver on both sides: when the frame is handed to the driver, and when the driver hands its return back. So the number covers the NIC, the wire and the device, and not the host's own queues and scheduling between that boundary and Motion Master. A capture that shows late frames puts the delay on the wire or in the device. A clean capture beside the server's own warnings, "mailbox write(s) got no frame back", puts it inside the host. Read the two together. One capture at a time. The capture adds no frame to the bus and runs on a thread of its own, so the bus is not touched. The program needs `CAP_NET_RAW`, which the packages grant it at install.
+     *
+     * @name RunCapture
+     * @summary Record the EtherCAT frames of the bus adapter for a number of seconds
+     * @request POST:/api/captures
+     */
+    runCapture: (data?: {
+        /**
+         * How long to record. A capture is a measurement a person starts.
+         * @min 1
+         * @max 120
+         * @default 30
+         */
+        seconds?: number;
+        /**
+         * The adapter to record, when no bus is up. Defaults to the adapter of the bus.
+         * @example "enp0s13f0u1u2"
+         */
+        adapter?: string;
+    }, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<{
+        /**
+         * The pcap file, relative to the user-cache root
+         * @example "captures/capture-20261022-143005-enp0s13f0u1u2.pcap"
+         */
+        path: string;
+        /** @example "enp0s13f0u1u2" */
+        adapter: string;
+        /** @example 30 */
+        seconds: number;
+        /** How late the frames of a capture came back. See `POST /api/captures`. */
+        summary: CaptureSummary;
+    }, void | {
+        error: string;
+    }>>;
+    /**
+     * @description Reads `captures/{name}` from the user cache and answers the summary that `POST /api/captures` answers, over any Ethernet pcap: a file the server recorded, or one from `tcpdump` on another host that a user put into `captures/` with `PUT /api/user-cache/captures/{name}`. Microsecond and nanosecond timestamps and both byte orders are read.
+     *
+     * @name GetCaptureSummary
+     * @summary Summarise a pcap file in the user cache
+     * @request GET:/api/captures/{name}
+     */
+    getCaptureSummary: (name: string, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<{
+        /** @example "captures/capture-20261022-143005-enp0s13f0u1u2.pcap" */
+        path: string;
+        /** How late the frames of a capture came back. See `POST /api/captures`. */
+        summary: CaptureSummary;
+    }, void>>;
     /**
      * @description Reads the current EtherCAT Application Layer state for one or more devices. Omit the `positions` query parameter to query all discovered devices.
      *
@@ -1511,6 +1570,17 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
          * @example false
          */
         parametersUnavailable: boolean;
+        /**
+         * The low byte of ESC register 0x0000, which names the slave controller family: 0x85 is a netX (Integro), 0xC0 the controller of a Circulo, 0x90 a TI PRU-ICSS (Jasper). Null when the register could not be read at the scan, and over SPoE.
+         * @format int32
+         * @example 192
+         */
+        escType?: number | null;
+        /**
+         * Whether Motion Master writes each mailbox request to this device once and never sends it again. True for a Synapticon or Sensodrive device whose ESC type is not 0x85, because its EtherCAT stack locks its receive mailbox when it gets one request twice. False for a netX, which discards a repeat, and for every other vendor, where a write with no frame back is sent again.
+         * @example true
+         */
+        mailboxWriteOnce?: boolean;
         /**
          * Whether the device has an EtherCAT Slave Controller: SII, ESC registers, distributed clocks and the ESC diagnostics. False over SPoE, where those endpoints answer 409.
          * @example true

package/dist/generated/Api.js

@@ -972,6 +972,34 @@ export class Api extends HttpClient {
         format: "json",
         ...params,
     });
+    /**
+     * @description Runs the capture program `motion-master-capture`, which ships beside the server binary, on the adapter the bus is on, waits for it to exit, and answers the summary. The program records every EtherCAT frame that leaves or enters the adapter with a kernel timestamp and writes them as a pcap file under `captures/` in the user cache, so the file is listed, downloaded and deleted through the `/api/user-cache` routes and opens in Wireshark. The summary matches each frame the master sent to the frame that came back for it, by the index and the header of its first datagram, and reports per kind of frame how late the returns were. The cyclic process-data frame is one kind; mailbox and register datagrams, the control plane, are the other. The bands are the three waits the driver uses, 2 ms, 20 ms and 100 ms, and they are cumulative: a frame later than 100 ms counts in all three. A frame sent again with the same index and header while its first copy had no answer counts once, as `resent`, and its return is timed from the first copy. The time is the kernel's, taken at the boundary to the NIC driver on both sides: when the frame is handed to the driver, and when the driver hands its return back. So the number covers the NIC, the wire and the device, and not the host's own queues and scheduling between that boundary and Motion Master. A capture that shows late frames puts the delay on the wire or in the device. A clean capture beside the server's own warnings, "mailbox write(s) got no frame back", puts it inside the host. Read the two together. One capture at a time. The capture adds no frame to the bus and runs on a thread of its own, so the bus is not touched. The program needs `CAP_NET_RAW`, which the packages grant it at install.
+     *
+     * @name RunCapture
+     * @summary Record the EtherCAT frames of the bus adapter for a number of seconds
+     * @request POST:/api/captures
+     */
+    runCapture = (data, params = {}) => this.request({
+        path: `/api/captures`,
+        method: "POST",
+        body: data,
+        type: ContentType.Json,
+        format: "json",
+        ...params,
+    });
+    /**
+     * @description Reads `captures/{name}` from the user cache and answers the summary that `POST /api/captures` answers, over any Ethernet pcap: a file the server recorded, or one from `tcpdump` on another host that a user put into `captures/` with `PUT /api/user-cache/captures/{name}`. Microsecond and nanosecond timestamps and both byte orders are read.
+     *
+     * @name GetCaptureSummary
+     * @summary Summarise a pcap file in the user cache
+     * @request GET:/api/captures/{name}
+     */
+    getCaptureSummary = (name, params = {}) => this.request({
+        path: `/api/captures/${name}`,
+        method: "GET",
+        format: "json",
+        ...params,
+    });
     /**
      * @description Reads the current EtherCAT Application Layer state for one or more devices. Omit the `positions` query parameter to query all discovered devices.
      *

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

@@ -1420,6 +1420,84 @@ export interface DcSyncStatus {
      */
     systemTimeDifference: number;
 }
+/** The counts for one kind of frame. The bands are cumulative. */
+export interface CaptureKindSummary {
+    /**
+     * Frames the master sent. A frame sent again counts once.
+     * @example 60021
+     */
+    sent: number;
+    /**
+     * Frames sent again with the same index and header while the first copy had no answer yet. A register datagram goes out again every 2 ms, so a late one shows here too.
+     * @example 12
+     */
+    resent: number;
+    /**
+     * Sent frames that came back
+     * @example 60018
+     */
+    returned: number;
+    /**
+     * Sent frames with no return before the capture ended
+     * @example 3
+     */
+    lost: number;
+    /**
+     * Returns later than 2 ms after the first send
+     * @example 1210
+     */
+    over2Ms: number;
+    /**
+     * Returns later than 20 ms. Counted in over2Ms as well.
+     * @example 1198
+     */
+    over20Ms: number;
+    /**
+     * Returns later than 100 ms. Counted in the two above as well.
+     * @example 1195
+     */
+    over100Ms: number;
+    /**
+     * The latest return, in microseconds after its first send
+     * @format int64
+     * @example 221748
+     */
+    latestUs: number;
+}
+/** How late the frames of a capture came back. See `POST /api/captures`. */
+export interface CaptureSummary {
+    /**
+     * Every record in the capture
+     * @example 120050
+     */
+    frames: number;
+    /**
+     * Records that are not an EtherCAT command frame
+     * @example 0
+     */
+    notEtherCat: number;
+    /**
+     * Frames from the slaves with no send to match, such as the second answer to a frame sent twice
+     * @example 8
+     */
+    unmatchedReturns: number;
+    /**
+     * Timestamp of the first record, epoch microseconds
+     * @format int64
+     * @example 1761143405000123
+     */
+    firstUs: number;
+    /**
+     * Timestamp of the last record, epoch microseconds
+     * @format int64
+     * @example 1761143435000456
+     */
+    lastUs: number;
+    /** The counts for one kind of frame. The bands are cumulative. */
+    control: CaptureKindSummary;
+    /** The counts for one kind of frame. The bands are cumulative. */
+    cyclic: CaptureKindSummary;
+}
 export interface AlStatusCode {
     /**
      * AL Status Code value (ETG.1000.6 §6.4.1)

package/package.json

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