@synapticon/motion-master-client 6.0.0-alpha.115 → 6.0.0-alpha.116

package/dist/generated/Api.d.ts

@@ -1,4 +1,4 @@
-import { AlStatusCode, AutoTuningError, AutoTuningRunRequest, AutoTuningRunResponse, AutoTuningStatus, BrakeState, CaptureSummary, Cia402Status, DcSyncStatus, DeviceDiagnostics, DeviceFile, DeviceParameter, Encoders, EscRegister, EsiParseResult, FirmwareCompatibility, FirmwarePackageName, FoeErrorCode, GameLoopHealth, HardwareDescription, HrdRecording, IcHausRegister, IcMuRestoreFile, IdentifiedPlantModel, 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, IcHausRegister, IcMuRestoreFile, IcMuStatusBit, IdentifiedPlantModel, 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> {
     /**
@@ -1206,6 +1206,27 @@ export declare class Api<SecurityDataType = unknown> extends HttpClient<Security
      * @request POST:/api/hardware-description/parse
      */
     parseHardwareDescription: (data: string, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<HardwareDescription, void>>;
+    /**
+     * @description Decodes an encoder status word, the value of 0x2111:04 or 0x2113:04, into the same bits the `ic-mu-encoder-status` procedure reports. Bus-independent: it reads nothing from a drive, so a value from a log can be decoded with no hardware present. A `GET` with a query, like `/api/firmware-package-name`, because the input is one number.
+     *
+     * @name GetIcMuEncoderStatus
+     * @summary Decode an iC-MU encoder status word
+     * @request GET:/api/ic-mu-encoder-status
+     */
+    getIcMuEncoderStatus: (query: {
+        /**
+         * The word, in decimal or in hexadecimal with a 0x prefix.
+         * @example "0x1000"
+         */
+        encoderStatus: string;
+    }, params?: RequestParams) => Promise<import("./http-client.js").HttpResponse<{
+        /**
+         * @format int64
+         * @example 4096
+         */
+        encoderStatus: number;
+        encoderStatusBits: IcMuStatusBit[];
+    }, void>>;
     /**
      * @description Decodes a `circulo_integrated_encoder_<sensor port>_config.bin` supplied in the request body. The `ic-mu-encoder-configuration` procedure writes this file. It holds `[address, value]` pairs of iC-MU registers, and the drive writes them into the encoder when the iC-MU reports a corrupted EEPROM. Each pair comes back with the iC-MU register at its address. The file is refused when the drive would refuse it: an odd length, or more than 66 bytes.
      *

package/dist/generated/Api.js

@@ -901,6 +901,20 @@ export class Api extends HttpClient {
         format: "json",
         ...params,
     });
+    /**
+     * @description Decodes an encoder status word, the value of 0x2111:04 or 0x2113:04, into the same bits the `ic-mu-encoder-status` procedure reports. Bus-independent: it reads nothing from a drive, so a value from a log can be decoded with no hardware present. A `GET` with a query, like `/api/firmware-package-name`, because the input is one number.
+     *
+     * @name GetIcMuEncoderStatus
+     * @summary Decode an iC-MU encoder status word
+     * @request GET:/api/ic-mu-encoder-status
+     */
+    getIcMuEncoderStatus = (query, params = {}) => this.request({
+        path: `/api/ic-mu-encoder-status`,
+        method: "GET",
+        query: query,
+        format: "json",
+        ...params,
+    });
     /**
      * @description Decodes a `circulo_integrated_encoder_<sensor port>_config.bin` supplied in the request body. The `ic-mu-encoder-configuration` procedure writes this file. It holds `[address, value]` pairs of iC-MU registers, and the drive writes them into the encoder when the iC-MU reports a corrupted EEPROM. Each pair comes back with the iC-MU register at its address. The file is refused when the drive would refuse it: an odd length, or more than 66 bytes.
      *

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

@@ -451,7 +451,7 @@ export interface ProgressStep {
     /** @example "succeeded" */
     status: "idle" | "running" | "succeeded" | "failed";
     /**
-     * What the step produced, if anything — shape is per procedure. Absent when the step produced nothing. For `os-command` it is an object with `status`, `data`, `errorCode` when the drive sent one, and `fsBuffer` when the request asked to read bulk data. For `read-object-dictionary` it is an object with `byteCount` and `values`, one entry per object with its `index`, `subindex` and `value`. For `ic-mu-encoder-status` the `read-registers` step holds an array of `IcMuEncoderStatus`, and for `ic-mu-encoder-configuration` the `verify` step holds one. For `ic-mu-calibration` the `validate` step holds an `IcMuCalibrationPlan`, each `iteration-<n>` step an `IcMuCalibrationIteration`, and the `validation` step an `IcMuCalibrationValidation`.
+     * What the step produced, if anything — shape is per procedure. Absent when the step produced nothing. For `os-command` it is an object with `status`, `data`, `errorCode` when the drive sent one, and `fsBuffer` when the request asked to read bulk data. For `read-object-dictionary` it is an object with `byteCount` and `values`, one entry per object with its `index`, `subindex` and `value`. For `ic-mu-encoder-status` the `read-registers` step holds an array of `IcMuEncoderStatus`, and for `ic-mu-encoder-configuration` the `verify` step holds one. For `ic-mu-calibration` the `validate` step holds an `IcMuCalibrationPlan`, each `iteration-<n>` step an `IcMuCalibrationIteration`, and the `validation` step an `IcMuCalibrationValidation`. For `ic-mu-key-registers` the `read-key-registers` step holds an array of `IcMuKeyRegister`, for `ic-mu-eeprom-export` the `read-eeprom` step an array of `IcMuEepromByte`, and for `ic-mu-i2c-register` the `i2c-transfer` step an `IcMuI2cTransfer`. For `ic-mu-restore-file` the `restore-file` step holds `file` and `entries`, the pairs written, as `IcMuRestoreFile` lists them. For `open-loop-field-control` the `validate` step holds an `OpenLoopFieldPlan`. For `ic-mu-eeprom-erase` the `read-eeprom` step holds the 77 erased bytes as `IcMuEepromByte`, and the `delete-restore-file` step the `file` it deleted, or null with a `reason`. For `controller-auto-tuning` the `drive-configuration` step holds the `DriveConfig` sent to the auto-tuning program, the `noise` step `noiseRpm` and a `warning`, the `compute` step a `ControllerTuningComputed`, and the `write` step a `ControllerTuningWrite`.
      * @example {"status":1,"data":[1,2,3,4,5,6]}
      */
     value?: any;
@@ -594,6 +594,11 @@ export interface Encoders {
 }
 /** A drive's brake configuration and current state — the parts of object 0x2004 that decide what commanding the brake will actually do. Returned by every brake endpoint, so the outcome of a release or engage arrives in the same shape as a plain read. */
 export interface BrakeState {
+    /**
+     * Whether the drive has the brake object 0x2004. A drive with no brake, such as one running Jasper firmware, has none: then `status` is `notConfigured`, `softwareControllable` is false, and release and engage write nothing and succeed.
+     * @example true
+     */
+    present: boolean;
     /**
      * Brake state (0x2004:07). A brake is spring-engaged, so `engaged` is also its powered-off state.
      * @example "engaged"
@@ -1102,6 +1107,163 @@ export interface IcMuEncoderStatus {
         /** @example 56 */
         maxAccelerationKrpmPerSecond: number;
     }[];
+    /**
+     * The encoder status word, 0x2111:04 for encoder 1 and 0x2113:04 for encoder 2, read with an SDO upload. It is a snapshot, not a live view of the chips. The drive writes it after a BiSS error bit and at start-up: iC-MU STATUS1 in bits 0-7, the iC-PVL status in bits 8-15 and iC-MU STATUS0 in bits 16-23, each with only the bits the drive watches. 0 means that nothing was latched since the drive started. The drive sets the word to 0 again only when a change of the encoder configuration object, 0x2110 or 0x2112, restarts the encoder; `ic-mu-encoder-configuration` does not clear it. The chips themselves are not read, because a read of STATUS1 clears the iC-MU errors.
+     * @format int64
+     * @example 4096
+     */
+    encoderStatus: number;
+    /** One entry for each set bit of encoderStatus, lowest bit first. */
+    encoderStatusBits: IcMuStatusBit[];
+}
+/** The `validate` step of `open-loop-field-control`: the move in the electrical units the drive takes, as OS command 2 writes them. */
+export interface OpenLoopFieldPlan {
+    /** @example 360 */
+    angleDegrees: number;
+    /**
+     * 0x2003:01.
+     * @example 5
+     */
+    polePairs: number;
+    /**
+     * The end electrical angle. The drive takes 2π as 6.28, so this is the mechanical angle times the pole pairs times 6280 / 360.
+     * @example 31400
+     */
+    angleEndMilliRadian: number;
+    /** @example 3 */
+    speedRadPerSecond: number;
+    /** @example 523 */
+    accelerationRadPerSquaredSecond: number;
+    /** @example 1000 */
+    lengthEndPerMille: number;
+    /** @example 10000 */
+    lengthRatePerMillePerSecond: number;
+    /**
+     * The velocity of the motor shaft the rounded speed gives.
+     * @example 5.73
+     */
+    velocityRpm: number;
+}
+/** The `compute` step of `controller-auto-tuning`: what the auto-tuning program tuned for, and the gains it returned in SI units, before the conversion to the drive's units. */
+export interface ControllerTuningComputed {
+    /** @example true */
+    full: boolean;
+    /** Position tuning only. */
+    controllerType?: "PI-P" | "P-PI";
+    /**
+     * The damping ratio the program chose, or the one the request gave.
+     * @example 0.9
+     */
+    dampingRatio: number;
+    /**
+     * Position tuning only. The settling time the program chose, or the one given.
+     * @example 120
+     */
+    settlingTimeMs?: number;
+    /**
+     * Velocity tuning only. The bandwidth the program chose, or the one given.
+     * @example 40.8
+     */
+    bandwidthHz?: number;
+    /**
+     * Kp and Ki of the position loop, in (rad/s)/rad and (rad/s)/(rad·s), and of the velocity loop, in Nm/(rad/s) and Nm/(rad/s·s). A velocity tuning returns zeros for the position loop.
+     * @example {"position":{"kp":30,"ki":4},"velocity":{"kp":0.05,"ki":2.5}}
+     */
+    gains: object;
+    /** The stability margins and other figures a full tuning reports, as the program renders them. Null for a tuning to targets. */
+    state: any | null;
+}
+/** The `write` step of `controller-auto-tuning`: each gain object, its value before and after the write, in the drive's units, and the Kd objects the drive does not have. */
+export interface ControllerTuningWrite {
+    gains: {
+        /** @example "0x2011:01" */
+        object: string;
+        /** @example 1.5 */
+        before: number;
+        /** @example 5.24 */
+        after: number;
+    }[];
+    /** @example ["0x2011:03"] */
+    skipped: string[];
+    /** Set when a full tuning computed the gains with a noise of 0, because the motor moved or the noise recording failed. */
+    warning: string | null;
+}
+/** One key register of an iC-MU, read from its RAM: the step value of `ic-mu-key-registers` is a list of 33 of them, in the order of the restore file. */
+export interface IcMuKeyRegister {
+    /** @example 82 */
+    ramAddress: number;
+    /**
+     * Where the EEPROM keeps the register. RAM 0x00-0x18 is EEPROM 0x00-0x18, and RAM 0x52-0x59 is EEPROM 0x19-0x20.
+     * @example 25
+     */
+    eepromAddress: number;
+    /** @example 47 */
+    value: number;
+    /** The iC-MU register at `ramAddress`, as `/api/meta/ic-haus-registers` lists it, or null for an address the register map does not list. */
+    register: IcHausRegister | null;
+}
+/** One byte of the EEPROM of an iC-MU encoder: the step value of `ic-mu-eeprom-export` is a list of 77 of them, 0x00-0x4C. 0x00-0x3F is the configuration of the iC-MU and 0x40-0x4C that of the iC-PVL. The `read-eeprom` step of `ic-mu-eeprom-erase` holds the same list, read back after the erase. */
+export interface IcMuEepromByte {
+    /** @example 64 */
+    address: number;
+    /** @example 40 */
+    value: number;
+}
+/** The step value of `ic-mu-i2c-register`. */
+export interface IcMuI2CTransfer {
+    /** @example "ic-pvl" */
+    target: "eeprom" | "ic-pvl" | "ic-pvl-status";
+    /**
+     * The I²C device id with the R/W bit, as written to I2C_DEVID (0x5E).
+     * @example 195
+     */
+    deviceId: number;
+    /** @example false */
+    write: boolean;
+    /** @example 16 */
+    registerAddress: number;
+    /**
+     * The byte read or written.
+     * @example 240
+     */
+    value: number;
+}
+/** One set bit of the encoder status word. A set bit that the drive masks out has no name, title, description or remedy. */
+export interface IcMuStatusBit {
+    /**
+     * The bit in the encoder status word.
+     * @example 12
+     */
+    bit: number;
+    /**
+     * The chip the bit comes from, null for bits 24-31.
+     * @example "iC-PVL"
+     */
+    chip: "iC-MU" | "iC-PVL" | null;
+    /**
+     * The status register of the chip, null for bits 24-31.
+     * @example "STATUS"
+     */
+    register: "STATUS0" | "STATUS1" | "STATUS" | null;
+    /**
+     * The bit in that register.
+     * @example 4
+     */
+    registerBit: number;
+    /**
+     * The datasheet name.
+     * @example "BAT_ERR"
+     */
+    name: string | null;
+    /** @example "Battery error" */
+    title: string | null;
+    /** @example "The battery voltage is too low (iC-PVL datasheet, Elec. Char. No. 404). The position is not valid." */
+    description: string | null;
+    /**
+     * What to do, null where there is nothing to do.
+     * @example "Change the battery, then reset the fault of the drive."
+     */
+    remedy: string | null;
 }
 /** What an iC-MU calibration decided before the motor moved. */
 export interface IcMuCalibrationPlan {
@@ -1167,6 +1329,16 @@ export interface IcMuCalibrationIteration {
      * @example 8.9
      */
     recordedRevolutions: number;
+    /**
+     * The master periods MU_3SL calculated from the recording. Reported as the library gives it; nothing judges it.
+     * @example 32
+     */
+    calculatedMasterPeriods?: number;
+    /**
+     * The fewest samples MU_3SL saw in one master period of the recording. Reported as the library gives it; nothing judges it.
+     * @example 12.5
+     */
+    minimalSamplesPerMasterPeriod?: number;
     /** Present when the recording covered less than one turn of the ring. */
     warning?: string;
     /** The permissible nonius phase error. */
@@ -1191,6 +1363,16 @@ export interface IcMuCalibrationValidation {
     samples: number;
     /** @example 8.9 */
     recordedRevolutions: number;
+    /**
+     * As in IcMuCalibrationIteration.
+     * @example 32
+     */
+    calculatedMasterPeriods?: number;
+    /**
+     * As in IcMuCalibrationIteration.
+     * @example 12.5
+     */
+    minimalSamplesPerMasterPeriod?: number;
     warning?: string;
     phaseRangeLimit: number;
     /** A curve over the ring: at most 720 points of [ring angle in degrees, value]. The value is in the unit of phaseRangeLimit. */
@@ -1243,7 +1425,7 @@ export interface ProcedureRequest {
      */
     command?: number[];
     /**
-     * Ceiling on the whole command. Not a liveness check — the drive fails a command no service acknowledges within 5 s on its own — so size it for the command being run. Hitting it aborts the command on the drive.
+     * Ceiling on the whole command. Not a liveness check — the drive fails a command no service acknowledges within 5 s on its own — so size it for the command being run. Hitting it aborts the command on the drive. For `open-loop-field-control` it is how long the move may take after the drive is enabled, from 1000 ms, with 60000 ms as its default.
      * @min 1
      * @max 600000
      * @default 1000
@@ -1266,25 +1448,30 @@ export interface ProcedureRequest {
     /** `os-command` only, and required when `fsBuffer` is `write`: the bytes to send, base64-encoded into this JSON string. Rejected for the other two directions rather than ignored, so a request that names one and forgets the other is told rather than running a command that moves nothing. (Deliberately not `format: byte`, for the reason spelled out on `packageContent`.) */
     fsBufferData?: string;
     /**
-     * `encoder-register-communication`, `ic-mu-calibration-mode`, `ignore-biss-status-bits`, `ic-mu-encoder-configuration` and `ic-mu-calibration`: the encoder ordinal of the OS commands, which picks the drive's encoder to address. Encoder 1 is the encoder configured in 0x2110 and encoder 2 the one configured in 0x2112, so the ordinal picks a configuration object rather than a kind of encoder. Required for `ic-mu-encoder-configuration` and `ic-mu-calibration`, because a default would write the EEPROM of an encoder that nobody named.
+     * `encoder-register-communication`, `ic-mu-calibration-mode`, `ignore-biss-status-bits`, `ic-mu-encoder-configuration`, `ic-mu-calibration`, `ic-mu-key-registers`, `ic-mu-eeprom-export`, `ic-mu-i2c-register`, `ic-mu-restore-file` and `ic-mu-eeprom-erase`: the encoder ordinal of the OS commands, which picks the drive's encoder to address. Encoder 1 is the encoder configured in 0x2110 and encoder 2 the one configured in 0x2112, so the ordinal picks a configuration object rather than a kind of encoder. Required for every `ic-mu-` procedure that takes it, because a default would address an encoder that nobody named.
      * @default 1
      * @example 1
      */
     encoderOrdinal?: 1 | 2;
     /**
-     * `encoder-register-communication` only: false reads the register, true writes `value` into it. Either way the drive reports what the register holds afterwards.
+     * `encoder-register-communication` and `ic-mu-i2c-register`: false reads, true writes `value`. `encoder-register-communication` reports what the register holds afterwards; `ic-mu-i2c-register` reports the byte it wrote.
      * @default false
      */
     write?: boolean;
     /**
-     * `encoder-register-communication` only, and required for it: the register to access. The map belongs to the encoder chip rather than to the drive's firmware.
+     * `encoder-register-communication` and `ic-mu-i2c-register`, and required for both: the register to access. For `encoder-register-communication` the map belongs to the encoder chip rather than to the drive's firmware. For `ic-mu-i2c-register` it is an address on `target`: an EEPROM address, or an iC-PVL register.
      * @min 0
      * @max 255
      * @example 117
      */
     registerAddress?: number;
     /**
-     * `encoder-register-communication` only: the byte to write into the register. Ignored when reading.
+     * `ic-mu-i2c-register` only, and required for it: what the I²C transfer of the iC-MU addresses. `eeprom` is the EEPROM that holds the configuration of the iC-MU and the iC-PVL, `ic-pvl` every iC-PVL register, and `ic-pvl-status` only the status and command registers of the iC-PVL, where the command register is 0x01. The server picks the I²C device id from `target` and `write`.
+     * @example "eeprom"
+     */
+    target?: "eeprom" | "ic-pvl" | "ic-pvl-status";
+    /**
+     * `encoder-register-communication` and `ic-mu-i2c-register`: the byte to write. Ignored when reading. `ic-mu-i2c-register` requires it for a write.
      * @min 0
      * @max 255
      * @default 0
@@ -1314,6 +1501,11 @@ export interface ProcedureRequest {
      * @example "18-microamperes"
      */
     batteryMode?: "default" | "6-microamperes" | "10-microamperes" | "18-microamperes" | "36-microamperes" | "72-microamperes";
+    /**
+     * `ic-mu-encoder-configuration` only: writes the configured registers to the restore file of the sensor port, `circulo_integrated_encoder_<sensor port>_config.bin`. The drive writes that file back into the encoder when the iC-MU reports a corrupted EEPROM. False keeps the file there now. The drive keeps a restore file only for sensor ports 1 and 2.
+     * @default true
+     */
+    writeRestoreFile?: boolean;
     /**
      * `ic-mu-calibration` only: where the ring of an external encoder on sensor port 3 to 5 sits. Required there, and refused for port 1, which is always inner, and port 2, which is always outer. The calibration starts from the values measured for that position.
      * @example "inner"
@@ -1373,6 +1565,76 @@ export interface ProcedureRequest {
      * @example 2
      */
     finalState?: 1 | 2 | 3 | 4 | 8;
+    /**
+     * `open-loop-field-control` only, and required for it: how far to turn the motor shaft, in mechanical degrees. Negative turns the other way.
+     * @example 360
+     */
+    angle?: number;
+    /**
+     * `open-loop-field-control` only: the highest velocity of the motor shaft, in rpm. The drive takes whole electrical rad/s, so a slow move is rounded; the `validate` step reports the velocity the drive runs.
+     * @default 5
+     * @example 5
+     */
+    velocity?: number;
+    /**
+     * `open-loop-field-control` only: the acceleration and the deceleration of the motor shaft, in rpm/s.
+     * @default 1000
+     * @example 1000
+     */
+    acceleration?: number;
+    /**
+     * `open-loop-field-control` only: the current of the rotating field, in per mille of the rated current.
+     * @default 1000
+     * @example 1000
+     */
+    fieldLength?: number;
+    /**
+     * `open-loop-field-control` only: how fast the field length rises from 0, in per mille of the rated current per second.
+     * @default 10000
+     * @example 10000
+     */
+    fieldLengthRate?: number;
+    /**
+     * `controller-auto-tuning` only, and required for it: the controller to tune.
+     * @example "position"
+     */
+    controller?: "position" | "velocity";
+    /**
+     * `controller-auto-tuning` only, position tuning only: the structure of the cascaded position controller the gains are computed for. PI-P puts the integral action in the position loop, P-PI in the velocity loop.
+     * @default "PI-P"
+     * @example "PI-P"
+     */
+    controllerType?: "PI-P" | "P-PI";
+    /**
+     * `controller-auto-tuning` only: true lets the auto-tuning program choose the damping ratio and the settling time or the bandwidth, from the drive configuration and the velocity noise. False computes the gains for `dampingRatioPermil` and `settlingTimeMs` or `bandwidthMilliHz`.
+     * @default true
+     * @example true
+     */
+    full?: boolean;
+    /**
+     * `controller-auto-tuning` only, when `full` is false: the damping ratio of the closed loop, in per mille.
+     * @min 400
+     * @max 2000
+     * @default 1000
+     * @example 1000
+     */
+    dampingRatioPermil?: number;
+    /**
+     * `controller-auto-tuning` only, position tuning only, when `full` is false: the time the step response takes to stay within 5 % of the target.
+     * @min 20
+     * @max 1000
+     * @default 200
+     * @example 200
+     */
+    settlingTimeMs?: number;
+    /**
+     * `controller-auto-tuning` only, velocity tuning only, when `full` is false: the bandwidth of the closed velocity loop, in mHz.
+     * @min 200
+     * @max 100000
+     * @default 5000
+     * @example 5000
+     */
+    bandwidthMilliHz?: number;
     [key: string]: any;
 }
 export interface OutputStageResult {

package/package.json

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