Automatic time detection

Automatic time detection receives time suggestions from various sources, selects the best option, and then sets the system clock in Android to match. Previous Android releases provided two ways to set date and time, either manually set per user or by automatic time detection, and set by one of these options:

  • telephony uses Network Identity and Time Zone (NITZ) telephony signals.
  • network uses Network Time Protocol (NTP) time servers.

Each option requires connections to external networks, which aren't always available in Android Automotive. For example, in some countries, some cars might not have built-in telephony. Therefore, Global Satellite Navigation Systems (GNSS) time is provided as a source of system time for you to use when network connectivity is unavailable.

This upcoming Android release provides two more options to automatically detect and set time:

  • gnss uses Global Satellite Navigation Systems (GNSS).
  • external uses a VHAL property or the System API.

Enable automatic time detection

To enable automatic time detection, be sure to select Settings > Date & Time > Automatic Date & Time:

Figure 1. Select Automatic Date & Time

Configure time sources

To specify which time sources to include in automatic time detection, and the priority in which these time sources should be considered, you must modify the device's resource configuration file, core/res/res/values/config.xml:

<!-- Specifies priority of automatic time sources. Suggestions from higher entries in the list
     take precedence over lower ones. See com.android.server.timedetector.TimeDetectorStrategy for
     available sources. -->
<string-array name="config_autoTimeSourcesPriority">
    <item>telephony</item>
    <item>network</item>
</string-array>

In this example, telephony and network are considered in automatic time detection and telephony time suggestions are priortized ahead of network time suggestions.

Generally speaking, suggestions from a higher priority source are ignored if the suggestion is either invalid or if the suggestion is too old. Also, if the highest priority valid suggestion matches the device's current system clock time to within several seconds (the default value is two (2) seconds), the time won't be changed.

Lower time bound

Android 12 provides a new lower time bound to use when validating time suggestions. Before this feature, automatic time detection wouldn't validate the suggested incoming UTC time. With this feature, times that elapse before the lower bound are discarded.

The lower bound value is determined from a date derived from the build timestamp. This works on the principle that a valid time cannot occur before the system image was built. Android does not enforce an upper bound.

GNSS time suggestions

The gnss time source is new to Android 12 and is provided by GPS signals. This is a reliable source for time when telephony and network aren't available. This option is added to the new GnssTimeUpdateService in SystemServer that passively listens to location updates. When a valid location is received, GnssTimeUpdateService makes a suggestion to TimeDetectorService, which then determines if the system clock should be updated.

By default, the gnss time source is not enabled in AOSP and, therefore, must be enabled by partners:

<!-- Specifies priority of automatic time sources. Suggestions from higher entries in the list
    take precedence over lower ones.
    See com.android.server.timedetector.TimeDetectorStrategy for available sources. -->
<string-array name="config_autoTimeSourcesPriority">
    <item>telephony</item>
    <item>network</item>
    <item>gnss</item>
</string-array>

<!-- Enables the GnssTimeUpdate service. This is the global switch for enabling Gnss time based
    suggestions to TimeDetector service. See also config_autoTimeSourcesPriority. -->
<bool name="config_enableGnssTimeUpdateService">true</bool>

To enable this feature:

  1. Update config_enableGnssTimeUpdateService. The value for config_enableGnssTimeUpdateService must be set to true.
  2. Update config_autoTimeSourcesPriority. gnss must be added to the item list for config_autoTimeSourcesPriority. The position of gnss in the priority list determines the priority given to GNSS suggestions, with respect to values from other sources.

Impact on power

GnssTimeUpdateService listens passively to location updates, which means that it never actively turns on the GPS to consume additional power. As a result, the power consumed when the GNSS source is enabled is negligible. This also means that unless another app or service in the system actively requests location updates, GnssTimeUpdateService doesn't get a location update and suggest a GNSS time.

Testing

Compatibility test suite (CTS)

A CTS test is provided to verify that a GNSS-provided time is available. For details, see LocationShellCommand.java.

Unit tests

See the basic unit tests in the following file:

atest frameworks/base/services/tests/servicestests/src/com/android/server/timedetector/GnssTimeUpdateServiceTest.java

Manual tests

To test this feature, new commands have been added to LocationShellCommand.java. Use these commands to add test providers with which you can specify a location and the associated GNSS time. GnssTimeUpdateService listens to these location updates, and periodically makes suggestions.

Note: The interface for these commands may change between releases. 

# Enable Master Location Switch in the foreground user (usually user 10 on automotive).
# If you just flashed, this can be done through Setup Wizard.
adb shell cmd location set-location-enabled true --user 10

# Add GPS test provider (this usually fails the first time and will throw a SecurityException
# with "android from <some-uid> not allowed to perform MOCK_LOCATION".)
adb shell cmd location providers add-test-provider gps

# Enable mock location permissions for previous UID
adb shell appops set <uid printed in previous error> android:mock_location allow

# Add GPS test provider (Should work with no errors.)
adb shell cmd location providers add-test-provider gps

# Enable GPS test provider
adb shell cmd location providers set-test-provider-enabled gps true

# Set location with time (time can't be earlier than the limit set by the lower bound.)
adb shell cmd location providers set-test-provider-location gps --location <LATITUDE>,<LONGITUDE> --time <TIME>

External time suggestions

External time suggestions are another way to provide automatic time suggestions to Android. This new options enables you to provide entirely customized time suggestions to Android, which can originate from various ECUs that, in turn, can use a combination of a real-time clock, GNSS, NITZ, or any other time source.

The following suggestions are available in Android 12 to consider as external time suggestions:

  • VHAL properties. A new VHAL property named EPOCH_TIME is provided. This property denotes the number of milliseconds that have elapsed since 1/1/1970 UTC. Its value can be passed to the Android TimeManager to suggest a new system time. A sample VHAL implementation that updates this property is provided in the reference implementation below.
  • System APIs. A new method called suggestExternalTime() is available in TimeManager to provide the system with an external time suggestion. If the system is configured to take external time suggestions into account (using config_autoTimeSourcesPriorityin the configuration file), the timestamp passed to this method is used to set the system time, if there are no higher priority time suggestions available.

You can implement an external time solution as described below:

  1. Update the resource configuration file (core/res/res/values/config.xml) and then add the value external to config_autoTimeSourcesPriority: 
    <string-array name="config_autoTimeSourcesPriority>
        <item>external</item>
        <item>gnss</item>
</string-array>

    Doing so instructs Android to give external time suggestions the highest priority when setting the system clock. Hardware on the vehicle writes a timestamp suggestion to the new EPOCH_TIME VHAL property.

  2. A vendor-provided app reads this property and calls TimeManager.suggestExternal(). Android can then use the provided timestamp as the new system clock value.