Skip to content

Introduction

This page explains how to install the kernel modules for the Keyboard, Audio, Touchbar and the Ambient Light sensor with DKMS. You will need a patched kernel.

Do you need to do this?

Are your keyboard and audio working? If no, then you'll need the BCE module.
If you have a Touchbar, is it working? If no, then you'll need the apple-ibridge module.

To get started with this guide, first install the dkms package.

You may have been using an outdated kernel or your distribution may have been using kernel modules that do not match the ones listed below (check using dkms status or ls -l /usr/src). If the version of apple-bce in the output is 0.1, you have to uninstall the old modules first to avoid any compatibility issues by running:

sudo dkms uninstall -m apple-bce -v 0.1
sudo dkms uninstall -m apple-ibridge -v 0.1
sudo rm -r /usr/src/apple-bce-0.1
sudo rm -r /usr/src/apple-ibridge-0.1
sudo rm -r /var/lib/dkms/apple-bce
sudo rm -r /var/lib/dkms/apple-ibridge

Installing modules

  1. Installing the BCE (Buffer Copy Engine) module for Keyboard and Audio

    • If you are on arch, you can use Aunali1's apple-bce-dkms-git package

    • Otherwise, run sudo git clone https://github.com/t2linux/apple-bce-drv /usr/src/apple-bce-0.2

      • Create a dkms.conf file in /usr/src/apple-bce-0.2 and put in the following:

        PACKAGE_NAME="apple-bce"
PACKAGE_VERSION="0.2"
MAKE[0]="make KVERSION=$kernelver"
CLEAN="make clean"
BUILT_MODULE_NAME[0]="apple-bce"
DEST_MODULE_LOCATION[0]="/kernel/drivers/misc"
AUTOINSTALL="yes"

    • Now run sudo dkms install -m apple-bce -v 0.2. If on a live ISO, use sudo dkms install -m apple-bce -v 0.2 -k x.x.x-mbp instead and change x.x.x-mbp to the kernel that you have installed, as by default dkms will try to build the module for the kernel that the live iso is using, which will most likely be older.

  2. Installing the Touchbar and Ambient Light sensor modules

    • If you are on a MacBook Pro (16 inch, 2019) or MacBook Pro (13 inch, 2020), and want keyboard backlight to work, run :

    sudo git clone https://github.com/Redecorating/apple-ib-drv /usr/src/apple-ibridge-0.1

    Else run :

    sudo git clone https://github.com/t2linux/apple-ib-drv /usr/src/apple-ibridge-0.1

    • Now run sudo dkms install -m apple-ibridge -v 0.1. If on a live ISO, use sudo dkms install -m apple-ibridge -v 0.1 -k x.x.x-mbp instead and change x.x.x-mbp to the kernel that you have installed, as by default dkms will try to build the module for the kernel that the live iso is using, which will most likely be older.

  3. Load the modules into the kernel

    Note

    This is only necessary if you wish to use the modules right away. If you are installing modules from a live iso the commands will fail as the modules have only been installed for the kernel you specified.

    sudo modprobe apple_bce
sudo modprobe apple_ib_tb
sudo modprobe apple_ib_als

The Touchbar and keyboard should be working. For audio, you'll also need some config files, refer to the Audio Config guide.

Make modules load on boot

Ubuntu

Ubuntu users may skip this step as it's already set up in their distro. If the modules are still not loading on boot, then you may follow this section.

echo apple-bce >> /etc/modules-load.d/t2.conf

Make modules load on early boot

Having the apple-bce module loaded early allows the use of the keyboard for decrypting encrypted volumes (LUKS). It also is useful when boot doesn't work, and the keyboard is required for debugging. To do this, one must ensure the apple-bce module as well as its dependent modules are included in the initial ram disk. If your distro uses initramfs-tools (all debian-based distros), then /etc/initramfs-tools/modules stores a list of extra modules to be included and loaded at early boot time:

cat <<EOF >> /etc/initramfs-tools/modules
# Required modules for getting the built-in apple keyboard to work:
snd
snd_pcm
apple-bce
EOF

Other distros use a different initramfs module loading mechanism. For example in Arch ensure that the /etc/mkinitcpio.conf file has:

MODULES="apple-bce"

And then run sudo mkinitcpio -P. See your distro-specific instructions for configuring apple-bce to added to your initramfs.

Module configuration

The Touchbar module offers some modes to set. In /etc/modprobe.d/apple-tb.conf, set fnmode (options apple-ib-tb fnmode=x) to one of the following options:

  • 0: Only show F1-F12
  • 1: Show media and brightness controls, use the fn key to switch to F1-12
  • 2: Show F1-F12, use the fn key to switch to media and brightness controls
  • 3: Only show media and brightness controls
  • 4: Only show the escape key

Ubuntu

Ubuntu has /etc/modprobe.d/apple-touchbar.conf added by default instead of /etc/modprobe.d/apple-tb.conf. Thus, its advised to rename apple-touchbar.conf to apple-tb.conf before editing.

Fixing Suspend

Copy this script to /lib/systemd/system-sleep/rmmod_tb.sh

Now run :-

sudo chmod 755 /lib/systemd/system-sleep/rmmod_tb.sh
sudo chown root:root /lib/systemd/system-sleep/rmmod_tb.sh

It unloads the Touchbar modules as they can cause issues for suspend.

Kernel panic when loading apple-ib-als

This was fixed in this commit, please follow the dkms guide to update.

Use ambient light sensor to automatically change brightness (if not working already)

You can use this script. Make sure you have the apple-ib-als module loaded.