cmvr-es/protos/cmvr/api/system_command.proto

syntax = "proto3";

import "cmvr/api/agv_command.proto";
import "cmvr/api/arm_command.proto";
import "cmvr/api/common.proto";

package cmvr.api;

enum DeviceType {
    AGV = 0;
    Battery = 1;
    Camera = 2;
    DexHand = 3;
    Gripper = 4;
    Microphone = 5;
    Robot = 6;
    Speaker = 7;
    Unknown = 20;
}

message DeviceList {
    string device_id = 1;
    DeviceType device_type = 2;
}

// Stable device categories used by GetDeviceList. This intentionally does not
// reuse the legacy DeviceType enum above: its zero value is AGV and it does not
// cover all DeviceManager categories.
enum SystemDeviceType {
    SYSTEM_DEVICE_TYPE_UNSPECIFIED = 0;
    SYSTEM_DEVICE_TYPE_AGV = 1;
    SYSTEM_DEVICE_TYPE_ARM = 2;
    SYSTEM_DEVICE_TYPE_BATTERY = 3;
    SYSTEM_DEVICE_TYPE_BIO_HEAD = 4;
    SYSTEM_DEVICE_TYPE_CAMERA = 5;
    SYSTEM_DEVICE_TYPE_CAN_BUS = 6;
    SYSTEM_DEVICE_TYPE_DEX_HAND = 7;
    SYSTEM_DEVICE_TYPE_GRIPPER = 8;
    SYSTEM_DEVICE_TYPE_MICROPHONE = 9;
    SYSTEM_DEVICE_TYPE_MOTOR = 10;
    SYSTEM_DEVICE_TYPE_MOTOR_SYSTEM = 11;
    SYSTEM_DEVICE_TYPE_MUJOCO_VIEWER = 12;
    SYSTEM_DEVICE_TYPE_MUJOCO_WORLD = 13;
    SYSTEM_DEVICE_TYPE_ROBOT = 14;
    SYSTEM_DEVICE_TYPE_SPEAKER = 15;
}

enum SystemDeviceState {
    SYSTEM_DEVICE_STATE_UNSPECIFIED = 0;
    SYSTEM_DEVICE_STATE_DISABLED = 1;
    SYSTEM_DEVICE_STATE_INITIALIZING = 2;
    SYSTEM_DEVICE_STATE_REGISTERED = 3;
    SYSTEM_DEVICE_STATE_READY = 4;
    SYSTEM_DEVICE_STATE_RUNNING = 5;
    SYSTEM_DEVICE_STATE_STOPPED = 6;
    SYSTEM_DEVICE_STATE_ERROR = 7;
}

enum SystemDeviceHealth {
    SYSTEM_DEVICE_HEALTH_UNSPECIFIED = 0;
    SYSTEM_DEVICE_HEALTH_HEALTHY = 1;
    SYSTEM_DEVICE_HEALTH_DEGRADED = 2;
    SYSTEM_DEVICE_HEALTH_FAULT = 3;
}

message SystemDeviceInfo {
    string device_id = 1;
    SystemDeviceType device_type = 2;

    // Concrete backend name for display and diagnostics only. Consumers must
    // use device_type, rather than this free-form string, for decisions.
    string type_name = 3;

    // GetDeviceList currently publishes only enabled entries. Keep this field
    // explicit so each row remains self-describing and future-compatible.
    bool enabled = 4;
    SystemDeviceState manager_state = 5;
    SystemDeviceHealth health = 6;
    bool has_error = 7;
    string error_message = 8;
    uint64 status_updated_at_unix_ms = 9;
}

message GetDeviceListCommand {
    message Request {}

    message Feedback {
        CommandHeader.Feedback header = 1;
        string manager_name = 2;
        string manager_version = 3;
        string manager_description = 4;
        repeated SystemDeviceInfo device_list = 5;
        uint64 sampled_at_unix_ms = 6;
    }
}

message GetSystemInfoCommand {
    message Request {}

    message Feedback {
        CommandHeader.Feedback header = 1;
        string system_name = 2;
        string version = 3;
        string description = 4;
        string os = 5;
        string kernel_version = 6;
        string architecture = 7;

        // Changes whenever the in-process ActionQueue idempotency ledger is
        // recreated. Clients bind submissions and retries to this value.
        string action_service_instance_id = 8;
    }
}

message GetSystemStatusCommand {
    message Request {}

    message Feedback {
        CommandHeader.Feedback header = 1;
        float cpu_usage = 2;
        float mem_total_mb = 3;
        float mem_used_mb = 4;
        float disk_total_gb = 5;
        float disk_used_gb = 6;
        repeated DeviceList device_list = 7;
    }
}

message UpdateParamsCommand {
    message Request {
        CommandHeader.Request header = 1;
        repeated ConfigParam params = 2;
    }

    message Feedback {
        CommandHeader.Feedback header = 1;
    }
}


message StopAllCommand {
    message Request {
        CommandHeader.Request header = 1;
    }

    message Feedback {
        CommandHeader.Feedback header = 1;
    }
}

// Final outcome of one ActionQueue execution.
enum ActionResultCode {
    ACTION_RESULT_CODE_UNSPECIFIED = 0;
    ACTION_RESULT_CODE_COMPLETED = 1;
    ACTION_RESULT_CODE_FAILED = 2;
    ACTION_RESULT_CODE_CANCELED = 3;
    ACTION_RESULT_CODE_TIMED_OUT = 4;
    ACTION_RESULT_CODE_REJECTED = 5;
}

// Describes whether this RPC admitted a new action or observed an existing
// idempotency record. Clients must not infer this from an error string.
enum ActionDeduplicationStatus {
    ACTION_DEDUPLICATION_STATUS_UNSPECIFIED = 0;
    ACTION_DEDUPLICATION_STATUS_ACCEPTED_NEW = 1;
    ACTION_DEDUPLICATION_STATUS_JOINED_IN_FLIGHT = 2;
    ACTION_DEDUPLICATION_STATUS_CACHED_RESULT = 3;
    ACTION_DEDUPLICATION_STATUS_RESULT_EVICTED = 4;
    ACTION_DEDUPLICATION_STATUS_LEDGER_EXHAUSTED = 5;
    ACTION_DEDUPLICATION_STATUS_ACTION_ID_CONFLICT = 6;
    ACTION_DEDUPLICATION_STATUS_SERVICE_INSTANCE_MISMATCH = 7;
}

// Edge-local delay between two device commands.
message DelayAction {
    // Delay duration in milliseconds. The server applies a bounded maximum.
    uint32 duration_ms = 1;
}

// One finite, synchronous command in an ActionQueue request.
message ActionStep {
    // Client-provided identifier used for diagnostics. It must be unique within
    // one ActionQueue request.
    string step_id = 1;

    // Per-step timeout in milliseconds. Zero inherits the remaining action
    // timeout or the server default.
    uint32 timeout_ms = 2;

    // Tags are grouped by domain so compatible commands can be added without
    // renumbering existing alternatives: Arm 10-19, AGV 20-29, built-ins 90+.
    oneof command {
        MoveJ.Request arm_move_j = 10;
        MoveL.Request arm_move_l = 11;

        AgvNavigateToPoseCommand.Request agv_navigate_to_pose = 20;
        AgvNavigateToStationCommand.Request agv_navigate_to_station = 21;
        AgvFollowPathCommand.Request agv_follow_path = 22;

        DelayAction delay = 90;
    }
}

// Atomically submits a complete command sequence for edge-local serial
// execution. Device motion alternatives must use synchronous execution.
message ActionQueueCommand {
    message Request {
        // Client-generated globally unique idempotency key. During one Action
        // service instance, retrying an identical accepted request with the
        // same action_id does not dispatch its steps a second time. Recent
        // terminal results can be returned; older accepted IDs are rejected
        // fail-closed after their result is evicted. Deduplication is not
        // persisted across an edge-service restart; the required instance
        // epoch below prevents an old retry from being replayed after restart.
        string action_id = 1;
        repeated ActionStep steps = 2;

        // Total queue-wait plus execution timeout in milliseconds. Zero uses a
        // bounded server default.
        uint32 total_timeout_ms = 3;

        // Required instance epoch obtained from GetSystemInfo. A mismatch
        // means the process-local deduplication ledger was recreated, so the
        // server rejects the request instead of risking a replay.
        string expected_service_instance_id = 4;
    }

    message Feedback {
        CommandHeader.Feedback header = 1;
        string action_id = 2;

        // Number of steps which completed successfully before the final result.
        uint32 completed_steps = 3;

        // Present only when a particular step caused failure, cancellation,
        // timeout, or rejection. Presence distinguishes index zero from no
        // failed step.
        optional uint32 failed_step_index = 4;
        ActionResultCode result = 5;
        string service_instance_id = 6;
        ActionDeduplicationStatus deduplication_status = 7;
    }
}