mecha10_controllers/

lib.rs

//! Hardware Controller Abstractions for Mecha10
//!
//! This crate provides a composable layer between hardware drivers and nodes.
//! Controllers wrap device SDKs/libraries and provide standardized interfaces
//! for nodes to manage hardware.
//!
//! # Architecture
//!
//! ```text
//! ┌─────────────────┐
//! │     Node        │  (Business logic)
//! └────────┬────────┘
//!          │
//!          ▼
//! ┌─────────────────┐
//! │   Controller    │  (Device management + SDK abstraction)
//! └────────┬────────┘
//!          │
//!          ▼
//!   ┌──────────────┐
//!   │ Hardware SDK │  (realsense-rust, bno055, etc.)
//!   └──────────────┘
//! ```
//!
//! # Core Concepts
//!
//! - **Controller**: Base trait for all hardware controllers
//! - **Domain-specific traits**: CameraController, ImuController, etc.
//! - **Health monitoring**: Built-in health checks and diagnostics
//! - **Capability discovery**: Query what a controller can do
//! - **Testing support**: Mock implementations for easy testing
//!
//! # Example
//!
//! ```rust,no_run
//! use mecha10_controllers::{Controller, CameraController};
//! use mecha10_controllers::camera::RealSenseController;
//!
//! #[tokio::main]
//! async fn main() -> anyhow::Result<()> {
//!     // Initialize controller
//!     let config = RealSenseConfig::default();
//!     let mut camera = RealSenseController::init(config).await?;
//!
//!     // Start acquisition
//!     camera.start().await?;
//!
//!     // Use controller
//!     let frame = camera.capture_frame().await?;
//!     println!("Captured frame: {}x{}", frame.width, frame.height);
//!
//!     // Clean shutdown
//!     camera.stop().await?;
//!     Ok(())
//! }
//! ```

use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::fmt;

pub mod camera;
pub mod imu;
pub mod lidar;
pub mod mock;
pub mod motor;

// Re-export traits
pub use camera::CameraController;
pub use imu::ImuController;
pub use lidar::LidarController;
pub use motor::MotorController;

// ============================================================================
// Core Controller Trait
// ============================================================================

/// Base trait for all hardware controllers
///
/// Controllers manage the lifecycle and interaction with physical hardware
/// or simulated devices. They abstract device SDKs and provide consistent
/// interfaces for nodes to use.
#[async_trait]
pub trait Controller: Send + Sync {
    /// Configuration type for this controller
    type Config: Send + Sync;

    /// Error type for this controller
    type Error: std::error::Error + Send + Sync + 'static;

    /// Initialize the controller with the given configuration
    ///
    /// This should perform all necessary setup including:
    /// - Opening device connections
    /// - Configuring device parameters
    /// - Running initialization sequences
    /// - Loading calibration data
    async fn init(config: Self::Config) -> Result<Self, Self::Error>
    where
        Self: Sized;

    /// Start the controller
    ///
    /// Begin data acquisition, motor control, or other active operations.
    /// This may start background threads or async tasks.
    async fn start(&mut self) -> Result<(), Self::Error>;

    /// Stop the controller
    ///
    /// Stop all active operations gracefully. The controller should still
    /// be in a valid state and can be restarted with `start()`.
    async fn stop(&mut self) -> Result<(), Self::Error>;

    /// Check the health status of the controller
    async fn health_check(&self) -> ControllerHealth;

    /// Get the capabilities of this controller
    ///
    /// Returns metadata about what features and operations this controller
    /// supports. This is useful for runtime capability detection.
    fn capabilities(&self) -> ControllerCapabilities;

    /// Get controller-specific diagnostics
    ///
    /// Returns detailed diagnostic information for debugging and monitoring.
    async fn diagnostics(&self) -> HashMap<String, String> {
        HashMap::new()
    }
}

// ============================================================================
// Health and Capabilities
// ============================================================================

/// Health status of a controller
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum ControllerHealth {
    /// Controller is healthy and ready
    Healthy,

    /// Controller is running but degraded (e.g., some sensors failing)
    Degraded { reason: String },

    /// Controller is unhealthy and not functioning
    Unhealthy { reason: String },

    /// Controller health is unknown (e.g., not initialized)
    Unknown,
}

impl fmt::Display for ControllerHealth {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Healthy => write!(f, "Healthy"),
            Self::Degraded { reason } => write!(f, "Degraded: {}", reason),
            Self::Unhealthy { reason } => write!(f, "Unhealthy: {}", reason),
            Self::Unknown => write!(f, "Unknown"),
        }
    }
}

/// Capabilities of a controller
///
/// Describes what features and operations a controller supports.
/// This allows runtime capability detection and adaptation.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ControllerCapabilities {
    /// Controller type identifier (e.g., "camera", "imu", "lidar")
    pub controller_type: String,

    /// Specific implementation (e.g., "realsense", "bno055", "rplidar")
    pub implementation: String,

    /// Hardware vendor (e.g., "Intel", "Bosch", "Slamtec")
    pub vendor: Option<String>,

    /// Hardware model (e.g., "D435i", "BNO055", "A2M8")
    pub model: Option<String>,

    /// Firmware version if available
    pub firmware_version: Option<String>,

    /// Feature flags indicating what operations are supported
    pub features: HashMap<String, bool>,

    /// Additional metadata
    pub metadata: HashMap<String, String>,
}

impl ControllerCapabilities {
    /// Create a new capabilities struct
    pub fn new(controller_type: impl Into<String>, implementation: impl Into<String>) -> Self {
        Self {
            controller_type: controller_type.into(),
            implementation: implementation.into(),
            vendor: None,
            model: None,
            firmware_version: None,
            features: HashMap::new(),
            metadata: HashMap::new(),
        }
    }

    /// Add a feature flag
    pub fn with_feature(mut self, name: impl Into<String>, supported: bool) -> Self {
        self.features.insert(name.into(), supported);
        self
    }

    /// Add metadata
    pub fn with_metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.metadata.insert(key.into(), value.into());
        self
    }

    /// Set vendor
    pub fn with_vendor(mut self, vendor: impl Into<String>) -> Self {
        self.vendor = Some(vendor.into());
        self
    }

    /// Set model
    pub fn with_model(mut self, model: impl Into<String>) -> Self {
        self.model = Some(model.into());
        self
    }

    /// Check if a feature is supported
    pub fn supports(&self, feature: &str) -> bool {
        self.features.get(feature).copied().unwrap_or(false)
    }
}

// ============================================================================
// Common Errors
// ============================================================================

/// Common controller errors
#[derive(Debug, thiserror::Error)]
pub enum ControllerError {
    /// Device not found or not connected
    #[error("Device not found: {0}")]
    DeviceNotFound(String),

    /// Device initialization failed
    #[error("Initialization failed: {0}")]
    InitializationFailed(String),

    /// Device communication error
    #[error("Communication error: {0}")]
    CommunicationError(String),

    /// Invalid configuration
    #[error("Invalid configuration: {0}")]
    InvalidConfiguration(String),

    /// Operation timeout
    #[error("Operation timed out: {0}")]
    Timeout(String),

    /// Device is not in the correct state for this operation
    #[error("Invalid state: {0}")]
    InvalidState(String),

    /// Hardware fault detected
    #[error("Hardware fault: {0}")]
    HardwareFault(String),

    /// Feature not supported by this controller
    #[error("Feature not supported: {0}")]
    NotSupported(String),

    /// Generic error
    #[error("Controller error: {0}")]
    Other(String),
}

// ============================================================================
// Controller State
// ============================================================================

/// Common controller states
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum ControllerState {
    /// Not initialized
    Uninitialized,

    /// Initialized but not started
    Initialized,

    /// Running normally
    Running,

    /// Stopped
    Stopped,

    /// Error state
    Error,
}

impl fmt::Display for ControllerState {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Uninitialized => write!(f, "Uninitialized"),
            Self::Initialized => write!(f, "Initialized"),
            Self::Running => write!(f, "Running"),
            Self::Stopped => write!(f, "Stopped"),
            Self::Error => write!(f, "Error"),
        }
    }
}