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.
248 .proto files organized into 20 categories covering the full AA protocol surface: session control, audio/video streaming, input, sensors, navigation, Bluetooth, WiFi projection, car control, radio, and more.
Architecture overview: These definitions describe services carried by the Android Auto multiplexed protocol. For framing, SDP binding, and capability negotiation, see the Channel Architecture Reference.
These definitions were reverse-engineered from Android Auto firmware (APK v16.1 through v17.3) and extended from f1x.studio's aasdk (Michal Szwaj's original Android Auto SDK). The collection is predominantly proto2, with a proto3 subset for enum wrappers and newer types. Per-file syntax declarations are authoritative. The repository adds dozens of previously undocumented messages and 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.
Version tags publish an orphan dist branch containing only this README,
LICENSE, and oaa/**/*.proto. Documentation links in this file point back to
the full main branch so they remain usable from that minimal snapshot.
- Added the audited Android Auto 17.3 protocol surface, including blended/multi-display UI configuration, modern media and service markers, car-intent support, critical-UI and integrated-overlay payloads, and newer navigation and vehicle-energy structures.
- Added GAL-gated behavior documented for downstream rollout: GAL 4.3 display/video additions; GAL 5.0 extended AV/audio start data; GAL 5.1 standalone audio
MediaOptionsandVehicleEnergyForecast; and GAL 6.0 video media options and optional modern codec paths. - Renamed
AVChannel.channel_idtodisplay_idat the existinguint32field 6 and changed AV stream fields to the correctMediaCodecTypeenum. These preserve their wire tags and wire types but require regeneration and generated-source updates. - Corrected
ChannelDescriptorfields 16 and 17 to the audited car-local-media and buffered-media service markers and added car intent at field 18. The wire type remains length-delimited, but consumers of the earlier incorrect field meanings must update their service bindings. - Corrected AV message-ID names and assignments through
0x8015;0x8010remains reserved/unknown.
Definitions carry confidence: comments. gold, silver, and bronze record
decreasing levels of corroboration; unverified marks a candidate awaiting
evidence; and retracted marks preserved research history that consumers must
not treat as supported Android Auto protocol. Find retracted definitions in a
distribution with:
grep -R -l -E 'confidence: retracted|RETRACTED' oaa --include='*.proto'The complete methodology is in the confidence-tier documentation.
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 |
carintent |
1 | Car intent service payloads |
common |
16 | Shared enums and base types: status codes, channel types, session info, error codes |
control |
35 | 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 |
mediabrowser |
2 | Legacy media browser message IDs and payloads |
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 |
6 | Radio channel: tuner control, presets, station metadata, band/codec enums |
sensor |
43 | Sensor channel: GPS, accel, gyro, speed, RPM, fuel, gear, HVAC, vehicle data |
verification |
2 | GAL verification and diagnostics messages |
video |
20 | Video channel: resolution, FPS, focus negotiation, display config, overlays |
wifi |
23 | WiFi projection: security, connection, version negotiation |
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.protoPython:
protoc --proto_path=. --python_out=generated/ \
oaa/sensor/GPSLocationData.proto \
oaa/sensor/SensorEventIndicationMessage.protoGo:
protoc --proto_path=. --go_out=generated/ --go_opt=paths=source_relative \
oaa/video/VideoConfigData.proto \
oaa/video/VideoResolutionEnum.protoCompile everything:
find oaa -name '*.proto' | xargs protoc --proto_path=. --cpp_out=generated/The following verification tooling lives on main and is intentionally not
part of the minimal dist branch. In a full repository checkout, create a local
test environment and run the repository verification contract:
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-test.txt
make PYTHON=.venv/bin/python verifymake PYTHON=.venv/bin/python test-integration runs the optional historical
APK-index checks. It prints explicit skips when the ignored local index
snapshots are unavailable.
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)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 |
Some newer notification, response, and buffered-media files retain audited APK names that do not use these suffixes. Their per-file package declarations are authoritative.
Import paths use the oaa/<category>/File.proto format:
import "oaa/common/StatusEnum.proto";
import "oaa/control/ChannelDescriptorData.proto";
import "oaa/video/VideoConfigData.proto";- Channel Architecture Reference — AA multiplexing, framing, SDP binding, capability negotiation
- Protocol Reference — auto-generated message catalog
- 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
- 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
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
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
How discoveries are tracked and validated:
- Confidence Tiers — Gold/Silver/Bronze scoring
- Audit Trail Format —
.audit.yamlsidecar spec - Verification Procedures — wire capture and APK validation
- Source Provenance — attribution tracking
Protocol implementation details extracted from commercial AA head units:
- APK Analysis — Python indexer scripts and pre-built SQLite databases from Android Auto APK v16.1 and v16.2
- 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
- AGENTS.md — repository workflow loop and verification expectations
- Current Roadmap —
Now / Next / Laterpriorities - Session Handoffs — append-only continuity log between sessions
GPLv3. See LICENSE.
Original aasdk proto definitions copyright (C) 2018 f1x.studio (Michal Szwaj), licensed under GPLv3.
- 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