Repository navigation
Installation
Back to the README. Check Compatibility first, and read Recovery before you start.
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:
Prerequisites, both from the M.I.B. menu:
Advanced Settings → Info USB Ethernet devices → Install devices (again)-
Advanced Settings → Install SSHD(put yourid_rsa.pubin the card'sCustomfolder 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 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
syncand waits, but a forced reboot immediately afterwards can still leave a file truncated, and you will be left wondering why nothing loaded.
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.origThen edit the config — vi is on the unit:
vi /mnt/system/etc/eso/production/smartphone_integrator.jsonSearch 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 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.origThen 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.
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_injectsync and reboot.
mount -uw /mnt/app
touch /mnt/app/rgd_disableReboot. 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.
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.
| 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.
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.
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.