rover_nexus_core 0.2.0

// Copyright 2026 Rottinghaus Dynamics
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// core_model.rs
use crate::spatial_types::{GeoPose, LocalPose, Pose, SpatialData};
use serde::{Deserialize, Serialize};
use uuid::Uuid;
// Command structure sent from the server to robot agent
// agent acks uuid, removes InternalCommand to forward to robot software
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct NexusCommand {
    pub id: Uuid,
    pub command: RobotCommand,
}

// Use DateTime, Utc whenever actually processing time in code
// i64 - unix time milliseconds is the time to use on the wire, IPC
// From fleet command to rover
// All passed through until I need to remotely manage the agent..
// Formerly InternalCommand
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum RobotCommand {
    SetRobotMode(RobotMode), // set the robot to an operation mode, Auto, Teleop, etc
    Pause, // Pause, opposite of resume, intended to stop robot activity, motion, and pause the current mission
    Resume, // Opposite of Stop, resume the current activity or mission
    // A complete mission command with a path, target, geometry, capabilities and settings
    AssignMission(MissionCommand),
    // Set the status of a mission, mainly to resume or stop a mission, not overall motion
    // Remove/Delete a mission by Cancel or Abort.
    ControlMissionRun(ControlMissionRun),
    // Call a capability that the robot provides, was InvokeService
    InvokeService(ServiceCall),
    // Set a robot setting, must be one given in Capabilities or in the robot.toml settings
    UpdateSettings(Vec<SettingUpdate>),
    // Inform the robot of a new feature in the world
    UpdateFeature(FeatureOp),
    // Inform the robot of a new spatial directive. The spatial directive is calculated by the agent by default
    SpatialDirective(SpatialDirectiveOp),
    // Inform the robot of an object in the world
    Object(ObjectOp),
    // Command the robot to go to a location
    NavigateTo(Pose),
    // Set the raw trajectory of the robot, Rover Nexus only sends this in teleop mode.
    VelocityCmd(VelTwist),
    // Joystick command intended for teleop usage. Rover Nexus only sends this in teleop mode.
    TeleopJoy(TeleopJoy),
    // Request the robot to do something, intended for robots with LLM agents
    AgentTextRequest(AgentTextRequest),
    // Request the robot say something, for robots with speech capabilities
    SayText(SayTextRequest),
    // Operator confirmation of a robot message
    MessageConfirmation(MessageConfirmation),
}

// From rover to fleet command, formerly UplinkMsg
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum RobotUplinkMsg {
    MissionRunStatus(MissionRunStatus), // Mission status and progress
    GlobalMotionTelemetry(GlobalMotionTelemetry), // global robot GPS location
    LocalMotionTelemetry(LocalMotionTelemetry), // Local coordinate odometry.
    StatusTelemetry(StatusTelemetry),   // high level robot status
    SensorTelemetry(SensorTelemetry), // Sensor readings, including responses to InvokeService(ServiceCall)
    Capabilities(Capabilities), // What services, sensors, and settings that should be available on Rover Nexus. Re-sent by agent if needed
    AllowedCommands(AllowedCommands), // What InternalCommand messages the robot accepts, reliable delivery
    Fault(Fault),                     // A robot fault, robot must set and clear
    Feature(ReportedFeatureUpdate),   // World Feature reported by the robot
    Object(ObjectOp),                 // Object detected by the robot
    SystemHealth(SystemHealth),       // CPU, Memory, system device health
    UsageTelemetry(UsageTelemetry),   // Robot usage data
    ConsumableStatus(ConsumableStatus), // Levels of a consumable on the robot
    CurrentSettings(Vec<SettingUpdate>), // Snapshot of the robot's current settings. Re-sent.
    Message(Message), // Reliable, a message from the robot to appear in the Rover Nexus UI.
    AgentInfo(AgentInfo), // Re-sent by rover-agent if needed, robot software does not send
    SpatialDirectiveStatus(SpatialDirectiveStatus), // Status of a spatial directive reported by the robot agent by default.
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum MessageLevel {
    Info,
    Warn,
    Error,
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ServiceCall {
    pub service_name: String,
    pub setting: Option<bool>,
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ControlMissionRun {
    pub mission_id: String,
    pub run_id: String,
    pub action: MissionRunAction,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum MissionRunAction {
    Pause,
    Resume,
    Cancel,
    Abort,
}

// This is not log storage. Use your own logging infrastructure.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Message {
    pub unix_time_ms: i64,
    pub level: MessageLevel,
    pub message: String,
    pub needs_confirmation: bool, // Require the user to confirm or deny.
    pub confirmation_id: String,  // For confirming messages
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct MessageConfirmation {
    pub confirmed: bool,
    pub confirmation_id: String,
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AgentTextRequest {
    pub text: String,
    pub intent: AgentTextIntent,
    pub response_required: bool, // The robot must reply to Rover Nexus with a Message
}

/// An intent from the operator to a robot
/// This can only communicate intent, the robot must enforce operational safety.
/// It is recommended to sanitize inputs on the robot
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum AgentTextIntent {
    ObserveAndReport,       // Robot should retrieve data, then respond
    AnswerQuestion,         // Robot should not take action, simply answer the question
    OperatorInstruction,    // Operator asks the robot to take action
    TroubleshootingRequest, // Operator requests troubleshooting / diagnosis
    GeneralMessage,         // Anything else from operator to robot
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SayTextRequest {
    pub text: String,
    pub priority: SpeechPriority,
}

/// Speech priority, this is intent, must be enforced by the robot
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum SpeechPriority {
    Low,       // Say this at the robot's next convenience
    Next,      // Say this ASAP
    Interrupt, // interrupt current speech
}

/// Rover nexus rover-agent version. NOT LLM INFO.
/// Robot software does not need to send this
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AgentInfo {
    pub agent_version: String,
    pub software_version: Option<String>,
    pub os_info: Option<String>, // "Ubuntu 22.04 aarch64" - debugging
    pub uptime_s: Option<u64>,   // how long since boot - detect frequent reboots
}

/// What commands this robot allows.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AllowedCommands {
    pub set_mode: bool,
    // Pause and Resume are intentionally not represented here.
    // Robots cannot opt out of receiving Pause or Resume commands.
    pub assign_mission: bool,
    pub control_mission_run: bool,
    pub invoke_service: bool,
    pub update_settings: bool,
    pub update_feature: bool,
    pub spatial_directive: bool,
    pub object: bool,
    pub go_to: bool,
    pub velocity_cmd: bool,
    pub teleop_joy: bool,
    pub agent_text_request: bool,
    pub say_text_request: bool,
    pub message_confirmation: bool,
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct TeleopJoy {
    pub source_id: String,  // "webrtc-ui", "local-gamepad", "api-client:abc"
    pub session_id: String, // unique per teleop takeover/session
    pub axes: Vec<f32>,
    pub buttons: Vec<bool>,
    pub timestamp_ms: i64,
}

/// Server -> robot operation carrying a bare spatial primitive (Shape or Route).
/// Use `SpatialDirectiveOp` instead when the payload also carries timing,
/// parameters, or capabilities for application within a zone.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum FeatureOp {
    Upsert(Feature),
    Delete { id: String },
}

/// Server -> robot operation carrying a `SpatialDirective` (a persistent zone
/// with timing, parameters, and capabilities to apply within it).
// `Upsert` is intentionally unboxed: it is the common variant, the wire format
// (Cap'n Proto / JSON) is identical whether or not it is boxed, and boxing would
// only add a public-API `Box::new` requirement plus a hot-path allocation.
#[allow(clippy::large_enum_variant)]
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum SpatialDirectiveOp {
    Upsert(SpatialDirective),
    Delete { id: String },
}

// Object reported from the robot to Rover Nexus, scope determines if it is forwarded to other robots in the fleet
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum ObjectOp {
    Upsert(Object),
    Delete { id: String },
}

// Robot -> Rover Nexus feature/resource update.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ReportedFeatureUpdate {
    // The producer channel this update belongs to.
    pub resource_producer_id: String,
    pub timestamp_ms: i64,
    pub op: ReportedFeatureOp,
}

// For the robot to report a shape/geographic feature to Rover Nexus.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum ReportedFeatureOp {
    // Replace the whole feature for this producer/resource.
    Upsert(ReportedFeature),
    // Clear/delete the whole feature for this producer/resource.
    Clear,
}

#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RobotState {
    pub motion_dirty: bool,
    pub status_dirty: bool,
    pub extras_dirty: bool,
    // Set dirty bools when new data is written to the state
    // Set to false when uplink reads it to send to server
    pub motion_telemetry: GlobalMotionTelemetry,
    pub status_telemetry: StatusTelemetry,
    pub extras: SensorTelemetry,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum FaultSeverity {
    Info,
    Minor,
    Major,
    Critical,
}

/// Fault report structure for robot system faults
/// Robot software must send active == false when the fault clears, otherwise it persists on Rover Nexus
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Fault {
    pub unix_time_ms: i64,
    pub fault_id: String, // stable code, e.g. "BATTERY_UNDERVOLT"
    pub source: String,   // node/sensor
    pub severity: FaultSeverity,
    pub active: bool,             // true on raise, false on clear
    pub category: String,         // power, comms, nav, safety, etc.
    pub description: String,      // short human text
    pub suggested_action: String, // optional remediation hint
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum MissionStatus {
    Unknown,
    Ready,    // Accepted
    Starting, // Don't stay in this state
    Running,
    Paused,
    Blocked,
    Aborted,
    Completed,
    Error,
}

impl MissionStatus {
    /// Whether this is a terminal mission state — the run has finished and will
    /// not progress further (`Completed`, `Aborted`, or `Error`). All other
    /// states (including `Paused`/`Blocked`) are non-terminal: the run can still
    /// advance from them.
    pub fn is_terminal(self) -> bool {
        matches!(
            self,
            MissionStatus::Completed | MissionStatus::Aborted | MissionStatus::Error
        )
    }
}

// Capability and UI related types
// =============================================

// Robot -> UI: frequent, minimal, just the data
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct SensorReading {
    pub key: String,
    pub value: Value,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub unix_time_ms: Option<i64>, // per reading timestamp
}

// Tells the UI how to display the data
// Not all items are implemented yet
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub enum DisplayHint {
    None,  // Likely text
    OnOff, // Says On or Off with a little style
    Gauge, // ?
    Text,
    Online,       // Green "light"
    WarningLight, // Amber "light"
    Temperature,  // ?
    Progress,     // Health bar filled from left to right
                  // etc.
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct Range {
    pub min: f64,
    pub max: f64,
}

// Robot -> UI: once on connect or when config changes
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct SensorDescriptor {
    pub key: String,           // in code key for uniqueness
    pub label: String,         // label on the UI
    pub value_type: ValueType, // See ValueType
    #[serde(skip_serializing_if = "Option::is_none")]
    pub unit: Option<String>, // Unit appended to the value
    #[serde(skip_serializing_if = "Option::is_none")]
    pub range: Option<Range>, // for coloring and display range of gauges/visualization
    pub display_hint: DisplayHint, // How to show the reading, see DisplayHint
}

// Features/Resources that the robot can produce that can be used in Rover Nexus missions and operations
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct ResourceProducerDescriptor {
    pub resource_producer_id: String, // shared resource id
    pub label: String, // label on the UI, will be resource_id if left blank, for display only
    pub layer_role: LayerRole, // See LayerRole
    pub geometry_type: GeometryType,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>, // optional human-readable description shown in the UI
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub enum GeometryType {
    Point,
    LineString,
    Polygon,
    MultiPoint,
    MultiLineString,
    MultiPolygon,
}

// Custom sensor states and values reported by the robot software
// Rates & limits: let OEM push at their chosen rate, but expect the server to
// enforce rate caps, per-message size limits, and a maximum kv length.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SensorTelemetry {
    pub unix_time_ms: i64,
    /// Arbitrary scalar/status values published by the robot/OEM.
    /// Must correspond with a Sensor Capability
    /// Example entries:
    ///   "deck_rpm" -> "3120"
    ///   "hydraulic_temp_c" -> "64.2"
    ///   "camera_front_ok" -> "true"
    ///   "tilt_deg" -> "18.5"
    pub kv: Vec<SensorReading>,
}

// UI <-> Robot: user changing a setting
// This is always a patch message
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct SettingUpdate {
    pub key: String,
    pub value: Value,
}

// Robot -> UI: what settings exist and their constraints
// Includes a default value which defines the expected type as well
// Validate at ingest: “default matches value_type”
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct SettingDescriptor {
    pub key: String,
    pub label: String,
    pub value_type: ValueType,
    pub default: serde_json::Value,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub range: Option<Range>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub step: Option<f64>,
}

// What role the user must be to use the service, otherwise greyed out
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum Role {
    Viewer,
    Operator,
    Admin,
    Owner,
}

// How to display and also what message is sent
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum CapabilityType {
    Trigger,     // Button one-shot
    SetBool,     // 2 linked buttons for on and off
    MissionType, // No button, expresses a mission type a robot can do
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum DangerLevel {
    #[default]
    Normal, // regular styling
    Warning,  // yellow, requires confirmation
    Critical, // red, maybe requires typing "CONFIRM" or similar
}

// Defines what a robot can do, these become buttons and can also be tied to missions and areas
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ServiceCapability {
    pub name: String,                         // "start_mowing"
    pub description: String,                  // "Begin autonomous mowing routine"
    pub capability_type: CapabilityType,      // what args are needed (or empty)
    pub confirmation_message: Option<String>, // warn optionally with custom warning text
    pub state_key: Option<String>, // what sensor key is associated with this control, for displaying together
    pub requires_role: Role,       // e.g. "operator" or "admin", minimum role
    #[serde(default)]
    pub danger_level: DangerLevel, // Danger level, warning and critical require confirmation, default Normal
}

// Ui capabilities message that tells Rover Nexus what the robot can do and what settings it has
// The agent sends this on startup based on the robot.toml config. The robot software may optionally send it.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Capabilities {
    // Each category defaults to an empty list when absent, so a partial payload
    // or a capability row persisted before a newer category existed (e.g. JSON
    // without `resourceProducers`) still deserializes instead of erroring. An
    // absent category means "none of this kind", which is a valid state.
    #[serde(default)]
    pub services: Vec<ServiceCapability>, // These become buttons
    #[serde(default)]
    pub sensors: Vec<SensorDescriptor>, // What values are available and how to display them
    #[serde(default)]
    pub settings: Vec<SettingDescriptor>, // these become editable boxes when clicked, then all are sent with a "Save Settings" button
    #[serde(default)]
    pub resource_producers: Vec<ResourceProducerDescriptor>, // shared features the robot can add to to be used in operations and missions
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub enum ValueType {
    String,                        // Text box
    Int,                           // Text box accepts numbers only
    Number,                        // Text box accepts numbers only
    Bool,                          // Toggle switch, as 2 buttons
    Enum { options: Vec<String> }, // Always becomes a dropdown
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase", tag = "type", content = "data")]
pub enum Value {
    String(String),
    Int(i32),
    Number(f64),
    Bool(bool),
    Enum(String),
}

// End of capability types
// =============================================

/// Operational mode of the robot. Estop is reported separately on
/// `StatusTelemetry.estop`; fault conditions are reported separately as
/// `UplinkMsg::Fault`. RobotMode covers only the active operating mode.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum RobotMode {
    Manual,
    Auto,
    Teleop,
    Disabled,
    Maintenance,
}

// Mission status sent back, should be periodically sent as a mission progresses.
// The robot software is responsible for reporting the final state of a mission in status
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct MissionRunStatus {
    pub unix_time_ms: i64,
    pub mission_id: String,
    pub run_id: String,
    pub status: MissionStatus,
    pub status_message: Option<String>,
    pub progress_x100: Option<u16>, // progress_x100 (0..=10000) = percent * 100
    pub current_path_id: Option<String>,
    pub current_target: Option<GeoPose>,
    pub current_step: Option<u32>, // Can be waypoints
    pub total_steps: Option<u32>,
    // When this mission actually started running on the robot.
    pub time_started_ms: Option<i64>,
    // The robot's current best guess of when it'll be done.
    // This can move as the situation changes.
    pub expected_end_time_ms: Option<i64>,
    // Set when mission reaches a terminal state (COMPLETE / CANCELED / ERROR).
    pub time_completed_ms: Option<i64>,
    pub name: Option<String>, // If the robot makes and unknown mission or wants to rename the current mission
                              // Add pub remaining_distance_m: Option<f64>,
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct AssetIdentity {
    pub id: String,   // persistent id of the shape or route
    pub name: String, // display/debug only,
    pub rev: u32,     // 0 => not provided // Rev of 0 means not provided and can be ignored
    pub hash: String, // "" => not provided // Hash of the payload file pathHash == "" means “not provided”
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub enum CapabilityTiming {
    ImmediateTrigger, // fire once now at step start
    AtTargetTrigger,  // fire once after reaching target or starting path
    DuringStep,       // enable at start, disable at end. if bool
    DuringFeature,    // enable while traversing feature, disable at end if bool
    FinalTrigger,     // Fire at end of navigation
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct MissionCapability {
    pub name: String,
    pub timing: CapabilityTiming,
    pub value: bool,
}

/// A mission order from the fleet manager with one asset, one time use
/// Contains spatial data
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct MissionCommand {
    pub mission_id: String, // mission template UUID, given by fleet manager
    pub run_id: String,     // Given by scheduler on robot agent
    pub name: String,       // display name
    pub user_id: String,    // Who deployed the mission
    pub detail: String,     // Description for user's benefit
    // Times come from browser as ms in JSON, must be converted
    pub scheduled_start_ms: i64,                // milliseconds
    pub expected_end_time_ms: Option<i64>,      // Can be deadline, milliseconds
    pub mission_parameters: Vec<SettingUpdate>, // Settings to apply at the start of this mission step
    pub capabilities: Vec<MissionCapability>, // what features or services this mission should use or call
    pub feature: Option<Feature>,             // Path to follow, waypoints, or coverage area
}

/// SpatialDirective - a persistent zone (geometry + active rules) sent from
/// fleet to robot. Combines a `SpatialFeature` (Shape or Route) with timing,
/// zone parameters, and capabilities to invoke while in/at the zone.
///
/// This is distinct from a bare `SpatialFeature`, which is just geometry, and
/// from `MissionCommand`, which is a one-shot mission order.
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct SpatialDirective {
    pub directive_id: String,        // UUID, given by fleet manager
    pub name: String,                // display name
    pub start_time_ms: i64,          // when it should start being applied
    pub expire_time_ms: Option<i64>, // when it should expire
    pub zone_parameters: Vec<SettingUpdate>,
    pub capabilities: Vec<String>, // What services or features to apply in or on this zone
    pub spatial: Feature,
}

// Feedback about if a robot is in a zone and applying the directive specified by SpatialDirective
#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct SpatialDirectiveStatus {
    pub directive_id: String,
    pub last_eval_time_ms: i64,
    pub active: bool,      // currently inside + within time window + applicable
    pub inside_zone: bool, // robot's local evaluation
    pub distance_to_zone_m: Option<f32>,
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct Schedule {
    /// Who is responsible for scheduling triggers.
    /// - Server: server will enqueue MissionRuns.
    /// - Agent: rover-agent on robot will self-schedule when it receives this MissionCommand.
    /// - Robot: robot will self-schedule when it receives this MissionCommand.
    pub owner: TriggerSource,

    /// Interpreting cron requires a timezone; store it explicitly.
    /// Examples: "America/Phoenix", "UTC"
    pub timezone: String,

    /// Optional: don’t generate triggers before this time.
    pub start_time_ms: Option<i64>,

    /// Optional: stop generating triggers after this time.
    pub end_time_ms: Option<i64>,

    /// The actual schedule definition.
    pub kind: ScheduleKind,
}

#[derive(Debug, Clone, Copy, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub enum TriggerSource {
    Server,
    Agent,
    Robot,
}

#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)]
#[serde(rename_all = "camelCase", rename_all_fields = "camelCase")]
pub enum ScheduleKind {
    /// Classic cron string.
    /// Choose a convention and document it (5-field vs 6/7-field).
    Cron {
        /// e.g. "0 6 * * 1-5" (06:00 Mon–Fri) if using 5-field cron (min hour dom mon dow)
        expr: String,
    },

    /// Simple interval schedule (super easy for OEMs)
    Interval {
        every_seconds: u32,
    },
    Once, // Only fire once at the start time
}

/// Origin of the GPS fix reported on `MotionTelemetry`. Replaces two booleans
/// (`gps_simulated`, `gps_estimated`) that allowed nonsensical "both true"
/// states. The default for actual hardware fixes is `Real`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, Default)]
#[serde(rename_all = "camelCase")]
pub enum GpsSource {
    #[default]
    Real, // actual hardware fix
    Simulated, // running in a simulator, no real hardware
    Estimated, // hardware lost lock, using dead-reckoning / IMU
}

// High frequency motion data
// Odometry will override this value if sent after
// This bumps the last seen time on Rover Nexus and will tell the server that the robot is online
// Recommended publish rate: 1Hz when idle, Maximum 10Hz when in motion. Will be throttled above 10Hz,
// the latest value is always forwarded by the agent
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct GlobalMotionTelemetry {
    pub unix_time_ms: i64,
    pub pose: Option<GeoPose>,
    pub velocity: Option<VelTwist>,
    pub gps_fix: Option<GpsFixType>, // optional: include if you want map accuracy/confidence
    pub gps_source: GpsSource,
}

// High frequency motion data
// GlobalMotionTelemetry will override this value if sent after
// This bumps the last seen time on Rover Nexus and will tell the server that the robot is online
// Recommended publish rate: 1Hz when idle, Maximum 10Hz when in motion. Will be throttled above 10Hz,
// the latest value is always forwarded by the agent
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct LocalMotionTelemetry {
    pub unix_time_ms: i64,
    pub pose: LocalPose,
    pub velocity: VelTwist,
    pub accuracy_m: Option<f32>,
    /// Optional but useful if the local frame can change.
    pub frame: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct VelTwist {
    pub forward_mps: f32,
    pub angular_radps: f32,
}

// General status of the robot, must be published by robot software,
// This bumps the last seen time on Rover Nexus and will tell the server that the robot is online
// Recommended publish rate: 1Hz.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct StatusTelemetry {
    pub unix_time_ms: i64,
    pub battery: Option<BatteryStatus>,
    pub fuel: Option<FuelStatus>,
    pub range_remaining_m: Option<f64>,   // meters
    pub runtime_remaining_s: Option<f64>, // seconds
    pub mode: Option<RobotMode>,
    pub estop: EStop,
    pub faulted: bool,
    pub accepting_missions: bool, // was mission_active, which is now covered by the mission run status message, this is to indicate availability
    pub status: String,           // OEM-defined status string
}

// Robot usage statistics, source of truth must be the robot software that talks to the agent.
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct UsageTelemetry {
    pub unix_time_ms: i64,
    // Distance metrics
    pub total_distance_m: f64,
    pub auto_distance_m: f64,
    pub manual_distance_m: f64,
    // Time metrics
    pub uptime_total_s: f64,
    pub drive_time_total_s: f64,
    pub auto_time_total_s: f64,
    // Counters
    pub mission_count_total: u32,
    pub charge_cycles_total: u32,
    pub reboot_count: u32,
    // Last reboot (epoch ms)
    pub last_reboot_unix_time_ms: i64,
}

// This message is filled and published by the robot agent once every 5 seconds,
// the robot software may optionally publish their own to override the agent
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SystemHealth {
    pub unix_time_ms: i64,
    pub device_id: String, // if multiple computers or cpus on one robot, cpu1, gpu2, etc.
    pub cpu_pct: f32,
    pub mem_pct: f32,
    pub disk_pct: f32,
    pub cpu_temp: f32,
    pub signal_strength: f32, // RSSI
    pub signal_quality: f32,  // standard wifi link quality
}

// signal that the robot has been E-stopped and cannot take commands
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct EStop {
    pub unix_time_ms: i64,
    pub active: bool,
    pub ids: Vec<String>,
}

// Determines how messages are propagated through the fleet,
// This says who the intended recipient is.
#[repr(u8)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum ScopeType {
    Robot = 0,
    Fleet = 1,
    World = 2,
    User = 3,
}

#[repr(u8)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum ObjectType {
    Unknown = 0,
    // Living things
    Person = 1,
    Animal = 2,
    // Vehicles / mobile equipment
    Vehicle = 3,
    Robot = 4,
    // Infrastructure / static man-made things
    Structure = 5,
    Equipment = 6,
    // Physical obstacles / terrain-relevant things
    Obstacle = 7,
    Debris = 8,
    // Safety / operationally important things
    Hazard = 9,
    Marker = 10,
    PointOfInterest = 11,
}

#[repr(u8)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum LayerRole {
    // --- Intent / User-defined ---
    AllowedArea = 0,   // Geofence, an area the robot must stay inside
    Preferred = 1,     // Preferred area to drive, for planning
    Keepout = 2,       // Do not go here
    SoftExclusion = 3, // prefer not to go here
    WorkArea = 4,      // a resource the robot should do work on
    Target = 5,        // Goal the robot should go to / the robot's target
    Queue = 6,         // Staging, waiting, charging or queue area
    ControlZone = 7,   // Enforce a setting here
    TriggerZone = 8,   // Trigger something on entry / exit
    // --- State / System-generated ---
    Coverage = 10,    // Area the robot worked on, i.e. harvested field area
    Occupied = 11,    // Used by the reporting robot directly
    Reserved = 12,    // Robot is going to use this space, do not assign
    Consumed = 13,    // permanently or semi-permanently no longer available
    Hazard = 14,      // unsafe area
    Blocked = 15,     // impassible
    PlannedPath = 16, // where the robot will go, path and target
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Feature {
    pub identity: AssetIdentity,
    pub layer_role: LayerRole,
    pub scope: ScopeType,
    pub data: SpatialData,
    pub expires_at_ms: i64, // Unix time to discard the feature, in milliseconds
    // min_z_m/max_z_m (optional): treat area as an extruded prism for bridges/parking decks/ramps.
    pub min_z_m: f64,
    pub max_z_m: f64,
    pub level_id: i32, // level_id (optional): for multi-storey sites. Default to 0
}

// Reported shape from robot to Rover Nexus, if the scope is world or fleet, it is forwarded to all robots in the fleet
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ReportedFeature {
    pub name: String, // Human readable name, used as a unique id relative to the source robot
    pub layer_role: LayerRole,
    pub scope: ScopeType, // Rover Nexus gates this and can override
    pub data: SpatialData,
    pub expires_at_ms: i64, // Unix Time to discard the feature in milliseconds
    // min_z_m/max_z_m (optional): treat area as an extruded prism for bridges/parking decks/ramps.
    pub min_z_m: Option<f64>,
    pub max_z_m: Option<f64>,
    pub level_id: Option<i32>, // level_id (optional): for multi-storey sites.
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Trajectory {
    pub speed_mps: f64,         // scalar, meters/second
    pub course_deg: f64,        // degrees, 0=North (direction of travel, not heading)
    pub vertical_rate_mps: f64, // m/s, positive = ascending (drones only)
}

// Specifically for object tracking
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Object {
    pub identity: AssetIdentity,
    pub unix_time_ms: i64,  // Time of most recent detection
    pub expires_at_ms: i64, // Unix time to discard the object
    pub scope: ScopeType, // Robot and user just send to fleet manager, Fleet and world send to all robots in fleet
    pub object_type: ObjectType,
    pub pose: Pose,
    pub trajectory: Trajectory, // 3D velocity vector
    pub radius_m: f64,          // meters
}

// For ROS2
// # Navigation Satellite fix status for any Global Navigation Satellite System.
// # Whether to output an augmented fix is determined by both the fix
// # type and the last time differential corrections were received.  A
// # fix is valid when status >= STATUS_FIX.
// int8 STATUS_NO_FIX =  -1        # unable to fix position
// int8 STATUS_FIX =      0        # unaugmented fix
// int8 STATUS_SBAS_FIX = 1        # with satellite-based augmentation
// int8 STATUS_GBAS_FIX = 2        # with ground-based augmentation
// int8 status
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum GpsFixType {
    Unknown,
    Invalid,
    #[serde(rename = "GPS")]
    GPS, // maps to unaugmented fix
    #[serde(rename = "DGPS")]
    DGPS, // Differential
    #[serde(rename = "SBAS")]
    SBAS,
    FloatRTK,
    FixedRTK,
    #[serde(rename = "PPS")]
    PPS,
    GBAS, // Ros2 reported ground-based augmentation
}

impl GpsFixType {
    /// Convert from i8 representation (for ROS compatibility)
    // int8 STATUS_NO_FIX=-1
    // int8 STATUS_FIX=0
    // int8 STATUS_SBAS_FIX=1
    // int8 STATUS_GBAS_FIX=2
    pub fn from_ros_status(value: i8) -> Self {
        match value {
            -1 => Self::Invalid,
            0 => Self::GPS,
            1 => Self::SBAS,
            2 => Self::FixedRTK,
            _ => Self::Unknown,
        }
    }

    pub fn from_u8(value: u8) -> Self {
        match value {
            0 => Self::Unknown,
            1 => Self::Invalid,
            2 => Self::GPS,
            3 => Self::DGPS,
            4 => Self::SBAS,
            5 => Self::FloatRTK,
            6 => Self::FixedRTK,
            7 => Self::PPS,
            8 => Self::GBAS,
            _ => Self::Unknown,
        }
    }

    /// Convert to u8 representation (for ROS compatibility)
    pub fn to_u8(self) -> u8 {
        match self {
            Self::Unknown => 0,
            Self::Invalid => 1,
            Self::GPS => 2,
            Self::DGPS => 3,
            Self::SBAS => 4,
            Self::FloatRTK => 5,
            Self::FixedRTK => 6,
            Self::PPS => 7,
            Self::GBAS => 8,
        }
    }
}

/// Power supply status
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum PowerSupplyStatus {
    Unknown,
    Charging,
    Discharging,
    NotCharging,
    Full,
}

impl PowerSupplyStatus {
    /// Convert from u8 representation (for ROS compatibility)
    pub fn from_u8(value: u8) -> Self {
        match value {
            1 => Self::Charging,
            2 => Self::Discharging,
            3 => Self::NotCharging,
            4 => Self::Full,
            _ => Self::Unknown,
        }
    }

    /// Convert to u8 representation (for ROS compatibility)
    pub fn to_u8(self) -> u8 {
        match self {
            Self::Unknown => 0,
            Self::Charging => 1,
            Self::Discharging => 2,
            Self::NotCharging => 3,
            Self::Full => 4,
        }
    }
}

/// Power supply health
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum PowerSupplyHealth {
    Unknown,
    Good,
    Overheat,
    Dead,
    Overvoltage,
    UnspecifiedFailure,
    Cold,
    WatchdogTimerExpire,
    SafetyTimerExpire,
}

impl PowerSupplyHealth {
    /// Convert from u8 representation (for ROS compatibility)
    pub fn from_u8(value: u8) -> Self {
        match value {
            1 => Self::Good,
            2 => Self::Overheat,
            3 => Self::Dead,
            4 => Self::Overvoltage,
            5 => Self::UnspecifiedFailure,
            6 => Self::Cold,
            7 => Self::WatchdogTimerExpire,
            8 => Self::SafetyTimerExpire,
            _ => Self::Unknown,
        }
    }

    /// Convert to u8 representation (for ROS compatibility)
    pub fn to_u8(self) -> u8 {
        match self {
            Self::Unknown => 0,
            Self::Good => 1,
            Self::Overheat => 2,
            Self::Dead => 3,
            Self::Overvoltage => 4,
            Self::UnspecifiedFailure => 5,
            Self::Cold => 6,
            Self::WatchdogTimerExpire => 7,
            Self::SafetyTimerExpire => 8,
        }
    }
}

/// Power supply technology (battery chemistry)
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub enum PowerSupplyTechnology {
    Unknown,
    NiMH,
    LiIon,
    LiPo,
    LiFe,
    NiCd,
    LiMn,
}

impl PowerSupplyTechnology {
    /// Convert from u8 representation (for ROS compatibility)
    pub fn from_u8(value: u8) -> Self {
        match value {
            1 => Self::NiMH,
            2 => Self::LiIon,
            3 => Self::LiPo,
            4 => Self::LiFe,
            5 => Self::NiCd,
            6 => Self::LiMn,
            _ => Self::Unknown,
        }
    }

    /// Convert to u8 representation (for ROS compatibility)
    pub fn to_u8(self) -> u8 {
        match self {
            Self::Unknown => 0,
            Self::NiMH => 1,
            Self::LiIon => 2,
            Self::LiPo => 3,
            Self::LiFe => 4,
            Self::NiCd => 5,
            Self::LiMn => 6,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct BatteryStatus {
    pub soc_pct: f32, // 0 to 100
    pub voltage_v: Option<f32>,
    pub current_a: Option<f32>,
    pub charge_ah: Option<f32>,
    pub capacity_ah: Option<f32>,
    pub design_capacity_ah: Option<f32>,
    pub temperature: Option<f32>,
    pub power_supply_status: PowerSupplyStatus,
    pub power_supply_health: PowerSupplyHealth,
    pub power_supply_technology: PowerSupplyTechnology,
}

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct FuelStatus {
    pub level_pct: f32, // 0 to 100
    pub volume_remaining: Option<f32>,
    pub capacity: Option<f32>,           // how big is tank
    pub volume_unit: Option<String>,     // Liters or gallons or teaspoons if you like
    pub efficiency: Option<f32>,         // like miles per gallon
    pub efficiency_unit: Option<String>, // like miles per gallon
    pub is_refueling: bool,
}

#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ConsumableStatus {
    pub unix_time_ms: i64,
    pub kind: String,          // herbicide, water, seed
    pub tank_id: String,       // "main", "left", "right", etc.
    pub level_pct: f32,        // 0–100
    pub amount_remaining: f32, // quantity scalar
    pub unit: String,          // Unit for amount_remaining
    pub is_critical: bool,     // precomputed by robot if it wants
}