System Fan and Temperature Monitoring

Is your feature request related to a problem?

Yes, the current Unraid GraphQL API completely lacks system fan monitoring capabilities, which severely limits thermal management automation, system health monitoring, and integration with monitoring platforms. Currently, the API only provides disk temperature monitoring via SMARTCTL, but no system-wide thermal sensors or fan monitoring data.

This creates several critical problems:

• No visibility into cooling system performance - Cannot monitor fan speeds, RPM, or operational status
• Missing thermal management automation - No ability to detect overheating conditions or cooling failures
• Limited system health monitoring - Cannot track fan degradation, failure, or performance issues
• Inadequate integration capabilities - Monitoring platforms cannot access comprehensive thermal data
• No predictive maintenance - Cannot detect early warning signs of cooling system problems
• Incomplete system monitoring - While CPU, memory, and disk metrics are available, thermal management data is absent
• Safety concerns - No automated detection of cooling failures that could lead to hardware damage

Describe the solution you'd like

Add comprehensive system fan monitoring and thermal management capabilities to the Unraid GraphQL API with the following features:

Core Fan Monitoring

• System fan enumeration with identification, naming, and hardware details
• Real-time fan speed monitoring (RPM readings and percentage values)
• Fan status detection (operational, warning, critical, stopped)
• Fan control capabilities (PWM control, target speed setting)
• Multiple fan type support (CPU fans, case fans, PSU fans, custom controllers)

Thermal Sensor Integration

• Temperature sensor monitoring for CPU, motherboard, and system zones
• Thermal threshold management with configurable warning and critical levels
• Temperature correlation with fan performance and system load
• Thermal zone mapping to associate sensors with cooling zones

Advanced Monitoring Features

• Fan performance tracking with efficiency and degradation monitoring
• Historical data collection for trend analysis and capacity planning
• Configurable polling intervals for real-time vs. efficient monitoring
• Fan failure detection with automatic alerting capabilities

Proposed GraphQL Schema Extension

type Query {
  thermal: ThermalInfo!
  systemFans: [SystemFan!]!
  systemFan(id: ID!): SystemFan
  temperatureSensors: [TemperatureSensor!]!
  temperatureSensor(id: ID!): TemperatureSensor
}

type Mutation {
  setFanSpeed(input: SetFanSpeedInput!): SystemFan!
  setFanCurve(input: SetFanCurveInput!): SystemFan!
  resetFanSettings(fanId: ID!): SystemFan!
}

type Subscription {
  thermalUpdates: ThermalInfo!
  fanStatusChanged: SystemFan!
  temperatureAlert: TemperatureAlert!
}

type ThermalInfo {
  id: ID!
  fans: [SystemFan!]!
  sensors: [TemperatureSensor!]!
  overallStatus: ThermalStatus!
  lastUpdated: DateTime!
}

type SystemFan {
  id: ID!
  name: String!
  label: String
  type: FanType!
  status: FanStatus!
  
  # Current readings
  currentRpm: Int
  targetRpm: Int
  currentPercentage: Float # 0-100%
  targetPercentage: Float # 0-100%
  
  # Capabilities
  controllable: Boolean!
  minRpm: Int
  maxRpm: Int
  pwmChannel: Int
  
  # Hardware details
  connector: String
  sensorChip: String
  hwmonPath: String
  
  # Performance metrics
  efficiency: Float # RPM per percentage
  powerConsumption: Float # Watts (if available)
  
  # Status information
  lastSeen: DateTime!
  errorCount: Int!
  warningThreshold: Int
  criticalThreshold: Int
  
  # Associated temperature sensors
  associatedSensors: [TemperatureSensor!]!
}

type TemperatureSensor {
  id: ID!
  name: String!
  label: String
  type: SensorType!
  location: String
  
  # Current readings
  currentTemperature: Float!
  unit: TemperatureUnit!
  
  # Thresholds
  warningThreshold: Float
  criticalThreshold: Float
  maxThreshold: Float
  
  # Hardware details
  sensorChip: String
  hwmonPath: String
  
  # Status
  status: SensorStatus!
  lastUpdated: DateTime!
  
  # Associated cooling
  associatedFans: [SystemFan!]!
}

type TemperatureAlert {
  id: ID!
  sensor: TemperatureSensor!
  alertType: AlertType!
  temperature: Float!
  threshold: Float!
  timestamp: DateTime!
  message: String!
}

enum FanType {
  CPU
  CASE_INTAKE
  CASE_EXHAUST
  PSU
  GPU
  RADIATOR
  CHIPSET
  CUSTOM
  UNKNOWN
}

enum FanStatus {
  NORMAL
  WARNING      # Low performance or approaching thresholds
  CRITICAL     # Very low RPM or failure conditions
  STOPPED      # Fan not spinning
  DISCONNECTED # Fan not detected
  UNKNOWN
}

enum SensorType {
  CPU
  MOTHERBOARD
  AMBIENT
  GPU
  DISK
  PSU
  CHIPSET
  CUSTOM
  UNKNOWN
}

enum SensorStatus {
  NORMAL
  WARNING
  CRITICAL
  DISCONNECTED
  UNKNOWN
}

enum ThermalStatus {
  OPTIMAL
  WARNING
  CRITICAL
  EMERGENCY
}

enum AlertType {
  WARNING
  CRITICAL
  EMERGENCY
  RECOVERY
}

enum TemperatureUnit {
  CELSIUS
  FAHRENHEIT
}

input SetFanSpeedInput {
  fanId: ID!
  targetRpm: Int
  targetPercentage: Float
  mode: FanControlMode!
}

input SetFanCurveInput {
  fanId: ID!
  curvePoints: [FanCurvePoint!]!
  hysteresis: Float
}

input FanCurvePoint {
  temperature: Float!
  fanSpeed: Float! # Percentage 0-100
}

enum FanControlMode {
  MANUAL_RPM
  MANUAL_PERCENTAGE
  AUTOMATIC
  CURVE_BASED
}

Additional context

Implementation Considerations

The Unraid codebase already includes foundational components that can be leveraged:

• systeminformation library for system monitoring (currently used for CPU, memory, disk metrics)
• Established GraphQL infrastructure with proven patterns for system monitoring
• Existing temperature handling with basic Temperature enum and disk temperature monitoring
• Hardware sensor access through standard Linux /sys/class/hwmon/ interfaces
• Authentication and authorization mechanisms already in place

Suggested Implementation Approach

1. Leverage systeminformation sensors() function for comprehensive thermal data collection
2. Create ThermalService and FanService for data collection, caching, and real-time monitoring
3. Implement hwmon integration for direct hardware sensor access via /sys/class/hwmon/
4. Add GraphQL resolvers and subscriptions for real-time thermal monitoring
5. Include fan control capabilities through PWM interfaces for advanced thermal management
6. Implement efficient caching to minimize system impact during frequent queries
7. Add historical data collection with configurable retention policies

Use Cases and Benefits

• Enterprise monitoring integration with tools like Grafana, Prometheus, Zabbix, and PRTG
• Automated thermal management with dynamic fan curve adjustments based on system load
• Predictive maintenance through fan performance degradation tracking
• System safety monitoring with automatic alerts for cooling failures or overheating
• Performance optimization through thermal bottleneck identification and resolution
• Data center management for rack-level thermal monitoring and optimization
• Custom automation scripts for advanced thermal management scenarios
• Integration with building management systems for comprehensive facility monitoring

Technical Benefits

• Comprehensive thermal visibility across all system components
• Real-time monitoring capabilities through GraphQL subscriptions
• Standardized data formats for easier integration across platforms
• Scalable architecture supporting multiple fan controllers and sensor types
• Hardware abstraction providing consistent interface across different sensor chips
• Performance optimization through efficient sensor polling and caching strategies

Hardware Compatibility

• Standard hwmon sensors (lm-sensors compatible chips)
• CPU thermal sensors (Intel, AMD built-in sensors)
• Motherboard sensors (various sensor chips: IT87xx, NCT67xx, etc.)
• Fan controllers (PWM and voltage-controlled fans)
• Custom fan controllers (USB, I2C, and other interfaces)
• IPMI-based systems for enterprise server thermal monitoring

Community Impact

This feature would significantly enhance Unraid's appeal for:

• Enterprise and prosumer users requiring comprehensive thermal monitoring
• Data center operators managing multiple Unraid servers
• System builders and enthusiasts optimizing cooling performance
• Automation platform users building sophisticated thermal management systems
• Monitoring solution developers creating comprehensive system health dashboards
• System administrators requiring proactive thermal management and alerting

Current API Gap Analysis

Based on comprehensive codebase analysis, the current Unraid GraphQL API provides:

• ✅ Disk temperature monitoring via SMARTCTL
• ✅ Basic temperature units (Celsius/Fahrenheit)
• ✅ System information (CPU, memory, OS details)
• ✅ UPS monitoring (recently added)
• ❌ System fan monitoring (completely missing)
• ❌ Thermal sensor data (not implemented)
• ❌ Fan control capabilities (absent)
• ❌ Thermal management (not available)

Performance Considerations

• Minimal system overhead through efficient sensor polling strategies
• Configurable update intervals balancing real-time needs with resource usage
• Intelligent caching to reduce repeated hardware queries
• Subscription-based updates for efficient real-time monitoring
• Hardware-specific optimizations for different sensor chip types

Environment (if relevant)

Unraid OS Version: 7.1.4

Pre-submission Checklist

• I have searched existing issues to ensure this feature hasn't already been requested
• This is not an Unraid Connect related feature (if it is, please submit via the support form instead)
• I have provided clear examples or use cases for the feature

Start by reading the existing GraphQL system-monitoring patterns and the systeminformation sensors() entry point, then inspect the /sys/class/hwmon/ interfaces described in the issue. Done would require an agreed scope and tests covering the requested thermal, fan, control, alerting, and subscription capabilities across supported hardware.