Background

The HubPiWi Blue is an add-on for the Raspberry Pi Zero that gives you three USB ports, and a combined WiFi/Bluetooth adapter (RealTek chipset). If you poked around after install, you likely noticed that there's a module for a Realtek device already detected and running. We're part of the way there, unfortunately, it's only the "Bluetooth" part and I'm not even sure that it truly works. Thankfully, RealTek provides module sources for a Linux driver and they were great with Raspbian (with a few Makefile tweaks). Unfortunately, this means we'll not be able to update the kernel after this without repeating a lot of these steps again.

Initial Setup

I’ll skip the basics except for this: Get an SD card, load the latest Raspbian image onto it and pop that into the Pi Zero’s available card.  You’ll want a monitor/keyboard handy or an FTDI adapter.  And you’ll need some time – my recommendation: line up some chores to do during each of the major steps and you’ll get a bit done while you’re waiting.

What you’ll need

If you want to follow this post exactly, here’s what you’ll need.  I’ve included notes about alternatives where I can, but I’m doing this as I write, so I’m providing what I used to make it work.

• A Raspberry Pi Zero
• A HubPiWi Blue
• USB power and Micro USB cable
• An HDMI display and Keyboard or an FTDI Adapter
• A Wireless network you intend to attach to.

Before We Build the Driver

As always, run the following commands:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade
sudo reboot

It’s a Pi Zero, so it’s going to take a while.  To its credit, it performed faster than my original Raspberry Pi.  And for $5 (or if you were one of the lucky ones that grabbed one at Microcenter for a buck), you can’t really complain.

I used the non-LITE version of Raspbian and ended up with 122 packages that needed updating, which took around 35 minutes.

Building and Installing the WiFi Kernel Module

The HubPiWi uses the Realtek 8723BU Chipset and the same Bluetooth module found in the 8723AU. Luckily, there are kernel modules for these. I've created a fork of the WiFi driver repository and modified the Makefile to allow for an easy build on Raspbian, so we'll clone my forked repository and use that to build the module.

cd ~/
git clone https://github.com/Diagonactic/rtl8723bu.git

The driver is kernel version specific, so we need to get the correct linux headers.

sudo apt-get install raspberrypi-kernel-headers

Time for some more chores.  This clocked in at about 10 minutes.

cd ~/rtl8723bu
make 

This will run about 30-40 minutes.  When you’re done, you’ll have a compiled driver and be ready to install:

sudo make install 

At this point you can either reboot with the “reboot” command or type the following:

sudo insmod 8723bu.ko
ifconfig

You should see your wlan0 device ready to go! Of course, you still need to configure it to attach to your network. There's a variety of ways to do that so simply search away and set that up and you'll be connected.  That’s fairly easy and there’s several articles on how to do that.  This device also comes with Bluetooth support, so follow the remaining instructions to get that working if that’s something you’re interested in.

Building and Installing the Bluetooth Kernel Module (Optional)

Since it’s always a good idea to only enable the features you’re actually going to use, if you have nothing to pair the device with or no use for Bluetooth at this time, you can skip this.  These steps are Bluetooth specific and doing them will not improve or affect your ability to get going with WiFi, which is more-than-likely what you wanted to get working, anyway.

The modules above do not include the Bluetooth part, so for that we need to grab and compile a new module.

cd ~/
git clone https://github.com/lwfinger/rtl8723au_bt.git –b kernel
cd rtl8723au_bt.git
make
sudo make install

Note the “-b kernel” on the git clone command.  If you fail to include this the make command will not work (and will instruct you to grab the kernel branch, which is why we’re including the –b kernel above).  This will take about 15-20 minutes on the Pi Zero, so kick back and drink some more coffee.

Now all we need to do is insmod a few modules and we’re in business

sudo insmod btrtl.ko
sudo insmod btintel.ko
sudo insmod btbcm.ko
sudo insmod btusb.ko

Assume you received no error messages, we can now verify that Bluetooth is working:

sudo bluetoothctl

You should see something along the lines of “[New] Controller xx:xx:xx:xx:xx:xx yourhostname [default]”

That’s it!  Pairing devices with this controller is done the same way it would be done with a Raspberry Pi 3.  If you need instructions on that, I’ll leave you to google away since that may change as time progresses (but should always be the same process for this device as it is with others).

Bluetooth Device Compatibility

If you chose to install the Bluetooth Kernel module there’s a small but important disclaimer.  Bluetooth implementations can be hit and miss.  Despite having a “certification” component that’s supposed to mean that a Bluetooth device will operate with anything else that’s certified (indicated by the Bluetooth logo being present on your device), this is often not the case in the real world.  I expect you’ll have no problems with any Android or iOS device, however, if you’re trying to pair with something a little more exotic, like an older Microsoft Windows Mobile phone, Microsoft Branded “Sync” stereo, or other stereo/TV, you may have problems (I’m not picking on Microsoft, directly, here, these are just devices that I have owned that I’ve had Bluetooth pairing problems with in the past).  Bluetooth keyboards, for instance, are notoriously painful to get to pair properly (you may want to use the GUI tools to do this, though it will be very slow on the Pi Zero)

Ongoing Maintenance Note - IMPORTANT!

If you've been messing with Raspberry Pi hardware for a while, you'll recognize those first few steps as common steps for updating the Pi.

Nearly every bit of "help" will point you at these steps as a "do this first" (keeping software up-to-date is always a good idea). The issue, though, is that this will sometimes install a new kernel version. When that happens, the new kernel will not have a module for your WiFi adapter. Not to worry: simply repeat the process from Building and Installing the WiFi Module after a new kernel comes down and you'll be back up and running.

UPDATE: The HubPiWi Blue includes this chipset and the instructions for that also work with the USB dongle. I've provided an updated set of instructions here that are a bit simpler and are targetted at Raspbian Jessie. You should use those, instead.

I recently started getting my second RPi setup, only on this one I wanted to use a dual WiFi/Bluetooth USB dongle.  I picked a device based on the Realtek RTL8723BU after reading a few posts indicating success.  Unfortunately, it doesn’t work “out-of-the-box” with Raspbian Wheezy on Kernel 4.1.13.

Before we Proceed

I’ve been tinkering with RPi’s for a little bit, but I’m by no means an expert.  If there are obvious problems with the steps I’m doing here, kick me a comment and I’ll correct them.  This worked for me.  It might not work for you.  I’m assuming you’re on 4.1.13+ installed via NOOBS and you haven’t added/changed much up to this point.  If you have, some of the steps (like removing the build/src folder) might already have things in them that you don’t want to lose, so exercise some discretion before running each command.  And, of course, this comes with NO WARRANTY expressed or implied – use at your own risk, my friend.

What You’ll Need

Besides the hardware, you’ll need a wired or working wireless connection (using a device other than the one we’re building a module for).

If you’ve done the Raspbian install from NOOBS, you should have all of the necessary packages required to build the driver.  If you haven’t, you might need to apt-get build-essential and others that I’m not entirely sure of.

Overview

We’ll update the system, clone the git repo for the driver, download the kernel source, set up the build environment, and build the driver.

I’ll also provide the steps I took to get the miserable thing to actually work!

Let’s Get To It

To get this going, you’ll need the kernel source and it’s probably a good idea to make sure you’re all up to date.

apt-get update
apt-get upgrade dist-upgrade
reboot

You can go run some errands during the dist-upgrade, it took over an hour for me.

To start, get the latest drivers

cd ~/
git clone https://github.com/lwfinger/rtl8723bu.git

If you’ve installed from NOOBS (as I did), at this point, you’re not going to be able to make the driver.  You need the kernel headers for the kernel you’re running.  Normally, apt-get install linux-headers or something along those lines would do the trick.  Not this time.

Unfortunately, when I wrote this, the linux headers for the version of the kernel used by Raspbian, 4.1.13+, were not available from aptitude.  After some searching, I found a downloadable debian package that works.

wget https://www.niksula.hut.fi/~mhiienka/Rpi/linux-headers-rpi/linux-headers-4.1.13%2B_4.1.13%2B-2_armhf.deb
sudo dpkg –i ./linux-headers-4.1.13+-2_armhf.deb

If you lack one or more of the dependencies, install them with apt-get install <dependency>, then apt-get –f install which will finish up the installation of the headers.

Modifying the Makefile for Raspbian

We’ll need to tweak the Makefile for the driver to build properly.  I’m not sure that all of this needs to be added – I grabbed it from several google searches.  But, hey, it worked, so here’s what I changed.

nano Makefile

Hit CTRL+W and type “CONFIG_PLATFORM_I386_PC =” and hit Enter.  Set it to “n”. Add a line below it and type “CONFIG_RASPBIAN = y”.

Hit CTRL+W and type “ifeq ($(CONFIG_BT_COEXIST)” and hit Enter.  Insert the following text above that line.

ifeq ($(CONFIG_RASPBIAN), y)
EXTRA_CFLAGS += -DCONFIG_LITTLE_ENDIAN
EXTRA_CFLAGS += -DCONFIG_IOCTL_CFG80211
EXTRA_CFLAGS += -DRTW_USE_CFG80211_STA_EVENT # only enable when kernel >= 3.2
EXTRA_CFLAGS += -DCONFIG_P2P_IPS
ARCH := arm
CROSS_COMPILE := arm-linux-gnueabihf-
KVER := $(shell uname -r)
KSRC ?= /lib/modules/$(KVER)/build
MODULE_NAME := 8723bu
MODDESTDIR := /lib/modules/$(KVER)/kernel/drivers/net/wireless/
endif

Hit CTRL+X then “Y” to save the file.

Build It

sudo –i
cd /home/pi/rtl8723bu
make && make install

That part took almost an hour on my RPi Model B.

Making It Work

Well, at this point, you can just reboot.  But if you want to test prior to rebooting, run the following:

insmod 8723bu.ko
ifconfig

You should now see “wlan0” among the network adapters!