Testing your car app ensures that users don't encounter unexpected results or a poor experience. How you test your app depends on whether your app will be running on Android Auto or Android Automotive OS.
See one of the following sections to get started:
Test your app for Android Auto
The Desktop Head Unit (DHU) enables your development machine to emulate an Android Auto head unit, so that you can run and test Android Auto apps. The DHU runs on Windows, macOS, and Linux systems.
This section teaches you how to install and run the DHU on your development machine to test your apps. After you've installed the DHU, you can test your Android Auto apps by connecting your mobile device to it via one of the supported connection mechanisms described in Run the DHU.
To report bugs or request features related to the DHU, use this issue tracker.
Install the DHU
Follow these steps to install the DHU on your development machine:
- Enable developer mode on a mobile device running Android 6.0 (API level 23) or higher, as described in Configure on-device developer options.
- Compile and install your app on the device.
- Install Android Auto on the device. If Android Auto is already installed, make sure that you are using the latest version.
Open the SDK Manager and navigate to the SDK Tools tab, then download the Android Auto Desktop Head Unit Emulator package.
The DHU is installed in the
SDK_LOCATION/extras/google/auto/
directory.On Linux or macOS systems, run the following command in that directory to ensure the DHU binary is executable:
chmod +x ./desktop-head-unit
Additional steps for Linux only
If you are running version 2.0 on a Linux system, you need to install some
additional libraries. The DHU binary depends on GLIBC
version 2.32 or above.
You can check the GLIBC
version of your system by running this command:
ldd --version
If the version is lower than 2.32, you must either update GLIBC
to 2.32 or
above, or upgrade the OS to a version that is compatible with GLIBC
2.32 or
above.
You must also install the libc++1
and libc++abi1
libraries. The installation
procedure varies depending on your Linux distribution. For example, on
Debian-derived Linux distributions, you can install the libraries with this
command:
sudo apt-get install libc++1 libc++abi1
Install pre-release versions of the DHU {#:dhu-pre-release}
To get access to pre-release versions of the DHU, you can either use a preview version of Android Studio or change the update channel of your existing Android Studio installation to the beta channel.
Run the DHU
After you install the DHU, you can test your Android Auto apps by connecting your mobile device and workstation over USB. Run the DHU by connecting your mobile device to a development machine using either the Accessory Mode (recommended for DHU 2.0), or ADB Tunneling.
Connecting using Accessory Mode (DHU 2.0 only)
Android Auto supports connecting to the DHU with the Android Open Accessory (AOA) protocol, using the following command:
./desktop-head-unit --usb
By default, the DHU scans through the list of available USB devices and attempts
to connect to the first compatible one. To target a specific device, include the
device ID as part of the --usb
command, as follows:
./desktop-head-unit --usb=[DEVICE_ID]
Connecting using ADB Tunneling
This method requires setting up a connection to the Android Auto head unit server over Android Debug Bridge (ADB). Follow these steps to set up tunneling and run the DHU:
Do one of the following to open the Android Auto settings, depending on the version of Android running on the device:
- Android 10 or higher: On the device tap Settings > Apps & notifications > See all apps > Android Auto > Advanced > Additional settings in the app.
- Android 9 or lower: In the Android Auto app, tap the Menu, then tap Settings.
Scroll to the About section near the bottom and tap Version to display all of the version and permission information.
Tap the Version and permission info section 10 times.
The Allow development settings dialog appears.
Tap OK.
Developer mode is now enabled and you can access developer options in the overflow menu. You only need to enable developer mode the first time you run the Android Auto app.
If the head unit server is not already running, tap the three dots in the top right of the screen to open the overflow menu and select Start head unit server (see figure 1).
On the device, a foreground service appears in the notification area that indicates that the server is running (see figure 2).
Figure 1. Context menu with developer options.
Figure 2. Notification that the head unit server is running.
In the Android Auto app, tap Previously connected cars near the top of the Settings, and ensure Add new cars to Android Auto is enabled.
Connect the mobile device to the development machine via USB.
Make sure the mobile device has its screen unlocked; otherwise it cannot launch the DHU.
On the development machine, run the following
adb
command to forward socket connections from the development machine's port 5277 to the same port number on the Android device. This configuration enables the DHU to connect to the head unit server running on your phone over a TCP socket.adb forward tcp:5277 tcp:5277
Start the DHU by running the command
desktop-head-unit.exe
(on Windows) or./desktop-head-unit
(on macOS or Linux) from theSDK_LOCATION/extras/google/auto/
directory.cd SDK_LOCATION/extras/google/auto
desktop-head-unit.exe # Windows
./desktop-head-unit # macOS or Linux
If this is the first time you are connecting the mobile device to the DHU, check the mobile device's screen to accept the terms of service and adjust permission settings as needed.
After the DHU has started, you can use DHU console commands to run and test your app.
Command line options
By default, the head unit server connects over port 5277. To override the host
or port (for example, to forward over SSH), use the --adb=<[localhost:]port>
flag, as in the following example:
./desktop-head-unit --adb=5999
By default, the DHU emulates a Android Auto-compatible head unit with a touch
screen user interface. You can simulate user touches by clicking the DHU with
a mouse. To emulate head units that use a rotary controller for input, you can
use the -i controller
flag, as in this example:
./desktop-head-unit -i controller
When the DHU is in rotary-controller mode, you can use keyboard shortcuts to simulate controller operations. See the Rotary Controller for more details. In rotary controller mode, the DHU ignores mouse clicks; you must operate Android Auto with the simulated rotary-controller operations.
Option | Description |
---|---|
-c , --config=FILE |
Use the specified configuration .ini file. Refer to the
Configure the DHU section for more
details. |
-i , --input=INPUT |
Use specified input mode, one of: touch ,
rotary , or hybrid . |
-a , --adb=HOSTPORT |
Use ADB transport (optional host:port
or port ). Defaults to port 5277. |
-a , --usb=DEVICE_ID |
Use USB (AOA) transport (optional DEVICE_ID ). |
-v , --version |
Show version information. |
-l , --licenses |
Show open source licenses. |
-h , --headless |
Run in headless mode (no UI). |
-t , --always_show_window_on_top |
Show DHU windows on top of other windows (off by default) |
-? , --help |
Show this help listing. |
DHU User Guide
This section describes the features supported by version 2.0 of the DHU and how to use them.
Commands are entered in the terminal window where you started DHU. Multiple
commands can be run on the same line by separating them with a ;
.
System
Command | Key | Description |
---|---|---|
help [command] |
Shows full command set. If a command name is specified (for example,
help day ), shows help for that command. |
|
quit exit |
Alt+Q | Quits the head unit. |
sleep [seconds] |
Sleeps for one second. If a delay is specified, sleeps that many
seconds . This can be used for scripting the head unit
(./desktop-head-unit < script.txt ), for example in a CI
environment. |
|
screenshot filename.png
|
Saves a screenshot to filename.png.
|
|
licenses |
Display licenses of libraries used in DHU | |
keycode keycode
|
Send keycode, one of the names listed in the Keycodes section. |
Touch and Touchpad
When touch or touchpad is enabled, clicking in either the display window (for touch) or touchpad window (for touchpad) will be registered as touch events.
For touch, you can simulate multi-touch by right clicking on the first finger location, then click-and-hold the right button for the second finger. The centerpoint of the two fingers remains fixed and moving the mouse will allow you to either rotate them around the center or pinch in-and-out (or both).
For touchpad, click-and-hold the left button to scroll between different UI elements on the screen. Clicking the right button will select the element that currently has focus.
Command | Key | Description |
---|---|---|
tap x y
|
Simulate a touch event at the specified coordinates |
Rotary Controller
The DHU has rotary controller support. When it is enabled, the following actions are supported:
- Up, down, left, and right on the Dpad
- Rotating clockwise and counterclockwise
- Performing a rotation flick (5 steps at once)
- Clicking down on the controller and back on the controller
The commands and key bindings are listed below.
A scroll wheel on a mouse will send dpad rotate
commands, and the middle
mouse button click (usually the scroll wheel) will send dpad click
commands.
Note that most cars have touch screens. Some cars have rotary controller-only, and some have a hybrid touch and controller. Cars can also support a touchpad which can be used for map panning and text entry. Bear these different configurations in mind when simulating different vehicle head units.
Command | Key | Description |
---|---|---|
dpad {up|down|left|right} |
Arrow keys | Movement of the rotary controller. |
dpad {ur|dl|ul|dr} |
Movement of the rotary controller. | |
dpad soft {left|right} |
Shift + Arrow keys | Side buttons available on some rotary controllers. |
dpad click |
Return | Pressing the rotary controller. |
dpad back |
Backspace | Back button available below some rotary controllers. |
dpad rotate left |
1 | Rotary controller left (counter-clockwise) movement. |
dpad rotate right |
2 | Rotary controller right (clockwise) movement. |
dpad flick left |
Shift+1 | Fast counter-clockwise spin of the rotary controller. |
dpad flick right |
Shift+2 | Fast clockwise spin of the rotary controller. |
dpad 0-9*#+ |
Num pad |
Microphone
The DHU supports using a microphone for voice input or playing a pre-recorded
voice track. For your convenience, we have provided the following sound files
for common voice commands. These sound files are installed in the
SDK_LOCATION/extras/google/auto/voice/
directory.
File name | Text |
---|---|
navhome.wav |
Navigate to home. |
navwork.wav |
Navigate to work. |
navsoh.wav |
Navigate to Sydney Opera House. |
navgoogle.wav |
Navigate to 1600 Amphitheatre Parkway, California, USA. |
exitnav.wav |
Exit navigation. |
howlong.wav |
How long until I get there? |
showtraffic.wav |
Show traffic. |
showalternateroute.wav |
Show alternate routes. |
pause.wav |
Pause music |
nextturn.wav |
When is my next turn? |
To run an individual .wav
file in the DHU prompt:
mic play /path/to/filename.wav
Command | Key | Description |
---|---|---|
mic begin |
M | Activates the microphone (equivalent to clicking the steering-wheel button) and waits for input from the computer microphone. |
mic play filename.wav
|
Activates the microphone and plays the specified WAV file recording. Note: You will not hear the WAV file being played, but you will hear the response from Android Auto. | |
mic repeat |
Repeats the last recording used with mic play . |
|
mic reject {on|off} |
Enables or disables rejection of microphone requests. When on, all microphone requests will be rejected. |
Sensors
The DHU supports simulating changes in the vehicle's sensor data with the
following commands. To mock sensor data and send them to Android Auto, the
corresponding sensors have to be enabled with the configuration
.ini
file when starting the DHU.
Command | Description |
---|---|
fuel [percentage] |
Set the fuel level to the specified percent, or do not pass in a value to disable fuel level. |
range [km] |
Set the range to the specified kilometers, or do not pass in a value to disable range data. |
lowfuel [{on|off}] |
Set the low fuel warning sensor, or do not pass in a value to disable the sensor. |
accel [x] [y] [z] |
Set the accelerometer to the specified x, y, and z values (m/s^2), or do not pass in parameters to unset the accelerometer data. Pass in NAN to skip optional parameters if needed. |
compass bearing [pitch] [roll] |
Set the compass to the specified bearing, pitch, and roll values (degrees). Pass in NAN to skip optional parameters if needed. |
gyro [x] [y] [z] |
Set the gyroscope to the specified x, y, and z rotation speed (rad/s), or do not pass in parameters to unset the gyroscope data. Pass in NAN to skip optional parameters if needed. |
location lat long [accuracy] [altitude] [speed] [bearing] |
Set the location to the specified lat and long values along with the optional accuracy (m), altitude (m), speed (m/s), and bearing (degrees). Pass in NAN to skip optional parameters if needed. |
odometer km [current_trip_km] |
Set the odometer to the specified kilometers along with an optional current trip km value. |
speed [speed] |
Set the vehicle speed to the specified value (m/s), or do not pass in a value to disable the sensor. |
tollcard {insert|remove} |
Indicates whether a toll card was inserted or removed. |
Day/Night Mode
The DHU supports simulating changing between day and night mode with the following commands and key bindings.
Command | Key | Description |
---|---|---|
day |
Shift+N | Activate day mode (high-brightness, full color). |
night |
Ctrl+N | Activate night mode (low-brightness, high-contrast). |
daynight nightday |
N | Toggle current day or night mode. |
Focus Management
The DHU supports simulating whether or not Android Auto has focus on the head unit with the following commands.
Command | Description |
---|---|
focus video {on|off|toggle} |
Enables or disables whether Android Auto has video focus on the head unit. Turning off video focus simulates the head unit going into native mode. |
focus audio {on|off|toggle} |
Enables or disables whether Android Auto has audio focus on the head unit. Turning off audio focus simulates the head unit playing its own audio source. |
focus nav {on|off|toggle} |
Enables or disables whether Android Auto has navigation focus on the head unit. Turning off navigation focus simulates the head unit running its own navigation system. |
Restrictions/Driving Status
The DHU supports simulating certain restrictions when the vehicle is moving, such as disabling the keyboard and disallowing phone configurations.
Command | Key | Description |
---|---|---|
restrict none |
U | Disables all restrictions. |
restrict all |
Shift+U | Enables all restrictions (for example, to simulate driving). |
Instrument Cluster
The DHU supports emulating an instrument cluster (usually located behind the steering wheel) which shows basic info during navigation about the next turn (such as the next road name, distance/time, or a turn arrow) and information about an ongoing phone call.
This can be enabled using the instrumentcluster
entry in the [general]
section of the configuration file, or by the navcluster
or phonecluster
entries to control each feature separately.
[general]
...
instrumentcluster = true
Cluster Display
Some vehicles have cluster displays capable of displaying rich visual information such as map tiles. Starting with version 2.1 of the DHU (currently available via the Android Studio Beta update channel ), you can emulate such a display on your development machine.
This can be done using a configuration file with a cluster [display]
section.
[display]
sections support the same
video configuration options as the main display
configured in the [general]
section of the file.


...
# The display name following the colon can be whatever you like.
[display:cluster]
# Setting the displaytype as cluster is what lets the DHU know how to handle it.
displaytype = cluster
resolution = 800x480
dpi = 160
...
This configuration can either be added directly to an existing .ini
file or
you can reuse it by putting it in a separate file and passing multiple
configuration files when launching the DHU. When using multiple configuration
files, later definitions of a given value override earlier ones.
# Launch your landscape configuration with your cluster display configuration
./desktop-head-unit -c landscape.ini -c cluster.ini
# Launch the portait configuration with the same cluster display configuration
./desktop-head-unit -c portrait.ini -c cluster.ini
Media Playback Status
The DHU supports an additional information display to show media playback status, for example, what track is playing.
This can be enabled using the playbackstatus
entry in the [general]
section.
[general]
...
playbackstatus = true
Keycodes
The DHU provides a set of default keycodes that simulates the set of shortcut
buttons that are commonly available in different vehicles. For example, the
home
keycode can be triggered in the DHU prompt as follows:
keycode home
Keycode | Description |
---|---|
home |
Go to the home screen. |
back |
Go back. |
call |
Make or end a call. |
search |
Trigger search. |
media_play_pause media_play media_pause |
Play or pause a media. |
media_next media_previous |
Go to the next or previous media track. |
media |
Go to the default media app. |
navigation |
Go to the default navigation app. |
tel |
Go to the default telephone app. |
Configure the DHU
The DHU supports a configuration .ini
file to change the input modes available
(touch, controller), the frame rate, resolution and DPI the head unit requests
from the phone.
The default location for the configuration file is ~/.android/headunit.ini
. If
you wish to change the configuration of the head unit on your system, you can
modify this file.
You can also specify a configuration file to load using the -c
flag.
./desktop-head-unit -c /path/to/config.ini
Sample configuration
[general]
touch = true
touchpad = false
controller = false
instrumentcluster = false
resolution = 800x480
dpi = 160
framerate = 30
fueltypes = unleaded,electric,hydrogen
evconnectors = supercharger
Sample configuration files can be found under the
SDK_LOCATION/extras/google/auto/config/
folder to
demonstrate different head unit settings you can test against. For more advanced
use cases, please refer to the supported settings below.
Input Configuration
Name | Default | Type | Description |
---|---|---|---|
inputmode |
default |
String | Defines the input mode. The options touch , rotary , hybrid enable and disable touchscreen and rotary support and set default keycodes as appropriate, while default defers to the touch and controller options below. |
controller |
false |
Boolean | Enable rotary controller input. Ignored unless inputmode is default . |
touch |
true |
Boolean | Enables touchscreen. Ignored unless inputmode is default . |
touchpad |
false |
Boolean | Enables touchpad. |
touchpadnavigation |
false |
Boolean | Enables touchpad to be used for UI navigation. |
touchpadtapasselect |
false |
Boolean | When true, a tap on the touchpad is a select event. |
touchpaduiabsolute |
false |
Boolean | When touchpadnavigation is true , this sets
whether the touches should be treated as absolute or as gestures. |
Video Configuration
Android Auto supports three video resolutions:
- 480p (800x480 -- default)
- 720p (1280x720)
- 1080p (1920x1080)
To support different aspect ratios other than the ones above, the head unit is able to specify a margin to letterbox/pillarbox as necessary. For example, if you wanted a 1000x600 screen, you would set the resolution to 720p (1280x720) and a marginwidth of 280 and marginheight of 120. This has the effect of adding a 140px margin on both the left and right edges, and 60px top and bottom.
Example configuration to emulate a typical 6 inch screen (750x450):
[general]
...
resolution = 800x480
marginwidth = 50
marginheight = 30
And a very-wide screen:
[general]
...
resolution = 1280x720
marginwidth = 0
marginheight = 220
Name | Default | Type | Description |
---|---|---|---|
resolution |
800x480 |
Strings | One of: 800x480 , 1280x720 ,
1920x1080 . |
dpi |
160 |
Integer | |
normalizedpi |
false |
Boolean | When true , reduces DHU window size to account for larger
DPI values. When false , larger DPI values result in larger
windows (which does not mimic real displays, but does allow easier
inspecting of visual content). |
realdpi |
160 |
Integer | Used in video configuration. |
framerate |
30 |
Integer | Used in video Configuration. |
marginheight |
0 |
Integer | Used in video configuration. |
marginwidth |
0 |
Integer | Used in video configuration. |
margins |
0,0,0,0 |
String | Used in video configuration, overrides marginwidth and
marginheight if present. Format is top, bottom, left,
right. |
contentinsets |
0,0,0,0 |
String | Used in video configuration. Format is top, bottom, left, right. |
stablecontentinsets |
0,0,0,0 |
String | Used in video configuration. Defaults to the value of
contentinsets . Format is top, bottom, left, right. |
cropmargins |
false |
Boolean | If margins , marginheight , or
marginwidth is specified, a true value for this
setting removes those margins from the displayed video. This reflects more
closely what the end user sees. |
pixelaspectratio |
1.0 |
Float | Used in video configuration. |
Sensors Configuration
To mock sensor data and send them to Android Auto, the corresponding sensors have to be enabled using the options below. If a sensor is disabled, any data sent for that sensor using the DHU commands is ignored.
Name | Default | Type | Description |
---|---|---|---|
accelerometer |
false |
Boolean | Enable accelerometer sensor data. |
compass |
false |
Boolean | Enable compass sensor data. |
driving_status |
false |
Boolean | Enable driving status sensor data. |
fuel |
false |
Boolean | Enable fuel sensor data. |
gyroscope |
false |
Boolean | Enable gyroscope sensor data. |
location |
false |
Boolean | Enable vehicle location sensor data. |
night_mode |
false |
Boolean | Enable night mode sensor data. |
odometer |
false |
Boolean | Enable odometer sensor data. |
speed |
false |
Boolean | Enable speed sensor data. |
toll_card |
false |
Boolean | Enable toll card sensor data. |
Miscellaneous
Name | Default | Type | Description |
---|---|---|---|
instrumentcluster |
false |
Boolean | Enable instrument cluster. Adds a window to the UI to display navigation and phone status. |
navcluster |
false |
Boolean | Enable instrument cluster. Adds a window to the UI to display navigation status. |
phonecluster |
false |
Boolean | Enable instrument cluster. Adds a window to the UI to display phone status. |
playbackstatus |
false |
Boolean | Enable playback status. Adds a window to the UI to display playback status messages. |
driverposition |
left |
String | One of: left , center , or
right . |
windowleft |
|
Integer | Set the left position of the main window. |
windowtop |
|
Integer | Set the top position of the main window. |
fueltypes |
unleaded |
Strings | One or more of (separated by ,):
|
evconnectors |
|
Strings | Zero or more of (separated by ,):
fueltypes contains electric .
|
Troubleshooting
DHU showing a blank screen when first connected
This is a known issue we are working on. You can work around this by doing the following:
- Close the DHU.
- Follow Step 5 described in Run the DHU to stop and restart the Head Unit Server.
- Start the DHU again.
- There may be additional permission granting steps on the phone screen. Complete those steps and the DHU might shut down once more.
- Restart the DHU.
Test your app for Android Automotive OS
You can use the Android Emulator to test how your apps run on Android Automotive OS. This section describes how to set up an Android Virtual Device (AVD) to test your app.
Edit your run configurations for media apps
Media apps on Automotive OS apps are different than other Android apps. Android Automotive OS interacts with your media app using explicit intents and by sending calls to your media browser service.
In order to test your app, verify that your app has no launch activity in its manifest, and then prevent your automotive module from launching with an activity by following these steps:
In Android Studio, select Run > Edit Configurations.
Select your automotive module from the list of modules in your app.
Under Launch Options > Launch, select Nothing.
Click Apply, and then click OK.
Add system images
Before you can create AVDs that match specific manufacturer hardware, you need to add system images for these devices through the Android Studio SDK Manager. Then, when you're creating an AVD, you can download these system images to use with the AVD.
Add system images from car manufacturers
Currently, you can add OEM-specific system image for the Polestar 2 & Volvo. Follow these steps to add a system image:
- In Android Studio, select Tools > SDK Manager.
- Click the SDK Update Sites tab.
- Click Add
.
Enter the following Name and URL, then click OK:
Name: Polestar 2 System Image
URL:
https://developer.polestar.com/sdk/polestar2-sys-img.xml
Name: Volvo System Image
URL:
https://developer.volvocars.com/sdk/volvo-sys-img.xml
Click Apply, then click OK.
Install generic system images
Android Studio also includes a generic system image for Android Automotive OS that you can also use to test your app. This generic system image includes the Google Assistant so that you can test your app's integration.
Follow these steps to install the generic system image:
- In Android Studio, select Tools > SDK Manager.
- Click the SDK Platforms tab.
- Click Show Package Details.
- Under Android 9.0 (Pie), select Automotive Intel x86 Atom System Image.
Click Apply, then click OK.
Create a car AVD and run the emulator
Follow these steps to create an Android Virtual Device (AVD) that represents an Android Automotive OS vehicle and then use that AVD to run the emulator:
- In Android Studio, select Tools > AVD Manager.
- Click Create Virtual Device.
- From the Select Hardware dialog, select Automotive, and then select a device and click Next.
- Select a system image that targets Automotive, such as Android 9.0 (Automotive), and click Next.
- Name your AVD and select any other options that you want to customize and then click Finish.
- From tool window bar, select your Android Automotive OS AVD as your deployment target.
- Click Run
.
Additional testing requirements for media apps
If you are testing a media app, then you should also test for the scenarios that are covered in this section (in addition to testing your app on Android Auto, Android Automotive OS, or both).
Test MediaBrowserService startup scenarios
To help keep drivers and passengers safe, users have additional restrictions on
how they can interact with apps while driving. For this reason, Android Auto and
Android Automotive OS have some MediaBrowserService
startup scenarios that your app must be able to handle so that users can
continue to enjoy your content while they're on the road.
Test your app to make sure it can handle each of the following scenarios:
- The
MediaBrowserService
is run before anyActivity
is opened. - The
MediaBrowserService
is run when noActivity
can be shown. - The
MediaBrowserService
is run when the user is not signed in.
While testing for these scenarios, be sure to try the following methods:
- Force stop the media app, then launch Android Auto or Android Automotive OS.
- Clear the media app data, then launch Android Auto or Android Automotive OS.
Also make sure to set an appropriate error message when necessary.
Media testing tools
The Media Controller Test app allows you to test the intricacies of media playback on Android and helps verify your media session implementation. To get started with this tool, see Using the media controller test app.