Cluster

Introduction

This tutorial guides you through the integration of navigation elements on the instrument cluster of your vehicle.

Cluster activity

Automotive Navigation Application includes a dedicated Cluster Activity designed to display navigation information on the vehicle's instrument cluster.
The Cluster Activity provides a customizable UI for displaying navigation elements such as maps, maneuvers, and Estimated Time of Arrival (ETA) information.
It automatically adapts to the current navigation state, ensuring that relevant information is presented to the driver.

How to integrate the Cluster Activity

Define default configuration

The first step in integrating the Cluster Activity is to define your own default configuration.
The Cluster Activity can be configured at launch time by passing a JSON configuration as an extra in the intent used to start the Activity.
The configuration allows you to define which components are displayed on the Cluster and their layout.

Consult the configuration parameters section below for an overview of the available configuration parameters and their default values.

Start the Cluster Activity

The Cluster Activity can be started through an intent.
While it is possible to start the Cluster Activity with its built-in default configuration, it is recommended to start it while passing the appropriate default configuration as an extra.

1val myClusterActivityDefaultConfiguration = """
2    {
3      "displayHpComponent": true,
4      "displayVignette": true,
5      "displayPX": false,
6      (...),
7    }
8""".trimIndent()
9
10val intent = Intent()
11intent.action = "com.tomtom.automotive.clusterui.cluster.COMPONENT_VISIBILITY"
12intent.addCategory("android.car.cluster.NAVIGATION")
13intent.putExtra("clusterConfigurationUpdate", myClusterActivityDefaultConfiguration)
14startActivity(intent)

Update configuration at runtime

You can update the configuration of the Cluster Activity at runtime through the same intent used to start it.
Note that the configuration update does not need to be exhaustive, meaning that you can update only the parameters you want to change.

Example of changing ETA component visibility

You can programmatically update the configuration through an intent:

1val intent = Intent()
2intent.action = "com.tomtom.automotive.clusterui.cluster.COMPONENT_VISIBILITY"
3intent.addCategory("android.car.cluster.NAVIGATION")
4intent.putExtra("clusterConfigurationUpdate", "{\"displayHpComponent\": false}")
5startActivity(intent)

The same can be accomplished through adb:

1adb shell
2am start -a "com.tomtom.automotive.clusterui.cluster.COMPONENT_VISIBILITY" \
3         -c "android.car.cluster.NAVIGATION" \
4         --es "clusterConfigurationUpdate" '{"displayHpComponent": false}'

Configuration parameters

The Cluster Activity configuration is defined using JSON and supports the following parameters:

Parameter	Description	Type	Default value
displayHpComponent	Displays the Horizon Panel component on the Cluster if the parameter is set to true, hides it otherwise. Its dimensions and position on the screen are dictated by the values of the hpComponentRect parameter.	boolean	true
hpComponentRect	Represents a rectangle which configures the dimensions and position of the Horizon Panel.	object	implementation defined
hpElementsToShowOnCluster	Configures which sub panels are shown on Horizon panel. Possible values: SLG: Simple Lane Guidance Panel CMP: Consecutive Maneuver Panel ETA: Estimated Time of Arrival Panel JV: Junction View Panel UEP: Upcoming Events Panel	set	CMP
nipLayoutType	Represents the layout configuration of the Next Instruction Panel (shown as part of the Horizon Panel). Possible values: NORMAL_LAYOUT, LANDSCAPE_MINIMAL, LANDSCAPE_MEDIUM, LANDSCAPE_MAXIMAL, PORTRAIT_MINIMAL, PORTRAIT_MEDIUM, PORTRAIT_MAXIMAL.	string	NORMAL_LAYOUT
etaLayoutType	Represents the ETA panel layout configuration type (shown as part of the Horizon Panel). Possible values: NORMAL_LAYOUT_WIDE, NORMAL_LAYOUT_NARROW, MINIMAL, MEDIUM, MAXIMAL.	string	MINIMAL
displayMapComponent	Displays the Map component on the Cluster if the parameter is set to true, hides it otherwise.	boolean	true
displayVignette	Displays a vignette on the outer edges of the Cluster if the parameter is set to true, hides it otherwise.	boolean	true
displayPX	Supports pixels display configuration if parameter is set to true. The parameter should be set to true if you supply startMargin, topMargin, width, and height in pixels. If the parameter is set to false, supply them in density-dependent pixels.	boolean	false
safeAreaComponentRect	Represents a rectangle which configures the dimensions and position of the safe area component on the Cluster. The chevron is positioned in the middle of the safe area rectangle.	object	implementation defined

Example configuration

An example configuration can be found below:

1    {
2      "displayHpComponent": true,
3      "hpComponentRect": {
4        "topMargin": 0,
5        "startMargin": 0,
6        "width": 403,
7        "height": 640
8      },
9      "hpElementsToShowOnCluster": [
10        "CMP"
11      ],
12      "nipLayoutType": "NORMAL_LAYOUT",
13      "etaLayoutType": "MINIMAL",
14      "displayMapComponent": true,
15      "displayVignette": true,
16      "displayPX": false,
17      "safeAreaComponentRect": {
18        "topMargin": 0,
19        "startMargin": 574,
20        "width": 574,
21        "height": 840
22      }
23    }

Best practices

Since you can only configure (not modify) the Cluster Activity:

• Adapt to your display density: Use the displayPX parameter appropriately based on your instrument cluster's display characteristics.