battery_monitor

A Flutter plugin that monitors battery level and state natively on iOS and Android and notifies Flutter when:

• the battery drops to or below a configurable threshold while discharging, or
• the battery state changes (e.g. plugged in, unplugged, full).

---

Features

Feature	Android	iOS
Real-time level updates (via broadcast / UIDevice)	✅	✅
Threshold reached event	✅	✅
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.thresholdReached:
      print('Low battery! Level: ${event.level}%');
      break;
    case BatteryEventType.stateChanged:
      print('State changed to: ${event.state}  (level ${event.level}%)');
      break;
  }
});

// 2. Start monitoring.
//    threshold        — fire once when level drops to/below this % while discharging.
//    notifyOnStateChange — fire on every state transition.
await monitor.startMonitoring(
  threshold: 20,
  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({int? threshold, 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
thresholdReached	Level ≤ threshold while discharging (once per discharge cycle).
stateChanged	Battery state transitioned (only when notifyOnStateChange: true).

---

Threshold behaviour

The threshold event fires once per discharge cycle:

1. Level drops to ≤ threshold while discharging → event fires, guard set.
2. Level rises above threshold (e.g. charger plugged in) → guard reset.
3. Level drops again → event fires again.

---

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.