Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

Test Android apps for cars

Testing your vehicle app ensures that users don't encounter unexpected results or have a poor experience. Your app can be accessed on a car's console as well as a user's phone screen, so you need to test your app on both.

This topic shows you how to test your app for each type of display that drivers can use to access your app. In addition, this topic provides instructions for testing other required functionality.

Test your app for Android Auto compatible car displays

The DHU enables your development machine to emulate an Android Auto head unit, so that you can easily run and test Android Auto apps. The DHU runs on Windows, macOS, and Linux hosts.

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 and workstation via USB.

Install the DHU

Follow these steps to install the DHU on your development machine:

  1. Enable developer mode on your mobile device, as described in Enabling on-device developer options.
  2. Compile your app in your development environment and install your app on a physical mobile device running Android 5.0 (API level 21) or higher. To check the version of Android on a Nexus device, go to Settings > About phone (or About tablet) > Android version.
  3. Install the Android Auto app on the mobile device. If Android Auto is already installed, make sure that you are using the latest version.
  4. Open the SDK Manager and download the DHU package Android Auto Desktop Head Unit emulator from the SDK Tools tab. The DHU is installed in the <sdk>/extras/google/auto/ directory.

If you are running the DHU on Linux, you must also 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
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.

After you install the DHU, you can test your Android Auto apps by connecting your phone and workstation via USB.

Run the DHU

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

    On the device, a foreground service appears in the notification area.

  6. In the Android Auto app, return the main screen by pressing the back button, then open Settings > Connected cars from the navigation drawer, 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 Mac or Linux) from the <sdk>/extras/google/auto/ directory.

    cd <sdk>/extras/google/auto
    ./desktop-head-unit
    

Once the DHU has started, you can use DHU commands and keybindings to run and test your app.

Android Auto is launched on the mobile device

Figure 3. Android Auto is launched on the mobile device.

DHU is launched on the development machine

Figure 4. DHU is launched on the development machine.

Command line flags

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 the most common form of the Android Auto-compatible head unit, which uses 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, as described in DHU commands and key bindings. In rotary controller mode, the DHU ignores mouse clicks; you must operate Android Auto with the simulated rotary-controller operations.

Issue DHU commands

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.

exitnav.wav
"Exit navigation."
navgoogle.wav
"Navigate to 1600 Amphitheatre Parkway, Mountain View."
navsoh.wav
"Navigate to Sydney Opera House."
nextturn.wav
"When is my next turn?"
showalternateroute.wav
"Show alternate routes."
howlong.wav
"How long until I get there?"
navhome.wav
"Navigate to home."
navwork.wav
"Navigate to work."
pause.wav
"Pause music."
showtraffic.wav
"Show traffic."

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.

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.

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.

Other testing requirements

Besides testing your app's behavior on car consoles and phone screens, you should also ensure it can perform the following scenarios.

Test media app "cold start"

Android Auto media apps should work even if no activity has ever been opened. Your app should respond appropriately under the following conditions:

  • The MediaBrowserService is run before any activity is opened.
  • The user is not signed in.
  • No activity can be shown.

In addition, test the following scenarios:

  • Force stop the media app, then launch Android Auto.
  • Clear the media app data, then launch Android Auto.

If the app cannot perform the requested behavior, set an appropriate error message.

Media testing tools

You can use the Media Controller Test app in order to verify media integrations for Android Auto and Android Automotive OS.

For more information, see the following resources: