This article discusses Android Automotive / Auto and provides guidance on implementing Android Auto support in an existing app.
In the past(™), not so long ago, the only purpose of connecting your smartphone to your car was to stream music via Bluetooth. Fortunately, this has changed more and more in recent years. It is now commonplace to connect your phone to your car, and Android Auto or Apple CarPlay offer much more than just music playback.
Have an appointment in your calendar and set the location? Get in the car and the software will most likely already know what the address of your destination will already be in the navigation system.
The popularity of this support continues to grow. Whether it is in the automotive sector or simple consumer applications, we see that this is an area that is growing as well.
Terminology
Android? Android Auto? Android Automotive? It’s the same right?
Android
Android is an operating system and software platform for mobile devices, including smartphones, tablet computers, televisions, media players, netbooks, and cars. It was developed by the Open Handset Alliance, founded by Google, and is based on a Linux kernel.
Android Auto
Android Auto is a feature that allows you to “project“ your smartphone onto your car’s display. It requires a connected smartphone.
The smartphone handles the rendering of the UI, while the car’s hardware forwards user input, such as buttons or touch events, to the phone.
Example: The car from company XYZ has its own operating system and navigation system, despite offering this interface.
Android Automotive
The car’s embedded operating system is based on Android, and we develop standalone applications for this platform.
Example: Polestar utilizes Android as the operating system for its cars, rather than developing its own.
As mentioned earlier, we will focus on Android Auto support and show how to add Android Auto features to an existing app.
Starting point
We will use an application we have already built to query the photon.komoot.io API for points of interest in our area. If we find a place interesting, we can open it in Google Maps. The app is sufficient for our needs.
The app’s source code is available but we will not be examining the mobile component. Our objective is to provide a small benefit to our app users while they are driving.
Implementation
Let’s get started. What is the minimum requirement to open our app on a smartphone while driving?
Prerequisites
To inform the system that our application is car-compatible, we must first complete the following steps.
Add dependency
In the code base available at GitHub we use the Gradle Version Catalog, but let’s keep it simple here.
implementation("androidx.car.app:app:1.2.0")
AndroidManifest.xml
We provide the system with the necessary information to indicate that it is ready for use in a car. We declare the POI category for our application.
An app that provides functionality relevant to finding points of interest, such as parking, charging stations, and gas stations.
We will also add permission here that will be necessary for implementing the PlaceListTemplate.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
<uses-permission android:name="androidx.car.app.MAP_TEMPLATES" /> <application ... <meta-data android:name="com.google.android.gms.car.application" android:resource="@xml/car_desc" /> <meta-data android:name="androidx.car.app.minCarApiLevel" android:value="1" /> <service android:name=".data.car.CarService" android:exported="true"> <intent-filter> <action android:name="androidx.car.app.CarAppService" /> <category android:name="androidx.car.app.category.POI" /> </intent-filter> </service> </application> |
Service
To be recognized by the host as a corresponding application, we must add a CarAppService.
|
1 2 3 4 5 6 7 8 9 |
class CarService : CarAppService() { override fun createHostValidator(): HostValidator { return HostValidator.ALLOW_ALL_HOSTS_VALIDATOR } override fun onCreateSession(): Session { return CarSession() } } |
CarAppService is an abstract service class that your application must implement and export in order to be discovered and managed by the host.
CarAppService now expects us to return a session.
Session
|
1 2 3 4 5 |
class CarSession : Session() { override fun onCreateScreen(intent: Intent): Screen { return MainScreen(carContext) } } |
The Session class is an abstract class that your app must implement and return using CarAppService.onCreateSession. It is the starting point for displaying information on the car screen and manages the lifecycle.
The host requests the initial screen to display using the onCreateScreen method when a Session is started, such as when the app is first launched.
Session expects us to return a screen…
Summary
To summarize, there are three code blocks.
We added some information to the AndroidManifest and created a CarAppService to inform the host that we can provide a certain functionality via the corresponding session.
The session manages the app’s lifecycle. We use onCreateScreen to specify the desired screen.
Screens and UI
The Screen class in the context of Android Auto is provided by the library for managing the user interface presented to the user.
The first screen
Unlike mobile device development, where we can create the UI ourselves using Compose or XML, Android Auto development requires the use of predefined templates from the library. This is a restriction due to safety regulations.
We will begin with the MainScreen and a GridTemplate, which will serve as the main menu.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
class MainScreen(carContext: CarContext) : Screen(carContext) { override fun onGetTemplate(): Template { val searchItem = GridItem.Builder() .setTitle("Search") .build() val iceCream = GridItem.Builder() .setTitle("Get Ice Cream") .build() val itemList = ItemList.Builder().addItem(searchItem).addItem(iceCream) return GridTemplate.Builder() .setTitle("Hello!") .setLoading(false) .setSingleList(itemList.build()) .build() } } |
In the Android Auto context, screens always follow a consistent structure. A template is provided and displayed by the system. In this screen, we use one of the templates (GridTemplate) provided by the Car Library to display a simple menu.
Deployment
Now that we understand how the system works, how do we install it in our car?
Luckily, there is a desktop head unit emulator available for testing, so there is no need to install the app on your phone and walk to your car.
Please refer to the official documentation for more information.
In a nutshell: To install the app, we install it as usual on our smartphone, which is connected to our laptop via USB. Route a port accordingly via adb and then start the head unit emulator.
More functionality
We will now examine two more templates to add some more functionality.
PlaceListTemplate
The PlaceListMapTemplate is utilized to display a list of places along with an accompanying map and markers.
This template functions precisely as its name suggests. Let’s take a look at some code.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 |
class PlaceListMapScreen(carContext: CarContext) : Screen(carContext), KoinComponent { init { loadResults() } private fun loadResults() { // Get Location and data from API // Set uiState Variable by result uiState = ListUiState(pois = listOf(poi1, poi2)) // Requests the current template to be invalidated, which eventually // triggers a call to onGetTemplate to get the new template to display. invalidate() } override fun onGetTemplate(): Template { // check for loading and error state val builder = PlaceListMapTemplate.Builder() .setTitle(carContext.getString(R.string.app_name)) .setHeaderAction(Action.BACK) .setCurrentLocationEnabled(true) // Add items val itemListBuilder = ItemList.Builder() uiState.pois.forEach { val item = buildPOIItem(it) { poi -> // onClick } itemListBuilder.addItem(item) } builder.setItemList(itemListBuilder.build()) return builder.build() } private fun buildPOIItem(poi: POI, clickListener: (poi: POI) -> Unit): Row { val place = Place.Builder( CarLocation.create(poi.long, poi.lat) ).setMarker( PlaceMarker.Builder() .setColor(CarColor.BLUE).build() ).build() val metadata = Metadata.Builder().setPlace(place).build() return Row.Builder() .setTitle(poi.name) .setMetadata(metadata) .setBrowsable(true) .setOnClickListener { clickListener(poi) } .addText(poi.address) .build() } } |
For illustrative purposes, the code is shortened to focus on building the UI.
Upon screen initiation, data is loaded from the API. A marker is built on the map and a row displays the results for each data point.
To round things off, we want to add the functionality of a POI detail view and launch navigation.
We could now start the navigation directly by clicking on the respective item …
|
1 2 3 4 5 6 7 8 9 10 |
return Row.Builder() .setOnClickListener { val intent = Intent().apply { action = CarContext.ACTION_NAVIGATE data = Uri.parse("geo:${poi.long},${poi.lat}") } carContext.startCarApp(intent) } .setTitle(poi.name) ... |
Sending the system a corresponding intent can accomplish this task easily. The system has already implemented this action for us. Additionally, there is another template available that allows for a deeper exploration of the UI.
PaneTemplate
In theory, we could use different templates in a screen by returning a specific template in onGetTemplate based on user interaction. However, this may not improve readability in our case.
We will therefore take a look at the PaneTemplate implemented on a second screen.
What is a Pane?
Well, it simply represents a list of rows used to display informational content and a set of actions that users can perform based on that content.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
class DetailPaneScreen(carContext: CarContext, val poi: POI) : Screen(carContext), KoinComponent { override fun onGetTemplate(): Template { val navigationAction = Action.Builder() .setTitle("Navigation") .setOnClickListener { // Start Navigation }.build() val backAction = Action.Builder() .setTitle("Back") .setOnClickListener { // go back }.build() val row = Row.Builder() .setTitle(poi.name) .addText(poi.address) .addText(poi.location) .setImage(CarIcon.APP_ICON) .build() return PaneTemplate.Builder( Pane.Builder() .addRow(row) .addAction(navigationAction) .addAction(backAction) .build() ) .setTitle("Details") .setHeaderAction(Action.BACK) .build() } } |
The code shown is minimally summarized, but it clearly shows how simple it is to achieve our goal so far.
Our template includes a simple UI with text and two actions. action and a simple back action.
Summary
This post explains how to add Android Auto functionality to an existing app. It covers various templates with different purposes and discusses the platform’s restrictions and benefits.
It is important to note that Android Auto and Android Automotive apps differ significantly, as previously mentioned.
The source code with added functionality, including a search function and basic error handling, is available on GitHub.
If you require assistance with Android automotive apps or are interested in working on such projects, feel free to contact us.
References
https://developers.google.com/cars/design/design-foundations
https://developer.android.com/training/cars
https://source.android.com/docs/automotive/start/terms
https://github.com/inovex/blog-android-car-finder
