Skip to content

Installation

Eugene Chefranov edited this page Nov 14, 2026 · 12 revisions

Installation

Back to the README. Check Compatibility first, and read Recovery before you start.

Get the release

Download the …-sd.zip of the latest release from Releases. It holds one folder, mod, laid out the way the card needs it:

mod/custom.sh
mod/command.sh            <- M.I.B. V3.6 and later run this one
mod/carplay/install.sh
mod/carplay/uninstall.sh
mod/carplay/VERSION
mod/carplay/bin/...

The release also lists a SHA256SUMS, with the archive and every payload file, to check a download against.

Use the release archive rather than a copy of the repository. The archive's scripts always have LF line endings. A repository copy checked out on Windows with CRLF breaks every script on the unit:

: cannot execute - No such file or directory
: unknown option
install.sh[21]: set:

Install A — network cable

Prerequisites, both from the M.I.B. menu:

  1. Advanced Settings → Info USB Ethernet devices → Install devices (again)
  2. Advanced Settings → Install SSHD (put your id_rsa.pub in the card's Custom folder first)

Plug the USB-Ethernet adapter in; the unit comes up on 172.16.250.248.

# from your machine, in the folder that contains the unpacked mod/
ssh root@172.16.250.248 'mount -uw /mnt/app; mkdir -p /mnt/app/root/carplay'
scp -O -r mod/carplay/* root@172.16.250.248:/mnt/app/root/carplay/
ssh root@172.16.250.248 'sh /mnt/app/root/carplay/install.sh'

Do not stage the files under /tmp. On this unit /tmp is a symlink to /dev/shmem, a flat shared-memory filesystem that has no directories at all — mkdir /tmp/carplay fails with Function not implemented. Any writable spot on /mnt/app works; the line above uses /mnt/app/root/carplay.

(-O is needed on recent macOS/OpenSSH, which defaults to SFTP; the unit only speaks the legacy SCP protocol. Older systems: drop it. If the unit's host key is rejected, add -o HostKeyAlgorithms=+ssh-rsa -o PubkeyAcceptedKeyTypes=+ssh-rsa.)

Then reboot the unit.

Install B — M.I.B. SD card

Install M.I.B. on the unit first, following its own instructions. After that M.I.B. lives on the unit, and its card is no longer needed.

Copy the mod folder from the release archive to the root of a FAT32 card. That can be the card you installed M.I.B. from or a fresh one, in either slot, because the script finds its own location. Eject the card safely, since a card pulled without ejecting can mount read-only. On a Mac, don't drop the folder over an existing mod folder: Finder replaces the folder rather than merging the two.

To install without route guidance (and so without the cluster map, which rides on it), put an empty file at mod/carplay/NO_RGI. For everything but the cluster map, an empty /mod/carplay/NO_ALTSCREEN. With a wireless adapter that does not ask for the cluster screen (the Carlinkit 2Air), an empty /mod/carplay/WIRELESS_MAP offers it the cluster map anyway — see below. The parking popup beside CarPlay is off by default; an empty /mod/carplay/PDC installs it, and only on P5089 and Q2 P5088, the firmware it was checked against. Other firmware carries other versions of the HMI classes it replaces, and there it keeps the unit on the start logo. An empty /mod/carplay/ETA_DEFAULT starts the line under the maneuver on the arrival time instead of the next street. The files combine.

Insert the card and run Advanced Settings → Run Custom Script — on M.I.B. V3.6 and later the item is Advanced Settings → Run individual script, which runs /mod/command.sh; that file only hands over to custom.sh. Either way it locates the payload, installs, and prints what it did. "Nothing to do!" means /mod/command.sh is not on the card. "it is all done!" alone, with no install log above it, means the script did not reach custom.sh — do not write your own command.sh with /mod/... paths: on the unit the card is /net/mmx/fs/sda0, not /.

Then reboot the unit: hold the MMI's button combination until the screen goes dark (on the A3/S3 8V, NAV/MAP + RADIO + the big rotary knob).

To uninstall this way, create an empty file /mod/carplay/UNINSTALL on the card and run the same menu item again.

Give the writes a moment before rebooting — the installer calls sync and waits, but a forced reboot immediately afterwards can still leave a file truncated, and you will be left wondering why nothing loaded.

Manual install — no scripts

Nine commands on the unit. Do this if the scripts give you trouble, or if you would rather see every change go by.

mount -uw /mnt/app
mount -uw /mnt/system

# 1. the jars
cp bin/dpad_hook.jar     /mnt/app/eso/hmi/lsd/jars/
cp bin/coverart_hook.jar /mnt/app/eso/hmi/lsd/jars/
cp bin/pdc_hook.jar      /mnt/app/eso/hmi/lsd/jars/   # only on P5089 / Q2 P5088 (#27)

# 2. the native hook
mkdir -p /mnt/app/eso/hmi/lib
cp bin/libcarplay_hook.so /mnt/app/eso/hmi/lib/

# 3. make them readable (a jar lsd cannot read is skipped silently)
chmod 755 /mnt/app/eso/hmi/lsd/jars/dpad_hook.jar \
          /mnt/app/eso/hmi/lsd/jars/coverart_hook.jar \
          /mnt/app/eso/hmi/lsd/jars/pdc_hook.jar \
          /mnt/app/eso/hmi/lib/libcarplay_hook.so

# 4. back up the one config you are about to edit
cp /mnt/system/etc/eso/production/smartphone_integrator.json \
   /mnt/system/etc/eso/production/smartphone_integrator.json.orig

Then edit the config — vi is on the unit:

vi /mnt/system/etc/eso/production/smartphone_integrator.json

Search for IPL_CONFIG_DIR_DIO_MANAGER (/IPL_CONFIG_DIR_DIO_MANAGER then Enter). It appears exactly once, on the carplay child's envs line. Add one entry at the end of that array, so the line ends like this:

… "IPL_CONFIG_DIR_DIO_MANAGER=/etc/eso/production", "LD_PRELOAD=/mnt/app/eso/hmi/lib/libcarplay_hook.so"],

Save and quit (:wq), then sync, wait a few seconds, and reboot.

Only want the touchpad D-pad? Step 1's first line plus its chmod is the whole install — no hook, no config edit.

Route guidance, by hand

Route guidance is independent of the config edit above: it does not touch smartphone_integrator.json at all. It needs its jar and hook, the renderer with its atlas and compiled shaders, a supervisor script, and a shim in front of mm-ipod.

# 1. the jar and the hook
cp bin/rgd_hook.jar   /mnt/app/eso/hmi/lsd/jars/
cp bin/librgd_hook.so /mnt/app/eso/hmi/lib/
chmod 755 /mnt/app/eso/hmi/lsd/jars/rgd_hook.jar /mnt/app/eso/hmi/lib/librgd_hook.so

# 2. the renderer, its texture atlas, the transparent placeholder bitmap and
#    the four compiled shaders
cp bin/maneuver_render /mnt/app/eso/hmi/lib/maneuver_render
chmod 755 /mnt/app/eso/hmi/lib/maneuver_render
cp bin/flag_atlas.rgba bin/rgd_blank.png /mnt/app/eso/hmi/lib/
mkdir -p /mnt/app/eso/hmi/lib/shaders
cp bin/shaders/*.bin /mnt/app/eso/hmi/lib/shaders/

# 3. keep the real mm-ipod, under its own name
mkdir -p /mnt/app/armle/usr/sbin/rgd_real
cp -p /mnt/app/armle/usr/sbin/mm-ipod /mnt/app/armle/usr/sbin/rgd_real/mm-ipod
cp -p /mnt/app/armle/usr/sbin/mm-ipod /mnt/app/armle/usr/sbin/mm-ipod.orig

Then write the supervisor with vi /mnt/app/eso/hmi/lib/rgd_render_sup.sh. It keeps exactly one renderer alive, starts the cluster map's own supervisor when that is installed, and exits when the off switch appears:

#!/bin/sh
BIN=/mnt/app/eso/hmi/lib/maneuver_render
LOG=/dev/null
LOCK=/dev/shmem/rgd_render_sup.pid
LD_LIBRARY_PATH=/mnt/app/eso/hmi/lib:/eso/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
cd /mnt/app/eso/hmi/lib 2>/dev/null
[ -f /mnt/app/rgd_disable ] && exit 0
if [ -f "$LOCK" ]; then
    read old < "$LOCK"
    if [ -n "$old" ] && kill -0 "$old" 2>/dev/null; then exit 0; fi
fi
echo $$ > "$LOCK"
[ -x /mnt/app/eso/hmi/lib/altscreen_sup.sh ] && /mnt/app/eso/hmi/lib/altscreen_sup.sh &
while [ ! -f /mnt/app/rgd_disable ]; do
    "$BIN" >> "$LOG" 2>&1
    sleep 2
done
rm -f "$LOCK"

chmod 755 /mnt/app/eso/hmi/lib/rgd_render_sup.sh, then write the shim with vi /mnt/app/armle/usr/sbin/mm-ipod, replacing the binary with exactly this:

#!/bin/sh
[ -f /mnt/app/rgd_disable ] || LD_PRELOAD=/mnt/app/eso/hmi/lib/librgd_hook.so
export LD_PRELOAD
[ -f /mnt/app/rgd_disable ] || [ ! -x /mnt/app/eso/hmi/lib/rgd_render_sup.sh ] || \
    /mnt/app/eso/hmi/lib/rgd_render_sup.sh &
exec /mnt/app/armle/usr/sbin/rgd_real/mm-ipod "$@"

chmod 755 /mnt/app/armle/usr/sbin/mm-ipod, then sync and reboot.

The real binary has to keep the name mm-ipod inside rgd_real/: the hook only arms itself when argv[0]'s basename is that, so a renamed copy loads the library and then does nothing.

CarPlay map in the cluster, by hand

On top of route guidance and the config edit above (it lives in the same hook):

cp bin/altscreen_render bin/altscreen_sup.sh /mnt/app/eso/hmi/lib/
chmod 755 /mnt/app/eso/hmi/lib/altscreen_render /mnt/app/eso/hmi/lib/altscreen_sup.sh
mkdir -p /mnt/app/eso/hmi/lib/altscreen_shaders
cp bin/altscreen_shaders/*.bin /mnt/app/eso/hmi/lib/altscreen_shaders/
touch /mnt/app/altscreen_inject

sync and reboot.

Turning route guidance off without uninstalling

mount -uw /mnt/app
touch /mnt/app/rgd_disable

Reboot. Both halves read that file: the shim skips the LD_PRELOAD, and the HMI patch returns before it starts anything, so the cluster keeps its own navigation exactly as stock. Delete the file and reboot to turn it back on. Cover art and the D-pad are not affected.

Installing without it in the first place: RGI=0 sh install.sh on the network route, or the NO_RGI marker on the card.

The CarPlay map in the cluster: on and off

A long press of the left steering-wheel roller swaps the cluster between the CarPlay map and the stock one; the choice survives the ignition. To take the map out altogether, run the installer again with ALTSCREEN=0 (or the NO_ALTSCREEN file on the card): it removes the map's files and leaves everything else.

Wireless adapters. The phone draws the cluster map only when the head unit offers it a second screen, and it is offered to whoever asks for it. A cable and most adapters ask; some, such as the Carlinkit 2Air (#25), do not, and then there is no map in the cluster. WIRELESS_MAP=1 sh install.sh (or an empty WIRELESS_MAP file on the card) offers it regardless. It is off by default: an adapter that cannot handle a second screen may take it for its main one and show a broken picture. If that happens, install again without it.

What the installer changes

Path Change Backup
/mnt/app/eso/hmi/lsd/jars/rgd_hook.jar new file (route guidance) — (delete to undo)
/mnt/app/eso/hmi/lib/librgd_hook.so new file (route guidance) — (delete to undo)
/mnt/app/eso/hmi/lib/maneuver_render new file, the renderer — (delete to undo)
/mnt/app/eso/hmi/lib/rgd_render_sup.sh new file, keeps one renderer alive — (delete to undo)
/mnt/app/eso/hmi/lib/flag_atlas.rgba new file, texture atlas — (delete to undo)
/mnt/app/eso/hmi/lib/rgd_blank.png new file, transparent placeholder — (delete to undo)
/mnt/app/eso/hmi/lib/shaders/ new directory, four compiled shaders — (delete to undo)
/mnt/app/eso/hmi/lib/altscreen_render new file, the cluster map's renderer — (delete to undo)
/mnt/app/eso/hmi/lib/altscreen_sup.sh new file, keeps it running — (delete to undo)
/mnt/app/eso/hmi/lib/altscreen_shaders/ new directory, three compiled shaders — (delete to undo)
/mnt/app/altscreen_inject new empty file, switches the cluster map on — (delete to undo)
/mnt/app/eso/hmi/lib/rgd_frames/ deleted if an earlier release left it, ~90 MB freed — (gone for good; reinstall an old release to get it back)
/mnt/app/armle/usr/sbin/mm-ipod replaced by a shim that preloads the hook mm-ipod.orig, plus the real binary at rgd_real/mm-ipod
/mnt/app/eso/hmi/lsd/jars/coverart_hook.jar new file — (delete to undo)
/mnt/app/eso/hmi/lsd/jars/dpad_hook.jar new file — (delete to undo)
/mnt/app/eso/hmi/lsd/jars/pdc_hook.jar new file (parking sensors beside CarPlay), only with PDC=1, and only on P5089 / Q2 P5088 — (delete to undo)
/mnt/app/eso/hmi/lib/libcarplay_hook.so new file — (delete to undo)
/mnt/system/etc/eso/production/smartphone_integrator.json one LD_PRELOAD entry added to the carplay child's envs …json.orig, written once
/mnt/app/eso/hmi/lsd/jars/NavActiveIgnore.jar renamed to ….carplay-off if M.I.B. put it there renamed back by uninstall

mm-ipod is the one stock binary that is replaced, and it lives on /mnt/app, not on the flash partition; the installer keeps two copies of the original before touching it. Everything else is a new file. The edit is line-based on purpose: the file is JSON with # metadata and ## comment lines that any JSON rewriter would silently drop, and it is written through the existing file rather than replacing it, so the config keeps its own mode and owner.

Permissions. The installer chmod 755s everything it copies. This matters on the SD card path: FAT32 carries no Unix modes, so a jar can land unreadable, and lsd skips a jar it cannot read without logging anything — you would see no patch and no error. Stock files in that directory are -rwxrwxrwx root:root. The installer prints an ls -l of the three files at the end so you can check. Nothing on the card needs the executable bit: custom.sh is invoked as sh custom.sh, and it calls the other scripts the same way.

The jars need no loader change — lsd.sh already scans /mnt/app/eso/hmi/lsd/jars/ and puts what it finds on the bootclasspath ahead of lsd.jxe, which is what lets a patched class win over the stock one.

Upgrading

Just run install.sh again — there is no need to uninstall first. It overwrites the files, keeps the .orig backup it already made, and leaves the config alone once our LD_PRELOAD entry is there. A part you leave out this time (RGI=0, ALTSCREEN=0) that an earlier install put there is taken off, so no old version keeps running beside the new one. The hook is put in place with rename, so an upgrade does not disturb a dio_manager that happens to be running; the new one takes effect at the next start.

Reboot afterwards, as with a first install.

Uninstall

ssh root@172.16.250.248 'sh /mnt/app/root/carplay/uninstall.sh'

or the UNINSTALL marker file described above. Reboot afterwards. The .orig backup is deliberately left behind; remove it by hand if you want no trace.