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

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> {
     /**
@@ -1320,6 +1320,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.
      *

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.98",
   "description": "Isomorphic TypeScript client for Motion Master: the generated HTTP API client, the WebSocket connection, and helpers.",
   "license": "MIT",
   "repository": {