xref: /frameworks/base/docs/html/training/auto/start/index.jd

page.title=Getting Started with Auto
page.tags="auto", "car", "automotive"
page.article=true
page.image=auto/images/assets/icons/auto_app_in_simulator.png

@jd:body

<div id="tb-wrapper">
<div id="tb">
  <h2>Dependencies and Prerequisites</h2>
  <ul>
    <li>Android 5.0 (API level 21) or higher</li>
  </ul>

  <h2>This class teaches you how to</h2>
  <ol>
    <li><a href="#dev-project">Set Up an Auto Project</a></li>
    <li><a href="#build-it">Build Auto Apps</a></li>
    <li><a href="#test-it-dhu">Run and Test Auto Apps </a></li>
  </ol>

 <h2>You should also read</h2>
 <ul>
   <li><a href="{@docRoot}design/auto/index.html">Designing for Auto</a></li>
   <li><a href="{@docRoot}training/auto/audio/index.html">Providing Audio Playback with Auto</a></li>
   <li><a href="{@docRoot}training/auto/messaging/index.html">Providing Messaging for Auto</a></li>
 </ul>
</div>
</div>

<p>Android Auto extends the Android platform into the car. When users connect
their handheld devices running Android 5.0 or higher to a compatible vehicle,
the Auto user interface provides a car-optimized Android experience on the
vehicle's screen. Users interact with compatible apps and services through
voice actions and the vehicle's input controls (like a touchscreen or dashboard
buttons).</p>

<p>Auto currently supports two types of apps:</p>

<ul>
<li><em>Audio apps</em> that allow users to browse and play music and spoken
audio content in the car.</li>
<li><em>Messaging apps</em> that receive incoming notifications, read messages
  aloud via text-to-speech, and send replies via voice input in the car.</li>
</ul>

<p>You can enable your existing audio and messaging apps developed for
phones and tablets to work in the car, without having to worry about
vehicle-specific hardware differences. To enable your app for Auto, your
app must target Android 5.0 (API level 21) or higher. Your app’s manifest must
also declare the car capabilities that it uses, such as audio playback or
messaging services. </p>

<p>This lesson describes how to start building apps for Auto, including
setting up your development environment and meeting the the minimum requirements
to enable an app to communicate with Auto.</p>

<h2 id="dev-project">Set Up an Auto Project</h2>
<p>This section describes how to create a new app or modify an existing app to
communicate with Auto.</p>

<h3 id="prerequisites">Prerequisites</h3>
<p>Before you begin building apps for Auto, you must:</p>

<ul>
<li><strong><a href="{@docRoot}sdk/installing/create-project.html">Create or
update your app project</a></strong> - Android 5.0 (API level 21) provides new
APIs for implementing audio playback and messaging that is compatible with Auto.
To access the new APIs, create a project or modify an existing project to target
Android 5.0 (API level 21) or higher. This means you must set the manifest
<a href="{@docRoot}topics/manifest/uses-sdk-element.html">{@code targetSdkVersion}</a>
to 21 or higher.
</li>
<li><strong><a href="{@docRoot}tools/support-library/setup.html">Install the
support library</a></strong> - If you are building messaging apps for Auto, you
need the {@link android.support.v4.app.NotificationCompat.CarExtender} class
contained in the
<a href="{@docRoot}tools/support-library/features.html#v4">v4 support library</a>.
This class allows you to create notifications that are compatible with Auto
devices.</li>
</ul>

<h3 id="auto-metadata">Declare Auto capabilities</h3>
<p>The Auto features that your app can access are controlled
by the settings in your app manifest and a separate XML configuration file.
Before adding Auto features to your app, you must first define the Auto
XML configuration file and add a manifest entry referencing your XML file.</p>

<h4 id="auto_xml">Define the Auto XML configuration file</h4>
<p>Specify the car capabilities that your app uses in an XML file that you
place in your project’s resources directory ({@code res/xml/}). For example, to
extend an audio application for Auto, create a file called
{@code automotive_app_desc.xml} and store it under your projects’s
{@code res/xml/} folder. The {@code automotive_app_desc.xml} file contains the
following metadata:</p>
<pre>
&lt;automotiveApp&gt;
   &lt;uses name="media" /&gt;
&lt;/automotiveApp&gt;
</pre>
<p>The {@code &lt;uses&gt;} element declares the Auto capability your app
intends to use. Multiple {@code &lt;uses&gt;} tags can be added if your
application uses multiple car capabilities. The {@code name} attribute indicates
the specific capability your app uses. The values supported are:</p>
<ul>
<li>{@code media} - The app uses the Android framework APIs to play music in
a vehicle. Set this value if you are enabling an audio app for Auto.</li>
<li>{@code notification} - The app displays message notifications in the car’s
Overview screen, allows users select a message to be read aloud, and lets them
respond through voice input. Set this value if you are enabling a messaging
app for Auto.
</ul>

<h4 id="auto_xml">Add a manifest entry</h4>
<p>In your app’s manifest ({@code AndroidManifest.xml}), provide a reference to
the Auto XML configuration file you created in the previous section. Add a
{@code "com.google.android.gms.car.application"} metadata entry under the
<a href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;application&gt;}</a>
element that references your Auto XML configuration file. Omit the {@code .xml}
file extension when specifying the configuration filename.</p>
<p>The following code snippet shows how to include this reference in your
manifest.</p>
<pre>
&lt;application&gt;

    ...
    &lt;meta-data android:name="com.google.android.gms.car.application"
     android:resource="@xml/automotive_app_desc"/&gt;

&lt;/application&gt;
</pre>

<h2 id="build-it">Add Auto Features to Your Apps</h2>
<p>After you have completed the steps described above, you're ready to add Auto
features to your apps. See these additional topics to help you build apps for
Auto:</p>

<ul>
<li><a href="{@docRoot}training/auto/audio/index.html">Providing Audio Playback for Auto</a>
- Create apps that let users browse and play music in the car.</li>
<li><a href="{@docRoot}training/auto/messaging/index.html">Providing Messaging for Auto</a>
- Enable users to receive and reply to messages in the car.</li>
</ul>

<p class="caution"><strong>Important:</strong> Google takes driver distraction
very seriously. There are specific design requirements your app must meet to
qualify as an Auto app on Google Play. By adhering to these
requirements, you can reduce the effort for building and testing your app. For
more information, see
<a href="{@docRoot}distribute/essentials/quality/auto.html">Auto App Quality</a>.</p>



<h2 id="test-it-dhu">Run and Test Auto Apps </h2>

<p>
  As you develop, you can run and test your app on your development machine
  using the <em>Desktop Head Unit</em> (DHU). The DHU replaces the existing
  simulators and enables your development machine to simulate a vehicle
  dashboard system running Android Auto.
</p>

<h3 id="installing-dhu">Installing the DHU</h3>

<ol>
  <li>Enable developer mode on your mobile device, as described in
    <a href="{@docRoot}tools/device.html#developer-device-options">Enabling On-device
    Developer Options</a>. </li>
  <li>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
    <strong>Settings &gt; About phone</strong> (or <strong>About tablet</strong>) <strong>&gt;
    Android version</strong>.</li>

  <li>Install the
     <a class="external-link"
     href="https://play.google.com/store/apps/details?id=com.google.android.projection.gearhead&hl=en"
     >Android Auto app</a> on the mobile device.</li>
  <li>Open the <a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a> and
    download the DHU package <strong>Android Auto Desktop Head Unit</strong> from the
    <em>SDK Tools</em> tab. The DHU installs in the <code>&lt;sdk&gt;/extras/google/auto/</code>
    directory.</li>
  <li>If you are running the DHU on Linux, you must also install
    the portaudio, libpng, sdl2, and sdl2_ttf libraries.
    The procedure to do this varies depending on your Linux distribution. For example, on
    Debian-derived Linux distributions, you can install the libraries with this command:

<pre class="no-pretty-print">
$ sudo apt-get install libsdl2-2.0-0 libsdl2-ttf-2.0-0 libportaudio2 libpng12-0
</pre>

  </li>
</ol>

<div class="figure" style="width:330px">
  <img src="{@docRoot}images/training/auto-desktop-head-unit-server-running.png"
      alt="" >
  <p class="img-caption">
    <strong>Figure 2.</strong> Notification that the head unit server is running.
  </p>
</div>
<img src="{@docRoot}images/training/auto-desktop-head-unit-context-menu-enabled.png"
    alt="" >
<p class="img-caption">
  <strong>Figure 1.</strong> Context menu with developer options.
</p>

<h3 id="connecting-dhu">Connecting the DHU to your mobile device</h3>

<p>Run the DHU by connecting your mobile device to a development machine and setting up a connection to
  the head unit server over <a href="{@docRoot}tools/help/adb.html">Android Debug Bridge
  (ADB)</a>. Follow these steps to set up tunneling and start the DHU:</p>

<ol>
  <li>On the mobile device, enable Android Auto developer mode by starting the Android Auto
    companion app, and then tapping the header image 10 times.
    This step is only required the first time you run the companion app.
  </li>
  <li>If the server is not already running, select <strong>Start head unit server</strong>
     from the Android Auto menu.
    <p>On the device, a foreground service appears in the notification area. </p>
  </li>

  <li>Connect the mobile device to the development machine via USB. Your device must be unlocked to
    launch the DHU.
  </li>
  <li>On the development machine, run the following {@code adb} command to
    forward socket connections from the
    development machine's port 5277 to the same port number on the Android device.
    This configuration allows the DHU to connect to the head unit server running on your phone over
    a TCP socket.
    <pre class="no-pretty-print">$ adb forward tcp:5277 tcp:5277</pre>
  </li>

  <li>Start the DHU by running the command <code>desktop-head-unit.exe</code> (on Windows)
    or <code>./desktop-head-unit</code> (on Mac or Linux) from the
    <code>&lt;sdk&gt;/extras/google/auto/</code> directory.

<pre class="no-pretty-print">$ cd &lt;sdk&gt;/extras/google/auto
$ ./desktop-head-unit</pre>

    <p>
      By default, the head unit server connects over port 5277. To override the host or port
      (for example, to forward over SSH), use the <code>--adb</code> flag.
    </p>

  </li>
</ol>

<div class="figure" style="width:432px">

    <img src="{@docRoot}images/training/auto-desktop-head-unit-wkst-launch.png"
        alt="" >
    <p class="img-caption">
      <strong>Figure 4.</strong> DHU launches on the development machine.
    </p>
</div>

    <img src="{@docRoot}images/training/auto-desktop-head-unit-launch.png"
        alt="" >
    <p class="img-caption">
      <strong>Figure 3.</strong> Android Auto launches on the mobile device.
    </p>

<p>
  After you set up and start the DHU, you can run DHU commands from the command line to run and
  test your app from the terminal. You can also run these commands by using keyboard shortcuts. For
  more information about DHU configuration and commands, see <a href=
  "{@docRoot}tools/help/desktop-head-unit.html">Desktop Head Unit</a>.
</p>