feat(telemetry): implement AppleSmartBattery health telemetry provider (fixes #17 )

2026-09-08 12:46:22 +01:00
5 changed files with 322 additions and 0 deletions
@@ -27,6 +27,7 @@
 		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 */; };
+		8EDDC2171C55B6E7FC999DAB /* MMBatteryTelemetryProvider.m in Sources */ = {isa = PBXBuildFile; fileRef = 9C92D0D2B62B3081ECCA9920 /* MMBatteryTelemetryProvider.m */; };
 		901EF4853E785A2856E54BC9 /* MMKernelTelemetryTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = DE40072F9A1F9DBD1C48A3B1 /* MMKernelTelemetryTests.swift */; };
 		925245C5B5F8D8DA3C89C4BA /* MMComponentThermalProvider.m in Sources */ = {isa = PBXBuildFile; fileRef = C65F5835516BC2A65BCE25D2 /* MMComponentThermalProvider.m */; };
 		93EF83FE087C6DEAAE3EC0CC /* MMProcessTelemetryProvider.m in Sources */ = {isa = PBXBuildFile; fileRef = 728C692778909D2B7451C07B /* MMProcessTelemetryProvider.m */; };
@@ -40,6 +41,7 @@
 		ACC914C61AB3762EB0C40513 /* MMLoadAverageTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7EB05C092C94C3972727AAA7 /* MMLoadAverageTests.swift */; };
 		AE3C28BDC3CEF40A9E8F2B20 /* MMGPUTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 80A0F723121CDF9597316F58 /* MMGPUTests.swift */; };
 		B9C2D6574E808B517BA34C83 /* MMMemoryTelemetryProvider.m in Sources */ = {isa = PBXBuildFile; fileRef = 991AEEAF262F3C6BE930BC77 /* MMMemoryTelemetryProvider.m */; };
+		BC487DB86227F09CB0603894 /* MMBatteryTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = B0EB61D811D989279BCBE478 /* MMBatteryTests.swift */; };
 		CD91FC663B19DA1FEA3D49D7 /* MMAppleSMCClient.m in Sources */ = {isa = PBXBuildFile; fileRef = 5555436CD3CB8A73F5D6504F /* MMAppleSMCClient.m */; };
 		E3CCE93A7D4D1EB0187D3E52 /* MMNetworkBandwidthProvider.m in Sources */ = {isa = PBXBuildFile; fileRef = C539AEA27C794C6F428EA875 /* MMNetworkBandwidthProvider.m */; };
 		E6F2F695B8D3E7045967C082 /* MMFanTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 336CEE35A745F3C7E9F70F43 /* MMFanTests.swift */; };
@@ -72,6 +74,7 @@
 		2345555FF9780B02A90CC7A9 /* CoreFoundation.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = CoreFoundation.framework; path = System/Library/Frameworks/CoreFoundation.framework; sourceTree = SDKROOT; };
 		27C612287333D757C92A076A /* MMNetworkBandwidthTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MMNetworkBandwidthTests.swift; sourceTree = "<group>"; };
 		2C55E977DBFBE7FF04621608 /* MMLoadAverageProvider.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMLoadAverageProvider.h; sourceTree = "<group>"; };
+		2DC6E55C9D3F646A1C62133D /* MMBatteryTelemetryProvider.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMBatteryTelemetryProvider.h; sourceTree = "<group>"; };
 		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>"; };
@@ -101,9 +104,11 @@
 		8FBB436F3D9472194D8C6EDD /* MMSMCDefines.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMSMCDefines.h; sourceTree = "<group>"; };
 		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>"; };
+		9C92D0D2B62B3081ECCA9920 /* MMBatteryTelemetryProvider.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = MMBatteryTelemetryProvider.m; sourceTree = "<group>"; };
 		9DC54CCE276F93D5AF0A0C28 /* MMGPUTelemetryProvider.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMGPUTelemetryProvider.h; sourceTree = "<group>"; };
 		ADEA6BD38BA8D887B1DB64A9 /* MacMonitorApp.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MacMonitorApp.swift; sourceTree = "<group>"; };
 		AFA681E2464EA78CC19B54E0 /* MMDiskIOProvider.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMDiskIOProvider.h; sourceTree = "<group>"; };
+		B0EB61D811D989279BCBE478 /* MMBatteryTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MMBatteryTests.swift; sourceTree = "<group>"; };
 		B288C7402E2C00E75F8CD016 /* MMComponentThermalTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MMComponentThermalTests.swift; sourceTree = "<group>"; };
 		B5F2256DF514DD737306302B /* MMLoadAverageProvider.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = MMLoadAverageProvider.m; sourceTree = "<group>"; };
 		C539AEA27C794C6F428EA875 /* MMNetworkBandwidthProvider.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = MMNetworkBandwidthProvider.m; sourceTree = "<group>"; };
@@ -211,6 +216,8 @@
 		8B31CE7F9319FEC373E6CDC6 /* Power */ = {
 			isa = PBXGroup;
 			children = (
+				2DC6E55C9D3F646A1C62133D /* MMBatteryTelemetryProvider.h */,
+				9C92D0D2B62B3081ECCA9920 /* MMBatteryTelemetryProvider.m */,
 				CBA91906CA8B7936CC82A36B /* MMPowerTelemetryProvider.h */,
 				02F5FDE260999C39E978D849 /* MMPowerTelemetryProvider.m */,
 			);
@@ -296,6 +303,7 @@
 			isa = PBXGroup;
 			children = (
 				2EC3EDFCD5C50CB352FCED87 /* MacMonitorTests.swift */,
+				B0EB61D811D989279BCBE478 /* MMBatteryTests.swift */,
 				B288C7402E2C00E75F8CD016 /* MMComponentThermalTests.swift */,
 				4CE92B1A8D7FDBB6499448E1 /* MMCPULoadTests.swift */,
 				0F2BD3777A674DC4EB442890 /* MMCPUThermalTests.swift */,
@@ -450,6 +458,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				BC487DB86227F09CB0603894 /* MMBatteryTests.swift in Sources */,
 				160334CC765E091A7CBE21AA /* MMCPULoadTests.swift in Sources */,
 				87818E46CEA5145A8215D0E3 /* MMCPUThermalTests.swift in Sources */,
 				57BA02AE1CE24DBD02BD03A4 /* MMComponentThermalTests.swift in Sources */,
@@ -476,6 +485,7 @@
 			files = (
 				A9FCAEC0BF27A419DB148C4A /* ContentView.swift in Sources */,
 				CD91FC663B19DA1FEA3D49D7 /* MMAppleSMCClient.m in Sources */,
+				8EDDC2171C55B6E7FC999DAB /* MMBatteryTelemetryProvider.m in Sources */,
 				4419FE7554489B23976E2970 /* MMCPULoadProvider.m in Sources */,
 				87A9E18362486D0D385BBC4A /* MMCPUThermalProvider.m in Sources */,
 				925245C5B5F8D8DA3C89C4BA /* MMComponentThermalProvider.m in Sources */,
@@ -27,5 +27,6 @@
 #import "MMProcessTelemetryProvider.h"
 #import "MMProcessDetailInspector.h"
 #import "MMGPUTelemetryProvider.h"
+#import "MMBatteryTelemetryProvider.h"

 #endif /* MacMonitor_Bridging_Header_h */
@@ -0,0 +1,23 @@
+//
+//  MMBatteryTelemetryProvider.h
+//  MacMonitor
+//
+//  Telemetry provider for AppleSmartBattery health, cycle count, capacity, and adapter info.
+//
+
+#import <Foundation/Foundation.h>
+#import "MMTelemetryProvider.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface MMBatteryTelemetryProvider : NSObject <MMTelemetryProvider>
+
+@property (nonatomic, readonly) BOOL hasBattery;
+
+- (instancetype)init;
+
+ (NSDictionary<NSString *, id> *)calculateBatteryHealthWithProperties:(nullable NSDictionary<NSString *, id> *)rawProps;
+
+@end
+
+NS_ASSUME_NONNULL_END
@@ -0,0 +1,179 @@
+//
+//  MMBatteryTelemetryProvider.m
+//  MacMonitor
+//
+//  Telemetry provider for AppleSmartBattery health, cycle count, capacity, and adapter info.
+//
+
+#import "MMBatteryTelemetryProvider.h"
+#import <IOKit/IOKitLib.h>
+#import <IOKit/ps/IOPowerSources.h>
+#import <IOKit/ps/IOPSKeys.h>
+
+@implementation MMBatteryTelemetryProvider
+
+- (instancetype)init {
+    self = [super init];
+    return self;
+}
+
+- (MMTelemetryDomain)domain {
+    return MMTelemetryDomainPower;
+}
+
+- (NSString *)providerIdentifier {
+    return @"com.i3omb.macmonitor.telemetry.battery";
+}
+
+- (BOOL)isAvailable {
+    io_service_t service = IOServiceGetMatchingService(kIOMainPortDefault, IOServiceMatching("AppleSmartBattery"));
+    if (service != IO_OBJECT_NULL) {
+        IOObjectRelease(service);
+        return YES;
+    }
+    return NO;
+}
+
+- (BOOL)hasBattery {
+    return [self isAvailable];
+}
+
+ (NSDictionary<NSString *, id> *)calculateBatteryHealthWithProperties:(nullable NSDictionary<NSString *, id> *)rawProps {
+    if (!rawProps || rawProps.count == 0) {
+        return @{
+            @"hasBattery": @(NO),
+            @"installed": @(NO),
+            @"healthCondition": @"No Battery",
+            @"healthPercent": @(0.0),
+            @"cycleCount": @(0),
+            @"designCycleCount": @(0),
+            @"currentCapacity": @(0),
+            @"maxCapacity": @(0),
+            @"designCapacity": @(0),
+            @"temperature": @(0.0),
+            @"voltage": @(0.0),
+            @"amperage": @(0.0),
+            @"watts": @(0.0),
+            @"isCharging": @(NO),
+            @"isCharged": @(NO),
+            @"externalConnected": @(NO),
+            @"timeRemainingMinutes": @(-1),
+            @"manufacturer": @"N/A",
+            @"serial": @"N/A",
+            @"deviceName": @"N/A"
+        };
+    }
+
+    BOOL installed = [rawProps[@"BatteryInstalled"] boolValue];
+    NSInteger cycleCount = [rawProps[@"CycleCount"] integerValue];
+    NSInteger designCycleCount = rawProps[@"DesignCycleCount9C"] ? [rawProps[@"DesignCycleCount9C"] integerValue] : 1000;
+    
+    NSInteger currentCapacity = [rawProps[@"CurrentCapacity"] integerValue];
+    NSInteger maxCapacity = [rawProps[@"MaxCapacity"] integerValue];
+    
+    // DesignCapacity might be at top level or inside BatteryData
+    NSInteger designCapacity = [rawProps[@"DesignCapacity"] integerValue];
+    if (designCapacity <= 0 && [rawProps[@"BatteryData"] isKindOfClass:[NSDictionary class]]) {
+        designCapacity = [rawProps[@"BatteryData"][@"DesignCapacity"] integerValue];
+    }
+    
+    // Health percentage = (MaxCapacity / DesignCapacity) * 100.0
+    double healthPercent = 0.0;
+    if (designCapacity > 0) {
+        healthPercent = ((double)maxCapacity / (double)designCapacity) * 100.0;
+        if (healthPercent > 100.0) healthPercent = 100.0;
+    } else if (maxCapacity > 0) {
+        healthPercent = 100.0;
+    }
+    
+    // Health condition evaluation
+    NSString *condition = @"Normal";
+    BOOL permanentFailure = [rawProps[@"PermanentFailureStatus"] integerValue] != 0;
+    if (permanentFailure) {
+        condition = @"Permanent Failure";
+    } else if (healthPercent < 70.0 || (designCycleCount > 0 && cycleCount > designCycleCount)) {
+        condition = @"Service Recommended";
+    } else if (healthPercent < 80.0) {
+        condition = @"Fair";
+    } else {
+        condition = @"Normal";
+    }
+    
+    // Temperature: AppleSmartBattery returns in units of 0.01 deg C or 0.1 deg C (e.g. 3151 = 31.51 deg C)
+    double rawTemp = [rawProps[@"Temperature"] doubleValue];
+    double tempC = rawTemp > 1000.0 ? (rawTemp / 100.0) : (rawTemp > 100.0 ? rawTemp / 10.0 : rawTemp);
+    
+    double voltage = [rawProps[@"Voltage"] doubleValue] / 1000.0; // mV -> V
+    
+    // Amperage can be signed 64-bit stored as unsigned in dict
+    int64_t rawAmp = [rawProps[@"InstantAmperage"] longLongValue];
+    if (rawAmp == 0) {
+        rawAmp = [rawProps[@"Amperage"] longLongValue];
+    }
+    int32_t signedAmp = (int32_t)rawAmp; // standard cast from uint32/uint64 representation
+    double amperage = ((double)signedAmp) / 1000.0; // mA -> A
+    double watts = fabs(voltage * amperage);
+    
+    BOOL isCharging = [rawProps[@"IsCharging"] boolValue];
+    BOOL fullyCharged = [rawProps[@"FullyCharged"] boolValue];
+    BOOL externalConnected = [rawProps[@"ExternalConnected"] boolValue];
+    NSInteger timeRemaining = [rawProps[@"TimeRemaining"] integerValue];
+    if (timeRemaining == 65535) {
+        timeRemaining = -1;
+    }
+    
+    NSString *manufacturer = rawProps[@"Manufacturer"] ?: @"Apple";
+    NSString *serial = rawProps[@"Serial"] ?: @"";
+    NSString *deviceName = rawProps[@"DeviceName"] ?: @"";
+    
+    // Power adapter details
+    NSDictionary *adapterDetails = [rawProps[@"AdapterDetails"] isKindOfClass:[NSDictionary class]] ? rawProps[@"AdapterDetails"] : nil;
+    NSInteger adapterWatts = 0;
+    if (adapterDetails && adapterDetails[@"Watts"]) {
+        adapterWatts = [adapterDetails[@"Watts"] integerValue];
+    }
+    
+    return @{
+        @"hasBattery": @(YES),
+        @"installed": @(installed),
+        @"healthCondition": condition,
+        @"healthPercent": @(round(healthPercent * 10.0) / 10.0),
+        @"cycleCount": @(cycleCount),
+        @"designCycleCount": @(designCycleCount),
+        @"currentCapacity": @(currentCapacity),
+        @"maxCapacity": @(maxCapacity),
+        @"designCapacity": @(designCapacity),
+        @"temperature": @(round(tempC * 10.0) / 10.0),
+        @"voltage": @(round(voltage * 100.0) / 100.0),
+        @"amperage": @(round(amperage * 100.0) / 100.0),
+        @"watts": @(round(watts * 10.0) / 10.0),
+        @"isCharging": @(isCharging),
+        @"isCharged": @(fullyCharged),
+        @"externalConnected": @(externalConnected),
+        @"timeRemainingMinutes": @(timeRemaining),
+        @"manufacturer": manufacturer,
+        @"serial": serial,
+        @"deviceName": deviceName,
+        @"adapterWatts": @(adapterWatts)
+    };
+}
+
+- (nullable NSDictionary<NSString *, id> *)sampleTelemetryWithError:(NSError **)error {
+    io_service_t service = IOServiceGetMatchingService(kIOMainPortDefault, IOServiceMatching("AppleSmartBattery"));
+    if (service == IO_OBJECT_NULL) {
+        return [MMBatteryTelemetryProvider calculateBatteryHealthWithProperties:nil];
+    }
+    
+    CFMutableDictionaryRef props = NULL;
+    kern_return_t kr = IORegistryEntryCreateCFProperties(service, &props, kCFAllocatorDefault, 0);
+    IOObjectRelease(service);
+    
+    if (kr != KERN_SUCCESS || !props) {
+        return [MMBatteryTelemetryProvider calculateBatteryHealthWithProperties:nil];
+    }
+    
+    NSDictionary *dict = (__bridge_transfer NSDictionary *)props;
+    return [MMBatteryTelemetryProvider calculateBatteryHealthWithProperties:dict];
+}
+
+@end
@@ -0,0 +1,109 @@
+//
+//  MMBatteryTests.swift
+//  MacMonitorTests
+//
+//  Unit and integration tests for MMBatteryTelemetryProvider.
+//
+
+import XCTest
+@testable import MacMonitor
+
+final class MMBatteryTests: XCTestCase {
+    var provider: MMBatteryTelemetryProvider!
+
+    override func setUp() {
+        super.setUp()
+        provider = MMBatteryTelemetryProvider()
+    }
+
+    override func tearDown() {
+        provider = nil
+        super.tearDown()
+    }
+
+    func testDomainAndIdentifier() {
+        XCTAssertEqual(provider.domain, .power)
+        XCTAssertEqual(provider.providerIdentifier, "com.i3omb.macmonitor.telemetry.battery")
+    }
+
+    func testCalculateBatteryHealthWithSimulatedNormalBattery() {
+        let raw: [String: Any] = [
+            "BatteryInstalled": true,
+            "CycleCount": 250,
+            "DesignCycleCount9C": 1000,
+            "CurrentCapacity": 3000,
+            "MaxCapacity": 4000,
+            "DesignCapacity": 4400,
+            "Temperature": 3150, // 31.5 C
+            "Voltage": 11100, // 11.1 V
+            "Amperage": -1500, // -1.5 A
+            "IsCharging": false,
+            "FullyCharged": false,
+            "ExternalConnected": false,
+            "TimeRemaining": 120,
+            "Manufacturer": "SMP",
+            "Serial": "TEST123456",
+            "DeviceName": "bq20z451"
+        ]
+
+        let health = MMBatteryTelemetryProvider.calculateBatteryHealth(withProperties: raw)
+        XCTAssertEqual(health["hasBattery"] as? Bool, true)
+        XCTAssertEqual(health["installed"] as? Bool, true)
+        XCTAssertEqual(health["healthCondition"] as? String, "Normal")
+        
+        let healthPercent = (health["healthPercent"] as? Double) ?? 0.0
+        XCTAssertEqual(healthPercent, 90.9, accuracy: 0.1)
+        XCTAssertEqual(health["cycleCount"] as? Int, 250)
+        XCTAssertEqual(health["designCycleCount"] as? Int, 1000)
+        XCTAssertEqual(health["temperature"] as? Double, 31.5)
+        let watts = (health["watts"] as? Double) ?? 0.0
+        XCTAssertEqual(watts, 16.7, accuracy: 0.2)
+        XCTAssertEqual(health["manufacturer"] as? String, "SMP")
+    }
+
+    func testCalculateBatteryHealthWithServiceRecommended() {
+        let raw: [String: Any] = [
+            "BatteryInstalled": true,
+            "CycleCount": 1100,
+            "DesignCycleCount9C": 1000,
+            "CurrentCapacity": 1500,
+            "MaxCapacity": 2500,
+            "DesignCapacity": 4400, // ~56.8% health
+            "Temperature": 3200,
+            "Voltage": 10800,
+            "Amperage": -1000,
+            "IsCharging": false,
+            "FullyCharged": false,
+            "ExternalConnected": false,
+            "TimeRemaining": 90,
+            "Manufacturer": "Apple"
+        ]
+
+        let health = MMBatteryTelemetryProvider.calculateBatteryHealth(withProperties: raw)
+        XCTAssertEqual(health["healthCondition"] as? String, "Service Recommended")
+        let healthPercent = (health["healthPercent"] as? Double) ?? 0.0
+        XCTAssertLessThan(healthPercent, 70.0)
+    }
+
+    func testCalculateBatteryHealthWithNil() {
+        let health = MMBatteryTelemetryProvider.calculateBatteryHealth(withProperties: nil)
+        XCTAssertEqual(health["hasBattery"] as? Bool, false)
+        XCTAssertEqual(health["installed"] as? Bool, false)
+        XCTAssertEqual(health["healthCondition"] as? String, "No Battery")
+    }
+
+    func testLiveSampleBattery() {
+        do {
+            let sample = try provider.sampleTelemetry()
+            XCTAssertNotNil(sample)
+            if provider.hasBattery {
+                XCTAssertEqual(sample["hasBattery"] as? Bool, true)
+                XCTAssertNotNil(sample["cycleCount"])
+                XCTAssertNotNil(sample["healthPercent"])
+                XCTAssertNotNil(sample["healthCondition"])
+            }
+        } catch {
+            XCTFail("sampleTelemetry threw error: \(error)")
+        }
+    }
+}