feat(fan): implement MMFanTelemetryProvider for multi-fan RPM and utilization (Issue #4)

MacMonitor.xcodeproj/project.pbxproj

@@ -14,6 +14,7 @@
 		3C0AC14F803C813287D8A663 /* IOKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 007F48A5A599AB4E8D216D16 /* IOKit.framework */; };
 		4419FE7554489B23976E2970 /* MMCPULoadProvider.m in Sources */ = {isa = PBXBuildFile; fileRef = D68FC8100D08DB6202F46339 /* MMCPULoadProvider.m */; };
 		6201FD599FED061F6C736E8B /* MMMemoryTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 099DCF7EF03A58ADA40A94A1 /* MMMemoryTests.swift */; };
+		655366D7066478A02EDA91BB /* MMFanTelemetryProvider.m in Sources */ = {isa = PBXBuildFile; fileRef = C9ED8F75E082D4F8AC2FF2F5 /* MMFanTelemetryProvider.m */; };
 		87818E46CEA5145A8215D0E3 /* MMCPUThermalTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0F2BD3777A674DC4EB442890 /* MMCPUThermalTests.swift */; };
 		87A9E18362486D0D385BBC4A /* MMCPUThermalProvider.m in Sources */ = {isa = PBXBuildFile; fileRef = 62C377EFD025D6A6B5563E77 /* MMCPUThermalProvider.m */; };
 		88387CDAE2AC1CC74EF89B57 /* MacMonitorApp.swift in Sources */ = {isa = PBXBuildFile; fileRef = ADEA6BD38BA8D887B1DB64A9 /* MacMonitorApp.swift */; };
@@ -22,6 +23,7 @@
 		A9FCAEC0BF27A419DB148C4A /* ContentView.swift in Sources */ = {isa = PBXBuildFile; fileRef = E142AE61F9B87757997870DD /* ContentView.swift */; };
 		B9C2D6574E808B517BA34C83 /* MMMemoryTelemetryProvider.m in Sources */ = {isa = PBXBuildFile; fileRef = 991AEEAF262F3C6BE930BC77 /* MMMemoryTelemetryProvider.m */; };
 		CD91FC663B19DA1FEA3D49D7 /* MMAppleSMCClient.m in Sources */ = {isa = PBXBuildFile; fileRef = 5555436CD3CB8A73F5D6504F /* MMAppleSMCClient.m */; };
+		E6F2F695B8D3E7045967C082 /* MMFanTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 336CEE35A745F3C7E9F70F43 /* MMFanTests.swift */; };
 		EAFAF5A10502D4ACC64F4720 /* MMTelemetryCoordinator.m in Sources */ = {isa = PBXBuildFile; fileRef = F9F9AD1268F906761032AF4D /* MMTelemetryCoordinator.m */; };
 		EC9FA3E4A119277B89E73F8D /* MMSMCTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 940D608A1AF80F75584E744E /* MMSMCTests.swift */; };
 		F2F7A141F2452EC1B4FB45D8 /* MMStorageTelemetryProvider.m in Sources */ = {isa = PBXBuildFile; fileRef = 6DCBCEA450103E2404761B78 /* MMStorageTelemetryProvider.m */; };
@@ -46,7 +48,9 @@
 		2345555FF9780B02A90CC7A9 /* CoreFoundation.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = CoreFoundation.framework; path = System/Library/Frameworks/CoreFoundation.framework; sourceTree = SDKROOT; };
 		2EC3EDFCD5C50CB352FCED87 /* MacMonitorTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MacMonitorTests.swift; sourceTree = "<group>"; };
 		32340166F6100A08105308D3 /* MMTelemetryCoordinator.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMTelemetryCoordinator.h; sourceTree = "<group>"; };
+		336CEE35A745F3C7E9F70F43 /* MMFanTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MMFanTests.swift; sourceTree = "<group>"; };
 		375AA781A2AA0A20B119C7B7 /* MMSMCParser.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = MMSMCParser.m; sourceTree = "<group>"; };
+		3CFC5B905E428A6B854E0AB4 /* MMFanTelemetryProvider.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMFanTelemetryProvider.h; sourceTree = "<group>"; };
 		46DE3AE12DAE26C4FE58034C /* MMStorageTelemetryProvider.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMStorageTelemetryProvider.h; sourceTree = "<group>"; };
 		4CE92B1A8D7FDBB6499448E1 /* MMCPULoadTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MMCPULoadTests.swift; sourceTree = "<group>"; };
 		5555436CD3CB8A73F5D6504F /* MMAppleSMCClient.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = MMAppleSMCClient.m; sourceTree = "<group>"; };
@@ -62,6 +66,7 @@
 		940D608A1AF80F75584E744E /* MMSMCTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MMSMCTests.swift; sourceTree = "<group>"; };
 		991AEEAF262F3C6BE930BC77 /* MMMemoryTelemetryProvider.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = MMMemoryTelemetryProvider.m; sourceTree = "<group>"; };
 		ADEA6BD38BA8D887B1DB64A9 /* MacMonitorApp.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MacMonitorApp.swift; sourceTree = "<group>"; };
+		C9ED8F75E082D4F8AC2FF2F5 /* MMFanTelemetryProvider.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = MMFanTelemetryProvider.m; sourceTree = "<group>"; };
 		D68FC8100D08DB6202F46339 /* MMCPULoadProvider.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = MMCPULoadProvider.m; sourceTree = "<group>"; };
 		D73CCC7B5E6BF1825EA68E2B /* MMCPUThermalProvider.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMCPUThermalProvider.h; sourceTree = "<group>"; };
 		E142AE61F9B87757997870DD /* ContentView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ContentView.swift; sourceTree = "<group>"; };
@@ -146,6 +151,7 @@
 			isa = PBXGroup;
 			children = (
 				78383CED205BCA772701AE48 /* CPU */,
+				AD2995435E44FA3E1790A4F3 /* Fan */,
 				EE2F5EFC9DC33CEDA79A131F /* Memory */,
 				B6EB3F6545276C40212C2992 /* Storage */,
 				DBDC37231C01F0A2D4A7FC73 /* Thermal */,
@@ -161,6 +167,15 @@
 			path = Hardware;
 			sourceTree = "<group>";
 		};
+		AD2995435E44FA3E1790A4F3 /* Fan */ = {
+			isa = PBXGroup;
+			children = (
+				3CFC5B905E428A6B854E0AB4 /* MMFanTelemetryProvider.h */,
+				C9ED8F75E082D4F8AC2FF2F5 /* MMFanTelemetryProvider.m */,
+			);
+			path = Fan;
+			sourceTree = "<group>";
+		};
 		B6EB3F6545276C40212C2992 /* Storage */ = {
 			isa = PBXGroup;
 			children = (
@@ -185,6 +200,7 @@
 				2EC3EDFCD5C50CB352FCED87 /* MacMonitorTests.swift */,
 				4CE92B1A8D7FDBB6499448E1 /* MMCPULoadTests.swift */,
 				0F2BD3777A674DC4EB442890 /* MMCPUThermalTests.swift */,
+				336CEE35A745F3C7E9F70F43 /* MMFanTests.swift */,
 				099DCF7EF03A58ADA40A94A1 /* MMMemoryTests.swift */,
 				940D608A1AF80F75584E744E /* MMSMCTests.swift */,
 				78325870C7CD8312AECA2236 /* MMStorageTests.swift */,
@@ -308,6 +324,7 @@
 			files = (
 				160334CC765E091A7CBE21AA /* MMCPULoadTests.swift in Sources */,
 				87818E46CEA5145A8215D0E3 /* MMCPUThermalTests.swift in Sources */,
+				E6F2F695B8D3E7045967C082 /* MMFanTests.swift in Sources */,
 				6201FD599FED061F6C736E8B /* MMMemoryTests.swift in Sources */,
 				EC9FA3E4A119277B89E73F8D /* MMSMCTests.swift in Sources */,
 				1B15F48F6B19E9EA4556ECD5 /* MMStorageTests.swift in Sources */,
@@ -323,6 +340,7 @@
 				CD91FC663B19DA1FEA3D49D7 /* MMAppleSMCClient.m in Sources */,
 				4419FE7554489B23976E2970 /* MMCPULoadProvider.m in Sources */,
 				87A9E18362486D0D385BBC4A /* MMCPUThermalProvider.m in Sources */,
+				655366D7066478A02EDA91BB /* MMFanTelemetryProvider.m in Sources */,
 				B9C2D6574E808B517BA34C83 /* MMMemoryTelemetryProvider.m in Sources */,
 				1B3F1C8ABF0ADFAA290FF6F6 /* MMSMCParser.m in Sources */,
 				F2F7A141F2452EC1B4FB45D8 /* MMStorageTelemetryProvider.m in Sources */,

Sources/Bridging/MacMonitor-Bridging-Header.h

@@ -16,5 +16,6 @@
 #import "MMMemoryTelemetryProvider.h"
 #import "MMStorageTelemetryProvider.h"
 #import "MMCPUThermalProvider.h"
+#import "MMFanTelemetryProvider.h"
 
 #endif /* MacMonitor_Bridging_Header_h */

Sources/Telemetry/Fan/MMFanTelemetryProvider.h

@@ -0,0 +1,31 @@
+#ifndef MMFanTelemetryProvider_h
+#define MMFanTelemetryProvider_h
+
+#import <Foundation/Foundation.h>
+#import "MMTelemetryProvider.h"
+#import "MMAppleSMCClient.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * MMFanTelemetryProvider
+ * Samples multi-fan telemetry from AppleSMC: current RPM, min RPM, max RPM, target RPM,
+ * and fan utilization percentages.
+ */
+@interface MMFanTelemetryProvider : NSObject <MMTelemetryProvider>
+
+@property (nonatomic, strong, readonly) MMAppleSMCClient *smcClient;
+@property (nonatomic, readonly) NSInteger fanCount;
+
+- (instancetype)initWithSMCClient:(MMAppleSMCClient *)client;
+
+/**
+ * Static calculator method for deterministic unit testing.
+ */
++ (NSDictionary<NSString *, id> *)calculateFanMetricsFromFanList:(NSArray<NSDictionary<NSString *, NSNumber *> *> *)fanList;
+
+@end
+
+NS_ASSUME_NONNULL_END
+
+#endif /* MMFanTelemetryProvider_h */

Sources/Telemetry/Fan/MMFanTelemetryProvider.m

@@ -0,0 +1,147 @@
+#import "MMFanTelemetryProvider.h"
+
+@interface MMFanTelemetryProvider () {
+    MMAppleSMCClient *_smcClient;
+    NSInteger _probedFanCount;
+}
+@end
+
+@implementation MMFanTelemetryProvider
+
+- (instancetype)init {
+    return [self initWithSMCClient:[MMAppleSMCClient sharedClient]];
+}
+
+- (instancetype)initWithSMCClient:(MMAppleSMCClient *)client {
+    self = [super init];
+    if (self) {
+        _smcClient = client;
+        _probedFanCount = -1;
+        [self probeFans];
+    }
+    return self;
+}
+
+- (void)probeFans {
+    if (!_smcClient.isAvailable) return;
+    
+    NSNumber *num = [_smcClient readNumericValueForKey:@"FNum" error:nil];
+    if (num) {
+        _probedFanCount = [num integerValue];
+    } else {
+        // Fallback probe F0Ac
+        NSNumber *f0 = [_smcClient readNumericValueForKey:@"F0Ac" error:nil];
+        if (f0 && [f0 doubleValue] >= 0.0) {
+            _probedFanCount = 1;
+            NSNumber *f1 = [_smcClient readNumericValueForKey:@"F1Ac" error:nil];
+            if (f1 && [f1 doubleValue] >= 0.0) {
+                _probedFanCount = 2;
+            }
+        } else {
+            _probedFanCount = 0;
+        }
+    }
+}
+
+- (MMTelemetryDomain)domain {
+    return MMTelemetryDomainFan;
+}
+
+- (NSString *)providerIdentifier {
+    return @"com.i3omb.macmonitor.telemetry.fan";
+}
+
+- (BOOL)isAvailable {
+    return _smcClient.isAvailable;
+}
+
+- (MMAppleSMCClient *)smcClient {
+    return _smcClient;
+}
+
+- (NSInteger)fanCount {
+    return (_probedFanCount >= 0) ? _probedFanCount : 0;
+}
+
++ (NSDictionary<NSString *, id> *)calculateFanMetricsFromFanList:(NSArray<NSDictionary<NSString *, NSNumber *> *> *)fanList {
+    if (!fanList || fanList.count == 0) {
+        return @{
+            @"fanCount": @(0),
+            @"fans": @[],
+            @"averageRPM": @(0.0),
+            @"peakRPM": @(0.0)
+        };
+    }
+    
+    NSMutableArray<NSDictionary<NSString *, id> *> *resultList = [NSMutableArray arrayWithCapacity:fanList.count];
+    double sumRPM = 0.0;
+    double peakRPM = 0.0;
+    
+    for (NSUInteger i = 0; i < fanList.count; i++) {
+        NSDictionary<NSString *, NSNumber *> *raw = fanList[i];
+        double current = [raw[@"currentRPM"] doubleValue];
+        double min = [raw[@"minRPM"] doubleValue];
+        double max = [raw[@"maxRPM"] doubleValue];
+        double target = [raw[@"targetRPM"] doubleValue];
+        
+        double util = 0.0;
+        if (max > min && current >= min) {
+            util = ((current - min) / (max - min)) * 100.0;
+            if (util < 0.0) util = 0.0;
+            if (util > 100.0) util = 100.0;
+        }
+        
+        if (current > peakRPM) peakRPM = current;
+        sumRPM += current;
+        
+        [resultList addObject:@{
+            @"fanIndex": @(i),
+            @"currentRPM": @(current),
+            @"minRPM": @(min),
+            @"maxRPM": @(max),
+            @"targetRPM": @(target),
+            @"utilizationPercent": @(util)
+        }];
+    }
+    
+    double avgRPM = fanList.count > 0 ? (sumRPM / fanList.count) : 0.0;
+    
+    return @{
+        @"fanCount": @(fanList.count),
+        @"fans": [resultList copy],
+        @"averageRPM": @(avgRPM),
+        @"peakRPM": @(peakRPM)
+    };
+}
+
+- (nullable NSDictionary<NSString *, id> *)sampleTelemetryWithError:(NSError **)error {
+    if (_probedFanCount < 0 && _smcClient.isAvailable) {
+        [self probeFans];
+    }
+    
+    NSInteger count = [self fanCount];
+    NSMutableArray<NSDictionary<NSString *, NSNumber *> *> *rawList = [NSMutableArray arrayWithCapacity:count];
+    
+    for (NSInteger i = 0; i < count; i++) {
+        NSString *acKey = [NSString stringWithFormat:@"F%ldAc", (long)i];
+        NSString *mnKey = [NSString stringWithFormat:@"F%ldMn", (long)i];
+        NSString *mxKey = [NSString stringWithFormat:@"F%ldMx", (long)i];
+        NSString *tgKey = [NSString stringWithFormat:@"F%ldTg", (long)i];
+        
+        NSNumber *ac = [_smcClient readNumericValueForKey:acKey error:nil] ?: @(0.0);
+        NSNumber *mn = [_smcClient readNumericValueForKey:mnKey error:nil] ?: @(0.0);
+        NSNumber *mx = [_smcClient readNumericValueForKey:mxKey error:nil] ?: @(6000.0);
+        NSNumber *tg = [_smcClient readNumericValueForKey:tgKey error:nil] ?: ac;
+        
+        [rawList addObject:@{
+            @"currentRPM": ac,
+            @"minRPM": mn,
+            @"maxRPM": mx,
+            @"targetRPM": tg
+        }];
+    }
+    
+    return [MMFanTelemetryProvider calculateFanMetricsFromFanList:rawList];
+}
+
+@end

Tests/MMFanTests.swift

@@ -0,0 +1,48 @@
+import XCTest
+@testable import MacMonitor
+
+final class MMFanTests: XCTestCase {
+    
+    func testFanUtilizationCalculation() {
+        let fanList: [[String: NSNumber]] = [
+            [
+                "currentRPM": NSNumber(value: 2000.0),
+                "minRPM": NSNumber(value: 1200.0),
+                "maxRPM": NSNumber(value: 5000.0),
+                "targetRPM": NSNumber(value: 2000.0)
+            ],
+            [
+                "currentRPM": NSNumber(value: 2500.0),
+                "minRPM": NSNumber(value: 1200.0),
+                "maxRPM": NSNumber(value: 5000.0),
+                "targetRPM": NSNumber(value: 2500.0)
+            ]
+        ]
+        
+        let metrics = MMFanTelemetryProvider.calculateFanMetrics(fromFanList: fanList)
+        
+        let count = metrics["fanCount"] as? Int ?? 0
+        let avgRPM = metrics["averageRPM"] as? Double ?? 0
+        let peakRPM = metrics["peakRPM"] as? Double ?? 0
+        let fans = metrics["fans"] as? [[String: Any]] ?? []
+        
+        XCTAssertEqual(count, 2)
+        XCTAssertEqual(avgRPM, 2250.0, accuracy: 0.1)
+        XCTAssertEqual(peakRPM, 2500.0, accuracy: 0.1)
+        XCTAssertEqual(fans.count, 2)
+        
+        let fan0 = fans[0]
+        let util0 = fan0["utilizationPercent"] as? Double ?? 0
+        // (2000 - 1200) / 3800 * 100 = 21.05%
+        XCTAssertEqual(util0, 21.05, accuracy: 0.1)
+    }
+    
+    func testLiveFanProvider() throws {
+        let provider = MMFanTelemetryProvider()
+        XCTAssertEqual(provider.domain, .fan)
+        
+        let sample = try provider.sampleTelemetry()
+        XCTAssertNotNil(sample)
+        XCTAssertNotNil(sample["fanCount"])
+    }
+}