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.