@deeptrekker/api-domain 1.0.43-x4-localization.0 → 1.0.43-x4-localization.2

package/dist/constants/schema/schema.json

@@ -2393,6 +2393,10 @@
                     "description": "Dead Reckoning availability flag",
                     "type": "boolean"
                 },
+                "resetFilter": {
+                    "description": "Re-zeroes the position filter.",
+                    "type": "boolean"
+                },
                 "rovGpsStatus": {
                     "$ref": "#/definitions/GpsStatus"
                 },
@@ -2405,6 +2409,14 @@
                 },
                 "topsideGpsStatus": {
                     "$ref": "#/definitions/GpsStatus"
+                },
+                "topsidePosition": {
+                    "$ref": "#/definitions/TopsidePosition",
+                    "description": "Position of the topside, which is the surface end of the tether and the reference the USBL head is offset from."
+                },
+                "usblOffset": {
+                    "$ref": "#/definitions/UsblOffset",
+                    "description": "Fixed offset from the topside to the USBL head."
                 }
             },
             "type": "object"
@@ -2415,7 +2427,12 @@
                 "NONE",
                 "SEATRAC_USBL",
                 "EXTERNAL_GPS",
-                "STATIC"
+                "STATIC",
+                "ROV_GPS",
+                "USBL",
+                "EXTERNAL",
+                "MANUAL",
+                "AUTOMATIC"
             ],
             "type": "string"
         },
@@ -3576,6 +3593,25 @@
             ],
             "type": "string"
         },
+        "TopsidePosition": {
+            "additionalProperties": false,
+            "description": "Topside position",
+            "properties": {
+                "lat": {
+                    "description": "Latitude of the topside, in degrees.",
+                    "maximum": 90,
+                    "minimum": -90,
+                    "type": "number"
+                },
+                "lng": {
+                    "description": "Longitude of the topside, in degrees.",
+                    "maximum": 180,
+                    "minimum": -180,
+                    "type": "number"
+                }
+            },
+            "type": "object"
+        },
         "TransferError": {
             "additionalProperties": false,
             "description": "Error message from the Bridge Box",
@@ -3686,6 +3722,21 @@
             },
             "type": "object"
         },
+        "UsblOffset": {
+            "additionalProperties": false,
+            "description": "USBL head offset",
+            "properties": {
+                "x": {
+                    "description": "Distance east from the topside to the USBL head (in meters). Negative is west.",
+                    "type": "number"
+                },
+                "y": {
+                    "description": "Distance north from the topside to the USBL head (in meters). Negative is south.",
+                    "type": "number"
+                }
+            },
+            "type": "object"
+        },
         "VehicleHpDiagnostics": {
             "additionalProperties": false,
             "properties": {

package/dist/constants/versions/index.d.ts

@@ -1 +1 @@
-export declare const API_VERSION = "1.0.43-x4-localization.0";
+export declare const API_VERSION = "1.0.43-x4-localization.2";

package/dist/constants/versions/index.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.API_VERSION = void 0;
 /* AUTO GENERATED FILE */
-exports.API_VERSION = "1.0.43-x4-localization.0";
+exports.API_VERSION = "1.0.43-x4-localization.2";

package/dist/types/devices/vehicles/navigation/index.d.ts

@@ -247,19 +247,19 @@ export type PositionNavigationOption = {
      */
     rovGpsStatus?: GpsStatus;
     /**
-     * Position of the controller, which is the surface end of the tether and the
+     * Position of the topside, which is the surface end of the tether and the
      * reference the USBL head is offset from.
      *
      * @remarks Reported by the vehicle whatever the source, so a client that did not
      * issue the write still renders it. Settable only when {@link PositionNavigationOption.topSource}
      * is `STATIC`. X4 only.
-     * @see {@link ControllerPosition | ControllerPosition}
+     * @see {@link TopsidePosition | TopsidePosition}
      */
-    topsidePosition?: ControllerPosition;
+    topsidePosition?: TopsidePosition;
     /**
-     * Fixed offset from the controller to the USBL head.
+     * Fixed offset from the topside to the USBL head.
      *
-     * @remarks Applies when the head is not co-located with the controller. X4 only.
+     * @remarks Applies when the head is not co-located with the topside. X4 only.
      * @see {@link UsblOffset | UsblOffset}
      */
     usblOffset?: UsblOffset;
@@ -273,22 +273,23 @@ export type PositionNavigationOption = {
     resetFilter?: boolean;
 };
 /**
- * Controller position
+ * Topside position
  *
- * @remarks Latitude and longitude of the controller, in degrees.
+ * @remarks Latitude and longitude of the topside controller at the surface end of the
+ * tether, in degrees.
  * @group Devices
  * @category Navigation
  */
-export type ControllerPosition = {
+export type TopsidePosition = {
     /**
-     * Latitude of the controller, in degrees.
+     * Latitude of the topside, in degrees.
      *
      * @minimum -90
      * @maximum 90
      */
     lat?: number;
     /**
-     * Longitude of the controller, in degrees.
+     * Longitude of the topside, in degrees.
      *
      * @minimum -180
      * @maximum 180
@@ -298,18 +299,18 @@ export type ControllerPosition = {
 /**
  * USBL head offset
  *
- * @remarks Offset from the controller to the USBL head, in metres. Note these are
+ * @remarks Offset from the topside to the USBL head, in metres. Note these are
  * compass-aligned rather than vehicle-relative: `x` is east and `y` is north.
  * @group Devices
  * @category Navigation
  */
 export type UsblOffset = {
     /**
-     * Distance east from the controller to the USBL head (in meters). Negative is west.
+     * Distance east from the topside to the USBL head (in meters). Negative is west.
      */
     x?: number;
     /**
-     * Distance north from the controller to the USBL head (in meters). Negative is south.
+     * Distance north from the topside to the USBL head (in meters). Negative is south.
      */
     y?: number;
 };

package/dist/types/devices/vehicles/x4/deviceAllocation/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The physical mounting position of a thruster on the X4 chassis.
+ * @group X4
+ * @category Device Allocation
+ */
+export declare enum ThrusterPosition {
+    FRONT_LEFT = "FRONT_LEFT",
+    FRONT_RIGHT = "FRONT_RIGHT",
+    VERTICAL_LEFT = "VERTICAL_LEFT",
+    VERTICAL_RIGHT = "VERTICAL_RIGHT",
+    REAR_LEFT = "REAR_LEFT",
+    REAR_RIGHT = "REAR_RIGHT",
+    VERTICAL_REAR = "VERTICAL_REAR"
+}
+/**
+ * The physical mounting position of a light node on the X4 chassis.
+ * @group X4
+ * @category Device Allocation
+ */
+export declare enum LightPosition {
+    LIGHT_0 = "LIGHT_0",
+    LIGHT_1 = "LIGHT_1"
+}
+/**
+ * Commands the frontend can issue to drive device allocation (thruster/light configuration).
+ * @group X4
+ * @category Device Allocation
+ */
+export declare enum DeviceConfigCmd {
+    ENTER_CONFIG_MODE = "ENTER_CONFIG_MODE",
+    EXIT_CONFIG_MODE = "EXIT_CONFIG_MODE",
+    ACTIVATE_NEXT_UNKNOWN = "ACTIVATE_NEXT_UNKNOWN",
+    STOP = "STOP",
+    /** Requires `deviceId`. */
+    ASSIGN = "ASSIGN",
+    SAVE = "SAVE",
+    CLEAR_SELECTION = "CLEAR_SELECTION",
+    CLEAR_CONFIG = "CLEAR_CONFIG",
+    /** Thruster only. Requires `deviceId`. */
+    INVERT_DIRECTION = "INVERT_DIRECTION"
+}
+/**
+ * Backend-reported progress of the device allocation state machine.
+ * @group X4
+ * @category Device Allocation
+ */
+export declare enum DeviceConfigState {
+    IDLE = "IDLE",
+    READY = "READY",
+    ACTIVATING = "ACTIVATING",
+    AWAITING_ASSIGN = "AWAITING_ASSIGN",
+    ASSIGNING = "ASSIGNING",
+    SAVING = "SAVING",
+    FULL_CONFIG_COMPLETE = "FULL_CONFIG_COMPLETE",
+    CONFIG_WRITTEN = "CONFIG_WRITTEN"
+}
+/**
+ * Error codes the backend can report when rejecting a device allocation command.
+ * @group X4
+ * @category Device Allocation
+ */
+export declare enum DeviceConfigError {
+    NONE = "NONE",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR",
+    MISSING_ASSIGN_ID = "MISSING_ASSIGN_ID",
+    INVALID_ASSIGN_ID = "INVALID_ASSIGN_ID",
+    DUPLICATE_ID = "DUPLICATE_ID",
+    NOT_IN_CORRECT_STATE = "NOT_IN_CORRECT_STATE",
+    NOT_IN_CONFIG_MODE = "NOT_IN_CONFIG_MODE",
+    SAVE_FAILED = "SAVE_FAILED"
+}
+/**
+ * Whether a thruster spins in its default or inverted direction.
+ * @group X4
+ * @category Device Allocation
+ */
+export declare enum DeviceDirection {
+    DEFAULT = "DEFAULT",
+    INVERTED = "INVERTED"
+}
+/**
+ * Shared shape for the device allocation payload. The frontend sets `cmd` (and `deviceId`
+ * where required); the backend reports progress back through `state`/`errorCode`/`knownDevices`/`unknownCount`.
+ * @typeParam TDevicePosition - The position enum for the device type being allocated (e.g. {@link ThrusterPosition}, {@link LightPosition}).
+ * @group X4
+ * @category Device Allocation
+ */
+export type DeviceConfigPayload<TDevicePosition extends string> = {
+    /**
+     * Frontend-issued command. See {@link DeviceConfigCmd | DeviceConfigCmd}.
+     */
+    cmd?: DeviceConfigCmd;
+    /**
+     * The device position targeted by `cmd`. Required for `ASSIGN` and `INVERT_DIRECTION`.
+     */
+    deviceId?: TDevicePosition;
+    /**
+     * Backend-reported state of the allocation state machine. See {@link DeviceConfigState | DeviceConfigState}.
+     */
+    state?: DeviceConfigState;
+    /**
+     * Backend-reported error from the most recently rejected command. See {@link DeviceConfigError | DeviceConfigError}.
+     */
+    errorCode?: DeviceConfigError;
+    /**
+     * The set of device positions that have already been assigned to a physical device.
+     */
+    knownDevices?: TDevicePosition[];
+    /**
+     * The number of physical devices detected that have not yet been assigned a position.
+     */
+    unknownCount?: number;
+};
+/**
+ * Device allocation payload for X4 thrusters.
+ * @group X4
+ * @category Device Allocation
+ */
+export type ThrusterConfig = DeviceConfigPayload<ThrusterPosition> & {
+    /**
+     * The current prop spin direction for each assigned thruster position.
+     */
+    directions?: Partial<Record<ThrusterPosition, DeviceDirection>>;
+};
+/**
+ * Device allocation payload for X4 lights.
+ * @group X4
+ * @category Device Allocation
+ */
+export type LightConfig = DeviceConfigPayload<LightPosition>;

package/dist/types/devices/vehicles/x4/deviceAllocation/index.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceDirection = exports.DeviceConfigError = exports.DeviceConfigState = exports.DeviceConfigCmd = exports.LightPosition = exports.ThrusterPosition = void 0;
+/**
+ * The physical mounting position of a thruster on the X4 chassis.
+ * @group X4
+ * @category Device Allocation
+ */
+var ThrusterPosition;
+(function (ThrusterPosition) {
+    ThrusterPosition["FRONT_LEFT"] = "FRONT_LEFT";
+    ThrusterPosition["FRONT_RIGHT"] = "FRONT_RIGHT";
+    ThrusterPosition["VERTICAL_LEFT"] = "VERTICAL_LEFT";
+    ThrusterPosition["VERTICAL_RIGHT"] = "VERTICAL_RIGHT";
+    ThrusterPosition["REAR_LEFT"] = "REAR_LEFT";
+    ThrusterPosition["REAR_RIGHT"] = "REAR_RIGHT";
+    ThrusterPosition["VERTICAL_REAR"] = "VERTICAL_REAR";
+})(ThrusterPosition || (exports.ThrusterPosition = ThrusterPosition = {}));
+/**
+ * The physical mounting position of a light node on the X4 chassis.
+ * @group X4
+ * @category Device Allocation
+ */
+var LightPosition;
+(function (LightPosition) {
+    LightPosition["LIGHT_0"] = "LIGHT_0";
+    LightPosition["LIGHT_1"] = "LIGHT_1";
+})(LightPosition || (exports.LightPosition = LightPosition = {}));
+/**
+ * Commands the frontend can issue to drive device allocation (thruster/light configuration).
+ * @group X4
+ * @category Device Allocation
+ */
+var DeviceConfigCmd;
+(function (DeviceConfigCmd) {
+    DeviceConfigCmd["ENTER_CONFIG_MODE"] = "ENTER_CONFIG_MODE";
+    DeviceConfigCmd["EXIT_CONFIG_MODE"] = "EXIT_CONFIG_MODE";
+    DeviceConfigCmd["ACTIVATE_NEXT_UNKNOWN"] = "ACTIVATE_NEXT_UNKNOWN";
+    DeviceConfigCmd["STOP"] = "STOP";
+    /** Requires `deviceId`. */
+    DeviceConfigCmd["ASSIGN"] = "ASSIGN";
+    DeviceConfigCmd["SAVE"] = "SAVE";
+    DeviceConfigCmd["CLEAR_SELECTION"] = "CLEAR_SELECTION";
+    DeviceConfigCmd["CLEAR_CONFIG"] = "CLEAR_CONFIG";
+    /** Thruster only. Requires `deviceId`. */
+    DeviceConfigCmd["INVERT_DIRECTION"] = "INVERT_DIRECTION";
+})(DeviceConfigCmd || (exports.DeviceConfigCmd = DeviceConfigCmd = {}));
+/**
+ * Backend-reported progress of the device allocation state machine.
+ * @group X4
+ * @category Device Allocation
+ */
+var DeviceConfigState;
+(function (DeviceConfigState) {
+    DeviceConfigState["IDLE"] = "IDLE";
+    DeviceConfigState["READY"] = "READY";
+    DeviceConfigState["ACTIVATING"] = "ACTIVATING";
+    DeviceConfigState["AWAITING_ASSIGN"] = "AWAITING_ASSIGN";
+    DeviceConfigState["ASSIGNING"] = "ASSIGNING";
+    DeviceConfigState["SAVING"] = "SAVING";
+    DeviceConfigState["FULL_CONFIG_COMPLETE"] = "FULL_CONFIG_COMPLETE";
+    DeviceConfigState["CONFIG_WRITTEN"] = "CONFIG_WRITTEN";
+})(DeviceConfigState || (exports.DeviceConfigState = DeviceConfigState = {}));
+/**
+ * Error codes the backend can report when rejecting a device allocation command.
+ * @group X4
+ * @category Device Allocation
+ */
+var DeviceConfigError;
+(function (DeviceConfigError) {
+    DeviceConfigError["NONE"] = "NONE";
+    DeviceConfigError["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+    DeviceConfigError["MISSING_ASSIGN_ID"] = "MISSING_ASSIGN_ID";
+    DeviceConfigError["INVALID_ASSIGN_ID"] = "INVALID_ASSIGN_ID";
+    DeviceConfigError["DUPLICATE_ID"] = "DUPLICATE_ID";
+    DeviceConfigError["NOT_IN_CORRECT_STATE"] = "NOT_IN_CORRECT_STATE";
+    DeviceConfigError["NOT_IN_CONFIG_MODE"] = "NOT_IN_CONFIG_MODE";
+    DeviceConfigError["SAVE_FAILED"] = "SAVE_FAILED";
+})(DeviceConfigError || (exports.DeviceConfigError = DeviceConfigError = {}));
+/**
+ * Whether a thruster spins in its default or inverted direction.
+ * @group X4
+ * @category Device Allocation
+ */
+var DeviceDirection;
+(function (DeviceDirection) {
+    DeviceDirection["DEFAULT"] = "DEFAULT";
+    DeviceDirection["INVERTED"] = "INVERTED";
+})(DeviceDirection || (exports.DeviceDirection = DeviceDirection = {}));

package/dist/types/devices/vehicles/x4/index.d.ts

@@ -1,6 +1,8 @@
 import { Movement } from "../../../core";
 import { DeviceModel, MotorDiagnostics, Sonar, StereoCamera, X4CameraHead } from "../../cameraHeads";
 import { ImpaqDriver, SensorPod, X4Light } from "../../peripherals";
+import { LightConfig, ThrusterConfig } from "./deviceAllocation";
+export * from "./deviceAllocation";
 import { CygnusType } from "../..";
 import { NavigationOptions } from "../navigation";
 /**
@@ -730,6 +732,16 @@ export type X4 = {
      * @readonly
      */
     thrusters?: Record<string, X4Thruster>;
+    /**
+     * The current state of in-app thruster device allocation (mapping physical thrusters to
+     * their logical vehicle position). See {@link ThrusterConfig | ThrusterConfig}.
+     */
+    thrusterConfig?: ThrusterConfig;
+    /**
+     * The current state of in-app light device allocation (mapping physical light nodes to
+     * their logical vehicle position). See {@link LightConfig | LightConfig}.
+     */
+    lightConfig?: LightConfig;
     /**
      * A record of camera heads associated with the X4 vehicle.
      * Each camera head is identified by its unique MAC address and contains properties such as tilt, motor diagnostics, and temperatures.
@@ -784,7 +796,7 @@ export type X4 = {
     vehiclePosition?: X4Position;
     /**
      * Navigation settings and options for the X4: which source supplies the global position,
-     * where the controller is, and the heading corrections.
+     * where the topside is, and the heading corrections.
      *
      * Only `navigationOptions` is taken from {@link Navigation | Navigation}, rather than
      * intersecting the whole type as {@link RovVehicle | RovVehicle} does. The X4 reports

package/dist/types/devices/vehicles/x4/index.js

@@ -1,6 +1,21 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ControlMode = exports.CoordinateType = void 0;
+__exportStar(require("./deviceAllocation"), exports);
 /**
  * The coordinate system used for navigation and positioning.
  * @internal

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@deeptrekker/api-domain",
-    "version": "1.0.43-x4-localization.0",
+    "version": "1.0.43-x4-localization.2",
     "description": "A business domain of types and schemas that the Deep Trekker topside communicates with via an API.",
     "main": "dist/index.js",
     "engines": {