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

Test Android apps for cars

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 phone to it via adb forwarding.

To report bugs or feature requests related to the DHU, please use this issue tracker.

Install the DHU

The latest available version of the DHU is 2.0 rc1. This version includes features that are not available in the previous version (1.1) and is the recommended version to install and use. If you are experiencing issues with version 2.0 rc1, you can install version 1.1 instead.

Install DHU version 2.0 rc1

Follow these steps to install DHU 2.0 rc1 on your development machine:

  1. Enable developer mode on a mobile device running Android 6.0 (API level 23) or higher, as described in Enabling on-device developer options.
  2. Compile and install your app on the device.
  3. Install Android Auto on the device. If Android Auto is already installed, make sure that you are using the latest version.
  4. Open Android Studio and switch Android Studio to use the Beta channel. If you are prompted to update to a newer version of Android Studio, you can ignore the update.
  5. Open the SDK Manager and navigate to the SDK tools tab, then download version 2.0 rc1 of the Android Auto Desktop Head Unit Emulator package.

    The SDK Manager showing DHU 2.0 rc1.

    The DHU is installed in the SDK_LOCATION/extras/google/auto/ directory. After the download has finished, you can switch Android Studio back to the Stable channel if you don't want to use the Beta channel version of other tools.

  6. On Linux or macOS systems, run the following command to ensure the DHU binary is executable:

    chmod +x ./desktop-head-unit
    
Additional steps for Linux only

If you are running version 2.0 rc1 on a Linux system, you need to install some additional libraries. The DHU binary depends on GLIBC version 2.27 or above. You can check the GLIBC version of your system by running this command:

ldd --version

If the version is lower than 2.27, you must either update GLIBC to 2.27 or above, or upgrade the OS to a version that is compatible with GLIBC 2.27 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 DHU version 1.1

If you are encountering issues with version 2.0 rc1, follow these steps to install DHU 1.1 on your development machine:

  1. Enable developer mode on a mobile device running Android 6.0 (API level 23) or higher, as described in Enabling on-device developer options.
  2. Compile and install your app on the device.
  3. Install Android Auto on the device. If Android Auto is already installed, make sure that you are using the latest version.
  4. Open Android Studio and check that Android Studio is using the Stable channel.
  5. Open the SDK Manager and navigate to the SDK tools tab, then download version 1.1 of the Android Auto Desktop Head Unit Emulator package.

    The DHU is installed in the SDK_LOCATION/extras/google/auto/ directory. After the download has finished, you can switch Android Studio back to another update channel if you don't want to use the Stable channel version of other tools.

  6. On Linux or macOS systems, run the following command to ensure the DHU binary is executable:

    chmod +x ./desktop-head-unit
    
Additional steps for Linux only

If you are running version 1.1 on a Linux system, you need to install some additional libraries. Install the portaudio, libpng, sdl2, and sdl2_ttf 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 libsdl2-2.0-0 libsdl2-ttf-2.0-0 libportaudio2 libpng12-0

Run the DHU

After you install the DHU, you can test your Android Auto apps by connecting your phone and workstation via USB. Run the DHU by connecting your mobile device to a development machine and setting up a connection to the head unit server over Android Debug Bridge (ADB).

Follow these steps to set up tunneling and run the DHU:

  1. In the Android Auto app, tap the Menu, then tap Settings.
  2. Scroll to the About section near the bottom and tap Version to display all of the version and permission information.
  3. Tap the Version and permission info section 10 times.

    The Allow development settings dialog appears.

  4. 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.

  5. 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).

    Context menu with developer options

    Figure 1. Context menu with developer options.

    Notification that the head unit server is running

    Figure 2. Notification that the head unit server is running.

  6. 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.

  7. Connect the mobile device to the development machine via USB.

  8. Make sure the mobile device has its screen unlocked; otherwise it cannot launch the DHU.

  9. 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
    
  10. Start the DHU by running the command desktop-head-unit.exe (on Windows) or ./desktop-head-unit (on macOS or Linux) from the SDK_LOCATION/extras/google/auto/ directory.

    cd SDK_LOCATION/extras/google/auto
    desktop-head-unit.exe # Windows
    ./desktop-head-unit # macOS or Linux
    

    DHU is launched on the development machine

  11. 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.

The full set of command line options that the DHU supports vary depending on whether you are using version 2.0 rc1 or 1.1.

Version 2.0 rc1
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.
v, --version Show version information.
l, --licenses Show open source licenses.
h, --headless Run in headless mode (no UI).
?, --help Show this help listing.
Version 1.1
Option Description
i, --input=INPUT Use specified input mode, one of: touch or rotary.
-a, --adb=HOSTPORT Use ADB transport (optional host:port or port). Defaults to port 5277.
v, --version Show version information.
l, --licenses Show open source licenses.
h, --headless Run in headless mode (no UI).

DHU User Guide (2.0 rc1)

This section describes the features supported by version 2.0 rc1 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.

Day/Night Mode

The DHU supports simulating changing between day and night mode via 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.

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 configuration file, or by the navcluster or phonecluster entries to control each feature separately.

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 configuration file.

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
endcall
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

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:

  1. 480p (800x480 -- default)
  2. 720p (1280x720)
  3. 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.
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.

DHU User Guide (1.1)

DHU commands allow you to test your app with Android Auto features, such as playing voice input or switching between night and day display mode. You can issue commands to the DHU from the terminal window where you launched the DHU. You can also issue commands by selecting the DHU window and using keyboard shortcuts. The DHU commands and key bindings for all controls are listed in DHU commands and key bindings.

Switch between day and night mode

Android Auto supports different color schemes for day and night. You should test your app in both day and night mode. You can switch between night and day mode in either of the following ways:

  • Run the command daynight in the terminal where you launched the DHU.
  • Select the DHU window and press the N key.

Microphone testing

The DHU supports using a microphone for voice input. You can also instruct the DHU to treat a prerecorded voice track as input, as if the DHU had heard the track through the microphone.

To use a prerecorded sound file as input, enter this command:

mic play <sound_file_path>/<sound_file>.wav

For your convenience, we have provided the following sound files for common voice commands. These sound files are installed in the <sdk>/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?
DHU commands and key bindings

The DHU supports the following commands.

Table 1. Commands and key bindings

Category Command Subcommand Argument(s) Keyboard Shortcut(s) Description
System help [command] Shows the full command set. Specifying a command name (for example, help day) causes the system to show help for that command.
quit Alt+q Quits the head unit.
sleep [seconds] Sleeps for one second. Specifying an argument (for example, sleep 30) causes the system to sleep the specified number of seconds. This command is useful if you are writing scripts for the DHU. (You can run a script by using I/O redirection from the command line: ./desktop-head-unit < script.txt loads commands from the file script.txt.)
screenshot filename.png Saves a screenshot to filename.png.
Microphone mic begin m Activates the microphone (equivalent to pressing the microphone button on the steering wheel) and waits for input from the computer microphone.
play filename.wav Causes the DHU to treat filename.wav as voice input, as if that sound were relayed through the microphone. You do not hear the sound file being played, but you do hear the response from Android Auto.
repeat Repeats the last mic play command, as if you had called mic play again with the same sound file parameter.
Input dpad up
down
left
right
Arrow keys Simulates moving the rotary controller.
soft left
soft right
Shift+Arrow keys Simulates pressing the side buttons available on some rotary controllers.
click Return Simulates pressing the rotary controller.
back Backspace Simulates pressing the back button available below some rotary controllers.
rotate left
rotate right
1
2
Simulates rotating the rotary controller left (counter-clockwise) or right (clockwise).
flick left
flick right
Shift+1
Shift+2
Simulates a fast spin of the rotary controller to the left (counter-clockwise) or right (clockwise).
tap x y Simulates a touch event at the specified coordinates. For example, tap 50 100
Day/Night day Shift+N Activates day mode (high brightness, full color).
night Control+N Activates night mode (low brightness, high contrast).
daynight n Toggles current day/night mode.

Test your app for Android Automotive OS

You can use the Android Emulator to test how your driver-optimized app runs on an Android Automotive OS vehicle display. This section describes how to set up an Android Virtual Device (AVD) to test your app.

Edit your run configurations

Automotive OS apps are different than other Android apps. Android Automotive OS interacts with your 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:

  1. In Android Studio, select Run > Edit Configurations.

    The Run/Debug Configurations dialog box.

  2. Select your automotive module from the list of modules in your app.

  3. Under Launch Options > Launch, select Nothing.

  4. 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 only add a manufacturer-specific system image for the Polestar 2. Follow these steps to add a system image for the Polestar 2:

  1. In Android Studio, select Tools > SDK Manager.
  2. Click the SDK Update Sites tab.
  3. Click Add Add icon.
  4. Enter the following Name and URL, then click OK:

    Name: Polestar 2 System Image

    URL: https://developer.polestar.com/sdk/polestar2-sys-img.xml

  5. 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:

  1. In Android Studio, select Tools > SDK Manager.
  2. Click the SDK Platforms tab.
  3. Click Show Package Details.
  4. Under Android 9.0 (Pie), select Automotive Intel x86 Atom System Image.
  5. Click Apply, then click OK.

    List of SDK Platform compontents with generic system image
        selected.

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:

  1. In Android Studio, select Tools > AVD Manager.
  2. Click Create Virtual Device.
  3. From the Select Hardware dialog, select Automotive, and then select a device and click Next.
  4. Select a system image that targets Automotive, such as Android 9.0 (Automotive), and click Next.
  5. Name your AVD and select any other options that you want to customize and then click Finish.
  6. From tool window bar, select your Android Automotive OS AVD as your deployment target.
  7. Click Run Run icon.

Test your app for phone screens

Follow the steps below to sideload your app onto a phone and test.

Step 1. In the Android Auto app, enable Developer mode and unknown sources

  1. Install the Android Auto app, available on Google Play, on your phone. If Android Auto is already installed, make sure that you are using the latest version.
  2. In the Android Auto app, tap the Hamburger menu, then tap Settings.
  3. Scroll to the About section near the bottom and tap Version to display all of the version and permission information.
  4. Tap the Version and permission info section 10 times.

    The Allow development settings dialog appears.

  5. Tap OK.
  6. Tap the three dots in the top right of the screen to open the overflow menu, then tap Developer Settings.
  7. Tap Application Mode and select Developer.

    The app returns to the list of developer settings.

  8. Scroll down until you see Unknown sources and tap the checkbox.
  9. Restart Android Auto.

Step 2. On your phone, enable USB debugging

  1. In Settings > About phone, tap Build number seven times to enable the Developer Options.
  2. Go back to Settings > Developer Options, enable USB debugging.

Step 3. Install your app onto the phone and test

  1. Connect the phone to your machine through USB, so you can install apps directly to it as you develop. Use the adb devices command to ensure that your development computer can detect your device when connected via USB.
  2. Once your device is set up and connected via USB, navigate to your SDK's platform-tools/ directory and install the .apk on the device by running the following command:

    adb -d install path/to/your/app.apk
    

    You can now test your app and verify that everything works.

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 MediaBrowseService 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 any Activity is opened.
  • The MediaBrowserService is run when no Activity can be shown.
  • The MediaBrowserService is run when the user is not signed in.

While testing for these sceanrios, 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.