How to Inspect and Simulate Battery Hardware States on Android Using ADB dumpsys battery

Android devices rely on the framework BatteryService daemon and the underlying Health HAL (Hardware Abstraction Layer) to monitor power sources, cell temperature, state of charge, voltage curves, and charging current. During application development, hardware validation, or automated quality assurance testing, relying on physical charging cables or waiting for a battery to deplete naturally is impractical and imprecise. The Android Debug Bridge (ADB) provides direct administrative access to the battery subsystem through the dumpsys battery command. This diagnostic interface allows engineers to inspect real-time electrical telemetry and dynamically simulate power states, low-battery conditions, charger disconnects, and thermal thresholds without altering physical hardware.

Understanding Android BatteryService Architecture

The battery management architecture in Android spans multiple distinct layers, transitioning from kernel-level fuel-gauge drivers to high-level framework intent broadcasts:

• Linux Kernel Power Supply Subsystem: Kernel drivers query battery fuel-gauge ICs and charger controller chips via I2C or SPMI buses, exposing metrics via sysfs nodes (typically mounted under /sys/class/power_supply/battery/).
• Health HAL: The Android Health Hardware Abstraction Layer daemon (android.hardware.health-service) polls kernel sysfs nodes or listens for uevents, translating raw sensor metrics into standardised AIDL/HIDL structures.
• Framework BatteryService: The core system server component (com.android.server.BatteryService) ingests telemetry from the Health HAL, calculates aggregate state, updates system settings, and coordinates system-level responses.
• Public Telemetry and Intent Delivery: BatteryManager queries the service state and issues sticky system-wide broadcasts such as ACTION_BATTERY_CHANGED, ACTION_POWER_CONNECTED, and ACTION_BATTERY_LOW.

Querying Real-Time Battery Subsystem Diagnostics

To inspect the current operational parameters of the battery subsystem, connect your target Android device with USB debugging enabled and execute the diagnostic dump command:

adb shell dumpsys battery

The command outputs the operational parameters reported by the Health HAL. A representative output structure appears as follows:

Current Battery Service state:
  AC powered: false
  USB powered: true
  Wireless powered: false
  Dock powered: false
  Max charging current: 500000
  Max charging voltage: 5000000
  Charge counter: 2854320
  status: 2
  health: 2
  present: true
  level: 84
  scale: 100
  voltage: 4125
  temperature: 294
  technology: Li-ion

Decoding these fields requires understanding Android internal enumeration constants:

• Power Source Flags: AC powered, USB powered, Wireless powered, and Dock powered indicate which physical bus is supplying operational current.
• status: Represents the charging lifecycle state mapping to BatteryManager.BATTERY_STATUS_*:
  • 1: Unknown
  • 2: Charging
  • 3: Discharging
  • 4: Not charging
  • 5: Full
• health: Indicates physical cell condition mapping to BatteryManager.BATTERY_HEALTH_*:
  • 1: Unknown
  • 2: Good
  • 3: Overheat
  • 4: Dead
  • 5: Over voltage
  • 6: Unspecified failure
  • 7: Cold
• level and scale: level indicates the current percentage of charge relative to scale (standard scale is 100).
• voltage: Battery terminal potential expressed in millivolts (mV). In the output above, 4125 corresponds to 4.125 V.
• temperature: Internal pack temperature expressed in tenths of a degree Celsius. A value of 294 indicates 29.4 °C.
• Charge counter: Total accumulated microampere-hours (µAh).

Simulating Battery Hardware States for Development and Testing

Automated test suites and mobile application developers frequently need to observe how client software behaves when a device transitions to critical battery levels, disconnects from mains power, or reaches an overheated threshold. The dumpsys battery utility incorporates runtime overrides that intercept the Health HAL signal stream, forcing BatteryService to broadcast simulated states.

Simulating Power Disconnection (Unplugging)

When physical USB debugging is active, the connected host continuously supplies current, preventing the device from entering a discharging state. To simulate running solely on internal battery reserve while keeping the ADB debugging bridge active:

adb shell dumpsys battery unplug

This command switches AC powered, USB powered, and Wireless powered to false and updates the charging status to discharging. The Android operating system immediately triggers standard power-saving routines and background job throttling.

Overriding the Battery Percentage

To evaluate threshold-specific UI alerts, background synchronisation suspensions, or low-battery power modes, force the battery level to a specific integer:

# Force battery level to 5 percent (triggers low-battery warnings)
adb shell dumpsys battery set level 5

# Force battery level to 100 percent
adb shell dumpsys battery set level 100

Overriding Power Supply Types

You can selectively enable or disable individual simulated charging connections:

# Simulate standard USB charging
adb shell dumpsys battery set usb 1

# Simulate high-capacity AC adapter charging
adb shell dumpsys battery set ac 1

# Simulate wireless induction charging
adb shell dumpsys battery set wireless 1

# Disable AC charging simulation
adb shell dumpsys battery set ac 0

Simulating Battery Health and Temperature Alerts

Thermal management frameworks throttle CPU clusters and limit high-refresh-rate displays when battery temperatures exceed critical thresholds. You can trigger thermal protection pathways or battery error dialogues by manipulating the health and temperature flags:

# Simulate an overheated battery condition (Health code 3)
adb shell dumpsys battery set health 3

# Simulate high internal temperature (48.5 degrees Celsius = 485)
adb shell dumpsys battery set temp 485

# Simulate extreme sub-zero cold condition (Health code 7)
adb shell dumpsys battery set health 7

Simulating Charging Status Enums

You can override the operational status to test charging indicators, lock screen widgets, or always-on display states:

# Force status to Full (code 5)
adb shell dumpsys battery set status 5

# Force status to Discharging (code 3)
adb shell dumpsys battery set status 3

Resetting Simulated State and Restoring Hardware Telemetry

Overrides applied via dumpsys battery set or dumpsys battery unplug persist in memory until explicitly revoked or until the device reboots. If you disconnect an automated test bench without restoring the subsystem, the device will continue reporting false battery values and will fail to charge normally from real power supplies.

To clear all overrides and reconnect BatteryService to the active Health HAL hardware feed, execute:

adb shell dumpsys battery reset

Verify that the overrides have cleared by re-inspecting the service dump:

adb shell dumpsys battery

The diagnostic dump should reflect active physical measurements, with physical charging voltages and authentic ambient temperatures restored.

Automating Battery Stress Scenarios via Shell Scripts

For reproducible continuous integration pipelines, shell automation can sequence state transitions to validate responsive UI behaviour and system telemetry listeners. The following POSIX shell script demonstrates automating a full discharge cycle simulation:

#!/bin/sh
set -e

echo "[+] Initialising battery state simulation..."
adb shell dumpsys battery unplug

echo "[+] Simulating stepped battery discharge..."
for LEVEL in 50 20 15 10 5 2; do
  echo "[-] Setting battery level to ${LEVEL}%"
  adb shell dumpsys battery set level "${LEVEL}"
  sleep 3
done

echo "[+] Triggering critical low-battery power warning..."
adb shell dumpsys battery set status 3
adb shell dumpsys battery set level 1
sleep 5

echo "[+] Restoring hardware battery defaults..."
adb shell dumpsys battery reset
echo "[+] Battery simulation test completed successfully."

By integrating dumpsys battery overrides into automated regression workflows, software engineering teams can rigorously validate battery telemetry handlers, energy-saving policies, and thermal failsafes under deterministic conditions.