Google is committed to advancing racial equity for Black communities. See how.

TV Standby

In Android 11, inattentive sleep is a power-saving feature that allows a user inactivity timeout to be set after which the device goes to sleep, even if wakelocks are held. Shortly before the timeout expires, a message can be shown that warns the user that the device will go to sleep if they don't interact with the device.

In this context, user activity refers to anything that triggers a call to PowerManager#userActivity (without the USER_ACTIVITY_FLAG_NO_CHANGE_LIGHTS flag), including but not limited to:

  • Interacting with the touchscreen
  • Pressing a physical button
  • Input events from an external accessory (for example, connected keyboard, bluetooth remote, IR remote)
  • Voice interaction
  • Receiving certain HDMI CEC messages, such as One Touch Play
  • Starting a new cast session

Customization

If the feature is enabled, the device shows an onscreen warning after a specified time of user inactivity. If no action is taken, the device goes to sleep. You can customize the feature using these configuration options.

Configuring the timeout

To configure the timeout, update the following element in frameworks/base/core/res/res/values/config.xml:

  • config_attentiveTimeout
    • Specifies the default time in milliseconds of user inactivity after which device goes to sleep (even if wakelocks are in place).
    • Set at build time.
    • If the value is between 0 and config_minimumScreenOffTimeout, the timeout is set to config_minimumScreenOffTimeout to prevent the device from going to sleep shortly after waking up.
    • Default: -1, which disables this feature.

Overriding the default timeout

To override the default timeout setting, update the following element.

  • Settings.Secure.ATTENTIVE_TIMEOUT
    • If set, overrides the default inattentive sleep timeout set by config_attentiveTimeout.
    • Can be set at runtime.

Configuring the duration before warning appears

To configure the duration, update the following element in frameworks/base/core/res/res/values/config.xml:

  • config_attentiveWarningDuration
    • How long to show a warning message to the user before the device goes to sleep after prolonged user inactivity.
    • The value should be well below the set inattentive sleep timeout, otherwise the warning dialog shows constantly and can't be dismissed.
    • Default: 30000 (30s).

Showing the timeout preferences in TvSettings

To show the timeout preferences, update the following element in packages/apps/TvSettings/Settings/res/values/config.xml:

  • config_show_standby_timeout
    • Whether to show a preference item for allowing turning the screen off during media playback.
    • Default: false.

Resources for the warning UI

  • The layout of the warning dialog is defined in frameworks/base/packages/SystemUI/res/layout/inattentive_sleep_warning.xml.
  • The following strings for the dialog are defined in frameworks/base/packages/SystemUI/res/values/strings.xml and frameworks/base/packages/SystemUI/res-product/values/strings.xml.
    • inattentive_sleep_warning_title
    • inattentive_sleep_warning_message

The build time configurations and resources can be changed by resource overlays.

Implementation

Enable the feature using the following.

  1. Override the default config_attentiveTimeout.
  2. If using the AOSP TvSettings:
    • Disable the feature in settings by overriding config_show_standby_timeout.
    • Implement your own settings that set Settings.Secure.ATTENTIVE_TIMEOUT.

Validation

The CTS tests for the feature are at cts/hostsidetests/os/src/android/os/cts/InattentiveSleepTests.java.

Examples and source

  • frameworks/base/packages/SystemUI/src/com/android/systemui/power/InattentiveSleepWarningView.java contains the default warning UI implementation.
  • packages/apps/TvSettings provides an example of how to expose the feature in settings.

Manual test case example

  1. Make sure the stay_on_while_plugged_in developer setting is off if the device's health HAL reports that the device has a battery (battery_present is true) as this might prevent the feature from putting the device to sleep.
    adb shell settings put global stay_on_while_plugged_in 0

  2. Set an inattentive sleep timeout to be a few seconds more than the warning dialog duration.
    adb shell settings put secure attentive_timeout 32000
  3. Start playing back a video (to acquire a wakelock).
  4. Verify that the sleep warning dialog appears after a few seconds.
  5. Verify that the device goes to sleep after the set timeout expires.