Instrument Cluster

The Android Automotive OS (AAOS) instrument cluster is a specialized, mission-critical display designed to show vital vehicle information like speed, navigation, and warnings. Unlike the main Infotainment system (IVI), the cluster often has stringent latency, reliability, and safety requirements.

Instrument Cluster Display Management

In AAOS, display management extends beyond a single screen to support multi-display environments. The instrument cluster is typically modeled as a secondary or auxiliary display, but with high-priority rendering constraints.

AAOS handles this through the CarOccupantZoneManager and the internal display management infrastructure. The cluster is assigned a specific display ID during the boot phase.

// Example: Getting the cluster display
CarOccupantZoneManager occupantZoneManager = 
    (CarOccupantZoneManager) car.getCarManager(Car.CAR_OCCUPANT_ZONE_SERVICE);

Display clusterDisplay = occupantZoneManager.getDisplayForType(
    CarOccupantZoneManager.DISPLAY_TYPE_INSTRUMENT_CLUSTER);

ClusterHalService

The ClusterHalService is the bridge between the Android framework and the Vehicle HAL (VHAL) for cluster-specific properties. It handles communication regarding the state of the cluster hardware, such as display availability, readiness, and lifecycle events.

Key responsibilities:

• Initialization: Bootstrapping the connection with the cluster hardware.
• State Sync: Communicating UI state (e.g., whether navigation is active) to the VHAL.
• Input Events: Processing steering wheel controls or physical buttons mapped to cluster actions.

// Example: VHAL property for cluster reporting
enum VehicleProperty {
    ...
    CLUSTER_REPORT_STATE = 0x011 | VehiclePropertyGroup:SYSTEM | VehiclePropertyType:INT32_VEC | VehicleArea:GLOBAL,
    ...
};

ClusterHomeManager API

The ClusterHomeManager API provides the application-level interface for building instrument cluster applications. It allows the system UI or a dedicated OEM app to manage the rendering surface of the cluster display.

This API allows an application to register as the primary cluster UI and provides callbacks for visibility changes, bounds, and insets.

// Managing the cluster home state
ClusterHomeManager clusterHomeManager = 
    (ClusterHomeManager) car.getCarManager(Car.CLUSTER_HOME_SERVICE);

clusterHomeManager.registerClusterStateListener(
    context.getMainExecutor(), 
    new ClusterHomeManager.ClusterStateListener() {
        @Override
        public void onClusterStateChanged(ClusterState state) {
            // Handle cluster state changes (e.g., dimensions, visibility)
            updateClusterUI(state);
        }
    });

Rendering Navigation and Speed

Rendering to the cluster involves handling two primary streams of data: high-frequency vehicle properties (like speed and RPM) and rich graphical data (like turn-by-turn navigation).

1. Vehicle Properties (Speed/RPM): These are typically read directly from the VHAL via CarPropertyManager. Due to safety regulations, this rendering must happen with minimal latency.
2. Navigation Data: AAOS provides the CarNavigationStatusManager to send structured navigation metadata (next turn, distance, ETA) to the cluster. Alternatively, for full map rendering, a Virtual Display is created, and the navigation app renders its Presentation directly to the cluster's surface.

// Sending navigation state to the cluster
CarNavigationStatusManager navManager = 
    (CarNavigationStatusManager) car.getCarManager(Car.CAR_NAVIGATION_SERVICE);

Bundle navState = new Bundle();
navState.putInt("next_turn_distance_meters", 150);
navState.putString("next_turn_icon", "turn_right");

navManager.sendNavigationStateChange(navState);

To debug cluster displays and virtual displays, you can use dumpsys:

adb shell dumpsys display | grep -i cluster
adb shell dumpsys car_service --services CarOccupantZoneService