Changeling

An Android app for GrapheneOS that implements the Android Auto head-unit protocol on the phone side, so a car's stock head unit can connect to it exactly as if it were talking to real Android Auto — no head unit modification, no Google Android Auto app, no Google Play services required.

Why

GrapheneOS deliberately ships without Google Play services, which is what the real Android Auto app depends on. Changeling's goal is to provide equivalent functionality (maps, music, calls, voice) by speaking the Android Auto wire protocol directly from a degoogled phone, so the car itself doesn't need to know or care that anything is different.

How it works (planned)

Android Auto's phone↔head-unit protocol ("AASP") has already been reverse-engineered by the open-source community, most notably by the OpenAuto / aasdk projects, which implement the head unit side in C++. Changeling implements the phone side, in Kotlin, natively on Android:

1. Transport — USB accessory mode (AOAP), the same way a real phone connects to a car over a USB cable.
2. Session layer — SSL/TLS handshake and protobuf-framed control messages that negotiate which services (media, navigation, input, sensors) are available.
3. Service channels — audio output, video/rendering output for navigation, input events from the head unit's controls/touchscreen, and sensor data the car expects (e.g. GPS, night mode).
4. App layer — a real navigation/maps backend and a media player feeding into those channels.

This is an interoperability project: re-implementing a documented, already-reverse-engineered protocol so two pieces of hardware (phone, car) that already expect to speak it can do so without Google's official client.

Status

Early protocol prototype. The app currently has USB accessory matching, bulk-frame transport, control-channel version negotiation, a TLS server handshake, auth completion, service discovery/channel-open support, and a first media-audio path using either a generated tone or a user-picked audio file.

The main remaining reality check is hardware validation with a real Android Auto head unit. The JVM/Robolectric tests prove the framing, TLS negotiation, and media-audio channel behavior are internally consistent, but they do not prove that a car will accept the session. See PLAN.md and docs/roadmap.md for the current milestone state.

Building

Standard Gradle/Android Studio project. Requires Android SDK 34, JDK 17.

./gradlew test
./gradlew assembleDebug

For first hardware-test setup, see docs/hardware-testing.md:

make prep-phone
make capture-logs

License

GPLv3. This project vendors the Android Auto protobuf schema from aasdk (app/src/main/proto/), which is GPLv3-licensed, so the project as a whole is too. See LICENSE.