1# Doze
2
3`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.
4
5Always-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.
6
7![ss-aod](./imgs/aod.png)
8
9The 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].
10
11Note: 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.
12[DozeMachine][3] handles the following main states:
13* AOD - persistently showing UI when the device is in a low-powered state
14* Pulsing - waking up the screen to show notifications (from AOD and screen off)
15* Docked UI - UI to show when the device is docked
16* Wake-up gestures - including lift to wake and tap to wake (from AOD and screen off)
17
18## Doze States ([see DozeMachine.State][3])
19### DOZE
20Device is asleep and listening for enabled pulsing and wake-up gesture triggers. In this state, no UI shows.
21
22### DOZE_SUSPEND_TRIGGERS
23Device 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.
24
25### DOZE_AOD
26Device 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.
27
28### DOZE_AOD_PAUSED
29Device 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]).
30
31### DOZE_PULSING
32Device 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].
33
34### DOZE_AOD_DOCKED
35Device 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.
36
37[DozeDockHandler][11] listens for Dock state changes from [DockManager][10] and updates the doze docking state.
38
39## Wake-up gestures
40Doze sensors are registered in [DozeTriggers][8] via [DozeSensors][12]. Sensors can be configured per posture for foldable devices.
41
42Relevant sensors include:
43* Proximity sensor
44* Brightness sensor
45* Wake-up gestures
46  * tap to wake
47  * double tap to wake
48  * lift to wake
49  * significant motion
50
51And are configured in the [AmbientDisplayConfiguration][13] with some related configurations specified in [DozeParameters][14].
52
53## Doze Suppressors
54When 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:
55* in CAR_MODE
56* not provisioned
57* in power saver mode
58* being suppressed by an app (see [PowerManager#suppressAmbientDisplay][16])
59
60Refer to the documentation in [DozeSuppressors][15] for more information.
61
62## AOD burn-in and image retention
63Because 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.
64
65To 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.
66
67For 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].
68
69## Debugging Tips
70Enable DozeLog to print directly to logcat:
71```
72adb shell settings put global systemui/buffer/DozeLog v
73```
74
75Enable all DozeService logs to print directly to logcat:
76```
77adb shell setprop log.tag.DozeService DEBUG
78```
79
80Other helpful dumpsys commands (`adb shell dumpsys <service>`):
81* activity service com.android.systemui/.doze.DozeService
82* activity service com.android.systemui/.SystemUIService
83* display
84* power
85* dreams
86* sensorservice
87
88[1]: /frameworks/base/core/res/res/values/config.xml
89[2]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeService.java
90[3]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeMachine.java
91[4]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/dagger/DozeModule.java
92[5]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeScreenBrightness.java
93[6]: /frameworks/base/packages/SystemUI/res/values/config.xml
94[7]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozePauser.java
95[8]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeTriggers.java
96[9]: /frameworks/base/packages/SystemUI/src/com/android/systemui/dock/DockManagerImpl.java
97[10]: /frameworks/base/packages/SystemUI/src/com/android/systemui/dock/DockManager.java
98[11]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeDockHandler.java
99[12]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeSensors.java
100[13]: /frameworks/base/core/java/android/hardware/display/AmbientDisplayConfiguration.java
101[14]: /frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/DozeParameters.java
102[15]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeSuppressor.java
103[16]: /frameworks/base/core/java/android/os/PowerManager.java
104[17]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeUi.java
105[18]: /frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/DozeServiceHost.java
106[19]: /frameworks/base/packages/SystemUI/plugin/src/com/android/systemui/plugins/statusbar/StatusBarStateController.java
107[20]: /frameworks/base/packages/SystemUI/docs/clock-plugins.md
108