Pi Zero Side-Car

Would you like to transform you Pi Zero into an Ethernet USB gadget? Plug it into your PC as a USB stick and give it a Screen, Mouse and Keyboard in the most compact and cheap way possible.
This tutorial assumes that you will be working from a Windows platform but if you have a good grasp on things it should be easy to apply this to Linux or Mac.

This article has been published on The MagPi issue 44

Get your Rasbian ready to become a gadget

The very first thing that you need to do is to get an image of Rasbian from the download section of raspberrypi.org. Get the full version as we will need all the goodness that come with it. Have your breakfast now.

As the download proceeds it is a good time to visit Adafruit’s website looking for the article from which this tutorial is based and start the download of the new kernel that we are going to use to transform our Pi Zero into an USB Ethernet gadget. Simply click on

If you haven’t done it yet, download and install Win32DiskImager which we will use to transfer the Raspbian image to our SD card. If you have used Noobs to get your Rasbian installation there is no need to use Win32DiskImager.
Extract Raspbian somewhere

and move on to Win32DiskImager to write Jessie on your card.
Writing the image to the SD card with this tool is fairly straightforward but it will take a cup of tea and biscuits to get to the end.

One way or another you now have an SD card ready to run Rasbian but we will not do that just yet. Having the card in your reader is a great opportunity to transfer the new kernel that you have just downloaded so that we can get the rest of the steps done directly on the Pi.

Rename the file you have obtained from Adafruit into “gadgetkernel.tgz”

and move it to your card where these other files are

Solder, serial debugger and terminal

So that you can get your Pi Zero Side-Car set up you will need to make some preparations. You will need to solder the header on your Pi Zero so that you can use a USB to TTL Serial Cable to connect to it as you will configure it to become an Ethernet gadget.

I have used Ryanteck’s Raspberry Pi Debug Clip because I found it to be a really clean and fool proof solution. Here you can find Ryan’s Wiki.

If you are going to use something different be careful with the connections. You will need to follow the diagram below:

With the header soldered and your Pi Debug Clip in place you should have something that looks very much like this

Make sure that JP1 in the Debug Clip is closed as this will allow you to power the Pi Zero directly from the Debug Clip.

At this point you are ready to fire up your Pi Zero. Connect your Serial to TTL cable or your Pi Debug Clip and your OS should be able to download the right drivers for you. Be wary that some Prolific based adaptors will not work correctly and you will need to go about finding a workaround to install the correct driver.

My Debug Clip had been recognised as COM3. To find out what yours will be just go your Computer icon, right click and select Manage. Select Device Manager and you should see something like this

Your Pi is in the meantime booting up and by now it should be ready for you to finally connect to it. If you haven’t already install Putty or whichever terminal is your favourite and choose to connect via Serial at 9600 baud (115200 should give you a better result). For me this looked like the following:

Once the connection is established you might see nothing or some gibberish. Don’t worry, just hit Enter or some other keys a few times and you should be prompted for a login (sorry I could not find a more elegant way).

Finally! We are in.

Let’s begin the mutation

As you login you should be able to notice the kernel version that comes as standard from 2016-02-26-raspbian-jessie. If you have missed it just type

uname -r

You should get 4.1.13+
As we are doing some exploring, type the following commands and save the output by copy/paste it into a text editor including the kernel version from above

type

lsmod

and

ls -la /boot/kernel.img

Good, let the mutation begin.

You need to unpack and move the new kernel in order to replace the original one. Doing this will ensure that a newer with extra modules will be used instead allowing us to enable the USB gadget functionalities. In particular in our case the Ethernet Gadget has been enabled in the new kernel, all we need to do is to provide some overlays and modules for it to work correctly.

To unpack the kernel execute the following commands.
You are moving in your own directory, moving there the kernel from where you had copied during the SD card prepare and unpack it’s contents.

cd ~
sudo mv /boot/gadgetkernel.tgz .
tar -xvzf gadgetkernel.tgz

Just to be on the safe side we are also going to backup the original kernel.
Execute these commands from you home directory which you needn’t have to move away from throughout the rest of the steps.

sudo mv /boot/kernel.img /boot/kernel.img.org

and replace it with the new one

sudo mv tmp/boot/kernel.img /boot/

Ignore the following message as it won’t affect the outcome of what you are doing.

mv: failed to preserve ownership for ‘/boot/kernel.img’: Operation not permitted

You will get this type of message several time with the next two steps.

We now need to install the overlays and the modules.

sudo mv tmp/boot/overlays/* /boot/overlays/
sudo mv tmp/boot/*dtb /boot
sudo cp -R tmp/boot/modules/lib/* /lib

The moving and coping is finished, before we reboot we just need to change a few configuration files.
The first file to edit is /etc/modules in which we are going to tell the kernel to load the g_ether module.
sudo nano /etc/modules

and add g_ether at the bottom of the file. Mine looks like this:

# /etc/modules: kernel modules to load at boot time.
#
# This file contains the names of kernel modules that should be loaded
# at boot time, one per line. Lines beginning with “#” are ignored.

i2c-dev
g_ether

the other file that we need to change is /etc/network/interfaces

sudo nano /etc/network/interfaces

you need to add the parts that I have highlighted in red

# interfaces(5) file used by ifup(8) and ifdown(8)

# Please note that this file is written to be used with dhcpcd
# For static IP, consult /etc/dhcpcd.conf and ‘man dhcpcd.conf’

# Include files from /etc/network/interfaces.d:
source-directory /etc/network/interfaces.d

auto lo usb0
iface lo inet loopback

iface eth0 inet manual

allow-hotplug wlan0
iface wlan0 inet manual
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf

allow-hotplug wlan1
iface wlan1 inet manual
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf

allow-hotplug usb0
iface usb0 inet manual

This will allow the Pi to bring up the usb0 network interface and automatically configure an IP address.

All is ready for the long waited reboot so let’s do just that

sudo poweroff

Once the Pi is off, remove the Serial to TTL cable or the Pi Debug Clip and plug the micro USB connector into the USB Data of the Pi Zero, the other side obviously goes into your laptop or PC.

After a while you should hear the familiar sound of a USB peripheral being detected by your Windows OS.
A new RNDIS driver should be automatically downloaded and installed. Just check that all is fine by looking into Computer → Management → Device Manager

You should see something like this:

If this is the case then you are truly very close to be able to SSH to your Pi Zero via USB!

Sorting out the networking stuff

If you open up your Networking and Sharing Centre you should notice that the new Local Area Network created by the RNDIS driver is marked as public
This might create some problems for the next few steps as local firewalls will look at traffic coming from a public network as something bad, as they should. For our purpose though this will make things difficult and until the set up is finished I would recommend you disable the local firewall and re-enable it only at the end. Once we know how things should look like we should be able to configure the firewall to allow for the necessary traffic.
At this point what we want to achieve is to be able to refer to the Pi as raspberrypi.local instead of using an IP, automatically configure the networking for the Pi and be able to remote to it via VNC.
The magic that allow you to resolve raspberrypi.local is called mDNS and it is natively supported in Rasbian, in Linux in general, in MacOS but not in Windows. Worry not though because Apple is generous enough to provide a package to allow Windows to say Bonjour to the Pi.
Downloading and installing Bonjour for Windows is extremely easy, once the file is downloaded simply execute it and next, next till the end.
Once Bonjour is running you should be able to resolve raspberrypi.local. To test it simply open a CMD session by typing CMD.exe in Start → Search programs and files. Once the window opens up simply type

ping raspberrypi.local

and you should get a few replies from your Pi. This is because both Rasbian and Windows support something called Link-Local address which will automatically configure both with a valid IP in 169.254.0.0/16 subnet. Doing so is enough for the two to communicate over IP but it won’t be enough for the Pi to connect to the internet.

To do so we need to enable Internet Connection Sharing on Windows so that the Pi not only will get an IP but will also be able to use the Windows box as a gateway to the internet.
Enabling ICS is very easy. Under Network ans Sharing Centre on your Windows box select Change adapter settings.
In my case I needed to share my Wireless Network Connection. I suspect that in most cases this will be the same for you too. By right clicking on the Wireless Network Connection → Properties move to the Sharing Tab and select at least the check-box on top. Also choose the Connection to which you are going to share to. In my case it was Local Area Connection 2 that was created by the RNDIS driver and to which the Pi Zero is connected to.

This will configure the Local Area Connection 2 with 192.168.137.1 IP address and enable the interface to work as a DHCP thereby issuing an IP like 192.168.137.x to the Pi
Click OK on the window and try to ping raspberrypi.local as we did earlier. Your Pi should now reply with its new 192.168.137.x IP address.

You may drink some more tea now, if you got to this point you deserve it!

The last piece of the puzzle is to enable VNC.
With Putty we will now connect to the Pi Zero via SSH. Open putty and type raspberrypi.local into
Host Name then click Open

as you login get back to the output of the commands we have saved earlier on and compare it with the new results when issuing the same command as before

uname -r
lsmod
ls -la /boot/kernel.img

you will surely notice the more updated kernel and the g_ether module being loaded as we expected.

From the command prompt execute the following to install tightvncserver

sudo apt-get install tightvncserver

If all the steps above have been performed correctly the package should be downloaded from the internet using your laptop’s wireless connection. Cool right!

To enable VNC Server run

vncserver -geometry 1280×800

I have used 1280×800 because that’s my laptop’s resolution and will make it nice when running the VNC session in full screen. If you have a different resolution change the command accordingly.

The first time you run vncserver it will ask you to set up a password. Also note that running the command above will create a session on screen :1

Time to run VNC Viewer from our Windows box and enjoy the fruits of our hard work.

After installing VNC Viewer you can connect to your Pi Zero Side-car by writing raspberrypi.local:1 in the VNC Server field and click Connect!

Finally we can enjoy reading our favourite magazine on our Pi Zero USB Ethernet Gadget through a shared internet connection. Easy right?

The set up and configuration of this can be hugely improved and automated and I am sure it will become a lot easier in the future. Running the VNC server automatically on the Pi can for example already be done and you can find resources about this directly from the raspberrypi.org website. Also it would be nice if the Pi would gracefully shutdown as the laptop initiates its own shutdown. For the time being just remember to shutdown your Pi before shutting down your laptop. Simply run

sudo poweroff

and wait a few seconds.

This is it! I hope you enjoyed setting your Pi Zero Side-car and will use it to make your Pi more portable and maybe to revive some decrepit laptop you have hidden somewhere which can now have a second life.