🍏⚡ MacBook Pro Linux Revival

The Touch Bar died. So did the webcam. The MacBook didn't.

How a 2017 MacBook Pro with a dead Apple T1 chip became a fast, fully-usable
Ubuntu workstation — no macOS reinstall, every fix tested and documented.

📚 Docs (EN) · 📚 Docs (IT) · 🇮🇹 README italiano · 🐛 Report a bug

This is not a mockup. This is a software Touch Bar living on a Linux desktop,
drawn by a hand-written GNOME extension, from the login screen to shutdown:

The daily driver: Ubuntu 24.04, dock on the left, and the virtual Touch Bar living at the bottom edge.

Close-up: every key is clickable. Grey line = physical shortcut. Amber line = what the combo really does.

---

📑 Table of contents

1. The story
2. Results at a glance
3. How it works
4. Built with
5. Getting started
6. Documentation
7. War stories
8. Roadmap
9. About the author
10. License · Acknowledgments

📖 The story

What do you do when the security chip of a €3,800 laptop (1TB SSD build) dies?

On the 2016–2017 MacBook Pro, Apple's T1 chip drives the Touch Bar, the webcam, the ambient light sensor and Touch ID. When its firmware corrupts — and it survived a full power-off, an SMC reset and an NVRAM reset, so it was corrupted for good — all of that hardware dies with it. On this very machine that meant: no Esc key, no F1–F12, no brightness or volume keys, no webcam, and speakers that had never worked on Linux anyway.

Apple's answer would be a logic board replacement. This project's answer was Ubuntu 24.04, a compiler, and a methodical week of engineering:

diagnose from real data → fix with validated scripts → prove it with automated end-to-end tests → document every trap for the next person.

The result is a daily-driver laptop that boots in 5 seconds, plays music through its own speakers, and has better function-key ergonomics than it shipped with. The full journey — including the failures — is in this repo.

(back to top)

🏆 Results at a glance

	Before	After
⏱ Boot time	13.6 s	~5 s
🔊 Internal speakers	never worked on Linux	working (patched CS8409 driver, DKMS)
⌨️ Esc / F1–F12 / Delete	gone with the Touch Bar	restored on the physical fn layer (keyd)
🎚 Brightness / volume / mute	gone	fn+7…fn+', macOS-style
📸 Window screenshot	—	fn+ì, one keystroke
🧭 Back / Forward everywhere	—	fn+← / fn+→
🖥 Touch Bar	dead hardware	virtual, on-screen, login→shutdown
🔥 dGPU idle drain	9 W, fans always audible	7 W, fans at minimum
💡 Keyboard backlight	stuck off	auto-on + CLI control
🩺 SSD / battery health	unknown	verified: 0% wear / 97% health

⚰️ And what could NOT be saved — honesty required: the physical Touch Bar, the FaceTime webcam, the ambient light sensor and Touch ID all hang off the dead T1 chip and are unrecoverable without a macOS firmware restore. The full post-mortem is in hardware.md; any USB webcam works as a plug-and-play replacement.

⚙️ How it works

flowchart LR
    subgraph Physical keyboard
        FN[fn key] -->|applespi fnremap=8| RM[rightmeta]
        CAPS[CapsLock]
    end
    subgraph keyd - kernel-level remapper
        RM --> LAYER{fn layer}
        CAPS --> ESC[Esc]
        LAYER -->|1..6| FK[F1-F6]
        LAYER -->|7 8 9 0 '| MEDIA[🔆 brightness · 🔇 mute · 🔊 volume]
        LAYER -->|ì| SHOT[Alt+Print → window screenshot]
        LAYER -->|← →| NAV[Alt+arrows → back/forward]
    end
    subgraph GNOME Shell - Wayland
        EXT[Virtual Touch Bar extension] -->|Clutter virtual input| APPS[any app]
        FK --> APPS
        MEDIA --> APPS
    end

Loading

And because "it should work" is not a test: the repo ships an automated verifier that creates a virtual keyboard at kernel level (uinput), injects every combo as the physical keyboard would, and asserts the exact keycodes that come out of keyd. 13 test cases, self-cancelling side effects, zero human fingers.

(back to top)

🧰 Built with

🚀 Getting started

Target: MacBookPro14,3 · Ubuntu 24.04 · GNOME 46 on Wayland. Scripts are short, commented, and explain why inside the code. Read them first.

git clone https://github.com/paskaz/macbook-pro-linux-revival.git
cd macbook-pro-linux-revival

sudo scripts/01-system-tuning.sh        # boot 13.6s -> ~5s, snap cleanup, sensors
sudo scripts/02-keyboard-backlight.sh   # backlight on at boot + brightnessctl
sudo scripts/03-gpu-power-limit.sh      # tame the Radeon (systemd, NOT udev - see why inside)
sudo scripts/04-audio-cs8409.sh         # speakers (incl. the HWE mini-tarball trick)
sudo scripts/05-keyd-function-keys.sh   # the whole fn layer
sudo scripts/06-onscreen-touchbar.sh    # the virtual Touch Bar
sudo tests/test_keyd_mappings.py        # prove it: 13 end-to-end assertions

📚 Documentation

Every guide exists in English and Italian.

EN	IT	What's inside
keyboard.md	tastiera.md	The full mapping and how keyd + applespi cooperate
audio.md	audio.md	Why the speakers were mute and the HWE-kernel source trick
virtual-touchbar.md	touchbar-virtuale.md	The GNOME extension, design decisions included
hardware.md	hardware.md	T1 post-mortem, battery truths, SMART data
system-tuning.md	ottimizzazione-sistema.md	Boot, GPU power, the shelved Plan B

💥 War stories (the traps this repo paid for)

🌍 The Italian locale broke snap parsing

A cleanup script filtered snap list --all for the word disabled — but on an Italian system snap prints disabilitato, so it silently removed nothing. Every script here now runs with LANG=C. Lesson: never parse localized output.

⚡ The udev rule that could never fire

Capping the GPU with DRIVER=="amdgpu" in udev fails silently: at the add event the driver isn't bound yet, and no later event comes. The correct tool is a one-shot systemd unit. Lesson: know your event lifecycle.

🎹 The right Shift that pretends to be the left one

A back/forward mapping on "right Shift + arrow" passed all synthetic tests and failed on the real keyboard: this Apple keyboard reports both Shift keys as left Shift. Millisecond-level input monitoring caught it. Lesson: test on the real input path, not only the simulated one.

🦊 Firefox ignored the "correct" keys

The first navigation mapping emitted the semantically-correct XF86Back/Forward media keys. keyd emitted them perfectly — and Firefox on Wayland ignored them entirely. Alt+arrows work everywhere. Lesson: correct ≠ supported.

📦 Ubuntu ships no sources for HWE kernels

The audio driver build demands /usr/src/linux-source-<ver>.tar.bz2, which doesn't exist for HWE kernels. Solution: a sparse git clone of only sound/hda at the exact Ubuntu kernel tag (a few MB instead of 250), packed into a mini-tarball with the expected layout. Fully scripted and reusable.

👻 The test keyboard that keyd refused to see

keyd only treats a device as a keyboard if it declares all of 1-0 + QWERTY. The first minimal uinput test device was silently ignored — its raw CapsLock went straight through and locked the real keyboard in uppercase. The docstring of the test file now warns the next person.

(back to top)

🗺️ Roadmap

• Boot < 6 s
• Speakers via patched DKMS driver
• Full fn layer (F-keys, media, screenshot, navigation)
• Virtual Touch Bar from GDM to shutdown
• GPU power capping · keyboard backlight · health verification
• Bluetooth .hcd firmware extraction (full UART speed for BT audio)
• libinput palm-rejection tuning for the giant touchpad
• apple_set_os EFI hack → power the Radeon off entirely (~7 W more)

👤 About the author

This repository is a milestone in Pasquale Rienzo's journey — Road to AECO in AI System Integration: building real system-engineering, diagnostic and automation skills on real hardware, on the way to integrating AI systems across the AECO industry (Architecture, Engineering, Construction & Operations). From construction sites to system prompts.

@paskaz on GitHub · Pasquale Rienzo on LinkedIn

⭐ If this repo saved your MacBook — or just taught you a trap — a star helps others find it.

⚖️ License

Distributed under the MIT License — © 2026 Pasquale Rienzo.

🙏 Acknowledgments

roadrunner2/macbook12-spi-driver · F13-Kr1pt0n/macbook-pro-touchbar-driver · davidjo/snd_hda_macbookpro · rvaiya/keyd · Dunedan/mbp-2016-linux · moabdrabou/macbook-pro-2017-linux-guide · othneildrew/Best-README-Template

(back to top)