battery_monitor

A Flutter plugin that monitors battery level and state natively on iOS and Android, streaming every percentage change to Flutter in real time.

---

Features

Feature	Android	iOS
Stream every percentage change	✅	✅
State-change event	✅	✅
One-shot getBatteryLevel()	✅	✅
Simulator support	✅	⚠️ returns -1

---

Getting started

Add the package to your pubspec.yaml:

dependencies:
  battery_monitor: ^0.0.1   # once published on pub.dev

No additional permissions are needed — battery info is available to all apps on both platforms without any manifest/Info.plist entries.

---

Usage

import 'package:battery_monitor/battery_monitor.dart';

final monitor = BatteryMonitor.instance;

// 1. Subscribe BEFORE starting so no events are missed.
final sub = monitor.batteryEventStream.listen((BatteryEvent event) {
  switch (event.eventType) {
    case BatteryEventType.levelChanged:
      print('Battery level: ${event.level}%  state: ${event.state}');
      break;
    case BatteryEventType.stateChanged:
      print('State changed to: ${event.state}  (level ${event.level}%)');
      break;
  }
});

// 2. Start monitoring.
//    notifyOnStateChange — also fire on every state transition.
await monitor.startMonitoring(
  notifyOnStateChange: true,
);

// 3. One-shot level query (works independently of startMonitoring).
final level = await monitor.getBatteryLevel();
print('Current battery: $level%');

// 4. Stop and clean up when done.
await monitor.stopMonitoring();
await sub.cancel();

---

API reference

BatteryMonitor.instance

Singleton entry point.

Method / Property	Description
startMonitoring({bool notifyOnStateChange})	Configure and start native monitoring.
stopMonitoring()	Stop native monitoring and release resources.
getBatteryLevel()	Return current level as int (0–100, or -1 if unavailable).
batteryEventStream	Stream<BatteryEvent> — subscribe before startMonitoring.

BatteryEvent

Field	Type	Description
level	int	Current battery percentage (0–100, or -1).
state	BatteryState	Current battery state at event time.
eventType	BatteryEventType	What triggered this event.

BatteryState

charging · discharging · full · notCharging (Android only) · unknown

BatteryEventType

Value	When emitted
levelChanged	Every time the battery percentage changes by at least 1%.
stateChanged	Battery state transitioned (only when notifyOnStateChange: true).

---

Platform notes

Android

• Uses ACTION_BATTERY_CHANGED sticky broadcast (no permissions needed, API 21+).
• notCharging state is reported when the device is plugged in but not actively charging.

iOS

• Uses UIDevice.batteryLevelDidChangeNotification and UIDevice.batteryStateDidChangeNotification.
• Battery monitoring is disabled automatically when the stream is cancelled.
• iOS Simulator: battery level is always -1 and state is always .unknown.
• Background: UIDevice notifications are not delivered when the app is suspended. Foreground-only monitoring is sufficient for most use cases.