Get Started

Dustin Moore edited this page Jan 22, 2017 · 98 revisions

Get Started

You can contribute and test this module without touching your Mac's Hard Disk. You just need an USB 3.0 key to install Linux on, on top of your Linux installation Media. Best of both worlds, try Linux until you're ready to commit your internal drive. Please check linux.com article

General knowledge of WebCam support in linux: http://www.tldp.org/HOWTO/Webcam-HOWTO/hardware.html

Getting the driver working is two steps:

  • Firmware extraction: Run the script to download and install the firmware from Apple. Gentoo users using the ebuild skip this step. NixOS users can also skip this step.
  • Installation: Installing the driver itself.

See Additional Notes below in case you come across any issues.

Firmware extraction

Download the driver (zip version) and extract it by following these steps:

  • Clone the git repository with $ git clone https://github.com/patjak/bcwc_pcie.git
  • Change to the firmware directory with $ cd bcwc_pcie/firmware
  • Dependencies for make are curl, xzcat and cpio
  • Under bcwc_pcie/firmware type $ make and then as root type # make install
  • Result should be like:
$ make
Dowloading the driver, please wait...


Found matching hash from OS X, El Capitan 10.11.2
==> Extracting firmware...
 --> Decompressing the firmware using gzip...
 --> Deleting temporary files...
 --> Extracted firmware version 1.43.2
# make install

Copying firmware into '//usr/lib/firmware/facetimehd'

Installation

Now continue with one of

Get Started on Fedora

Tested on Fedora 23. - Extract firmware file as described in Firmware extraction

  • Become root sudo su -
  • Install packages kernel-devel (if you installed the Wireless Card driver, you likely already have it): dnf install kernel-devel
  • Clone the driver's code: git clone https://github.com/patjak/bcwc_pcie.git
  • Change into directory: cd bcwc_pcie
  • Build the kernel module: make
  • Install the kernel module: make install
  • Run depmod
  • Load the module: modprobe facetimehd
  • Check if all relevant modules are loaded: lsmod | grep facetimehd

Everything should load fine. Check with command dmesg, the main driver should have loaded and ignore the error about the missing .dat file in the firmware directory (these are the calibration files, we do not have them yet).

Time for testing: launch Cheese and enjoy your own smily face :-)

The driver now handles suspend / resume properly, you're all set.

IF YOU ENCOUNTER ANY ISSUES LOOK AT THE "ADDITIONAL NOTES" SECTION ON THE BOTTOM OF THIS PAGE OR REPORT AN ISSUE

Get Started on Debian

(very similar to arch instructions, which I copied and altered a bit ;) because I am lazy / efficient)

before you start, ensure you are running Linux kernel 4.4 or later or the driver will not work!

# indicates as root, you can use sudo if you prefer.
$ indicates as normal user

  • Extract and install the firmware file as described in Firmware extraction.
  • Install the dependencies : # apt-get install linux-headers git kmod libssl-dev checkinstall
    linux-headers may be slightly different e.g. linux-headers-4.3.0-1-amd64, you can check which kernel version you are running with $ uname -r
  • Clone the driver's code: $ git clone https://github.com/patjak/bcwc_pcie.git
  • Change into that dir: $ cd bcwc_pcie
  • Build the kernel module: $ make
  • Generate dkpg and install the kernel module, this is easy to uninstall later: # checkinstall
    Alternatively if you are really lazy just: # make install
  • Run depmod for the kernel to be able to find and load it: # depmod
  • Load kernel module: # modprobe facetimehd
  • try it out: $ mplayer tv://

IF YOU ENCOUNTER ANY ISSUES LOOK AT THE "ADDITIONAL NOTES" SECTION ON THE BOTTOM OF THIS PAGE OR REPORT AN ISSUE

Get Started on Ubuntu

All the steps are the same as Debian. (The only difference is that the firmware.bin is copied into /lib/firmware/facetimehd/ instead of /usr/lib/firmware/facetimehd/, but the script does that for you.)

Setting up DKMS (auto-compile on kernal update)

This assumes you have already followed the Debian/Ubuntu deb package steps. You will need to verify dkms.conf that the module name facetimehd and version number 0.1 are correct and either update the dkms.conf or adjust the instructions where -m and -v are used.

  • Install needed packages: # apt install debhelper dkms
  • Remove old package if installed: # dpkg -r bcwc-pcie
  • Make a directory to work from: # mkdir /usr/src/facetimehd-0.1
  • Change into the git repo dir: $ cd bcwc_pcie
  • Copy files over: # cp -r * /usr/src/facetimehd-0.1/
  • Change into that dir: # cd /usr/src/facetimehd-0.1/
  • Remove any previous debs and backups: # rm backup-*tgz bcwc-pcie_*deb
  • Clear out previous compile: # make clean
  • Register the new module with DKMS: # dkms add -m facetimehd -v 0.1
  • Build the module: # dkms build -m facetimehd -v 0.1
  • Build a Debian source package: # dkms mkdsc -m facetimehd -v 0.1 --source-only
  • Build a Debian binary package: # dkms mkdeb -m facetimehd -v 0.1 --source-only
  • Copy deb locally: # cp /var/lib/dkms/facetimehd/0.1/deb/facetimehd-dkms_0.1_all.deb ~
  • Get rid of the local build files: # rm -r /var/lib/dkms/facetimehd/
  • Install the new deb package: # dpkg -i /root/facetimehd-dkms_0.1_all.deb

If you have any trouble, please read this guide on making a DKMS package: http://www.xkyle.com/building-linux-packages-for-kernel-drivers/

Get started on Arch

There is AUR package available, and another one for the firmware itself (the separation will make upgrades less painful, and don't force you to keep firmware.bin around forever).

If you want to install the kernel module manually, instead, you should:

  • Extract firmware file as described in Firmware extraction.
  • Install dependencies: sudo pacman -S linux-headers git kmod
  • Clone driver's code: git clone https://github.com/patjak/bcwc_pcie.git
  • Step into cloned dir: cd bcwc_pcie
  • Build kernel module: make
  • Install kernel module: sudo make install
  • Run depmod for kernel to be able to find and load it: sudo depmod
  • Load kernel module: sudo modprobe facetimehd
  • Try it with the application of choice. mpv for example: sudo pacman -S mpv && mpv tv://

IF YOU ENCOUNTER ANY ISSUES LOOK AT THE "ADDITIONAL NOTES" SECTION ON THE BOTTOM OF THIS PAGE OR REPORT AN ISSUE

Get Started on Gentoo

On Gentoo it is no longer necessary to extract the firmware from a running OS X. Simply use the bcwc_pcie ebuild from https://github.com/toaster/gentoo-overlay.git.

The following steps have to be performed as root.

Adding the overlay using layman

First create a local overlay list:

echo '<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE repositories SYSTEM "/dtd/repositories.dtd">
<repositories xmlns="" version="1.0">
  <repo quality="experimental" status="unofficial">
    <name>toaster</name>
    <description>toasters own ebuilds</description>
    <homepage>https://github.com/toaster/gentoo-overlay</homepage>
    <owner type="project">
       <email>tilo@pruetz.net</email>
       <name>Tilo Prütz</name>
    </owner>
    <source type="git">https://github.com/toaster/gentoo-overlay.git</source>
    <feed>https://github.com/feeds/toaster/commits/gentoo-overlay/master</feed>
  </repo>
</repositories>' > /etc/layman/overlays/toaster.xml

Then make it known to layman and add it to your local overlays:

layman -L
layman -a toaster

Install the driver

Note that you have to set the ~amd64 keyword for the driver package and for media-video/apple_facetimehd_firmware. How this is done in detail depends on how you manage your keywords.

emerge -av media-video/bcwc_pcie

The firmware ebuild will download a partial OS X 10.11 upgrade and extract the firmware from it. It is not necessary to boot OS X and extract it manually.

IF YOU ENCOUNTER ANY ISSUES LOOK AT THE "ADDITIONAL NOTES" SECTION ON THE BOTTOM OF THIS PAGE OR REPORT AN ISSUE

Get Started on openSUSE

  • You need a least openSUSE Leap 42.1. If you are running openSUSE 13.2 upgrade to openSUSE Leap 42.1 (https://en.opensuse.org/SDB:System_upgrade) or install a kernel >= 3.19 (not tested)
  • Extract firmware file as described in Firmware extraction
  • Become root su -
  • Install packages kernel-devel and git: zypper install kernel-devel git
  • Clone the driver's code: git clone https://github.com/patjak/bcwc_pcie.git
  • Change into directory: cd bcwc_pcie
  • Build the kernel module: make
  • Install the kernel module: make install
  • Run depmod
  • Load the module: modprobe facetimehd
  • Check if all relevant modules a loaded: lsmod | grep facetimehd
facetimehd            102400  0 
videobuf2_dma_sg       20480  1 facetimehd
videobuf2_core         57344  1 facetimehd
videodev              176128  3 v4l2_common,facetimehd,videobuf2_core
  • At the moment the kernel module is not loaded automatically. If you would like the kernel module to be loaded at system startup add the following line to /etc/init.d/after.local (Note that this is not yet recommended since the driver is not 100% stable)
modprobe facetimehd
  • In order to get it working after suspend see below
  • To test the camera install mplayer from Packman repo. If not yet done add Packman repo first
zypper addrepo -f http://packman.inode.at/suse/openSUSE_Leap_42.1/ packman
zypper install mplayer
  • As user start mplayer: mplayer tv://
  • By the way, the Packman repo provides a driver for the WiFi card (Broadcom): zypper install broadcom-wl
  • In order to update the driver later to the newest version, change to the folder where your have cloned the driver's code cd bcwc_pcie run git pull followed by make clean; make; make install.

IF YOU ENCOUNTER ANY ISSUES LOOK AT THE "ADDITIONAL NOTES" SECTION ON THE BOTTOM OF THIS PAGE OR REPORT AN ISSUE

Get Started on NixOS

NixOS has built-in facetimehd support starting 16.03. Enabling the NixOS module will extract the firmware online, blacklist bdc_pci and add rmmod/modprobe hooks during suspend.

  1. Make sure the following lines (or its equivalent) are in /etc/nixos/configuration.nix
  hardware.facetimehd.enable = true;
  nixpkgs.config.allowUnfree = true;
  1. Execute nixos-rebuild boot to rebuild the configuration
  2. Reboot

IF YOU ENCOUNTER ANY ISSUES LOOK AT THE "ADDITIONAL NOTES" SECTION ON THE BOTTOM OF THIS PAGE OR REPORT AN ISSUE

Additional Notes

/dev/video not created

In some scenarios, you'll have to unload bdc_pci before inserting the kernel module, or /dev/video (or /dev/video0) won't be created. Do this with modprobe -r bdc_pci.

Make driver load correctly after suspend

Putting the computer to suspend and trying to use the camera afterwards makes the computer freeze. Here is a fix for that. Suspend/resume should now work without any additional fixes. Note that suspend/resume with the device opened is still not supported.

Make driver load correctly on startup

If you want the driver to be enabled on startup, extra steps may be required. On Ubuntu, the following should work:
echo facetimehd >> /etc/modules

For Ubuntu 15.04 and higher (Should work on some other distros too):

Put this in terminal. Use gedit or your favorite text editor: sudo gedit /lib/systemd/system-sleep/99facetimehd or if /lib/systemd/system-sleep does not exist: sudo gedit /usr/lib/systemd/system-sleep/99facetimehd

Paste this in the empty file:

#!/bin/sh
case $1/$2 in
  pre/*)
    echo "Going to $2..."
    modprobe -r facetimehd
    ;;
  post/*)
    echo "Waking up from $2..."
    modprobe -r bdc_pci
    modprobe facetimehd
    ;;
esac

And save.

Make it executable: sudo chmod a+x /lib/systemd/system-sleep/99facetimehd or sudo chmod a+x /usr/lib/systemd/system-sleep/99facetimehd

For Ubuntu 14.10 and lower / Mint 17 (Should work on some other distros too):

Paste this in terminal: sudo gedit /etc/pm/sleep.d/99_facetimehd

And paste this in and save file:

#!/bin/sh
case $1 in
    resume|thaw)
        logger -t pm 'Loading facetimehd kernel module'
        /sbin/rmmod bdc_pci
        /sbin/modprobe facetimehd
        ;;
    suspend|hibernate)
        logger -t pm 'Removing facetimehd kernel module'
        /sbin/rmmod facetimehd
        exit 0
        ;;
esac

And make it executable: sudo chmod a+x /etc/pm/sleep.d/99_facetimehd

If you cannot get mplayer to load after correctly creating /dev/vide0

Try: mplayer -vo gl tv:// If that did not work try this: mplayer -vo gl2 tv:// And if none of the two above worked try: mplayer -vo gl3 tv://

If you get a corrupted image in Cheese

This is because some Linux applications do not support high resolution cameras. To fix this go to Cheese settings and change the resolution to something lower. Then turn the computer OFF, and ON again. (Not reboot). This should fix the corrupted image.