How to Inspect Hardware Lights, Notification LEDs, and Illumination on Android Using ADB dumpsys lights

Modern Android smartphones, automotive dashboards, industrial handhelds, and IoT appliances feature diverse hardware illumination subsystems. These include multi-color notification LEDs, physical capacitive button backlights, keyboard backlights, battery charging indicators, camera flashlight LEDs, and ambient indicator lights. Operating systems must control the brightness, flash pulse frequency, color mixing (RGB), and power states of each light emitter.

Android abstracts physical lighting hardware through the Lights System Service (lights) and the hardware abstraction layer (HAL android.hardware.light). When diagnosing missing LED notification pulses, uneven button backlighting, or third-party notification app integration issues, developers and hardware QA engineers use the Android Debug Bridge (ADB) to inspect the live illumination framework via dumpsys lights.

Understanding the Android Lights Framework and Light IDs

The Android framework manages lighting through predefined hardware identifiers (Light IDs) defined in the system HAL:

• LIGHT_ID_BACKLIGHT (0): Controls main display panel backlight brightness levels.
• LIGHT_ID_KEYBOARD (1): Controls illumination behind physical hardware QWERTY keyboards.
• LIGHT_ID_BUTTONS (2): Governs backlighting behind physical or capacitive navigation buttons (Home, Back, Recents).
• LIGHT_ID_BATTERY (3): Reflects charging states (e.g. solid red for low battery, solid green for fully charged).
• LIGHT_ID_NOTIFICATIONS (4): Multi-color RGB LED that pulses or flashes to indicate missed calls, SMS messages, or pending application alerts.
• LIGHT_ID_ATTENTION (5): Dedicated alert light for high-priority emergency notifications.
• LIGHT_ID_BLUETOOTH & WIFI (6 & 7): Wireless radio activity indicators on specialized industrial hardware.

Connecting to ADB and Querying Lights State

Connect your Android test device or development board to your workstation with USB debugging enabled. Confirm device responsiveness:

adb devices

To inspect the current status of all lighting subsystems, run:

adb shell dumpsys lights

The service outputs the complete configuration of active and inactive lighting channels:

LightsService:
  Lights:
    Light id=0 (backlight):
      color=0xffc8c8c8 mode=0 onMS=0 offMS=0 brightnessMode=0
    Light id=2 (buttons):
      color=0x00000000 mode=0 onMS=0 offMS=0 brightnessMode=0
    Light id=3 (battery):
      color=0xffff0000 mode=0 onMS=0 offMS=0 brightnessMode=0
    Light id=4 (notifications):
      color=0xff0000ff mode=1 onMS=1000 offMS=2000 brightnessMode=0

Interpreting Critical Diagnostic Fields

When auditing light behavior or diagnosing unexpected battery drain from illuminated components, evaluate the following parameters:

Field	Reported Value	Technical Meaning
color	Hexadecimal ARGB (e.g. 0xff0000ff)	32-bit ARGB color value. In this example, Alpha=255, Red=0, Green=0, Blue=255 (solid blue).
mode	0, 1, or 2	Flash mode: 0 = Solid (constant), 1 = Timed flashing (onMS/offMS), 2 = Hardware pulse (breathing effect).
onMS	Milliseconds (e.g. 1000)	Duration the LED remains illuminated during each cycle of a flashing notification.
offMS	Milliseconds (e.g. 2000)	Duration the LED remains extinguished between illumination pulses.
brightnessMode	0 (User) or 1 (Sensor)	Indicates whether brightness is governed manually by system settings or automatically via ambient light sensors.

Auditing Notification LED Pulses

If an application fails to trigger the notification LED, inspect Light id=4 (notifications) while triggering a test notification:

adb shell dumpsys lights | grep -A 2 "Light id=4"

If color=0x00000000, the application’s NotificationChannel has disabled lights, the notification priority is set below IMPORTANCE_DEFAULT, or the device is currently in Do Not Disturb (DND) mode.

Diagnosing Battery Charging Indicators

When debugging power and charging behaviors on hardware prototypes or rugged devices, inspect Light id=3 (battery):

• Low Battery / Discharging: Often displays pulsing red (0xffff0000 mode=1).
• Charging: Displays solid orange or solid red (mode=0).
• Fully Charged: Transitions to solid green (0xff00ff00 mode=0).

If the LED remains green while discharging, it indicates that the Battery Service or Power HAL failed to signal the Lights Service upon cable disconnection.

Testing Lighting Changes via Command Shell

On supported devices with modern Lights HAL implementations, administrators and testers can interact with the lighting service directly via cmd lights:

adb shell cmd lights

To inspect available command options, review the built-in help text. For example, testing screen backlight brightness transitions without using the system settings UI:

adb shell cmd lights set-light 0 128

Tracing Live Lighting Events in Logcat

To monitor when apps request LED notifications, change backlight levels, or trigger hardware pulses in real time, filter the system logcat stream:

adb logcat -s LightsService:* LightHal:* LightsManager:*

Using dumpsys lights provides mobile developers, kernel engineers, and hardware integrators with direct, low-level transparency into Android’s illumination framework, streamlining notification validation and hardware verification.