# webbug-dev/mst2-cluster-nav-android-auto architecture

> Architecture diagram of the GitHub repository webbug-dev/mst2-cluster-nav-android-auto, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/webbug-dev/mst2-cluster-nav-android-auto
- Repository: https://github.com/webbug-dev/mst2-cluster-nav-android-auto

## Overview

This is a MIB2 Standard head-unit mod that puts Android Auto or CarPlay maps in the instrument cluster and converts phone route guidance into the cluster’s native arrows, lanes, ETA and street display. The principal flow is phone stream into SAL, decode and stock display capture; route data travels to the HMI datapool, which feeds the cluster’s navigation display. README relationships describe some runtime stages not shown in sampled source; those edges are cited to the README, and unsampled internals are represented at their known source paths.

Main entry points: [`hmi/src/mst2/clusternav/PhoneLink.java`](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/PhoneLink.java) (Phone link), [`native/src/sal/aa.c`](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/native/src/sal/aa.c) (SAL receiver), [`hmi/src/mst2/clusternav/Activator.java`](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/Activator.java) (HMI startup), [`hmi/src/mst2/clusternav/Datapool.java`](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/Datapool.java) (Navigation datapool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_native["Head-unit video"]
  node_sal["SAL receiver<br/>[aa.c]"]
  node_decode["Stream decode<br/>[decode.c]"]
  node_display["Display capture<br/>[dm.c]"]
end

subgraph group_protocol["Phone protocols"]
  node_aa_proto["Android Auto protocol<br/>[aa_proto.c]"]
  node_carplay_route["CarPlay route hook<br/>[route.c]"]
  node_iap2["CarPlay transport<br/>[ipod.c]"]
end

subgraph group_hmi["HMI integration"]
  node_activator["HMI startup<br/>[Activator.java]"]
  node_phone_link["Phone link<br/>[PhoneLink.java]"]
  node_aa_cluster["Android Auto service"]
  node_cp_cluster["CarPlay service"]
  node_map_state["Map ownership<br/>[KombiMap.java]"]
end

subgraph group_guidance["Route guidance"]
  node_guidance["Guidance snapshot<br/>[Guidance.java]"]
  node_lanes["Lane symbols<br/>[Lanes.java]"]
  node_maneuvers["Maneuver display<br/>[Maneuvers.java]"]
  node_datapool["Navigation datapool<br/>[Datapool.java]"]
end

node_android(("Android phone"))
node_carplay_phone(("CarPlay phone"))
node_cluster(("Instrument cluster"))

node_android -->|"sends video"| node_sal
node_android -->|"sends route"| node_sal
node_sal -->|"processes protocol"| node_aa_proto
node_sal -->|"provides stream"| node_decode
node_decode -->|"renders display"| node_display
node_display -->|"sends MOST video"| node_cluster
node_carplay_phone -.->|"sends route"| node_iap2
node_iap2 -.->|"dispatches guidance"| node_carplay_route
node_activator -->|"starts listener"| node_phone_link
node_activator -->|"installs service"| node_aa_cluster
node_activator -->|"installs service"| node_cp_cluster
node_phone_link -->|"parses route"| node_guidance
node_phone_link -->|"publishes guidance"| node_datapool
node_phone_link -->|"sets ownership"| node_aa_cluster
node_phone_link -->|"sets ownership"| node_cp_cluster
node_phone_link -->|"sets video state"| node_map_state
node_guidance -->|"contains lane data"| node_lanes
node_datapool -->|"writes BAP guidance"| node_cluster
node_carplay_route -.->|"forwards guidance"| node_phone_link
node_aa_proto -->|"sends navigation state"| node_phone_link
node_maneuvers -.->|"supplies maneuver data"| node_datapool

click node_sal "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/native/src/sal/aa.c"
click node_aa_proto "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/native/src/sal/aa_proto.c"
click node_decode "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/native/src/sal/decode.c"
click node_display "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/native/src/dm/dm.c"
click node_carplay_route "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/native/src/common/route.c"
click node_iap2 "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/native/src/ipod/ipod.c"
click node_activator "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/Activator.java"
click node_phone_link "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/PhoneLink.java"
click node_aa_cluster "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/ClusterAndroidAuto.java"
click node_cp_cluster "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/ClusterCarPlay.java"
click node_map_state "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/KombiMap.java"
click node_guidance "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/Guidance.java"
click node_lanes "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/Lanes.java"
click node_maneuvers "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/Maneuvers.java"
click node_datapool "https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/Datapool.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sal,node_decode,node_display toneBlue
class node_aa_proto,node_carplay_route,node_iap2 toneAmber
class node_activator,node_phone_link,node_aa_cluster,node_cp_cluster,node_map_state toneMint
class node_guidance,node_lanes,node_maneuvers,node_datapool toneRose
class node_android,node_carplay_phone,node_cluster toneIndigo
```

## Components

### Head-unit video

- [SAL receiver](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/native/src/sal/aa.c): `native/src/sal/aa.c`
- [Stream decode](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/native/src/sal/decode.c): `native/src/sal/decode.c`
- [Display capture](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/native/src/dm/dm.c): `native/src/dm/dm.c`

### Phone protocols

- [Android Auto protocol](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/native/src/sal/aa_proto.c): `native/src/sal/aa_proto.c`
- [CarPlay route hook](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/native/src/common/route.c): `native/src/common/route.c`
- [CarPlay transport](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/native/src/ipod/ipod.c): `native/src/ipod/ipod.c`

### HMI integration

- [HMI startup](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/Activator.java): `hmi/src/mst2/clusternav/Activator.java`
- [Phone link](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/PhoneLink.java): `hmi/src/mst2/clusternav/PhoneLink.java`
- [Android Auto service](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/ClusterAndroidAuto.java): `hmi/src/mst2/clusternav/ClusterAndroidAuto.java`
- [CarPlay service](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/ClusterCarPlay.java): `hmi/src/mst2/clusternav/ClusterCarPlay.java`
- [Map ownership](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/KombiMap.java): `hmi/src/mst2/clusternav/KombiMap.java`

### Route guidance

- [Guidance snapshot](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/Guidance.java): `hmi/src/mst2/clusternav/Guidance.java`
- [Lane symbols](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/Lanes.java): `hmi/src/mst2/clusternav/Lanes.java`
- [Maneuver display](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/Maneuvers.java): `hmi/src/mst2/clusternav/Maneuvers.java`
- [Navigation datapool](https://github.com/webbug-dev/mst2-cluster-nav-android-auto/blob/main/hmi/src/mst2/clusternav/Datapool.java): `hmi/src/mst2/clusternav/Datapool.java`

### Other components

- **Android phone**
- **CarPlay phone**
- **Instrument cluster**

## Connections

- Android phone → SAL receiver: sends video
- Android phone → SAL receiver: sends route
- SAL receiver → Android Auto protocol: processes protocol (evidence: `native/src/sal/aa.c`)
- SAL receiver → Stream decode: provides stream
- Stream decode → Display capture: renders display
- Display capture → Instrument cluster: sends MOST video
- CarPlay phone → CarPlay transport: sends route
- CarPlay transport → CarPlay route hook: dispatches guidance
- HMI startup → Phone link: starts listener (evidence: `hmi/src/mst2/clusternav/Activator.java`)
- HMI startup → Android Auto service: installs service (evidence: `hmi/src/mst2/clusternav/Activator.java`)
- HMI startup → CarPlay service: installs service (evidence: `hmi/src/mst2/clusternav/Activator.java`)
- Phone link → Guidance snapshot: parses route (evidence: `hmi/src/mst2/clusternav/PhoneLink.java`)
- Phone link → Navigation datapool: publishes guidance (evidence: `hmi/src/mst2/clusternav/PhoneLink.java`)
- Phone link → Android Auto service: sets ownership (evidence: `hmi/src/mst2/clusternav/PhoneLink.java`)
- Phone link → CarPlay service: sets ownership (evidence: `hmi/src/mst2/clusternav/PhoneLink.java`)
- Phone link → Map ownership: sets video state (evidence: `hmi/src/mst2/clusternav/PhoneLink.java`)
- Guidance snapshot → Lane symbols: contains lane data (evidence: `hmi/src/mst2/clusternav/Guidance.java`)
- Navigation datapool → Instrument cluster: writes BAP guidance (evidence: `hmi/src/mst2/clusternav/Datapool.java`)
- CarPlay route hook → Phone link: forwards guidance
- Android Auto protocol → Phone link: sends navigation state
- Maneuver display → Navigation datapool: supplies maneuver data
