[Feature]: FAN speeds reading

[shorshiii]

📂 Feature Category

System Monitoring - CPU, RAM, temperatures, uptime

🎯 Use Case / Problem Solved

I would like to be able to get notified when/if my FANs stop spinning.

💡 Proposed Solution

The "Airflow" section in the unraid dashboard does provide readings for all 4 of my FAN headers, so i believe it should be a readable stat.

🔄 Alternatives Considered

Currently using HDD temp readings

🖥️ Unraid Context

📊 Priority Level

Medium - Would improve my experience

🤝 Contribution

• I'm willing to test development versions
• I can help with documentation
• I have programming skills and could contribute code
• I can provide detailed requirements and feedback

📝 Additional Context

✅ Checklist

• I have searched existing open and closed issues to ensure this isn't a duplicate
• I have clearly described the problem this feature would solve
• I understand that feature requests might take time or not be implemented if they are not within project scope

[coderabbitai]

Coding Plan

Summary

• Blocker identified: The unraid-api library (v1.7.1) does not currently expose fan speed data, though Unraid's dashboard confirms the data exists on the server
• Prerequisite action: Request or contribute fan speed support to the unraid-api library before proceeding
• Implementation pattern: Follow the established DiskTemperatureSensor per-resource pattern to create individual FanSpeedSensor entities for each detected fan
• Graceful degradation: Design the implementation to handle missing fan data (older servers/APIs) without errors

Design Choices

Design Choice 1: API Library Support for Fan Speed Data

Options Considered:

1. Wait for the unraid-api library maintainers to add fan speed support, then implement sensors in this integration
2. Contribute fan speed support to the unraid-api library as a prerequisite, then implement sensors here
3. Investigate alternative data sources or direct API calls (would bypass the established architecture)

Chosen Option: 2

Rationale: The cleanest path is to first ensure unraid-api exposes fan data (via contribution or feature request), then implement the integration sensors following existing patterns. This maintains architectural consistency and proper separation of concerns.

Design Choice 2: Fan Data Structure

Options Considered:

1. Single aggregate sensor showing average/min fan speed
2. Per-fan sensors similar to per-disk temperature sensors
3. Both aggregate and per-fan sensors

Chosen Option: 2

Rationale: Per-fan sensors following the DiskTemperatureSensor pattern, as users specifically want to know when individual fans fail. This allows granular monitoring and alerting.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: API Library Prerequisite

This phase addresses the blocking dependency. The unraid-api library must expose fan speed data before integration work can proceed.

Task 1: Verify API Support Status

Confirm whether fan speed support exists or is planned in the unraid-api library.

• Check the unraid-api repository (PyPI or GitHub) for existing issues or PRs related to fan/airflow data
• Review the Unraid Connect API documentation (if available) to understand how fan data is exposed at the server level
• If no existing support, open a feature request or contribute the necessary API models

Task 2: Define Expected Data Model

Document the expected fan speed data structure for integration planning.

• Based on Unraid's "Airflow" dashboard section, anticipate a structure like FanSensor with fields: id, name, rpm (or speed)
• Expect this data to be included in SystemMetrics or a new Airflow model from the API
• The integration will need to handle cases where fan data is unavailable (older API versions, servers without fan sensors)

🤖 Prompt for AI agents

This phase is a research and prerequisite phase — no code changes are required
in the integration itself.

- Check the `unraid-api` repository (PyPI or GitHub) for any existing issues,
PRs, or changelog entries related to fan speed, airflow, or RPM data
- Review the Unraid Connect API documentation (if available) to understand how
fan data is exposed at the server level
- If no existing support is found, open a feature request or contribute the
necessary API models to the `unraid-api` library
- Document the expected fan speed data structure based on Unraid's "Airflow"
dashboard section, anticipating a model like `FanSensor` with fields such as
`id`, `name`, and `rpm` (or `speed`)
- Determine whether this data will be included in `SystemMetrics` or a new
`Airflow` model from the API
- Note that the integration will need to handle cases where fan data is
unavailable (older API versions, servers without fan sensors)

Phase 2: Sensor Implementation

Once the unraid-api library supports fan speed data, implement the sensors following established patterns.

Task 1: Add Fan Speed Sensor Entity Class

Create sensor entities for fan speed monitoring following the per-resource pattern.

• Add FanSpeedSensor class in custom_components/unraid/sensor.py following the DiskTemperatureSensor pattern
• Set _attr_translation_key = "fan_speed" with _attr_native_unit_of_measurement = "RPM"
• Use _attr_state_class = SensorStateClass.MEASUREMENT for statistics support
• Store _fan_id and implement _get_fan() helper method to locate the fan in coordinator data
• Unique ID format: {server_uuid}_fan_{fan_id}_speed
• Consider _attr_entity_registry_enabled_default = False if there may be many fans (user enables as needed)

Task 2: Update Coordinator Data Handling

Ensure the coordinator properly fetches and structures fan speed data.

• If the API adds fans to SystemMetrics, no coordinator changes needed—data flows automatically
• If a new API method is required, add the call to UnraidSystemCoordinator._async_update_data() in custom_components/unraid/coordinator.py
• Handle missing fan data gracefully (return empty list, log at debug level) following the optional query pattern used for UPS/containers

Task 3: Register Fan Sensors in Setup

Wire up fan speed sensors to be created during integration setup.

• Update async_setup_entry in custom_components/unraid/sensor.py to instantiate FanSpeedSensor entities
• Iterate over available fans from system_coordinator.data.metrics (or wherever the API exposes them)
• Follow the pattern used for per-disk sensors: create one entity per detected fan
• Add to the entities list alongside other system sensors

Task 4: Add Translations and Icons

Provide user-facing labels and iconography for fan sensors.

• Add "fan_speed" entry to custom_components/unraid/strings.json under entity.sensor with appropriate name placeholder pattern (e.g., "{name} Fan Speed")
• Add corresponding icon mapping in custom_components/unraid/icons.json using mdi:fan or similar
• Translations will auto-generate to translations/en.json

🤖 Prompt for AI agents

Implement fan speed sensor entities and wire them into the integration,
following existing per-resource sensor patterns established by
`DiskTemperatureSensor`.

**`custom_components/unraid/sensor.py`**
- Add a `FanSpeedSensor` class modelled on the `DiskTemperatureSensor` pattern
  - Set `_attr_translation_key = "fan_speed"`
  - Set `_attr_native_unit_of_measurement = "RPM"`
  - Set `_attr_state_class = SensorStateClass.MEASUREMENT`
  - Store `_fan_id` as an instance attribute
  - Implement a `_get_fan()` helper method to locate the fan in coordinator data
  - Use unique ID format: `{server_uuid}_fan_{fan_id}_speed`
- Consider setting `_attr_entity_registry_enabled_default = False` if many fans
are expected
- Update `async_setup_entry` to instantiate `FanSpeedSensor` entities
- Iterate over available fans from `system_coordinator.data.metrics` (or
wherever the API exposes them)
  - Create one entity per detected fan, following the per-disk sensor pattern
  - Add fan entities to the entities list alongside other system sensors

**`custom_components/unraid/coordinator.py`**
- If the API adds fans to `SystemMetrics`, no coordinator changes are needed —
data flows automatically
- If a new API method is required, add the call inside
`UnraidSystemCoordinator._async_update_data()`
- Handle missing fan data gracefully: return an empty list and log at debug
level, following the optional query pattern used for UPS/containers

**`custom_components/unraid/strings.json`**
- Add a `"fan_speed"` entry under `entity.sensor` with an appropriate `name`
placeholder pattern (e.g., `"{name} Fan Speed"`)

**`custom_components/unraid/icons.json`**
- Add a corresponding icon mapping for `fan_speed` using `mdi:fan` or similar
- Translations will auto-generate to `translations/en.json`

Phase 3: Testing and Validation

Ensure the implementation works correctly and handles edge cases.

Task 1: Add Test Fixtures and Unit Tests

Create test coverage for fan speed sensors.

• Update tests/conftest.py to add fan data to the make_system_data factory
• Add test cases in tests/ following existing sensor test patterns
• Test scenarios: fans present with valid RPM, fans missing, fan reporting 0 RPM (stopped)

Task 2: Update Test Mocks

Ensure mock data includes fan speed information.

• Update any API response mocks to include fan speed data structure
• Verify existing tests continue to pass with the new optional data field

🤖 Prompt for AI agents

Add test coverage for the new fan speed sensors, ensuring all relevant scenarios
and edge cases are validated.

**`tests/conftest.py`**
- Update the `make_system_data` factory to include fan speed data as an optional
field

**`tests/`** (following existing sensor test patterns)
- Add test cases covering the following scenarios:
  - Fans present with valid RPM values
- Fan data missing entirely (older API versions or servers without fan sensors)
  - A fan reporting 0 RPM (stopped fan)
- Update any API response mocks to include the fan speed data structure
- Verify that all existing tests continue to pass with the new optional data
field

Research

The integration follows a flat structure in custom_components/unraid/ with three data coordinators (UnraidSystemCoordinator, UnraidStorageCoordinator, UnraidInfraCoordinator) polling the unraid-api library at different intervals. All sensor entities extend UnraidSensorEntity and follow a consistent pattern exemplified by TemperatureSensor for single-value metrics and DiskTemperatureSensor for per-resource sensors. System metrics (CPU, RAM, temperature) flow through UnraidSystemCoordinator with a 30-second poll interval, stored in UnraidSystemData.metrics.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase is a research and prerequisite phase — no code changes are required
in the integration itself.

- Check the `unraid-api` repository (PyPI or GitHub) for any existing issues,
PRs, or changelog entries related to fan speed, airflow, or RPM data
- Review the Unraid Connect API documentation (if available) to understand how
fan data is exposed at the server level
- If no existing support is found, open a feature request or contribute the
necessary API models to the `unraid-api` library
- Document the expected fan speed data structure based on Unraid's "Airflow"
dashboard section, anticipating a model like `FanSensor` with fields such as
`id`, `name`, and `rpm` (or `speed`)
- Determine whether this data will be included in `SystemMetrics` or a new
`Airflow` model from the API
- Note that the integration will need to handle cases where fan data is
unavailable (older API versions, servers without fan sensors)
===============================================================================

Task: 2

Implement fan speed sensor entities and wire them into the integration,
following existing per-resource sensor patterns established by
`DiskTemperatureSensor`.

**`custom_components/unraid/sensor.py`**
- Add a `FanSpeedSensor` class modelled on the `DiskTemperatureSensor` pattern
  - Set `_attr_translation_key = "fan_speed"`
  - Set `_attr_native_unit_of_measurement = "RPM"`
  - Set `_attr_state_class = SensorStateClass.MEASUREMENT`
  - Store `_fan_id` as an instance attribute
  - Implement a `_get_fan()` helper method to locate the fan in coordinator data
  - Use unique ID format: `{server_uuid}_fan_{fan_id}_speed`
- Consider setting `_attr_entity_registry_enabled_default = False` if many fans
are expected
- Update `async_setup_entry` to instantiate `FanSpeedSensor` entities
- Iterate over available fans from `system_coordinator.data.metrics` (or
wherever the API exposes them)
  - Create one entity per detected fan, following the per-disk sensor pattern
  - Add fan entities to the entities list alongside other system sensors

**`custom_components/unraid/coordinator.py`**
- If the API adds fans to `SystemMetrics`, no coordinator changes are needed —
data flows automatically
- If a new API method is required, add the call inside
`UnraidSystemCoordinator._async_update_data()`
- Handle missing fan data gracefully: return an empty list and log at debug
level, following the optional query pattern used for UPS/containers

**`custom_components/unraid/strings.json`**
- Add a `"fan_speed"` entry under `entity.sensor` with an appropriate `name`
placeholder pattern (e.g., `"{name} Fan Speed"`)

**`custom_components/unraid/icons.json`**
- Add a corresponding icon mapping for `fan_speed` using `mdi:fan` or similar
- Translations will auto-generate to `translations/en.json`
===============================================================================

Task: 3

Add test coverage for the new fan speed sensors, ensuring all relevant scenarios
and edge cases are validated.

**`tests/conftest.py`**
- Update the `make_system_data` factory to include fan speed data as an optional
field

**`tests/`** (following existing sensor test patterns)
- Add test cases covering the following scenarios:
  - Fans present with valid RPM values
- Fan data missing entirely (older API versions or servers without fan sensors)
  - A fan reporting 0 RPM (stopped fan)
- Update any API response mocks to include the fan speed data structure
- Verify that all existing tests continue to pass with the new optional data
field

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

I've updated the plan above based on your feedback. Ready to proceed when you are!

[ruaan-deysel]

The fan control system has been implemented in the Unraid API. PR: unraid/api#1954

This adds GraphQL queries, mutations, and subscriptions for real-time fan monitoring and control (hwmon + IPMI), which will enable fan control support in this integration.

[coderabbitai]

I've updated the plan above based on your feedback. Ready to proceed when you are!