Open Android Auto

The most complete open-source Android Auto protocol reference available. Protocol buffer definitions, protocol documentation, wireless Bluetooth setup guides, decompiled headunit firmware analysis, and APK analysis tools.

234 .proto files organized into 17 categories covering the full AA protocol surface: session control, audio/video streaming, input, sensors, navigation, Bluetooth, WiFi projection, car control, radio, and more.

Architecture context: This channel is part of the Android Auto multiplexed protocol. For the overall architecture — framing, SDP binding, capability negotiation — see Channel Architecture Reference.

Origins

These definitions were reverse-engineered from Android Auto firmware (APK v16.1 and v16.2) and extended from f1x.studio's aasdk (Michal Szwaj's original Android Auto SDK). The original aasdk provided a proto2 foundation; this collection upgrades to proto3, adds dozens of previously undocumented messages, and includes field-level annotations from live protocol captures.

This repository is the protocol definition layer used by OpenAuto Prodigy, a clean-room open-source Android Auto head unit for Raspberry Pi.

Directory Structure

All proto files live under oaa/:

Category	Files	Description
audio	10	Audio channels: focus requests/responses, audio types, config
av	19	Shared audio/video channel types: setup, start/stop, media ack, codec types
bluetooth	9	Bluetooth channel: pairing, authentication, methods, status
carcontrol	3	Car control: HVAC, door locks, mirrors, vehicle properties
common	12	Shared enums and base types: status codes, channel types, session info, error codes
control	34	Session lifecycle: service discovery, channel open/close, ping, auth, shutdown
generic	1	Generic channel message wrapper (channel open acknowledgement)
input	23	Input channel: touch events, buttons, absolute/relative input, haptics
media	12	Media status: playback status, metadata, browsing, car local media
mic	1	Microphone channel: mic open response
navigation	17	Navigation status: turn events, distance, maneuvers, lane guidance, energy forecast
notification	2	Notification types and channel data
phone	3	Phone status: call state, input actions
radio	5	Radio channel: tuner control, presets, station metadata, band/codec enums
sensor	43	Sensor channel: GPS, accel, gyro, speed, RPM, fuel, gear, HVAC, vehicle data
video	17	Video channel: resolution, FPS, focus negotiation, display config, overlays
wifi	23	WiFi projection: security, connection, version negotiation

Quick Start

Compile with protoc

All commands assume you run from the repository root (the directory containing oaa/).

C++:

protoc --proto_path=. --cpp_out=generated/ \
  oaa/control/ServiceDiscoveryRequestMessage.proto \
  oaa/control/ServiceDiscoveryResponseMessage.proto

Python:

protoc --proto_path=. --python_out=generated/ \
  oaa/sensor/GPSLocationData.proto \
  oaa/sensor/SensorEventIndicationMessage.proto

Go:

protoc --proto_path=. --go_out=generated/ --go_opt=paths=source_relative \
  oaa/video/VideoConfigData.proto \
  oaa/video/VideoResolutionEnum.proto

Compile everything:

find oaa -name '*.proto' | xargs protoc --proto_path=. --cpp_out=generated/

Use in a CMake project

find_package(Protobuf REQUIRED)

file(GLOB_RECURSE PROTO_FILES "${CMAKE_CURRENT_SOURCE_DIR}/oaa/*.proto")

protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS ${PROTO_FILES})
add_library(aa_proto ${PROTO_SRCS} ${PROTO_HDRS})
target_include_directories(aa_proto PUBLIC ${CMAKE_CURRENT_BINARY_DIR})
target_link_libraries(aa_proto PUBLIC protobuf::libprotobuf)

Package Namespaces

Files use a suffix-based naming convention that maps to four protobuf packages:

Suffix	Package	Purpose
*Message.proto	oaa.proto.messages	Request/response/indication messages
*Data.proto	oaa.proto.data	Structured data types (configs, events, payloads)
*Enum.proto	oaa.proto.enums	Enumeration definitions
*IdsEnum.proto	oaa.proto.ids	Channel-specific message ID enumerations

Import paths use the oaa/<category>/File.proto format:

import "oaa/common/StatusEnum.proto";
import "oaa/control/ChannelDescriptorData.proto";
import "oaa/video/VideoConfigData.proto";

Documentation

Protocol Reference

• Channel Architecture Reference — AA multiplexing, framing, SDP binding, capability negotiation
• Protocol Reference — auto-generated message catalog (86 messages, 8 enums)
• Protocol Cross-Reference — cross-referencing phone-side (APK) and head-unit-side (firmware) protocol implementations
• Channel Map — channel IDs, message types, and data flow directions
• Field Notes — hard-won implementation knowledge and gotchas

Implementation Guides

• Wireless Bluetooth Setup — complete guide to Bluetooth-based wireless AA discovery (SDP, HFP, WiFi handoff)
• Video Resolution — AA video resolution negotiation and margin support
• Display Rendering — rendering AA video on non-standard displays with letterboxing and sidebars
• Phone-Side Debug — debugging AA from the phone's perspective
• Troubleshooting — common failure modes and diagnostic workflows

Channel Specifications

Detailed protocol specs for each Android Auto channel:

• Audio — codec negotiation, focus, PCM/AAC config
• Bluetooth — pairing, connection, status
• Car Control — HVAC, door locks, mirrors
• Coolwalk Layout — UI layout engine and phenotype flags
• Display Routing — multi-display content routing
• Input — touch, buttons, rotary, touchpad
• Media — playback status, metadata
• Navigation — turn-by-turn, routing, lane guidance
• Phone — call state, contacts, SIM
• Radio — tuner, presets, station metadata
• Sensor — GPS, speed, fuel, gear, accelerometer, 26 sensor types
• Video — projected display, focus modes, resolution, UI config
• WiFi Projection — wireless AA setup and config

Session Lifecycle

Step-by-step AA handshake and session lifecycle:

• Transport Setup — TCP/AOA connection
• Version & SSL Auth — TLS negotiation
• Service Discovery — SDP exchange
• Channel Lifecycle — open/close/teardown
• Session Maintenance — keep-alive, errors, disconnect

Verification Framework

How discoveries are tracked and validated:

• Confidence Tiers — Gold/Silver/Bronze scoring
• Audit Trail Format — .audit.yaml sidecar spec
• Verification Procedures — wire capture and APK validation
• Source Provenance — attribution tracking

Decompiled Headunit Firmware

Protocol implementation details extracted from commercial AA head units:

• Alpine Halo9
• Alpine ILX-W650BT
• Kenwood DNX
• Pioneer DMH
• Sony XAV

Analysis Tools

• APK Analysis — Python indexer scripts and pre-built SQLite databases from Android Auto APK v16.1 and v16.2

Research & Contributing

• Research Archive — reverse-engineering source material, tooling, and validation artifacts
• Research Provenance — exact source snapshot and import scope
• Contributing — how to add or improve definitions

Workflow

• AGENTS.md — repository workflow loop and verification expectations
• Current Roadmap — Now / Next / Later priorities
• Session Handoffs — append-only continuity log between sessions

License

GPLv3. See LICENSE.

Original aasdk proto definitions copyright (C) 2018 f1x.studio (Michal Szwaj), licensed under GPLv3.

Credits

• Michal Szwaj / f1x.studio -- original aasdk protobuf definitions that form the foundation of this collection
• OpenAuto Prodigy community -- protocol research, live capture analysis, and field annotation
• SonOfGib -- maintained aasdk fork with additional protocol work