iOS Device Monitor #

A comprehensive Flutter plugin for monitoring iOS device performance metrics including CPU information, GPU/Metal capabilities, thermal state, system uptime, and advanced CPU usage statistics with per-thread and per-core details.

📋 Overview #

The iOS Device Monitor plugin provides production-ready access to detailed iOS device monitoring capabilities through a clean, type-safe Dart API. Perfect for performance monitoring, diagnostics, system utilities, and developer tools that need deep insights into device behavior.

Why Use This Plugin? #

• 🎯 Comprehensive Monitoring: Access CPU, GPU, thermal, uptime, and detailed usage statistics
• 🔒 Type-Safe: Full null safety support with well-structured model classes
• 📊 Detailed Metrics: Thread-level and core-level CPU monitoring
• 🎨 Metal Integration: Complete GPU/Metal framework information
• 🔥 Thermal Awareness: Real-time thermal state and throttling detection
• ⚡ Performance Optimized: Efficient native implementation
• 📱 iOS Native: Direct access to iOS system APIs

✨ Features #

1. CPU Information (getCpuInfo) #

Get detailed CPU architecture and core information:

• CPU architecture (arm64, arm64e, etc.)
• Total core counts

2. GPU/Metal Information (getGpuInfo) #

Access comprehensive GPU and Metal framework details:

• GPU name
• Recommended maximum working set size (iOS 16+)
• Registry ID information
• Metal GPU family support (iOS 13+)
• Maximum threads per threadgroup

3. Thermal State Monitoring (getThermalState) #

Monitor device temperature and throttling:

• Current thermal level (nominal, fair, serious, critical)
• Performance throttling status
• User-friendly status messages
• Thermal state enum for easy comparisons
• Warning and critical state detection

4. System Uptime (getSystemUptime) #

Track system boot time and uptime:

• Boot time as Unix timestamp
• Uptime in seconds
• Formatted uptime strings (e.g., "2d 5h 32m")
• Boot date as DateTime
• Uptime in hours and days
• Duration checks (running for a day/week)

5. Advanced CPU Usage (getAdvancedCpuUsage) #

Get comprehensive CPU usage statistics:

• Overall CPU usage percentage
• User and system time breakdown
• Per-core usage statistics
• Thread count (total and active)
• Usage level indicators (low, medium, high)
• Timestamp information

📦 Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  ios_device_monitor: ^0.1.0

Then run:

flutter pub get

🚀 Quick Start #

import 'package:ios_device_monitor/ios_device_monitor.dart';
import 'package:ios_device_monitor/models/models.dart';

// Get CPU information
final cpuInfo = await IosDeviceMonitor.getCpuInfo();
print('CPU: ${cpuInfo.displayName}');
print('Cores: ${cpuInfo.coreCount}');

// Get GPU information
final gpuInfo = await IosDeviceMonitor.getGpuInfo();
print('GPU: ${gpuInfo.displayName}');
print('Memory: ${gpuInfo.memoryType}');

// Get thermal state
final thermal = await IosDeviceMonitor.getThermalState();
print('Thermal: ${thermal.statusMessage}');
print('Throttling: ${thermal.isThrottling}');

// Get system uptime
final uptime = await IosDeviceMonitor.getSystemUptime();
print('Uptime: ${uptime.uptimeFormatted}');

// Get CPU usage
final usage = await IosDeviceMonitor.getAdvancedCpuUsage();
print('CPU Usage: ${usage.usagePercentageString}');
print('Active Threads: ${usage.activeThreadCount}');

📖 Usage Examples #

1. CPU Information #

try {
  final cpuInfo = await IosDeviceMonitor.getCpuInfo();
        debugPrint(_cpuInfo?.architecture.toString());
        debugPrint(_cpuInfo?.coreCount.toString());
        debugPrint(_cpuInfo?.coreCountDescription.toString());
} on PlatformException catch (e) {
  print('Error: ${e.message}');
}

2. GPU/Metal Information #

try {
  final gpuInfo = await IosDeviceMonitor.getGpuInfo();
  
        debugPrint(_gpuInfo?.maxThreadsPerThreadgroup.toString());
        debugPrint(_gpuInfo?.name.toString());
        debugPrint(_gpuInfo?.recommendedMaxWorkingSetSize.toString());
        debugPrint(_gpuInfo?.registryID.toString());
        debugPrint(_gpuInfo?.supportedFeatures.toString());
        debugPrint(_gpuInfo?.supportsFamily.toString());
} on PlatformException catch (e) {
  print('Error: ${e.message}');
}

3. Thermal State Monitoring #

try {
  final thermal = await IosDeviceMonitor.getThermalState();
  
        debugPrint(_thermalState?.description.toString());
        debugPrint(_thermalState?.isCritical.toString());
        debugPrint(_thermalState?.isThrottling.toString());
        debugPrint(_thermalState?.isWarning.toString());
        debugPrint(_thermalState?.level.toString());
        debugPrint(_thermalState?.state.toString());
        debugPrint(_thermalState?.statusMessage.toString());
        debugPrint(_thermalState?.temperature.toString());
        debugPrint(_thermalState?.thermalLevel.toString());
} on PlatformException catch (e) {
  print('Error: ${e.message}');
}

4. System Uptime #

try {
  final uptime = await IosDeviceMonitor.getSystemUptime();
  
        debugPrint(_systemUptime?.bootDate.toString());
        debugPrint(_systemUptime?.bootDateFormatted.toString());
        debugPrint(_systemUptime?.bootTime.toString());
        debugPrint(_systemUptime?.hasBeenRunningForADay.toString());
        debugPrint(_systemUptime?.hasBeenRunningForAWeek.toString());
        debugPrint(_systemUptime?.shortUptimeDescription.toString());
        debugPrint(_systemUptime?.uptime.toString());
        debugPrint(_systemUptime?.uptimeDays.toString());
        debugPrint(_systemUptime?.uptimeFormatted.toString());
        debugPrint(_systemUptime?.uptimeHours.toString());
} on PlatformException catch (e) {
  print('Error: ${e.message}');
}

5. Advanced CPU Usage #

try {
  final usage = await IosDeviceMonitor.getAdvancedCpuUsage();
  
        debugPrint(_advancedCpuUsage?.activeThreadCount.toString());
        debugPrint(_advancedCpuUsage?.averageCoreUsage.toString());
        debugPrint(_advancedCpuUsage?.coreCount.toString());
        debugPrint(_advancedCpuUsage?.detailedCoreUsages.toString());
        debugPrint(_advancedCpuUsage?.isHighUsage.toString());
        debugPrint(_advancedCpuUsage?.isLowUsage.toString());
        debugPrint(_advancedCpuUsage?.isMediumUsage.toString());
        debugPrint(_advancedCpuUsage?.systemTime.toString());
        debugPrint(_advancedCpuUsage?.threadDetails.toString());
        debugPrint(_advancedCpuUsage?.timestamp.toString());
        debugPrint(_advancedCpuUsage?.timestampDate.toString());
        debugPrint(_advancedCpuUsage?.timestampFormatted.toString());
        debugPrint(_advancedCpuUsage?.totalThreadCount.toString());
        debugPrint(_advancedCpuUsage?.totalTime.toString());
        debugPrint(_advancedCpuUsage?.usage.toString());
        debugPrint(_advancedCpuUsage?.usageLevel.toString());
        debugPrint(_advancedCpuUsage?.usagePercentageString.toString());
        debugPrint(_advancedCpuUsage?.userTime.toString());
} on PlatformException catch (e) {
  print('Error: ${e.message}');
}

🎨 Advanced Usage #

Periodic Monitoring #

Monitor device metrics at regular intervals:

Timer.periodic(const Duration(seconds: 5), (timer) async {
  try {
    final thermal = await IosDeviceMonitor.getThermalState();
    final usage = await IosDeviceMonitor.getAdvancedCpuUsage();
    
    setState(() {
      _thermal = thermal;
      _cpuUsage = usage;
    });
    
    if (thermal.isCritical || usage.isHighUsage) {
      _showPerformanceWarning();
    }
  } catch (e) {
    print('Monitoring error: $e');
  }
});

Caching Static Information #

Cache information that doesn't change frequently:

class DeviceInfoService {
  CpuInfo? _cachedCpuInfo;
  GpuInfo? _cachedGpuInfo;
  
  Future<CpuInfo> getCpuInfo() async {
    _cachedCpuInfo ??= await IosDeviceMonitor.getCpuInfo();
    return _cachedCpuInfo!;
  }
  
  Future<GpuInfo> getGpuInfo() async {
    _cachedGpuInfo ??= await IosDeviceMonitor.getGpuInfo();
    return _cachedGpuInfo!;
  }
  
  Future<ThermalState> getThermalState() {
    return IosDeviceMonitor.getThermalState();
  }
  
  Future<AdvancedCpuUsage> getCpuUsage() {
    return IosDeviceMonitor.getAdvancedCpuUsage();
  }
}

Platform Check #

Always verify you're on iOS before calling methods:

if (await IosDeviceMonitor.isIOS) {
  final cpuInfo = await IosDeviceMonitor.getCpuInfo();
  // Safe to use iOS-specific features
} else {
  // Show error or use alternative approach
  print('This plugin only works on iOS');
}

// Get plugin version
final version = await IosDeviceMonitor.pluginVersion;
print('Using plugin version: $version');

📚 API Reference #

Core Methods #

Utility Methods #

Model Classes #

All models include:

• ✅ Full null safety support
• ✅ JSON serialization (fromJson, toJson)
• ✅ String representation (toString)
• ✅ Equality operators (==, hashCode)
• ✅ Immutable with copyWith method
• ✅ Helper getters and computed properties
• ✅ Comprehensive documentation

Available Models:

• CpuInfo - CPU information (137 lines)
• GpuInfo - GPU/Metal information (297 lines)
• ThermalState - Thermal state (202 lines)
• SystemUptime - Uptime information (150 lines)
• AdvancedCpuUsage - CPU usage details (516 lines)

See API_DOCUMENTATION.md for detailed model documentation.

🔧 Platform Support #

iOS Version Notes:

• iOS 11.0+: All basic features supported
• iOS 12.0+: Enhanced thread information
• iOS 13.0+: Metal GPU family support
• iOS 16.0+: Recommended max working set size

📋 Requirements #

Permissions #

No special permissions required! This plugin uses standard iOS APIs that don't require user authorization.

🤝 Contributing #

Contributions are welcome! Please follow these guidelines:

Getting Started #

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: flutter test
5. Check analysis: flutter analyze
6. Commit: git commit -m 'Add amazing feature'
7. Push: git push origin feature/amazing-feature
8. Open a Pull Request

Development Guidelines #

• Follow Dart style guide
• Add tests for new features
• Update documentation
• Maintain null safety
• Include examples for new APIs
• Keep backwards compatibility

Areas for Contribution #

• Additional iOS metrics
• Performance optimizations
• Example applications
• Documentation improvements
• Bug fixes
• Test coverage

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 iOS Device Monitor Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🙏 Acknowledgments #

• Built with Flutter
• Uses iOS native APIs and Metal framework
• Inspired by system monitoring tools
• Community feedback and contributions

Made with ❤️ for Flutter developers

Need help? Found a bug? Have a feature request? Open an issue!