Power

get_power_state reads the device's current high-level power state (adb shell dumpsys power) — wakefulness and, when reported, interactive state. wake_device turns a sleeping screen back on by injecting the WAKEUP key (adb shell input keyevent WAKEUP); it's idempotent and does not dismiss keyguard. reboot_device requests a reboot into the normal system image (adb reboot); it's destructive (denied unless ADB_AUTOMATION_ALLOW_DESTRUCTIVE=1) and returns as soon as the request is accepted, so pair it with wait_for_device_state.

get_power_state

Get the device's current high-level power state: adb shell dumpsys power.

dumpsys power's full output is large and full of unstable implementation detail, so this deliberately extracts only two fields: wakefulness (the device's core sleep/wake state) and, when present, whether it's currently interactive. Nothing else from the dump is parsed or exposed. To change power state, use wake_device or reboot_device.

Parameters:

Name	Type	Description	Default
serial	str	The target device's adb serial (see list_connected_devices).	required

Returns:

Type	Description
PowerState	The serial, wakefulness (the raw value dumpsys reports, e.g. "Awake", "Asleep", "Dreaming", "Dozing"), and interactive (True/ False when dumpsys reports it, None when that specific field isn't present in this dump — see Error handling).

Error handling

An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. dumpsys running but producing output with no recognizable wakefulness field at all (e.g. the power service isn't registered, or the dump format is otherwise unrecognizable) raises POWER_STATE_UNAVAILABLE — distinct from interactive simply being absent, which is returned as data (interactive=None), not raised. A permission rejection raises PERMISSION_DENIED; any other failure raises a generic BACKEND_ERROR.

Example

Called with serial="emulator-5554". A typical response:

{
  "status": "success",
  "message": "Awake on emulator-5554.",
  "data": {
    "serial": "emulator-5554",
    "wakefulness": "Awake",
    "interactive": true
  },
  "error": null
}

reboot_device

Reboot a device into its normal system image: adb -s serial reboot.

Categorized destructive (denied by default) because it interrupts everything running on the device and takes it offline for the length of a boot. adb returns the instant the request is delivered — well before the device is back — so a successful result means only that the request was accepted. The device will disappear from adb immediately; chain wait_for_device_state(serial, state="device") to block until it's back online before continuing automation. Rebooting into bootloader/recovery isn't implemented here.

Parameters:

Name	Type	Description	Default
serial	str	The target device's adb serial (see list_connected_devices).	required

Returns:

Type	Description
RebootResult	The serial, mode ("system"), accepted (always true when this returns without error — adb took the request), and adb's raw output (normally empty).

Error handling

An unknown serial raises DEVICE_NOT_FOUND; an unresponsive adb binary raises ADB_UNAVAILABLE. Any other non-zero exit raises BACKEND_ERROR. The device going offline right after this call is expected and is not reported as an error.

Example

Called with serial="emulator-5554". A typical response:

{
  "status": "success",
  "message": "Reboot request accepted for emulator-5554; it will drop off adb until it finishes booting.",
  "data": {
    "serial": "emulator-5554",
    "mode": "system",
    "accepted": true,
    "output": ""
  },
  "error": null
}

wake_device

Wake a sleeping device's screen: adb shell input keyevent WAKEUP.

Injects the WAKEUP power key so a device whose display has gone to sleep becomes interactive again — handy right before a screenshot or a sequence of UI taps. This does not unlock a locked keyguard; it only turns the screen back on. WAKEUP is idempotent: running it against an already-awake device is a harmless no-op, so this tool never fails just because the device was already awake. Putting the device back to sleep isn't implemented here.

Parameters:

Name	Type	Description	Default
serial	str	The target device's adb serial (see list_connected_devices).	required

Returns:

Type	Description
WakeResult	The serial, the keycode that was sent ("WAKEUP"), and accepted (always true when this returns without error — input produces no output, so success is read from its exit code). Chain get_power_state to confirm wakefulness afterwards if you need an independent check.

Error handling

An unknown serial raises DEVICE_NOT_FOUND; an unresponsive adb binary raises ADB_UNAVAILABLE. A rejection of the key injection raises PERMISSION_DENIED; any other non-zero exit raises BACKEND_ERROR.

Example

Called with serial="emulator-5554". A typical response:

{
  "status": "success",
  "message": "Sent WAKEUP to emulator-5554; the screen should be awake.",
  "data": {
    "serial": "emulator-5554",
    "keycode": "WAKEUP",
    "accepted": true
  },
  "error": null
}