108 lines
7.3 KiB
Markdown
108 lines
7.3 KiB
Markdown
# Doze
|
|
|
|
`Dozing` is a low-powered state of the device. If Always-on Display (AOD), pulsing, or wake-gestures are enabled, then the device will enter the `dozing` state after a user intent to turn off the screen (ie: power button) or the screen times out.
|
|
|
|
Always-on Display (AOD) provides an alternative 'screen-off' experience. Instead, of completely turning the display off, it provides a distraction-free, glanceable experience for the phone in a low-powered mode. In this low-powered mode, the display will have a lower refresh rate and the UI should frequently shift its displayed contents in order to prevent burn-in. The recommended max on-pixel-ratio (OPR) is 5% to reduce battery consumption.
|
|
|
|
|
|
|
|
The default doze component controls AOD and is specified by `config_dozeComponent` in the [framework config][1]. SystemUI provides a default Doze Component: [DozeService][2]. [DozeService][2] builds a [DozeMachine][3] with dependencies specified in [DozeModule][4] and configurations in [AmbientDisplayConfiguration][13] and [DozeParameters][14].
|
|
|
|
Note: The default UI used in AOD shares views with the Lock Screen and does not create its own new views. Once dozing begins, [DozeUI][17] informs SystemUI's [DozeServiceHost][18] that dozing has begun - which sends this signal to relevant SystemUI Lock Screen views to animate accordingly. Within SystemUI, [StatusBarStateController][19] #isDozing and #getDozeAmount can be used to query dozing state.
|
|
[DozeMachine][3] handles the following main states:
|
|
* AOD - persistently showing UI when the device is in a low-powered state
|
|
* Pulsing - waking up the screen to show notifications (from AOD and screen off)
|
|
* Docked UI - UI to show when the device is docked
|
|
* Wake-up gestures - including lift to wake and tap to wake (from AOD and screen off)
|
|
|
|
## Doze States ([see DozeMachine.State][3])
|
|
### DOZE
|
|
Device is asleep and listening for enabled pulsing and wake-up gesture triggers. In this state, no UI shows.
|
|
|
|
### DOZE_SUSPEND_TRIGGERS
|
|
Device is asleep and not listening for any triggers to wake up. This state is used only when CAR_MODE is active. In this state, no UI shows.
|
|
|
|
### DOZE_AOD
|
|
Device is asleep, showing UI, and listening for enabled pulsing and wake-up triggers. In this state, screen brightness is handled by [DozeScreenBrightness][5] which uses the brightness sensor specified by `doze_brightness_sensor_type` in the [SystemUI config][6]. To save power, this should be a low-powered sensor that shouldn't trigger as often as the light sensor used for on-screen adaptive brightness.
|
|
|
|
### DOZE_AOD_PAUSED
|
|
Device is asleep and would normally be in state `DOZE_AOD`; however, instead the display is temporarily off since the proximity sensor reported near for a minimum abount of time. [DozePauser][7] handles transitioning from `DOZE_AOD_PAUSING` after the minimum timeout after the NEAR is reported by the proximity sensor from [DozeTriggers][8]).
|
|
|
|
### DOZE_PULSING
|
|
Device is awake and showing UI. This is state typically occurs in response to incoming notification, but may also be from other pulse triggers specified in [DozeTriggers][8].
|
|
|
|
### DOZE_AOD_DOCKED
|
|
Device is awake, showing docking UI and listening for enabled pulsing and wake-up triggers. The default DockManager is provided by an empty interface at [DockManagerImpl][9]. SystemUI should override the DockManager for the DozeService to handle docking events.
|
|
|
|
[DozeDockHandler][11] listens for Dock state changes from [DockManager][10] and updates the doze docking state.
|
|
|
|
## Wake-up gestures
|
|
Doze sensors are registered in [DozeTriggers][8] via [DozeSensors][12]. Sensors can be configured per posture for foldable devices.
|
|
|
|
Relevant sensors include:
|
|
* Proximity sensor
|
|
* Brightness sensor
|
|
* Wake-up gestures
|
|
* tap to wake
|
|
* double tap to wake
|
|
* lift to wake
|
|
* significant motion
|
|
|
|
And are configured in the [AmbientDisplayConfiguration][13] with some related configurations specified in [DozeParameters][14].
|
|
|
|
## Doze Suppressors
|
|
When Dozing is enabled, it can still be suppressed based on the device state. On a high-level, doze and/or AOD may be suppressed if the device is:
|
|
* in CAR_MODE
|
|
* not provisioned
|
|
* in power saver mode
|
|
* being suppressed by an app (see [PowerManager#suppressAmbientDisplay][16])
|
|
|
|
Refer to the documentation in [DozeSuppressors][15] for more information.
|
|
|
|
## AOD burn-in and image retention
|
|
Because AOD will show an image on the screen for an elongated period of time, AOD designs must take into consideration burn-in (leaving a permanent mark on the screen). Temporary burn-in is called image-retention.
|
|
|
|
To prevent burn-in, it is recommended to often shift UI on the screen. [DozeUi][17] schedules a call to dozeTimeTick every minute to request a shift in UI for all elements on AOD. The amount of shift can be determined by undergoing simulated AOD testing since this may vary depending on the display.
|
|
|
|
For manual local testing, set [DozeUI][17]#BURN_IN_TESTING_ENABLED to true, and then manual time broadcasts (ie: `adb shell 'date 022202222022.00 ; am broadcast -a android.intent.action.TIME_SET'`) will update the burn-in translations of the views. For a general idea where burn-in may be an issue, run the [software burn-in script][20].
|
|
|
|
## Debugging Tips
|
|
Enable DozeLog to print directly to logcat:
|
|
```
|
|
adb shell settings put global systemui/buffer/DozeLog v
|
|
```
|
|
|
|
Enable all DozeService logs to print directly to logcat:
|
|
```
|
|
adb shell setprop log.tag.DozeService DEBUG
|
|
```
|
|
|
|
Other helpful dumpsys commands (`adb shell dumpsys <service>`):
|
|
* activity service com.android.systemui/.doze.DozeService
|
|
* activity service com.android.systemui/.SystemUIService
|
|
* display
|
|
* power
|
|
* dreams
|
|
* sensorservice
|
|
|
|
[1]: /frameworks/base/core/res/res/values/config.xml
|
|
[2]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeService.java
|
|
[3]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeMachine.java
|
|
[4]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/dagger/DozeModule.java
|
|
[5]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeScreenBrightness.java
|
|
[6]: /frameworks/base/packages/SystemUI/res/values/config.xml
|
|
[7]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozePauser.java
|
|
[8]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeTriggers.java
|
|
[9]: /frameworks/base/packages/SystemUI/src/com/android/systemui/dock/DockManagerImpl.java
|
|
[10]: /frameworks/base/packages/SystemUI/src/com/android/systemui/dock/DockManager.java
|
|
[11]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeDockHandler.java
|
|
[12]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeSensors.java
|
|
[13]: /frameworks/base/core/java/android/hardware/display/AmbientDisplayConfiguration.java
|
|
[14]: /frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/DozeParameters.java
|
|
[15]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeSuppressor.java
|
|
[16]: /frameworks/base/core/java/android/os/PowerManager.java
|
|
[17]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeUi.java
|
|
[18]: /frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/DozeServiceHost.java
|
|
[19]: /frameworks/base/packages/SystemUI/plugin/src/com/android/systemui/plugins/statusbar/StatusBarStateController.java
|
|
[20]: /frameworks/base/packages/SystemUI/docs/clock-plugins.md
|