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

DownloadNewKernel

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

ExtractJessie

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.

Win32DiskImager WriteJessie

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”

RenameNewKernel

and move it to your card where these other files are

JessieContents-Before

NewKernelCopied

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.

Zero Male Header - 40 Pin

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:

SerialTTL-Connection

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

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

COMPortDebugger

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:

PuttyConnect

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).

PuttySerialLogin

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.

Annotaded

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:

RNDIS StatusIf 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
NetworkAndsharingCentreThis 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.

Wireless Share

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

SSHtoPi

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!

VNCLogin

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

MagPiSiteInPiZeroUSBEthernetGadget

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.

4 comments

    1. Hi Ronald, I am glad you liked it!
      I am not a Mac user, I know I should … If you know your ways around Mac OS we can attempt something in a DM via Twitter. I am @GarageTechTweet.

  1. Hello Francesco

    Excellent well-explained article in April 2016 Magpi that attracted me to doing it and I have it working. It is a great way to use a Pi Zero with my laptop especially when staying at a hotel on business.

    I have a few comments that may help others.

    1.
    I did it with the Adafruit USB to TTL connector cable (4 connectors to the pins as you show in the diagram on p. 48 of April 16 Magpi magazine) because the Ryanteck Debug Clip is out of stock everywhere. No problems with that cable and it can be purchased from Amazon in the UK but is actually shipped from Orsay in France in just a few days. (“USB to TTL Serial Cable – Debug / Console Cable for Raspberry Pi”).

    2.
    I had difficulty sorting out the network (p.48 – 49) because I failed to realise the Wireless Network Connection I needed to configure was the one that my Windows 7 laptop itself is using to connect to the wifi network; not one of the other Wireless Network Connections that I thought it would use!!

    Also, I never was able to see the IP address of the Pi Zero in IPv4 style (e.g. 192.168.137.x, that you discuss on p.49) when from my Windows 7 laptop I used CMD.EXE and ran :

    ping raspberrypi.local

    It only showed IPv6 addresses starting FE08::

    A good way to see the IPv4 address is to use from the Pi Zero
    ifconfig -a

    3.
    On p.49 it says do:
    vnserver – geometry 1280×800

    It wouldn’t work it said “Couldn’t access /home/pi/.vnc.”

    I got it to work by using:
    sudo vncserver -geometry 1280×800

    4.
    Your article here well explains the VNC Viewer by having a diagram – that was missing in the limited space that you had in the MagPi magazine.

    Overall: I was very happy with the article and the care you took explaining what commands were doing. I learned a lot and I’m delighted to avoid having to use a mouse, keyboard and screen with my Pi Zero.

    Thanks a million.

    Geoff

    1. Hey Geoff,

      I am truly happy things worked out for you in the end and mostly that you found the article useful. This is what pays the most, thanks!
      With regards to your points:
      1) Absolutely! The Debug Clip is great but Adafruit’s can work as well of course.
      2) Yes I realise the networking bit wasn’t the crystal clear set-up I meant it to be; good you find your way out in the end. I must have disabled my IPv6 on the Windows box which I do when messing about with these things. The best way for you to be sure you would ping raspberrypi.local with IPv4 would have been to use ping -4 raspberrypi.local
      3) I don’t quote know why you would get that message when running vncserver without sudo. I found this link which might help you somehow https://www.raspberrypi.org/forums/viewtopic.php?t=39933&p=365834
      4) This is the reason why I felt it was nice to post this on my site too, magazines are great but the space is very limited and rightly so.

      Thanks once again!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.