1# ClusterHomeSample
2
3`ClusterHomeSample` is a sample reference application that runs on the cluster display.
4It uses `ClusterHomeManager` API (a.k.a. Cluster2) to interact with the CarService.
5It supports both the FULL mode and the LIGHT mode. However, in actual production cases,
6the cluster service supports one specific mode, thus the actual cluster application
7only needs to run in one specific mode.
8
9## CarService Configuration
10In order to enable `ClusterHomeService`, remove `cluster_service` from
11`config_allowed_optional_car_features` and add `cluster_home_service`,
12in the RRO configuration of the CarService.
13```
14<string-array translatable="false" name="config_allowed_optional_car_features">
15    ...
16    <item>cluster_home_service</item>
17    ...
18</string-array>
19```
20Set `config_clusterHomeServiceMode` to select what mode the `ClusterHomeService` to run in.
21```
22<!-- Configures the mode in which ClusterHomeService operates.
23     Currently supported modes are:
24         0 (full mode): All VHAL properties in ClusterHalService#CORE_PROPERTIES must be
25                        available. Otherwise, the entire ClusterHomeService is disabled.
26         1 (light mode): ClusterHomeService is always enabled even without any VHAL properties.
27-->
28<integer name="config_clusterHomeServiceMode">0</integer>
29```
30`config_clusterHomeActivity` sets the activity that runs on the cluster display.
31Note that the activity specified here will run as the system user,
32thus the activity's `showForAllUsers` attribute must be set to `true`
33in the application's `AndroidManifest.xml` file.
34```
35<!-- The name of Activity who is in charge of ClusterHome. -->
36<string name="config_clusterHomeActivity" translatable="false">com.android.car.cluster.home/.ClusterHomeActivity</string>
37```
38The followings are used by the `ClusterHomeManager#startVisibilityMonitoring(Activity)` method
39to configure parameters for visibility monitoring.
40```
41<!-- Configurations for ClusterHome visibility monitoring.
42     Please refer to {@link SurfaceControl#TrustedPresentationThresholds} for the detail.
43-->
44<fraction name="config_clusterHomeVisibility_minAlpha">100%</fraction>
45<fraction name="config_clusterHomeVisibility_minRendered">99.9%</fraction>
46<integer name="config_clusterHomeVisibility_stabilityMs">100</integer>
47```
48
49## Application Configuration
50### `directBootAware`
51A cluster application needs to be able to start regardless of user unlocked state.
52Therefore `dirctBootAware` must be set to `true` in the application's `AndroidManifest.xml`.
53```
54<application android:name=".ClusterHomeApplication"
55    ...
56    android:directBootAware="true">
57```
58See https://developer.android.com/privacy-and-security/direct-boot
59for more information on `directBootAware`.
60### `showForAllUsers`
61For the activities that run as the system user, the `showForAllUsers`
62attribute must be set to `true` in the `AndroidManifest.xml` file.
63```
64<activity android:name=".ClusterHomeActivity"
65    ...
66    android:showForAllUsers="true">
67```
68See https://developer.android.com/guide/topics/manifest/activity-element#showForAllUsers
69for more information on `showForAllUsers`.
70## FULL mode
71
72The cluster application makes full use of the `ClusterHomeManager` APIs in the FULL mode.
73It starts with the `UI_TYPE_HOME` activity running as user 0, and switches to `UI_TYPE_START`
74activity when the current user is unlocked. It can switch to other UI activity types
75(e.g. `UI_TYPE_MAPS`, `UI_TYPE_PHONE`, etc.) as necessary.
76
77See `ClusterHomeActivity` for more details.
78
79To run `ClusterHomeService` in the FULL mode, the device needs to have
80all the following VHAL properties defined:
81
82- `CLUSTER_SWITCH_UI`
83- `CLUSTER_REPORT_STATE`
84- `CLUSTER_DISPLAY_STATE`
85- `CLUSTER_REQUEST_DISPLAY`
86
87If the service is configured for the FULL mode but any of the above properties is not defined,
88`ClusterHomeManager` API will throw an `IllegalStateException`.
89
90## LIGHT mode
91
92In the LIGHT mode, it stays as the `UI_TYPE_HOME` activity that runs as user 0.
93`ClusterHomeManager#startVisibilityMonitoring` and `ClusterHomeManager#sendHeartbeat` are
94used in the LIGHT mode. The device must implement `CLUSTER_HEARTBEAT` VHAL property
95to be able to use these API.
96
97See `ClusterHomeActivityLightMode` for a sample implementation.