Recently I bought two TP-Link TL-WN725N adapters off Amazon. They’re cheap and according to the RPi peripherals list [here], are supposed to work well under Linux. They do, however, require a special driver which is not included in the Linux kernel itself. This leaves you with two options:

– Use one of MrEngman’s pre-compiled kernel modules which is available on the Raspberry Pi forums [here] (kudos to MrEngman to his ongoing effort!).

or

– You compile your own kernel module.

However, keep in mind the following very important caveat: whatever your choice is, this process requires some basic knowledge of Linux! If you don’t feel comfortable messing around with kernel modules and such, I would recommend that you proceed with caution and maybe even ask a more experienced friend to give you a hand. It’s unlikely you will ruin your Raspberry Pi but you may very well ruin your installation. PROCEED WITH CAUTION.

Now, be aware that if you just want your wifi up and running and don’t want to be bothered, you really should take the easy way out here and check whether MrEngman has a pre-compiled module that’s been compiled with the same revision of your kernel. If you cannot find one or if you’re feeling especially brave, read on for the step by step on how to compile it yourself.

Also keep in mind that this tutorial applies to the Raspbian distribution. It may (or may not) work in Pidora (and others) but it’s up to you to adjust accordingly.

Compiling a kernel module

Be wary, this assumes you’re going to compile a kernel module to the latest version of the Raspberry Pi firmware (and thus, at the time of writing, for the latest version of the 3.10.y branch). If you’re not running this version, consider updating [updating the RPi to the latest firmware]!

Pre-requisites

  • Linux kernel source for the Raspberry Pi (do NOT use the original Linux kernel as it does not contain all the patches and drivers required for your RPi to work smoothly), available on GitHub [here].
  • Driver for the RTL8188EU, available on GitHub [here].

Many Linux distributions provide a package just with the precompiled kernel headers and that makes it easier than what you’ll have to do on the Raspberry Pi. Still, it’s not so difficult. All you have to do is:

Cloning and compiling the Linux kernel

1. Start by cloning the Linux kernel for the RPi

cd /usr/src/
sudo git clone https://github.com/raspberrypi/linux.git rpi-3.10.y
cd /usr/src/rpi-3.10.y/

This will have created a folder called /usr/src/rpi-3.10.y/ where all the Linux kernel source now resides in your Raspberry Pi.

2. For ease of use, create a symbolic link to the /lib/modules/ structure

sudo ln -s /usr/src/rpi-3.10.y /lib/modules/`uname -r`/build

Be sure to write it in as is (or simply copy & paste it in!) as the backticks around uname -r will create the right name for the folder. At this point, your /lib/modules/ path will have a link to the directory where the source code resides. We do this so later when we compile the driver, our life becomes much easier (as the Makefile will automatically look in that directory).

3. Copy your kernel configuration file to the directory where the source is:

sudo sh -c 'zcat /proc/config.gz > .config'

This simply pulls the config from your running kernel into the new kernel you’re about to compile.

4. Pull the latest Module.symvers into your kernel’s directory. Note: this is one of the reasons why I would recommend updating first to the latest kernel, otherwise you’ll have to figure out which Module.symvers you need.

curl -O https://raw.githubusercontent.com/raspberrypi/firmware/master/extra/Module.symvers

5. Compile the kernel to a stage that is ready to be linked against kernel modules. You don’t want to compile the whole kernel since that’s 1) not necessary for compiling kernel modules and 2) would take ages on a Raspberry Pi with its limited computing power.

sudo make oldconfig
sudo make modules_prepare

6. Clone the driver off GitHub, compile it and off you go!

cd /usr/src/
git clone https://github.com/lwfinger/rtl8188eu.git
cd /usr/src/rtl8188eu/
sudo make
sudo make install

At this stage, the driver’s firmware as well as the compiled kernel module have been copied into place but there are a few more considerations to be had.

1 – Do NOT plug the wifi dongle with the Raspberry Pi turned on! Many people (including me) have reported that doing so causes the Raspberry Pi to suddenly restart and this can lead to serious corruption of your SD card. Be on the safe side! Shut down your Raspberry Pi (sudo shutdown -h now), plug in the dongle, and turn it back on.

2 – At this point, when you run “ifconfig” you should already have a wlan0 network which is not connected to anything. In my experience, getting it to connect was the biggest challenge so if you have a WPA/WPA2 network and would like to learn how to connect to it via command line, read on.

Connecting to a WPA/WPA2 network via command line

When you know what you’re doing, this is an extremely simple process. First off, run the following command:

wpa_passphrase <ssid>

Where you should replace with the actual SSID of your network (hint: use “” if your network’s name has spaces in it). It will then prompt you to type in the password for your network. This script generates then a few lines in the format of: </p>

network={
    ssid="Foo"
    #psk="FoobarFoobar"
    psk=f21df897e40a0e7253b8d53e35930e814f312df43ca2b085daa5109f2c2c5e54
}

I recommend that you delete the line started by #psk (as it reveals your password in clear text) and the rest you should copy and paste into a file at /etc/wpa_supplicant.conf. If it exists, overwrite it, if it does not exist, then create it (with e.g. sudo nano /etc/wpa_supplicant.conf).

After you’ve done that, you need to tell Linux how this network is going to get an IP address and how it’s managed. You can do so by editing the /etc/network/interfaces file as such:

sudo nano /etc/network/interfaces

Here you should lookout for a line that starts as “iface wlan0”. In my case, this line was setting wlan0 as manual which is NOT what we want. Ultimately you want something that looks like this:

iface wlan0 inet dhcp
wpa-conf /etc/wpa_supplicant.conf

And watch out! If there is a line starting with “wpa-roam”, you can safely delete it as it will conflict with your new WPA settings!

After you’ve modified the file you can then save it and we’re ready for action. Next thing you need to do is take the WLAN interface down and back up as such:

sudo ifdown wlan0
sudo ifup wlan0

And that’s it! If everything went well, your Raspberry Pi should now be connected to your network via wifi!

If there’s something that’s not clear enough or some steps that I missed, feel free to drop me an e-mail. My e-mail address is my first name [@] my last name [dot] nl. And you can find my first and last name in the url of this blog (hint, my first name is Tiago!).

Finally I would like to thank MrEngman for his dedication and continuous engagement in the Raspberry Pi forums as well as lwfinger for maintaining this driver and making it possible for us to use it on Linux! I would also like to thank Martijn from Grendelman.net for this blog post which helped me in getting all this to work. Thanks! In a future post I will come back and explain how to cross-compile a kernel module for the Raspberry Pi so you can get it done faster by using your (more powerful) desktop computer to do the compilation.