device

Stability: 2 - Stable

The device module provides information and operations related to the device, such as getting the device width and height, memory usage, IMEI, adjusting the device brightness, volume, etc. Some functions in this module, such as adjusting the volume, require "modify system settings" permission.

Some of the functions in this module, such as adjusting the volume, require the "Modify system settings" permission. If you don't have this permission, it will throw SecurityException and jump to the permission setting screen.

device.width

• {number}

The width of the device screen resolution. For example, 1080.

device.height

• {number}

The height of the device screen resolution. For example, 1920.

device.buildId

• {string}

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

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

device.broad

• {string}

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

The device's motherboard(?) The model number of the device.

device.brand

• {string}

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

The brand of the manufacturer with which the product/hardware will be associated, if any.

device.device

• {string}

The name of the industrial design.

The name of the device in the industrial design.

device.model

• {string}

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

Device model.

device.product

• {string}

The name of the overall product.

The name of the overall product.

device.bootloader

• {string}

The system bootloader version number.

The bootloader version of the device.

device.hardware

• {string}

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

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

device.fingerprint

• {string}

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

A string that uniquely identifies 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 version. For example, the sdkInt for Android 4.4 is 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}

E.g., "1.0" or "3.4b5".

Android system version number. For example, "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.

The user-visible security patch level.

device.codename

• {string}

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

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

device.getIMEI()

• {string}

Returns the IMEI of the device.

device.getAndroidId()

• {string}

Returns the Android ID of the device.

The Android ID is a 64-bit integer represented as a hexadecimal string, which is randomly generated when the device is first used and will not be changed afterwards unless factory settings are restored.

device.getMacAddress()

• {string}

Returns the Mac address of the device. This function needs to be available with WLAN connection to get it, otherwise it will return null.

Possible subsequent modifications: In the future, it may be added to get by root privileges if you have root access, so that the correct Mac address can be returned even without a WLAN connection, so please do not use this function to determine the WLAN connection.

device.getBrightness()

• {number}

Return the current (manual) brightness. The range is 0~255.

device.getBrightnessMode()

• {number}

Return the current brightness mode, 0 is manual brightness, 1 is auto brightness.

device.setBrightness(b)

• b {number} Brightness, range 0~255

Set the current manual brightness. If the current brightness mode is auto, this function will not affect the brightness of the screen.

This function requires the "modify system settings" permission. If you don't have this permission, it will throw a SecurityException and jump to the permission setting screen.

device.setBrightnessMode(mode)

• mode {number} Brightness mode, 0 is manual brightness, 1 is auto brightness

Set the current brightness mode.

This function requires "modify system settings" permission. If you don't have this permission, it will throw a SecurityException and jump to the permission setting screen.

device.getMusicVolume()

• {number} integer value

Return the current media volume.

device.getNotificationVolume()

• {number} The integer value

Return the current notification volume.

device.getAlarmVolume()

• {number} The integer value

Return the current alarm volume.

device.getMusicMaxVolume()

• {number} integer value

Return the maximum value of the media volume.

device.getNotificationMaxVolume()

• {number} integer value

Return the maximum value of the notification volume.

device.getAlarmMaxVolume()

• {number} integer value

Return the maximum value of the alarm volume.

device.setMusicVolume(volume)

• volume {number} volume

Set the current media volume.

This function requires the "modify system settings" permission. If you don't have this permission, it will throw a SecurityException and jump to the permission setting screen.

device.setNotificationVolume(volume)

• volume {number} volume

Set the current notification volume.

This function requires the "modify system settings" permission. If you don't have this permission, it will throw a SecurityException and jump to the permission setting screen.

device.setAlarmVolume(volume)

• volume {number} volume

Set the volume of current alarm.

This function requires the "modify system settings" permission. If you don't have this permission, it will throw a SecurityException and jump to the permission setting screen.

device.getBattery()

• {number} A floating point number from 0.0 to 100.0.

Return the current battery percentage.

device.isCharging()

• {boolean}

Returns if the device is charging.

device.getTotalMem()

• {number}

Returns the total amount of device memory in bytes (B). 1MB = 1024 * 1024B.

device.getAvailMem()

• {number}

Returns the current available memory of the device in bytes (B).

device.isScreenOn()

• Returns {boolean}

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

Note that the rest screen clock of Vivo xplay series does not belong to the case of "screen on", although the screen is indeed on, it only shows the clock and is not interactive, so isScreenOn() will also return false.

device.wakeUp()

Wake up the device. This includes waking up the device CPU, screen, etc. Can be used to light up the screen.

device.wakeUpIfNeeded()

Wake up the device if the screen is not lit.

device.keepScreenOn([timeout])

• timeout {number} The time, in milliseconds, that the screen stays on. If this parameter is not added, the screen will always be kept on.

Keep the screen always on.

This function does not prevent the user from using the lock button, etc. to turn off the screen normally, but only makes the device keep the screen always on when no one is operating it; also, if the screen is not lit when this function is called, it will wake up the screen.

On some devices, if the parameter timeout is not added, it can only keep the screen always on in the interface of CloudControl, and it will automatically fail in other interfaces, which is caused by the power saving strategy of the device. Therefore, it is recommended to use a longer timeout instead of keepScreenOn(3600 * 1000).

You can use device.cancelKeepingAwake() to cancel the screen on.

//Keep the screen on all the time
device.keepScreenOn()

device.keepScreenDim([timeout])

• timeout {number} The amount of time the screen stays on, in milliseconds. If this parameter is not added, the screen is kept always on.

Keep the screen always on, but allow it to dim to save power. This function can be used for timed script wakeup operations that do not require the user to look at the screen, and can allow the screen to dim to save power.

This function cannot prevent the user from using the lock button, etc. to turn off the screen normally, but can only make the device keep the screen always on when no one is operating it; also, if the screen is not lit when this function is called, it will wake up the screen.

You can use device.cancelKeepingAwake() to cancel the screen always on.

device.cancelKeepingAwake()

Cancel the device keeping awake state. Used to cancel the constant screen light set by device.keepScreenOn(), device.keepScreenDim() and other functions.

device.vibrate(ms)

• ms {number} The time to vibrate, in milliseconds

Make the device vibrate for a period of time.

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

device.cancelVibration()

Cancel vibration if the device is in vibration state.