About andreknieriem/open-headunit
andreknieriem/open-headunit is an open-source project on GitHub, mainly written in Kotlin. Headunit App for displaying Android Auto It currently holds 3,386 stars and 332 forks with 75 open issues, and was last pushed on 2026-11-16 (repository created 2025-10-28).
Project Overview
Git Homed tracks it on the Today's Trending board, currently at rank #80 with 31 new stars today.
GitHub Repository Details
README
Open Headunit
Open Headunit is an Android app that allows you to turn your Android tablet or phone into an Android Auto receiver. This project is a revived version of the original headunit project by the great Michael Reid. The original project can be found here: https://github.com/mikereidis/headunit
It runs on Android 4.1 and newer (Android 5.0 and newer for the Play Store build). Besides the stores above, you can download APKs from the Releases page.
Contents: How to use · Known Issues · Planned · Changelog · Contributing
NOTE!
Android Auto 17.4 and newer can prevent legacy wireless triggers from launching projection, including Self-Mode and automated startup via Wireless Helper. Rooted devices have a workaround: re-enable Android Auto's wireless startup receiver. Use a USB wireless dongle, Native Mode or the Headunit Server instead. Wireless Helper works up to Android Auto 17.3, or on 17.4+ with the root workaround. See Wireless Connection Options.Screenshots
How to use
Check out the Wiki for detailed documentation, setup guides and troubleshooting!Wired USB Connection
- Connect your Android device (phone) to the tablet running Open Headunit via USB cable.
- Make sure that Android Auto is installed on your phone.
- Set your phone to Host-Mode if necessary and select Android Auto
- Click the USB Button in Open Headunit, find your phone and click the right button to allow connection
- Click on your phone in the list and wait for Android Auto to start
Wireless Connection Options
Choose from the five options below depending on your Android Auto version and setup:1. USB Wireless Android Auto Dongle (Most Reliable)
- A standard hardware USB Wireless Android Auto Dongle (plugged into the headunit) handles the entire wireless negotiation independently.
- Provides seamless plug-and-play connection regardless of phone Android Auto version.
2. Native Mode (Wi-Fi Direct / Headunit Hotspot)
- Directly communicates with Android Auto's native wireless protocol without helper apps.
- Supports Wi-Fi Direct (P2P) or the Headunit Hotspot transport.
- Configure under Open Headunit Settings -> Wireless Connection -> Wireless Mode -> Native.
- Native Mode starts over Bluetooth, then moves to WiFi. Detect automatically fits most units. Units that keep Bluetooth on a separate module, or that use a relay, take one of these routes:
- ZLink module (experimental): units with a ZJ/ZLink Bluetooth service on port 3152.
- ZJ socket: Unisoc units whose module uses
/dev/socket/zj_bt_socket. - FYT BLINK module (experimental): FYT units with a separate module, such as DUDUAUTO on DUDUOS.
- HCT service: units with a verified HCT Bluetooth service, without root. The app detects it by itself.
- ESP32 relay: an original ESP32 relays the handshake. Firmware: aa-native-bt-broker-for-openheadunit.
3. Headunit Server (No-Root Option for Self-Mode on AA 17.4+)
- Starts the native Android Auto developer server directly on your phone or on the same device (Self-Mode).
- Setup:
4. Wireless Helper
- Our companion app triggers the wireless connection automatically in the background.
- Compatibility: Android Auto v17.3 and below, or v17.4+ with the root workaround in option 5.
- Download: Wireless Helper on Google Play Store
- Setup: Set Open Headunit Wireless Mode to Wireless Helper, ensure both devices are in the same network or Wi-Fi Direct group, and start the service in the Wireless Helper app.
5. Root Workaround for Android Auto 17.4+
On a rooted device running Android Auto, one shell command restores the previous wireless startup flow, so Wireless Helper keeps working. See the command and its limits.Optional automatic Wi-Fi scan pause
This is a setting, not a way to connect. On Android 8 and newer, Open Headunit can pause Android's automatic Wi-Fi searches during a Native wireless connection, through Shizuku. It is off by default. See the setup and limits per Android version.Connect Wirelessly via Intent (Power Users)
You can trigger a wireless connection attempt using an Android Intent. This is useful for automation tools like Tasker, MacroDroid, or via ADB.URI Scheme: headunit://connect?ip=<PHONE_IP>
Example ADB Command:
adb shell am start -a android.intent.action.VIEW -d "headunit://connect?ip=192.168.1.25"
The Automation guide lists every command.
Known Issues
- Google Maps in Portrait Mode: Touch interactions (searching, scrolling) within Google Maps may not work as expected when using Portrait Mode on some devices. Fix: Try reducing the Pixel density (DPI) setting to below 200 (e.g., 190) in the app settings. This often restores full functionality.
- Wireless Connection Drops: If the connection drops frequently, disable "WiFi Assistant" or "Switch between networks" in your phone's WiFi settings to prevent it from killing the connection due to "no internet." Check battery saving options.
- Self-mode on Android 10 (Q) and below: Google has disabled the automatic wireless projection startup for Android 10 and below in Android Auto versions 16.4 and higher. While Self-mode still works on newer Android versions, it is normally impossible to trigger projection on Android 10 and below directly with recent Google app updates. Workaround: You can still use Self-mode on these devices by starting the built-in Android Auto Headunit Server and connecting via Wi-Fi mode (loopback). See the Troubleshooting Guide for step-by-step instructions.
- WiFi Direct takes a long time to connect: One user traced this to Google Assistant in Android Auto. With Gemini on newer Android Auto versions it runs smoothly again. We do not know why.
- Stuck on "Android Auto is starting": Check your video codec in the settings, and set it to H.264 if your device does not support H.265. Some devices have a broken H.265 decoder, which leaves the app stuck on this message.
Planned
- more customization options for the UI and the app itself
Changelog
4.0.0
- New Homescreen, favorites under the card on 16:9 units, and drawer tabs for shortcuts, thanks to @andrecuellar
- Home: a separate switch for the widgets, and a panel opacity slider
- Settings: redesign the screen in Material 3 and make the accent blue, thanks to @andrecuellar
- Settings: a help button on every setting, sections ordered by use, a rail that folds to its icons, and one Bluetooth choice for Native AA
- Settings: remove the Fake Speed switch that did nothing, thanks to @teodortomas
- Wizard: test the decoder before recommending settings, thanks to @andrecuellar
- Status pill: stop saying Android Auto is starting when nothing is, thanks to @andrecuellar
- Added: Night overlay and gesture settings, with ILL+ calibration for the car_mode signal, thanks to @Anton111111
- Gestures: keep two-finger gestures off Android Auto, add edge taps, a two-finger swipe down, a dimmer and more overlay settings, thanks to @o-jcardenass and @Anton111111
- Added: Device-specific settings for Adayo (Haval) head units, thanks to @Anton111111
- Added: Scaling for the exit dialog, thanks to @Anton111111
- Automation: end the session when the charger is removed, turn the screen off and on, and connect a phone by name or MAC
- Overlay: show the head unit's battery, free memory and WiFi signal
- Native AA: connect faster
- Added: Bluetooth relay (ESP32) for Native AA, thanks to @kendrickkim
- Native AA: carry the handshake over the ZJ Bluetooth socket on Unisoc units, thanks to @justme-justus
- Native AA: support confirmed HCT Bluetooth bridges without root, thanks to @emotionbug
- WiFi Direct: detect a wedged P2P stack and offer a WiFi restart, and remember a unit that refuses every banded group, thanks to @mark-alexander-hub
- WiFi: Pause automatic searches during wireless sessions with Shizuku, thanks to @emotionbug
- Wireless: keep owned WPP channels across a projection Exit, and fix legacy Wi-Fi Direct metadata and cleanup callbacks, thanks to @emotionbug
- Hotspot: start tethering once, so auto-enable no longer tears down its own access point, thanks to @Duzttt
- Bluetooth auto-disconnect: end the session when the phone closes the held channel, thanks to @mohammed-just
- Bluetooth: open the app on units without a Bluetooth manager, and check ZBT reachability without activating the module, thanks to @emotionbug
- Bluetooth: apply XYAuto media policy automatically during wireless projection, thanks to @emotionbug
- USB: stop the permission dialog that comes back on every connect, let a plug-in leave the phone alone, and recover a lost link
- Fix(usb): Resolve dongle AOA switching
- AAP: send one version request over TCP, so a slow head unit server is not left deaf
- AAP: Keep media and navigation display updates off the receive path, and preserve frame boundaries during handshake, thanks to @emotionbug
- Video: Add H.264 support to bundled FFmpeg, reduce decoder polling and preserve recovery ownership, thanks to @emotionbug
- Projection: keep the decoder through a short cover, thanks to @andrecuellar
- Projection: fill the screen with a SurfaceView below Android 7
- Display: size Automatic DPI to the panel, and keep the widescreen layout it already had
- UI: respect system insets and refresh forced-scale projection geometry, thanks to @emotionbug
- Audio: Reduce renderer work, add independent music correction, and keep microphone foreground ownership across service starts, thanks to @emotionbug
- Audio: tap a channel's percentage to type an exact value, and raise the amplification ceiling to 250%, thanks to @teodortomas
- Android 4.x: keep GPS location resends and Self-ADB working on older versions, thanks to @emotionbug
- Fix: crash on ROMs that lack Activity.isDestroyed, and in the WiFi restart switch and the OEM app dialog on Android 4.2
- Updates: offer only a release whose APK is uploaded
- Translations: rewrite every locale against Android's own translations, and add the Wi-Fi scan screen, the Bluetooth relay screen and 17 other strings that were English only
- Logs: name captures OHU_Log_ instead of HUR_Log_, thanks to @teodortomas
v.3.5.0
- Native AA: reconnect to a network that is still there, wake the phone over Bluetooth or the external module, bring a lost group or hotspot back after sleep, boot or ACC wake, stop advertising an address that moves, and pick, wake or hold back only for a phone that is on
- Wireless: BSSID recovery via IPv6 EUI-64, keep the station stood down mid-session, hold every automatic bring-up while the unit is asleep, and log a refused start at boot instead of crashing
- Added: Option to use Open Headunit as a launcher, thanks to @amp3r1 for some improvements
- Added: Simplified Chinese 🇨🇳, Indonesian 🇮🇩, Hindi 🇮🇳, Thai 🇹🇭, European Portuguese 🇵🇹
- Connection: one attempt at a time, hold auto-connect behind settings and the pill's X, and fix the dongle's TLS handshake
- Add on-demand "Check for Updates" button
- Add FYT BLINK/DUDUAUTO module transport for Native AA thanks to @dohun0310
- Added: Apps drawer, thanks to @amp3r1
- Navigation: stop the road name from sticking after the road changes
- Self Mode: release the dummy VPN once the session is up, and start none for Android Auto 17.4 and later
- Video: no codec on a dying surface, a picture after a screen-off return in Texture mode, and a 720p fallback the phone can pick on a 2.4 GHz link
- Automation: restore the three dropped automation commands, and stop Headunit Server connects preempting each other
- Fix: crash when the USB service is missing, thanks to @muayyad-alsadi
- Added: Performance overlay with its own settings screen, choose which lines it shows
- Added: Root workaround for Android Auto 17.4+ wireless startup in the README, thanks to @mixalbl4-127
- Wireless: request low-latency Wi-Fi during projection, and keep active WPP control connections with isolated listener generations, thanks to @emotionbug
- Audio and mic: stabilize playback and AAC recovery with opt-in AAudio, honor the device's buffer minimum, smooth PCM transitions, isolate capture sessions and bound uplink flow control, thanks to @emotionbug
- Protocol and TLS: unify AAP framing and message reassembly, keep payloads across application-phase control records, and send the final ByeBye first, thanks to @emotionbug
- Connection: serialize session replacement, reconnect audio settings, cancel obsolete reconnect timers, and keep Nearby tunnels within their attempt, thanks to @emotionbug
- Video: isolate decoder workers and retire activity-owned surfaces, thanks to @emotionbug
- Floating button fixes and a connection status option, thanks to @Sesam17
- USB: recover a stale phone without a replug, keep the phone's Media audio on if you choose, and stop reconnecting when no screen comes up
- Settings: Exit in Android Auto ends the session again, Save writes only what changed, and the setup wizard sets the DPI again and asks for the vehicle type
- Updates: open the release APK itself on units below Android 5.0
- Audio: no more stutter or crackle with the Mgear Mstick4 dongle (firmware 1.9.4), thanks to @emotionbug
- Self Mode: leave the media buttons and the media widget to the phone's own player, thanks to @Duzttt
- Keymap: send letter keys to Android Auto, and give the night mode key its own entry, thanks to @Duzttt
- Home: grey out the connection buttons you did not choose, thanks to @amp3r1
- Night mode: new "Automatic (System)" option follows the system dark mode, thanks to @MohmmadQunibi
- Settings: Enter saves a text dialog when the keyboard covers its buttons, thanks to @mohammed-just
- DPI: fix the reduced Android Auto layout on small screens
v.3.4.0
- USB: connect non-Pixel phones without fighting a fast-reverting dongle
- Feat/automation command surface
- Video-Fit and ultrawide touch enhancements with dynamic scaling and rework all the options, thanks to @o-jardenass and @Sesam17
- Several enhancements for native mode, thanks to @o-jardenass
- Added darkmode for splashscreen
- Added ADB-Server to disable/close OEM apps like Zlink, Autokit etc. to reduce conflicts with OpenHU
- Added Support for BYD Steering wheel keys, thanks to @nicoruy
- Added floating Exit Button, thanks to @Sesan17
- Added Log to clipboard, thanks to @peter9811
- Native for External BT's + Connection Status pill + AAC improvements to @o-jardenass
- Moved Ui-Scale to theming
- Native AA: say when the unit's WiFi radio is off instead of retrying in silence
- Fix: Endless Loop in Permission Requests.
- Give Video its own transport thread
- Stop old Android promising what it cannot do
- Measure and size the audio sink
v.3.3.1
- Added: Option to auto-resume media playback on quick reconnect if music was playing before disconnect
- Fixed: Errors shown in playconsole
- Big Improvements to native mode. Huge Thanks to @o-jcardenass for this!
v.3.3.0
- Begin for theming of the App.
- Refactor WiFi-Code from AapService into their own classes for better maintenance, thanks to @MrEAlderson
- Refactor Self-Mode and USB-Mode from AapService into their own classes for better maintenance, thanks to @MrEAlderson
- Refactor Audio and Video Code from AapService into their own classes for better maintenance, thanks to @o-jcardenass
- USB-Blacklist Filter to prevent the app from asking for non Android phones
- Added: Option to disable the clock, thanks to @MrEAlderson
- Added: French translation 🇫🇷 thanks to @phiDu-fr
- Fix/session lifecycle and video concealment
- Video: pace the transport thread instead of shedding reference frames
- UI: a destroyed activity stops listening, and a recycled row keeps its subtitle
- Fix Android 4 Problems
- Fix Orientation issues
- Several Native Mode fixes and enhancements
- Mic: fix the uplink, and let the phone keep the microphone
- Fix: Close keyboard that stays open on older Android versions to prevent layout issues
- Per-channel audio stream selection, thanks to @nicoruy
- Added Android Auto 17.4 Notice for users, who don't know why their wireless setup broke
- Clean Up Dark Mode and Theming Option confusions
- Fix: Projection dies when a Bluetooth keyboard connects or disconnects
v.3.2.6
- Fix settings UI crash and dpi input on older Android devices
- Fix video artifacts
- Fixing wireless stack where failures stay broken until restart
- Bringing back old style USB List
- Fix broken theme after import: Reapply Theme selection after Settings import
- Make HUD Mode for apply for the whole app
v.3.2.5
- Fix black screen after backgrounding, and the washed-out picture a dropped frame leaves
- Fix headunit server socket leak
- Car GPS: deliver the head unit's fix when the phone asks, and keep it flowing
v.3.2.4
- Fix: Video and audio never catch up after a wireless link stall, thanks to @o-jcardenass
- Fix: Native AA wake poke takes down the head unit's own hands-free link, thanks to @o-jcardenass
- Stop the setup wizard from overwriting the reported manufacturer, thanks to @o-jcardenass
- Added: Let the Bluetooth side keep the media buttons, thanks to @o-jcardenass
v.3.2.3
- Adding custom log location (App folder or Download folder)
- additional fixing for the fps/freeze problems. Thanks to @o-jcardenass and @andrecuellar for helping
- Fix/hotspot unreadable config
- NativeAA: show when a P2P group that lands on channel 12 or 13
v.3.2.2
- Fixing location jumping, especially on lower speeds
- Fixing screen flicker again in video decoder
- Fix/video throughput telemetry and keyframe lockout, thanks to @o-jcardenass
- Fix Steering Wheel Buttons not working anymore
- added new native mode without WiFi-Direct creation, thanks to @o-jcardenass
v.3.2.1
- Fixing new welcome screen reappears, thanks to @andrecuellar
- Fixing screen flicker every 10s thanks to @o-jcardenass
- Fixing HW decoding on kitkat thanks to @o-jcardenass
- Fixing 2 Fatal errors shown in play console
- fix: move mic timestamp inside encrypted payload (byte 4), thanks to @bruno303
- making native mode work better and on more devices, thanks to @o-jcardenass
v.3.2.0
- Don't grab audio focus on connect in dynamic mode, thanks to @bnayahu
- Acquire transient audio focus while AA audio plays, thanks to @bnayahu
- Add GitHub Actions CI (build + unit tests), thanks to @bnayahu
- Fix picture stuck if used within DUDU's PiP, thanks to @MrEAlderson
- Fix(wifi): use public API for frequency, thanks to @DerTeufel
- Added pixel aspect ratio setting, thanks to @axel92b
- Added more audio features to gain audio focus and work with dsp headunits as setting
- Added display over other apps permission for better compatibility with some headunits, espacially with self mode
- Fix transport get stucked on multiple reconnects, thanks to @notathf
- Add car keys support for FYT headunits, thanks to @MrEAlderson
- Added Option to flip projection horizontal for Headup-Displays
- Recover automatically from post-first-frame video display stalls, thanks to @andrecuellar
- Settings and Onboarding Wizard redesign for better usability, thanks to @andrecuellar
- Fixing mulitiple WiFi-Direct and Native AA connection issues, thanks to @o-jcardenass, @andrecuellar and @notathf
- Various fixes PR, thanks to @MrEAlderson
- Selfmode on AA 17.4 now connects to the headunit dev server or opens the AA settings to start it
- Rename the app to Open Headunit because of confusion with Headunit Reloaded (HUR)
v.3.1.1
- Reduce pressure on sensor events like night and gps and start/stop these events in onConnected, onDisconnect and onDestroy
- Merged ffmpeg PR #625 by @mmwtl. This added ffmpeg software decoder for h265, which old devives could benefit a lot. Thank you!
- Wi-Fi Direct changes. Prevent duplicate start, graceful resets, cleaned up stale groups
- Remove Automatic Play Integrity Checks, so Playstore won't check the license and link to the playstore in headunits
- Added manual bssid for native Mode. This should help for users where the bssid is hidden for the app, thanks to @rakshan-kumr
- Added immediately network scan with wifi connection, thanks to @MrEAlderson for the PR
v.3.1.0
- Added libusb as alternative to the native usb stack for better compatibility with some devices
- Fixed Layout in Portrait Mode in nearly square devices
- Added Scale Slider for loading screen media
v.3.0.1
- Fixed: App Exit on Disconnect
- Enhanced: USB Workflow. This will hopefully eliminate some random usb disconnects
- Fixed keyboard input on Android < 6 Devices
- Enhanced WiFi Direct-Mode
- Enhanced File Selector for some devices
- Fixed some fatal errors, showing in play console
v.3.0.0
- Added: Custom loading screen (image/GIF/video), thanks to @andrecuellar
- Added: Settings-Reset Button, if you mess up something in the settings, you can now reset them to default
- Removed: Old deprecated ssl library written in C-Code for better maintenance, stability and smaller file sizes
- Added: Direct Logging to file without logcat, thanks to @Anton111111
- try to fix connection lost on carrier lost again
- keep usb disconnection for 8s alive, for