device - Device

老猫10/22/22About 5 min

Stability: 2 - Stable

The device module provides device-related information and controls, such as screen size, memory usage, IMEI, and adjusting brightness/volume.

Some functions (e.g. adjusting volume) require the “modify system settings” permission. Without it, a SecurityException will be thrown and the permission settings page will be opened.

device.width

{number}

Device screen width in pixels, e.g. 1080.

device.height

{number}

Device screen height in pixels, e.g. 1920.

device.buildId

{string}

Either a change list number, or a label like "M4-rc20".

Revision number or a label like "M4-rc20".

device.broad

{string}

The name of the underlying board, like "goldfish".

Underlying board model.

device.brand

{string}

The consumer-visible brand with which the product/hardware will be associated, if any.

Consumer-visible brand associated with the product/hardware, such as "Xiaomi", "Huawei", etc.

device.device

{string}

The name of the industrial design.

Industrial design name of the device.

device.model

{string}

The end-user-visible name for the end product.

Device model.

device.product

{string}

The name of the overall product.

Overall product name.

device.bootloader

{string}

The system bootloader version number.

Device bootloader version.

device.hardware

{string}

The name of the hardware (from the kernel command line or /proc).

Hardware name (from kernel command line or /proc).

device.fingerprint

{string}

A string that uniquely identifies this build. Do not attempt to parse this value.

Unique identifier string for this build.

device.serial

{string}

A hardware serial number, if available. Alphanumeric only, case-insensitive.

Hardware serial number.

device.sdkInt

{number}

The user-visible SDK version of the framework; its possible values are defined in Build.VERSION_CODES.

Android API level. For example, Android 4.4 has sdkInt 19.

device.incremental

{string}

The internal value used by the underlying source control to represent this build. E.g., a perforce change list number or a git hash.

device.release

{string}

The user-visible version string. E.g., "1.0" or "3.4b5".

Android release version string, such as "5.0", "7.1.1".

device.baseOS

{string}

The base OS build the product is based on.

device.securityPatch

{string}

The user-visible security patch level.

Security patch level.

device.codename

{string}

The current development codename, or the string "REL" if this is a release build.

Development codename, e.g. "REL" for release builds.

device.getAndroidId()

{string}

Returns the device Android ID.

Android ID is a 64-bit integer represented as a hex string. It is randomly generated on first use and does not change unless the device is factory-reset.

device.getMacAddress()

{string}

Returns the device MAC address. This requires an active WLAN connection; otherwise it returns null.

Possible future change: a root-based fallback may be added so it can return the correct MAC even without WLAN. Do not use this function to determine WLAN connectivity.

device.getBrightness()

{number}

Returns current (manual) brightness in the range 0~255.

device.getBrightnessMode()

{number}

Returns current brightness mode: 0 for manual, 1 for automatic.

device.setBrightness(b)

b {number} Brightness, 0~255

Set current manual brightness. If the device is in auto-brightness mode, this will not affect the screen brightness.

This requires the “modify system settings” permission. Without it, a SecurityException will be thrown and the permission settings page will be opened.

device.setBrightnessMode(mode)

mode {number} Brightness mode: 0 manual, 1 automatic

Set current brightness mode.

This requires the “modify system settings” permission. Without it, a SecurityException will be thrown and the permission settings page will be opened.

device.getMusicVolume()

{number} Integer value

Returns current media volume.

device.getNotificationVolume()

{number} Integer value

Returns current notification volume.

device.getAlarmVolume()

{number} Integer value

Returns current alarm volume.

device.getMusicMaxVolume()

{number} Integer value

Returns max media volume.

device.getNotificationMaxVolume()

{number} Integer value

Returns max notification volume.

device.getAlarmMaxVolume()

{number} Integer value

Returns max alarm volume.

device.setMusicVolume(volume)

volume {number} Volume

Set current media volume.

This requires the “modify system settings” permission. Without it, a SecurityException will be thrown and the permission settings page will be opened.

device.setNotificationVolume(volume)

volume {number} Volume

Set current notification volume.

This requires the “modify system settings” permission. Without it, a SecurityException will be thrown and the permission settings page will be opened.

device.setAlarmVolume(volume)

volume {number} Volume

Set current alarm volume.

This requires the “modify system settings” permission. Without it, a SecurityException will be thrown and the permission settings page will be opened.

device.getBattery()

{number} Float in range 0.0~100.0

Returns current battery level percentage.

device.isCharging()

{boolean}

Returns whether the device is charging.

device.getTotalMem()

{number}

Returns total device memory in bytes. 1MB = 1024 * 1024 bytes.

device.getAvailMem()

{number}

Returns currently available memory in bytes.

device.isScreenOn()

Returns {boolean}

Returns whether the screen is on. If on, returns true; otherwise false.

Note that some “always-on display” modes (e.g. certain vivo devices) are not considered “screen on”: although pixels are lit, it only shows a clock and is not interactive; isScreenOn() may still return false.

device.getScreenOrientation()

Returns {string}

Returns the current screen orientation string.

Common values include portrait and landscape.

log("Screen orientation: " + device.getScreenOrientation());

device.getScreenRotation()

Returns {number}

Returns current screen rotation in degrees.

Common values include 0, 90, 180, 270.

log("Screen rotation: " + device.getScreenRotation());

device.wakeUp()

Wake up the device, including CPU and screen. Can be used to turn on the screen.

device.wakeUpIfNeeded()

Wake up the device if the screen is not on.

device.keepScreenOn([timeout])

timeout {number} How long to keep the screen on (ms). If omitted, keep on indefinitely.

Keep the screen on.

This cannot prevent the user from turning off the screen normally (e.g. power button). It only keeps the screen on while the device is idle. If the screen is off when called, it will wake the screen.

On some devices, if timeout is omitted, keeping the screen on may only work within the Auto.js UI and fail elsewhere due to power-saving policies. It's recommended to pass a long timeout instead of “keep indefinitely”, e.g. device.keepScreenOn(3600 * 1000).

Use device.cancelKeepingAwake() to cancel keeping the screen on.

// Keep screen on indefinitely
device.keepScreenOn()

device.keepScreenDim([timeout])

timeout {number} How long to keep the screen awake (ms). If omitted, keep indefinitely.

Keep the screen awake but allow it to dim to save power. Useful for scheduled scripts that need the device awake but do not require the user to watch the screen.

This cannot prevent the user from turning off the screen normally. It only keeps the screen awake while idle. If the screen is off when called, it will wake the screen.

Use device.cancelKeepingAwake() to cancel keeping awake.

device.keepAwake([mode][, timeout])

mode {number} Wake mode (optional)
timeout {number} Wake duration in milliseconds (optional)

Keep the device awake. This is a lower-level API; usually prefer device.keepScreenOn() or device.keepScreenDim().

// Keep awake for 1 hour
device.keepAwake(0, 3600 * 1000);

device.cancelKeepingAwake()

Cancel keeping the device awake. Used to cancel device.keepScreenOn(), device.keepScreenDim(), etc.

device.vibrate(ms)

ms {number} Vibration duration in milliseconds

Make the device vibrate for a period of time.

// Vibrate for 2 seconds
device.vibrate(2000);

device.cancelVibration()

Cancel vibration if the device is currently vibrating.

Shortcut Properties (Mirrors of Methods)

In addition to methods, device also provides shortcut properties that can be read directly.
These properties usually mirror the semantics of the corresponding getXxx() / isXxx() methods, making it convenient to read status quickly in scripts.