Realtek 8188eu-based Wi-Fi adapters on the Raspberry Pi

NOTE: If you’re using Raspbian 2015.01 or later, the Raspberry Pi kernel 3.18 now includes this driver—you don’t need to compile anything and this tutorial is now irrelevant!

Raspberry Pi enthusiasts like to use Realtek 8188eu-based Wi-Fi adapters. Known as “micro” Wi-Fi adapters, they are small and inexpensive. For example, the TP-LINK WN725N V2 can be found for under $20 (the V1 and V3 use different chipsets. Thanks for making everything confusing, TP-LINK!).

As of October 2014 and Linux 3.12.29+, the driver for this Wi-Fi adapter isn’t available in the Raspberry Pi Linux kernel, so these Wi-Fi adapters are not supported out-of-the-box, despite otherwise you may find on the Internet. Definitely, they don’t work in a plug-and-play manner.

You can get these adapters to work by using an out-of-tree driver (i.e. a driver not included with the Linux kernel). People on the Internet have resorted to doing all these silly things like downloading random kernel modules or compiling the vendor Linux kernel trees from scratch trying to get this driver to work. You’re probably reading this article because you, like me, thought it was silly to chase files around on some random Internet forum.

The source code for the 8188eu driver is available on GitHub. Rather than trying to look for random files and hope they work, you can keep the source for the module on your Raspberry Pi and recompile the module as needed. Below are copy-and-pastable instructions to do this on Raspbian.

Make sure you have a compiler, etc installed.

sudo apt-get install build-essential git

Download the source code for the driver. I prefer to put source code for stuff like this somewhere convenient in my home directory, like ~/src/drivers/.

mkdir ~/src/drivers
cd ~/src/drivers/
git clone https://github.com/lwfinger/rtl8188eu.git

Now you have the source code for the driver, you need to get the source code for the kernel running on the Raspberry Pi. Finding the source code for the currently-running kernel on the Raspberry Pi can be a pain. I like to use Hexxeh’s rpi-source tool, which you can download, install, and run:

sudo wget https://raw.githubusercontent.com/notro/rpi-source/master/rpi-source -O /usr/local/bin/rpi-source && sudo chmod +x /usr/local/bin/rpi-source && /usr/local/bin/rpi-source -q --tag-update
sudo rpi-source

If you get an error about GCC, use the “skip-gcc” flag:

sudo rpi-source --skip-gcc

Now, compile the driver:

cd ~/src/drivers/rtl8188eu
sudo make all
sudo make install

Your Wi-Fi should be working, though you’ll need to configure it (configuring it is out of scope for this article).

You can double check whether the adapter is recognized by looking at the output of (assuming you’ve only one Wi-Fi adapter, it will be named wlan0):

sudo iwconfig wlan0

If you see nothing, the driver may have been installed wrong or your Wi-Fi adapter not working. If you see something like:

wlan0     unassociated  Nickname:"<WIFI@REALTEK>"
          Mode:Master  Frequency=2.412 GHz  Access Point: E8:DE:27:9E:65:D7   
          Sensitivity:0/0  
          Retry:off   RTS thr:off   Fragment thr:off
          Power Management:off
          Link Quality=0/100  Signal level=0 dBm  Noise level=0 dBm
          Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
          Tx excessive retries:0  Invalid misc:0   Missed beacon:0

Then you are good to go!

All of this seemed like a lot of work compared to hunting down the file, right? Except, it isn’t: when you update the kernel on your Raspberry Pi and reboot, the Wi-Fi will stop working because it will no longer have an appropriate driver. Rather than having to go on a witch hunt for files, you can simply recompile the driver again while offline:

cd ~/src/drivers/rtl8188eu
git pull # Run this if you have Internet access even though your Wi-Fi is down
make all
sudo make install

The above is all you need to turn your Raspberry Pi into a working Wi-Fi client.

If you want to use your shiny new Wi-Fi enabled Raspberry Pi as an access point, there’s a gotcha with Realtek Wi-Fi adapters (I’ve found this true of both the 8188eu and 8192cu chips): they won’t work with hostapd as included with Raspbian or Arch Linux. You’ll need to use a custom hostapd, such as this one posted by Jens Segers, to get a working access point.