# ClusterHomeSample

`ClusterHomeSample` is a sample reference application that runs on the cluster display.
It uses `ClusterHomeManager` API (a.k.a. Cluster2) to interact with the CarService.
It supports both the FULL mode and the LIGHT mode. However, in actual production cases,
the cluster service supports one specific mode, thus the actual cluster application
only needs to run in one specific mode.

## CarService Configuration
In order to enable `ClusterHomeService`, remove `cluster_service` from
`config_allowed_optional_car_features` and add `cluster_home_service`,
in the RRO configuration of the CarService.
```
<string-array translatable="false" name="config_allowed_optional_car_features">
    ...
    <item>cluster_home_service</item>
    ...
</string-array>
```
Set `config_clusterHomeServiceMode` to select what mode the `ClusterHomeService` to run in.
```
<!-- Configures the mode in which ClusterHomeService operates.
     Currently supported modes are:
         0 (full mode): All VHAL properties in ClusterHalService#CORE_PROPERTIES must be
                        available. Otherwise, the entire ClusterHomeService is disabled.
         1 (light mode): ClusterHomeService is always enabled even without any VHAL properties.
-->
<integer name="config_clusterHomeServiceMode">0</integer>
```
`config_clusterHomeActivity` sets the activity that runs on the cluster display.
Note that the activity specified here will run as the system user,
thus the activity's `showForAllUsers` attribute must be set to `true`
in the application's `AndroidManifest.xml` file.
```
<!-- The name of Activity who is in charge of ClusterHome. -->
<string name="config_clusterHomeActivity" translatable="false">com.android.car.cluster.home/.ClusterHomeActivity</string>
```
The followings are used by the `ClusterHomeManager#startVisibilityMonitoring(Activity)` method
to configure parameters for visibility monitoring.
```
<!-- Configurations for ClusterHome visibility monitoring.
     Please refer to {@link SurfaceControl#TrustedPresentationThresholds} for the detail.
-->
<fraction name="config_clusterHomeVisibility_minAlpha">100%</fraction>
<fraction name="config_clusterHomeVisibility_minRendered">99.9%</fraction>
<integer name="config_clusterHomeVisibility_stabilityMs">100</integer>
```

## Application Configuration
### `directBootAware`
A cluster application needs to be able to start regardless of user unlocked state.
Therefore `dirctBootAware` must be set to `true` in the application's `AndroidManifest.xml`.
```
<application android:name=".ClusterHomeApplication"
    ...
    android:directBootAware="true">
```
See https://developer.android.com/privacy-and-security/direct-boot
for more information on `directBootAware`.
### `showForAllUsers`
For the activities that run as the system user, the `showForAllUsers`
attribute must be set to `true` in the `AndroidManifest.xml` file.
```
<activity android:name=".ClusterHomeActivity"
    ...
    android:showForAllUsers="true">
```
See https://developer.android.com/guide/topics/manifest/activity-element#showForAllUsers
for more information on `showForAllUsers`.
### `showWhenLocked`
If your cluster activity needs to be shown even when the screen is locked,
set `showWhenLocked` to `true` in the `AndroidManifest.xml` file.
```
<activity android:name=".ClusterHomeActivity"
    ...
    android:showWhenLocked="true">
```
See https://developer.android.com/reference/android/R.attr#showWhenLocked
for more information on `showWhenLocked`.
### `turnScreenOn`
The `turnScreenOn` is set to specify whether the screen needs to be
turned on when the activity is resumed. Usually `turnScreenOn` is specified
with `showWhenLocked` to turn on the screen and show the activity
when the lockscreen is up.
```
<activity android:name=".ClusterHomeActivity"
    ...
    android:turnScreenOn="true">
```
See https://developer.android.com/reference/android/R.attr#turnScreenOn
for more information on `turnScreenOn`.

``
## FULL mode

The cluster application makes full use of the `ClusterHomeManager` APIs in the FULL mode.
It starts with the `UI_TYPE_HOME` activity running as user 0, and switches to `UI_TYPE_START`
activity when the current user is unlocked. It can switch to other UI activity types
(e.g. `UI_TYPE_MAPS`, `UI_TYPE_PHONE`, etc.) as necessary.

See `ClusterHomeActivity` for more details.

To run `ClusterHomeService` in the FULL mode, the device needs to have
all the following VHAL properties defined:

- `CLUSTER_SWITCH_UI`
- `CLUSTER_REPORT_STATE`
- `CLUSTER_DISPLAY_STATE`
- `CLUSTER_REQUEST_DISPLAY`

If the service is configured for the FULL mode but any of the above properties is not defined,
`ClusterHomeManager` API will throw an `IllegalStateException`.

## LIGHT mode

In the LIGHT mode, it stays as the `UI_TYPE_HOME` activity that runs as user 0.
`ClusterHomeManager#startVisibilityMonitoring` and `ClusterHomeManager#sendHeartbeat` are
used in the LIGHT mode. The device must implement `CLUSTER_HEARTBEAT` VHAL property
to be able to use these API.

See `ClusterHomeActivityLightMode` for a sample implementation.