Garage Mode

To provide periods of idle time in vehicles, Garage Mode keeps the system awake so that jobs in JobScheduler constrained with idleness can be executed.

What is Garage Mode?

On connected devices such as phones, users rely on the system to ensure devices are stable, up-to-date, and optimized. To achieve that state, the Android platform provides an idle time window during which apps can perform tasks when the user doesn't interact with the device. A phone is considered to be idle when the user doesn't touch it for an extended duration (60 minutes or more) and the screen is turned off. Unlike a phone, when a car isn't being used, it's turned off, which means the car has no idle time window. Garage Mode ensures idle time in a car.

When a car is turned off by the user, the system enters Garage Mode. While a car is in Garage Mode, the system is powered on, the display is turned off, and idle jobs in the JobScheduler queue are executed. To implement Garage Mode, see Device implementation guidelines.

Device implementation guidelines

To activate Garage Mode, when turning off the vehicle, the Vehicle HAL (VHAL) must send AP_POWER_STATE_REQ with the state SHUTDOWN_PREPARE with the parameter set to SHUTDOWN_ONLY or CAN_SLEEP.

For the state SHUTDOWN_PREPARE to be effective, the VHAL must specify the two parameters (state and the additional parameter) for the AP_POWER_STATE_REQ command. This enables the device to enter Garage Mode, which detects scheduled jobs in JobScheduler and prevents the system from proceeding to either suspend or shut down until the jobs are completed.

How do device implementations connect to the Android framework?

For Garage Mode, the framework requests the VHAL to extend the shutdown time until either the required duration is exceeded or all jobs have been executed, at which time the system shuts down. Under specific circumstances defined in the CDD, device implementations can shut down the system sooner. For details on Android compatibility requirements, see the Android Compatibility Definition Document (CDD).

If the VHAL must shut down the system before Garage Mode completes, the VHAL can issue SHUTDOWN_PREPARE with the parameter set to SHUTDOWN_IMMEDIATELY or SLEEP_IMMEDIATELY. Device implementations can use this under specific circumstances only, typically when the resources needed to keep the system running are unavailable. For example, when battery capacity is insufficient.

Garage mode

Figure 1. Garage Mode flow

How do app developers work with Garage Mode?

Apps and services don't interact directly with Garage Mode. Instead, apps schedule jobs in JobScheduler. Those jobs constrained by idleness are executed during Garage Mode.

The following code shows how to schedule a job to run during Garage Mode:

public class MyGarageModeJob extends JobService { ... }

Context context = ...;
int jobId = ...;

ComponentName myGarageModeJobName = new componentName(context,
                                                      MyGarageModeJob.class);

JobInfo.Builder infoBuilder = new JobInfo.Builder(jobId, myGarageModeJobName)
                    .setRequiresDeviceIdle(true);

// Example of an optional constraint:
infoBuilder.setRequiredNetworkType(NetworkType.NETWORK_TYPE_UNMETERED);

JobScheduler jobScheduler = (JobScheduler) context
                    .getSystemService(Context.JOB_SCHEDULER_SERVICE);

jobScheduler.schedule(infoBuilder.build());

Debug Garage Mode

To debug Garage Mode:

To enable logging categories relevant to Garage Mode:

adb shell stop
adb shell setprop log.tag.GarageMode VERBOSE
adb shell setprop log.tag.Finsky VERBOSE
adb shell setprop log.tag.CAR.POWER VERBOSE
adb shell setprop log.tag.JobScheduler.Connectivity VERBOSE
adb shell start

To review the logcat output to indicate that Garage Mode is starting:

GarageMode: [Controller]: CPM state changed to SHUTDOWN_PREPARE
GarageMode: [GarageMode]: Entering GarageMode
GarageMode: [Controller]: Sending broadcast with action: com.android.server.jobscheduler.GARAGE_MODE_ON

To determine that logcat output to indicate Garage Mode is finished (canceled or completed):
```
[GarageMode]: GarageMode was canceled
```
or
```
[GarageMode]: GarageMode completed normally
```
Garage Mode depends on the power state of the vehicle as described above.

Review the logcat output to indicate the correct power states are entered:

CAR.POWER: starting shutdown prepare without Garage Mode
GarageMode: [Controller]: CPM state changed to SHUTDOWN_PREPARE
GarageMode: [GarageMode]: Entering GarageMode
CAR.POWER: send shutdown prepare
CAR.POWER: setPowerState=SHUTDOWN_PREPARE(7) param=0