Android Auto and the Desktop Head Unit¶
Android Auto projects a phone app’s car UI to a head unit. The Desktop Head Unit (DHU) is Google’s desktop stand-in for that head unit.
provisionDevicecan set up projection on a phone emulator and start a headless DHU for you.startDevicecan start the DHU again for a phone that is already set up.tapAtandpressButtoncan then act on the head unit.
To do the setup yourself, or for the DHU console, capture and configs, see Desktop Head Unit by hand.
For a full car Android build that AutoMobile drives directly, use an Android Automotive OS emulator instead.
Testing Car App Library templates without a head unit¶
To check which templates your app built, enable the AutoMobile SDK template route in a debug build and
read the carAppTemplates block from observe on a phone emulator. See
Car App Library templates in observe.
It reports what the app built, not what the head unit rendered. For template unit tests, use
androidx.car.app.testing (TestCarContext, ScreenController).
Setting up projection with provisionDevice¶
Pass androidAuto to provisionDevice for an Android phone AVD on a Google Play system image (such as
google_apis_playstore). After boot, AutoMobile installs Android Auto from your APKs, prepares it and
starts a headless DHU against the emulator. No Google account is needed.
{
"device": {
"platform": "android",
"name": "Pixel_9_Play_36",
"spec": {
"runtime": "system-images;android-36;google_apis_playstore;arm64-v8a",
"deviceType": "pixel_9"
}
},
"androidAuto": { "apkDirectory": "/path/to/android-auto-apks" }
}
| Parameter | Required | Description |
|---|---|---|
androidAuto.apkDirectory |
yes | Host directory with the Android Auto split APKs you supplied: base.apk plus its split_*.apk files for the emulator’s ABI, language and density. AutoMobile never downloads them. They are installed only while the phone still runs the stub. |
androidAuto.dhuPath |
no | The desktop-head-unit binary. Defaults to $ANDROID_HOME/extras/google/auto/desktop-head-unit. |
androidAuto.dhuConfig |
no | Head unit config (.ini). Defaults to config/default_720p.ini beside the DHU binary. |
androidAuto requires boot: true (the default). The emulator’s language must be English, because
Android Auto’s settings are driven by their visible labels.
Result¶
The response gains an androidAuto block:
steps: one entry per step, in order:android-auto-apk,keyguard,stay-awake,notification-access,developer-mode,unknown-sources,head-unit-server,transport,desktop-head-unitandonboarding. Each has astatusofappliedoralready-done, and sometimes adetail. Running it again on a phone that is already set up reportsalready-doneand reuses the running DHU.desktopHeadUnit.running: whether the DHU holds its connection.desktopHeadUnit.configPath: the head unit config the DHU started with.
When the phone shows Welcome to Android Auto, provisioning taps Continue, which accepts Android
Auto’s terms, and reports the onboarding step as applied. It never signs in to Google.
Errors¶
| Error | What to do |
|---|---|
unsupported: Android Auto projection is missing the APK directory, base.apk, the DHU or the config |
Nothing was created or booted. The message names every missing path. Install the DHU with sdkmanager "extras;google;auto", or pass dhuPath. |
adb still reports the emulator as not ready (offline) after 60 s, or when the provision deadline left no more time |
Error code device_offline; nothing on the phone changed. Wait until adb -s <serial> get-state prints device (run adb kill-server if it stays offline), then retry, with a larger timeoutMs if the deadline ended the wait. |
| The phone still runs the Android Auto stub and the APK signer check fails | Supply the APKs of an official Android Auto release. Android rejects an update signed by a different key. |
| A Desktop Head Unit is already projecting another emulator, or one is unhealthy but still running | One emulator per host can project, because the DHU dials host port 5277. Release that emulator’s session or call killDevice on it, which stops its DHU, or provision that emulator again, which restarts an unhealthy DHU. |
| The DHU did not exit after SIGTERM and SIGKILL | End the desktop-head-unit process yourself, then provision again. Until it exits, other emulators are refused. |
| Host port 5277 is held by a redirect or process AutoMobile did not create | Remove it (adb -s <serial> emu redir del tcp:5277) or stop the process, then retry. |
| The head unit server is not listening, or the DHU did not hold a connection | Check developer mode in Android Auto and start the head unit server from its overflow menu, then retry. |
A failure after boot fails the whole request. AutoMobile rolls back an emulator the request created
and stops a DHU that request started. A DHU an earlier provision started keeps running. killDevice
on an emulator also stops its DHU.
The session holding the phone can end (you release it, its heartbeat lapses, it idles out or is cancelled) or move to another device. AutoMobile then stops the DHU it started for that phone and removes its port 5277 redirect, so another emulator can project. A provision of that phone still running finishes first. The phone keeps running.
Starting the head unit with startDevice¶
For a phone emulator that provisionDevice already set up for Android Auto, pass androidAuto.headUnit
to startDevice. Once the phone is ready, AutoMobile checks the same setup steps, starts a headless DHU
against it and reports it. It never installs Android Auto here.
{
"platform": "android",
"avdName": "Pixel_9_Play_36",
"androidAuto": { "headUnit": {} }
}
| Parameter | Required | Description |
|---|---|---|
androidAuto.headUnit |
yes | Start the head unit. Pass {} for the SDK’s DHU and default_720p.ini. |
androidAuto.headUnit.dhuPath |
no | The desktop-head-unit binary. Defaults to $ANDROID_HOME/extras/google/auto/desktop-head-unit. |
androidAuto.headUnit.dhuConfig |
no | Head unit config (.ini). Defaults to config/default_720p.ini beside the DHU binary. |
The response gains the same androidAuto block as provisionDevice (steps and desktopHeadUnit). If
a DHU is already projecting this phone, it is reused and reported as already-done, with the config
it started with; to use another config, call killDevice first.
If the head unit does not start, startDevice fails with a message that names the phone and its
session. The phone stays ready and held by that session: fix the cause and call startDevice again,
or release the device. The errors are the ones in the provisionDevice table above, plus:
| Error | What to do |
|---|---|
| The phone still runs the Android Auto stub | Run provisionDevice with androidAuto.apkDirectory first. |
| The Android Auto head unit is missing a DHU | The message names the missing path. Install the DHU with sdkmanager "extras;google;auto", or pass androidAuto.headUnit.dhuPath. |
| Timed out starting the Android Auto head unit | Raise timeoutMs and call startDevice again. A DHU that connects after the timeout is stopped. |
killDevice on the phone, or the end of the session holding it, stops its DHU. The first
startDevice after killing a projected phone is a cold boot (about 60 seconds). AutoMobile only ever
stops a DHU it started itself.
Acting on the head unit¶
Pass display: "headUnit" to tapAt or pressButton to send input to the head unit instead of the
phone. It uses the DHU that provisionDevice or startDevice started for that phone; it never starts
or stops one.
{ "x": 640, "y": 200, "display": "headUnit" }
| Tool | Head unit input |
|---|---|
tapAt |
x and y in head-unit pixels (1280x720 with default_720p.ini), sent as tap <x> <y>. Only a plain tap: action, durationMs, coordinateSpace, image, pointer, layer and snapshotId are refused. |
pressButton |
up, down, left, right, select and back as dpad input; home, playPause, next and previous as keycode input; the rotary_* buttons as dpad rotate, nudge and click (steps repeats a rotation). Other buttons are refused. |
The result gains a headUnit block:
commands: the console commands sent.effect:screenChangedand itsbasis(see below).idle: whether two reads in a row agreed (stable), what they were (basis:carAppTemplates,screenshotornone) and how long the wait took (waitedMs). AutoMobile waits about a second on a screen that still looks the same, so it does not report a slow screen push as no change. The wait ends after about three seconds either way.beforeandafter: the top screen of each projected session, read before and after the input. Absent with the screenshot fallback.projection: when Android Auto bound or released an app or a template host during the action, itstemplateHostsand boundappsbefore and after.
AutoMobile reads effect from the first source available:
| Source | basis |
What it tells |
|---|---|---|
Projected apps’ template stacks (carAppTemplates.projected[]) |
carAppTemplates changed or carAppTemplates unchanged |
Each app’s top screen class, stack depth and top template content; a tab switch or changed item on the same screen counts. A list scroll counts only when the template reports different items |
| DHU screenshot, when no projected app has the template route | screenshot changed or screenshot unchanged |
Changed pixels from unchanged ones, but not which screen is shown |
Nothing (a --headless DHU without video focus returns at once) |
no template data; screenChanged is absent |
The input went out, but whether it changed the screen is unknown |
When the source above reports no change, or cannot tell, AutoMobile also compares the apps and
template hosts Android Auto has bound before and after the input. If they differ, screenChanged is
true with basis: "projectedApps changed": the head unit opened an app or app category it had not
bound, including an app without the template route. Unchanged bindings do not mean an unchanged
screen, because Android Auto keeps every connected app bound while another one is shown.
Before sending input, the action checks that the head unit is still the one the previous head-unit action left. That means the same DHU process, the same config, and the same projected apps and car sessions. If any of them changed, the action sends nothing and fails. The check counts only apps with the template route, so it misses a switch to an app without it.
dpad back pops the current screen on the head unit, so pressButton back needs no fallback.
Call tapOn with display: "headUnit" and a selector.text or selector.textAny. It searches the
top template of each projected app (carAppTemplates.projected[]). It reads row titles and their
secondary lines, tab titles and titled actions. It never sends input, because the template data does not say
where the head unit draws a row. It always fails, with one of these messages:
- The match and where it is: its row number and the row count, the template type and title, the
app’s screen and the app’s package. Tap it with
tapAtat its head-unit pixels, or move focus to it withpressButtondownandselect. - No match, with up to ten labels the top templates show.
- No projected app reported a template, because none enabled the AutoMobile template route. Use
tapAtorpressButton.
elementId, testTag and accessibilityLink selectors are refused.
Head unit day, night and driving restrictions¶
With a DHU running for the phone, setDeviceState with deviceCondition.vehicle sends the DHU’s
console commands instead of changing the phone (see
Simulating driving and night mode for the
call):
| Value | DHU command |
|---|---|
nightMode: "on" |
night |
nightMode: "off" |
day |
motion: "driving" |
restrict all |
motion: "parked" |
restrict none |
The DHU does not report these back, so the result’s detail names the command AutoMobile sent, not
what the head unit shows. Reset or unset sends day and restrict none, the state a DHU starts
in. If the DHU exited before the reset, AutoMobile sends nothing. Without a running DHU, AutoMobile
refuses a phone as unsupported.
| Error | What to do |
|---|---|
| No Desktop Head Unit is running for the device | Start one with startDevice and androidAuto.headUnit, or provisionDevice with androidAuto, then retry. |
| The Desktop Head Unit is not running | The DHU exited. Call startDevice with androidAuto.headUnit again. |
| A button or field has no head unit equivalent | Use one of the inputs in the table above. |
| Head unit input not sent | The DHU restarted, its config changed, or the projected apps changed. Observe again, then retry the input. |
Making your app appear in Android Auto¶
Android Auto on a phone lists a Car App Library app only when its manifest has
com.google.android.gms.car.application meta-data pointing at the app’s automotive_app_desc XML. The
com.android.automotive key alone is read only by Android Automotive OS. Declare both if the app targets
both. Apps installed with adb appear only while Unknown sources is on. Apps must target SDK 24 or
higher to install on current emulator images, which excludes the Media Browser Simulator shipped in
extras/google/simulators.
What to expect from AutoMobile¶
Android Auto renders the projected UI on virtual displays on the phone. observe lists them under
otherDisplays (for example TemplateCarFragment, Dashboard and GhFacetBar). It may report the
projection display as the active one, with a warning that it has no accessible content.
The projected UI is not in the accessibility tree; observe and other tools act only on the phone
screen. To act on the head unit, use tapAt or pressButton with display: "headUnit" (see
Acting on the head unit).
The first observe on a fresh emulator installs AutoMobile’s on-device service. If the DHU connects
through adb forward, a dropped adb connection at that point ends the projection; use the emulator
redirect.
Projected templates in observe¶
While projecting, the phone’s foreground app is Android Auto, not your app. If your app enabled the
AutoMobile template route, observe reads it from every app Android Auto has bound. It returns
carAppTemplates.projected[] and projectedBy naming Android Auto.
projected[] field |
Content |
|---|---|
packageName |
The bound app |
sessions |
What the app built, not what the head unit rendered |
error |
template_read_failed, with no sessions, when an app that answered before failed this time |
Android Auto does not report which bound app the head unit shows. With several apps bound, check each entry’s top screen rather than assuming the first is visible.
While the head unit hosts Car App Library templates, observe also returns an androidAuto block.
Without a projection, observe has no androidAuto block.
androidAuto field |
Content |
|---|---|
projecting |
true |
projectedBy |
Android Auto |
templateHosts |
Android Auto’s bound template host services |
apps[] |
Each bound app whose template route answered, with userId and services |
No app is marked visible, because an app stays bound while another app is on the head unit. Check
carAppTemplates.projected[] and the head unit itself. The block leaves out apps without the
template route, and has no head unit screenshot.
The head unit in listDevices¶
While AutoMobile runs a healthy DHU for a phone, listDevices reports it on the phone’s entry as
headUnit. It is not one of the phone’s displays.panels.
headUnit field |
Content |
|---|---|
display |
"headUnit", the value tapAt and pressButton take |
role |
projected |
projectedBy |
androidAuto |
console |
The DHU process; it changes when the DHU restarts |
configPath |
The head unit config |
sizePx |
Head-unit pixels from the config’s resolution; 800x480 when it sets none, absent when it cannot be read |