Raspberry Pi Zero – Programming over USB! (Part 2)

This is a follow on post from the older, more detailed documentation in an earlier post.


An extremely simple new way to setup Raspberry Pi Zero as a USB virtual network gadget, allowing SSH, SFTP, VNC etc over a single USB cable. All without need of a keyboard, mouse, screen etc to setup!
To make it clear though, this can only work with the Raspberry Pi Zero.

Quick history lesson

So back over Christmas 2015, I had worked on getting the Raspberry Pi Zero OTG/Slave USB mode working and documented. My work was based off the excelent work done by awesome volunteers from the Raspberry Pi community here and here.
Back then, it required you have a screen, keyboard, mouse and internet connection to set everything up from a stock Raspbian image. This was a bit of a pain if all you had was your normal Windows/Mac/Linux computer with downloaded Raspbian, an SD card, Pi Zero and a USB cable.

Then, with the  2016-05-10 release of Raspbian, the required modules and kernel version were included on the stock Raspbian images, but they still required configuring. At least all this could be done with a screen and keyboard plugged into the Pi Zero (no internet required).

Now, after a heck of a lot of Linux Kernel documentation digging/hunting around, I have stumbled across what seems to be a very little known kernel cmdline parameter. This parameter allows us to do all the configuration on the /boot partition, which is formatted FAT32 and readable on Windows/Mac/Linux (vs normal root partition only being readable with Linux).

What does this mean?

You can now set up a virtual network connection between your Raspberry Pi Zero and normal PC using a single USB cable in a matter of seconds, without the need for any extra hardware!
No need for an HDMI screen, keyboard, mouse etc, all with stock Raspbian Jessie lite or full.
You can then SSH into the Raspberry Pi Zero, copy files with SFTP or use VNC (extra installation required).

How do I set it up?

Setup is super simple! Once you have flashed your Raspbian image, should take only a few minutes to set it up! See guide below.

238 thoughts on “Raspberry Pi Zero – Programming over USB! (Part 2)”

  1. This looks really great! Just one question – you used the g_ether module in your guide above; could other modules (such as g_serial or g_mass_storage) be implemented in this way?

  2. Does this only work on the zero or can it work with any Pi?

    Connecting over USB networking ‘out of the box’ was always the big advantage that the Beaglebone had over the Pi…

    1. This can only work with the Raspberry Pi Zero, given USB is directly connected to the processor, where as the larger Pis it goes via the LAN hub chip. A and A+ are missing the ID pin so can’t dynamically detect USB master or slave, so defaults to master.

  3. I wonder if this will work with the other Pi units. It would be really handy when working with Micro-Controllers and cannot get to the board easily. It would make mass setup of a bunch of units easier.

  4. I seem to be having a senior moment here, which, due to my age is appropriate.

    My main computer runs Windows 10. I’ve got the PiZero plugged into one of the USB ports using a micro usb male to normal usb male plug. I put the micro end into the non-power port, the one closest to the HDMI plug.

    The lights are on … but nobody seems to be home.

    When I use putty (port 22) to connect to raspberrypi.local it doesn’t find anything.

    Obviously user error. Any ideas?


      1. I checked out the task manager and Bonjour Services are running. I rebooted the box and still no joy.

        I am going to try some different cabling combinations.

        I hope to find a direct USB OTG male (connect to PIZero non-power port) to USB male (connect to a usb port on my PC).

        Thanks for trying to help me out.

        1. Same problem here.
          Windows 10. Image flashed ,config and commandline updated, after start no connection. Ipconfig on windows don’t show anything :/

          It seems I’ll have to buy mini hdmi cable after all ( or wifi dongle)

    1. Ted
      I also spent quite some time on trying to set this up!
      Problem 1 – just could not see the using boot directory, config,txt or cmdline.txt files in my Win 10 File Explorer; so I had to set up the keyboard/TV again so that I could access the Zero boot directory, and then alter the two files using the terminal and “sudo nano config.txt”. Save, reboot, and dismantle, then back to the USB plugin on my Win 10 laptop
      Problem 2 – fiddling around with Device Manager to work out which update to give the “yellow triangled Ethernet device” but eventually, it came up as a working USB.
      And then the Zero worked as a plug in USB over PuTTy.

      So maybe not quite the ‘super simple’ setup young Andrew writes about !! But hey! got there!

      1. I am not sure what is up here, but I have had no issues with Windows 10 and it appearing? The Raspbian SD card image includes a FAT32 partition and an ext3 partition. Windows will be unable to read the ext3 partition, but FAT32 is a standard partition format that Windows will happily accept, as the many other people trying this out have found without any issues.
        Windows 10 also should include the USB Gadget ethernet device driver, given it is actually just emulating a standard USB ethernet device, nothing special about it.

        Could perhaps there be something weird with your Windows 10 setup? Perhaps a machine connected to an enterprise network (and in turn locked down with Group Policy) or have something like an antivirus software that doesn’t like external devices?
        I am certainly not able to reproduce any of the issues you have brought up and is first anyone has reported them?

        1. Andrew – my apologies for being a bit snarky – you certainly do know what you are talking about [ and your extremely impressive “About Me” makes that point very convincingly]

          I retraced my steps and have identified my problem.

          1. Root cause – I had not enabled the “hidden/disabled” administrator account on Windows 10. [I was under the impression that Win10 accounts had administrator rights.]
          2 Yesterday, when working through raspberrypi.org, I downloaded Jessie and the Win32DiskImager, but Win32DiskImager wouldn’t run because it needed elevated rights. I backed off from sorting that out, and headed for the NOOB download and the raspberrypi.org method for copying files to the SD – and amending the config.txt and cmdline.txt files on my Zero. That worked – but a bit tedious on setting up the TV/keyboard/mouse front.
          3 This morning, I enabled the Win10 administrator account; ran the Win32DiskImager; and with the Jessie image on SD was able to quickly and simply amend the config.txt and cmdline.txt files.
          4 Simples!!

          Apologies again –
          YOU WERE RIGHT – this IS a “super simple” way to set up access to the Zero [though older folk like me might need to be gently reminded to work as an administrator]

    2. I had exactly the same problem. After plugging the USB cable between the Pi and the PC, in Device Manager, I get a Network adapter: USB Ethernet/RNDIS Gadget but with a yellow triangle. After I right clicked on the entry, then clicked “properties”->”advanced” I entered an IP address. This fixed the yellow triangle. Everything started working and I could log into the Pi zero.

      Hope this helps.

  5. Nice write up. Thank you. I will be trying this when I receive my rpiZ.
    Any idea if this works on other versions of RPI?

  6. For those that want to have internet access on the pi after doing this and are using windows:
    On the windows pc enable internet connection sharing (Control Panel > Network and sharing center > Adaptor settings > Properties > Sharing) .
    Don’t use a static IP address on the pi as internet connection sharing is not compatible with static IPs! (took me a while to figure out)
    With static IP disabled, To connect to the Pi use its host name. For windows to find devices by host name you will need to install bonjour or (samba?) or similar.

    1. I cant seem to figure this out. I am getting a 169.254 address on my pi and virtual interface which tells me it cant reach a dhcp server(my router). I cant update my pi because it cant resolve the domain names to grab the files because it seems that dns isnt working. I have network sharing enabled. Am I doing something wrong?

      1. I’m fairly certain that the windows pc acts as the dhcp server for the device that the internet connection is shared to. (PC = DHCP server for pi)

        For me the pc uses the addresses: on the (USB Ethernet/ RNDIS Gadget) for the ethernet connection provided by my routers DHCP server.

        The Pi Zero reports an address 192.168.137.*

        where * changes each time it is booted. So far I have not found a way to stop the pi’s address changing while still maintaining connection.

        I don’t understand the process well enough to know what the problem you’re having is caused by, but as a quick suggestion, make sure that internet connection sharing is enabled on the network adaptor that has your current internet connection on. Secondly try testing with any other networks disabled. (i.e. only enable the network with internet access and the Pi Zero connection.

        1. I managed to figure it out. I statically assigned a 192.168.137 address to the pi and everything started working.

    2. Hi, I did connect my host computer to my PiZero through SSH, and the internet is shared as you mention, no STATIC IP, but I still have problems to connect the PiZero to internet. I think, the problem is that the dynamic ip that my computer gives to the PiZero is not in the same ip address 192.168.1.*/24, instead, the PiZero ip adddress is 169.254.*.* . What I am missing?

  7. Wow, excellent write ups! Any chance this might work on the other models?

    ONLY KIDDING, LOL!!! You might need to change the font to luminous and flashing border….

  8. Great work Andrew! Will hopefully get a chance to play with this soon.

    It’s a shame so few people bother to read the existing comments, before posting theirs 😉

  9. I tried it under Linux Mint 17.3 without luck. dmesg shows the connected device but it’s not possible to connect to the RPi0 with ssh:

    [ 3782.623984] usb 2-2: new high-speed USB device number 2 using ehci-pci
    [ 3783.019595] usb 5-2: new full-speed USB device number 2 using ohci-pci
    [ 3783.487144] usb 2-2: new high-speed USB device number 3 using ehci-pci
    [ 3784.162493] usb 5-2: new full-speed USB device number 3 using ohci-pci
    [ 3784.320500] usb 5-2: not running at top speed; connect to a high speed hub
    [ 3784.334499] usb 5-2: New USB device found, idVendor=0525, idProduct=a4a2
    [ 3784.334511] usb 5-2: New USB device strings: Mfr=1, Product=2, SerialNumber=0
    [ 3784.334518] usb 5-2: Product: RNDIS/Ethernet Gadget
    [ 3784.334524] usb 5-2: Manufacturer: Linux 4.4.9+ with 20980000.usb
    [ 3784.343034] cdc_ether 5-2:1.0 usb0: register ‘cdc_ether’ at usb-0000:00:13.0-2, CDC Ethernet Device, a6:7a:69:71:b8:7a
    [ 3784.673937] userif-3: sent link down event.
    [ 3784.673971] userif-3: sent link up event.
    [ 3790.046232] userif-3: sent link down event.
    [ 3790.046244] userif-3: sent link up event.
    [ 3835.034499] userif-3: sent link down event.
    [ 3835.034509] userif-3: sent link up event.

        1. Seems that dns does not work somehow but it works with IPv6 !!!!!

          I found the IPv6 adr with:

          $ avahi-browse -art
          + usb0 IPv6 raspberrypi Remote Disk Management local

          = usb0 IPv6 raspberrypi Remote Disk Management local
          hostname = [raspberrypi.local]
          address = [fe80::ae54:35ca:1bdd:3400]
          port = [22]
          txt = []
          = usb0 IPv6 raspberrypi [42:e9:3b:10:2f:3f] Workstation local
          hostname = [raspberrypi.local]
          address = [fe80::ae54:35ca:1bdd:3400]
          port = [9]
          txt = []

          and RPI0 is available with ping:
          $ ping6 -I usb0 -c 3 fe80::ae54:35ca:1bdd:3400
          PING fe80::ae54:35ca:1bdd:3400(fe80::ae54:35ca:1bdd:3400) from XXXXXXXXXXX usb0: 56 data bytes
          64 bytes from fe80::ae54:35ca:1bdd:3400: icmp_seq=1 ttl=64 time=2.87 ms
          64 bytes from fe80::ae54:35ca:1bdd:3400: icmp_seq=2 ttl=64 time=0.870 ms
          64 bytes from fe80::ae54:35ca:1bdd:3400: icmp_seq=3 ttl=64 time=1.13 ms

          — fe80::ae54:35ca:1bdd:3400 ping statistics —
          3 packets transmitted, 3 received, 0% packet loss, time 2001ms
          rtt min/avg/max/mdev = 0.870/1.628/2.879/0.892 ms

          SSH connects to the RPi0 if the interface is specified:
          $ ssh -6 [email protected]::ae54:35ca:1bdd:3400%usb0

          Thanks a lot for your blog post!

          1. I also had the same problem with the USB-network only working over IPv6 on Ubuntu 14.04, but I figured out how to also get it working over IPv4, which ‘fixes’ raspberrypi.local 🙂

            You need to go into the network-manager menu, Edit Connections… and edit the new Ethernet connection (for me it was “Wired connection 2”). Switch to the IPv4 tab, and change the Method to “Link-Local only”. Click Save and then Close.

            The usb0 network interface will then get assigned a 169.254.x.y address, and “ssh [email protected]” will work just like it should.

          2. Thanks for this great info!

            I was not able to ping raspberrypi.local and went your ipv6 way.

            lsusb confirms that Pi Zero really provides network device:
            $ lsusb | grep USB
            Bus 001 Device 002: ID 0525:a4a2 Netchip Technology, Inc. Linux-USB Ethernet/RNDIS Gadget

            Next I got usb0 ipv6 address from /sbin/ifconfig:
            $ /sbin/ifconfig usb0
            usb0 Link encap:Ethernet HWaddr d6:89:a2:22:3f:9a
            inet6 addr: fe80::d489:a2ff:fe22:3f9a/64 Scope:Link
            RX packets:0 errors:1 dropped:0 overruns:0 frame:1
            TX packets:517 errors:0 dropped:0 overruns:0 carrier:0
            collisions:0 txqueuelen:1000
            RX bytes:0 (0.0 B) TX bytes:112873 (112.8 KB)


            Immediately ping6 worked as for you:
            $ ping6 -I usb0 -c 3 fe80::d489:a2ff:fe22:3f9a
            PING fe80::d489:a2ff:fe22:3f9a(fe80::d489:a2ff:fe22:3f9a) from fe80::d489:a2ff:fe22:3f9a usb0: 56 data bytes
            64 bytes from fe80::d489:a2ff:fe22:3f9a: icmp_seq=1 ttl=64 time=0.067 ms
            64 bytes from fe80::d489:a2ff:fe22:3f9a: icmp_seq=2 ttl=64 time=0.073 ms
            64 bytes from fe80::d489:a2ff:fe22:3f9a: icmp_seq=3 ttl=64 time=0.075 ms

            — fe80::d489:a2ff:fe22:3f9a ping statistics —
            3 packets transmitted, 3 received, 0% packet loss, time 1998ms
            rtt min/avg/max/mdev = 0.067/0.071/0.075/0.010 ms

            But “ssh -6” does not let me in:
            $ ssh -6 [email protected]::d489:a2ff:fe22:3f9a%usb0
            ssh: connect to host fe80::d489:a2ff:fe22:3f9a%usb0 port 22: Connection refused

            I did boot Raspbian with power, USB keyboard and HDMI and was able to successfully do “ssh localhost”, so sshd is running.

            The syntax seems to be correct as this change from usb0 to (non-existant) usb1 shows:
            $ ssh -6 [email protected]::d489:a2ff:fe22:3f9a%usb1
            ssh: Could not resolve hostname fe80::d489:a2ff:fe22:3f9a%usb1: Name or service not known

            What can be the reason the very last step of doing the actual “ssh” gets refused?


          3. Thank you so much rena2019 ! I spent several hours trying to connect to my Zero and your comment solved it perfectly. As a bonus i was always puzzled by this IPv6, first time it proves useful :=)

      1. Has anyone figured out a way to do this with an Android phone? I assume you would need a phone capable of OTG ethernet. It would be so convenient for me to be able to plug my deployed zeros into my phone instead of my bulky laptop in the field.

        1. Android phones are actually really easy. Just connect with OTG cable and micro USB cable, and in settings on your phone, go to More (at top near networking settings), then you should see something about tethering and hotspots, and in that menu you can activate USB Tethering. IP subnet should be the same on all phones, Use the app Fing to search that subnet and you should find you RPi zeros up address, and you can use your favorite SSH client on your phone to connect to it

  10. If I connect the RPi0 to a Windows PC I get the following error in the device manager under the “USB Ethernet/RNDIS Gadget” device (with yellow warning icon)

    “This device cannot start. (Code 10)
    {Operation Failed}
    The requested operation was unsuccessful.”

        1. I was able to SSH using putty only when I updated the driver software automatically for the “Ethernet Device”.
          So at first it appears yellow, right click and then click on update driver software.

  11. Great work, this is so much easier to setup now.

    Should this work on all operating systems using the 4.4 kernel? I can get g_ether working on Raspbian but not the May release of OSMC. Am I missing something obvious?

    1. It should for all that are using the official Raspbian kernels, but don’t enough experience with OSMC to say if it does or not.

  12. Got my Zero today, downloaded Jessie full, formatted an eight GB SD ultra card, used Image Writer to write the IMG, edited the files then booted Zero and tried to login;
    pi / raspberry
    Access Denied
    I’m using Putty (current version)
    With the Zero not plugged in Putty can’t connect so I know it is not something else I’m trying to login to.

      1. Rebuild the SD card twice, downloaded another image, twice, the keyboard has worked, is working with raspberry pi 2, and the pi/raspberry still doesn’t work on the Zero.
        The Bonjour configured the firewall, it shows Google Chrome (mDNS-In) owns the 5353 inbound UDP port.
        Tried ‘sharing’ the ‘Ethernet’ connection and lost connection to my local network…..
        I ordered all the cables, USB powered hub and another large bottle of TUMS.

        1. UPDATE: I double checked my PI 2 that it could do SSH still, nope. Seems all my windows 10 machines will not connect while XP machine will. My Windows 10 machines can connect to my Linux servers.

          From the auth.log
          May 30 16:41:07 raspberrypi sshd[1325]: pam_unix(sshd:auth): authentication failure; logname= uid=0 euid=0 tty=ssh ruser= rhost= user=pi
          May 30 16:41:09 raspberrypi sshd[1325]: Failed password for pi from port 50526 ssh2
          May 30 16:41:14 raspberrypi sshd[1325]: error: Received disconnect from 13: Unable to authenticate [preauth]

          Both Windows 10 machines are new installs as of 5 days ago.

          I just sudo apt-get update/upgrade on my PI 2 and now I can login from a Windows 10 machine

          1. Modified the files on the new SD card I had in the PI 2 after I had updated. Plugged the SD card into the ZERO and now can connect with Windows 10 Putty.

  13. After following the instructions on my newishly reinstalled Windows 10 Home 64 bit the pi appeared in device manager and as an ethernet adaptor but was assigned a default address in the 169.xxx.xxx.xxx range.
    To make it work I had to also do the following:
    1. Install Bonjour print services from the link in the post (as documented – I had already done this before connecting the pi)
    2. Go into Network & Sharing centre
    3. Click on my active internet connection – in my case Wi-Fi – opens the connection Status dialog
    4. Choose Properties – opens the connection properties dialog
    5. Select the Sharing tab
    6. Check the box “Allow other network users to connect…”
    7. Select the connection corresponding to the USB Ethernet/RNDIS Gadget – in my case Ethernet 5
    8. Hit OK.
    After a short pause the connection address changed from the 169 range to and I was able to point my ssh client at raspberrypi.local and connect.
    It may be that your machine already had ICS configured – no matter – what a handy thing to be able to do!
    Collateral benefit is that enabling ICS gives the Pi internet access from the start – I know this has already been covered in the comments but I found that ICS was essential in order for the Pi and the USB Ethernet device to get assigned addresses.
    Here’s another challenge – can this be adapted so that several Pi Zeroes can be connected via USB (hub? hubs?) such that they are all networked together and sharing just one ethernet or wifi dongle? Would be a great basis for a Pi Zero cluster!

    1. I am actually going to begin working on this and have begun my acquisition of pi zero’s. (Microcenter still only lets me buy one per visit so I go every day during my lunch hour) Thinking of using a raspberry pi 3 with 4 usb 4 port hubs and 16 pi zeros set up. Im only on day 3 of my acquisition though…

  14. Okay so it turns out the ICS thing is handy but not essential – raspberrypi.local is resolving to an IPV6 address so it’s not using the ICS at all – except that the Pi can see the internet via network adaptor usb0 which has an IPV4 address too – assigned from ICS. I’m still fascinated by the idea of a Pi cluster just using a master Pi connected to a wifi dongle or ethernet adaptor and several slave PiZeroes connected to it…

  15. Ok after following this tutorial, I am now operating my Pi completely headlessly and with internet access (Windows):
    1. Follow the instructions in the tutorial
    2. Once the Pi Zero appears as an ethernet device in device manager make sure the drivers are completely up to date (Right click and search online for drivers) luckily windows found them and pulled through for me.
    3. Open up putty and SSH using default port 22 and the address rapberrypi.local
    4. If all you want it terminal access stop here, if you want graphical access continue.
    5. You may want to configure the Pi Zero to have a static IP address on your home network, therefore you will need to edit the network interfaces file, type in “sudo nano /etc/network/interfaces” on your putty terminal.
    6. Comment out everything but the line “source-directory /etc/network/interfaces.d” and add all the information corresponding to your network setup as such:
    (information can be obtained by using cmd on your windows computer and typing “ipconfig” recording all important addresses such as gateway, broadcast etc if you dont already know them)
    auto lo
    iface lo inet loopback

    allow-hotplug usb0
    iface usb0 inet static
    address 192.168.0.XXX # whatever IP address you want the pi zero to occupy however it must not clash with the IP’s currently on the network or the ones which the DHCP assigns.
    network # the base IP of your network
    broadcast # whatever your broadcast #address is
    gateway # gateway IP for your network
    nameserver # google nameserver
    dns-nameserver # google dns servers

    7. Hop back over to your windows computer and go into “change adapter settings” in the networks and sharing center.
    8. Click on properties on Pi Zero ethernet adapter, and then click on ipv4 properties, set the IP address acquisition to manual and enter the static IP address you want assigned to the Pi Zero, along with the broadcast address, leave the gateway blank.
    9. Save these settings, and then highlight your Wi-Fi / Ethernet device and also your Pi Zero eth adapter and then click on “add to bridge” – this will bridge these two adapters and allow internet access to be shared.
    10. Restart your Pi Zero with the changes you made in step 6.
    11. Restart your computer also if necessary.
    12. When your computer starts up head over to putty log in to your Pi and type ifconfig in the terminal, you should see the ip address you assigned appear as the IP address of the device.
    13. Double check connections by pinging the IP address of the host device and then ping http://www.google.com , if this does not work try pinging which is a google nameserver, if it can get a response your DNS configuration may be an issue. Please check your route table and ensure that it has added the route to your host computer and to the router.
    14. If you can ping google you are in good shape, type in “sudo apt-get install xrdp” , then reboot
    15. Windows should already have installed remote desktop connection, type in the IP address you have assigned to the Pi Zero and you should be able to set up a remote connections, complete with visual control over the single USB cable!
    16. If you have any issues, post and I may be able to help.

    1. Hi

      Followed your instructions and everything works fine until I try to RDP into the RPi, I get the xrdp login screen enter pi/raspberry then get;

      connecting to sesman ip port 3350
      sesman connect ok
      sending login info to session manager, please wait…
      xrdp_mm_process_login_reponse: login successful for display
      started connecting
      connecting to 5910
      error – problem connecting

      Any help would be appreciated

      1. I found this and it worked for me
        Apparently there is a/are defect(s) which prevent xrdp working with the vncserver. However it works with tightvncserver

        Also the order of installation of tightvncserver and xrdp seems to be important.

        In summary
        •remove the following packages : xrdp, vnc4server, tightvnc

        sudo apt-get remove xrdp vnc4server tightvnc
        •install tightvnc server followed by xrdp

        sudo apt-get install tightvncserver

        sudo apt-get install xrdp

      2. Hey I was just dealing with this issue. I found this (https://raspberrypi.stackexchange.com/questions/56413/error-problem-connecting-to-raspberry-pi-3-with-xrdp) question stackexchange that solved it for me .

        I SSHed into my Rpi and typed the following:

        sudo apt-get remove xrdp
        sudo apt-get install vnc4server
        sudo apt-get install xrdp
        sudo service xrdp restart
        sudo reboot

        I’m assuming you are already providing your pi zero with an internet connection somehow? If not here’s a guide on how to share your computers internet through USB as well. http://www.circuitbasics.com/raspberry-pi-zero-ethernet-gadget/

        Hope this helps!

  16. This is my setup;
    auto lo
    iface lo inet loopback
    allow-hotplug usb0
    iface usb0 inet static

    But #9 stopped me, there is not any way to ‘highlight’ Ethernet 2 and Local Area Connection’ then Add to bridge. Windows 10.

    When I reboot ZERO Windows tells me there is a conflict with an IP address

    1. I found an error:
      Log Name: Microsoft-Windows-Kernel-PnP/Configuration
      Source: Microsoft-Windows-Kernel-PnP
      Date: 5/30/2016 9:31:09 AM
      Event ID: 441
      Task Category: None
      Level: Error
      User: SYSTEM
      Computer: Gate
      Device USB\VID_0525&PID_A4A2\5&7727b50&0&4 could not be migrated.

      Last Device Instance Id: SW\{EEAB7790-C514-11D1-B42B-00805FC1270E}\ASYNCMAC
      Class Guid: {4d36e972-e325-11ce-bfc1-08002be10318}
      Location Path:
      Migration Rank: 0xF000FFFFFFFFF132
      Present: true
      Status: 0xC0000719
      Event Xml:






      This is from the Acer Incorporated driver dated 1/13/2010 version

  17. Disconnect the pi and see if you can still ping from anywhere. You may genuinely have two machines with the same IP, if .244 is within the range handed out by your DHCP server. Or if you earlier configured another pi with the same setup and forgot it was still plugged in somewhere?

    1. I started from scratch but before adding ip information in the interfaces file I went to Network and Sharing Center / Change adapter settings and there I was able to ‘highlight’ Ethernet 2 (ZERO) and Local Area Connection then bridge them. The bridge operation gave Zero a DHCP address and I reserved that address in my router.
      sudo apt-get update now works!

  18. Update on Zero; I removed the bridge, Ebay was timing out and all sites were doggie. Internet now works again.

  19. Do I need besides the Zero and SD Card:
    an OTG usb cable/shim for this or will a regular micro to normal size USB cable work?
    I have read part 1 of blog too, but I am unsure 🙂

  20. Just a note, if you’ve changed your raspberry pi hostname from the default “raspberrypi” to something_else, you need to use that new hostname instead so it looks like

    ssh [email protected]_else.local

  21. I wonder if anyone else has played with separating networks using this to demonstrate to learners in networking that what seems like homogeneous device ecosystem (A.K.A Internet of Things), can actually be many devices connected over different interfaces and protocols.

    I’m working on something with wireless-lan, using rPi3 as a wireless access-point, that has rPi-zero’s connecting over wlan using built-in credentials from /etc/wpa_supplicant/wpa_supplicant.conf. Trying to switch to USB over gadget mode I feel kinda stumped…

    I’m not even sure how practical it would be to have N rpi-zero’s, but just the fact it could be boxed up, easily and affordably presented to showcase such a wide array of connected concepts interests me.

  22. Hi, I have used the information in the post and in comments to somewhat make pi zero work with my Ubuntu 16.04 desktop: I can ssh into the PI Zero, but I am really struggling to make the pi access the Internet through my PC. Is there a way to do that?

    1. See the link to the rough’n’ready script that I wrote to do this in another comment of mine below (written on 8th June 2016).

  23. Once I had the pizero connected as a usb slave and was able to ssh to it/apt-get update etc. I added the network section to /etc/wpa_supplicant/wpa_supplicant.conf for my wireless lan so now I can run it either in usb slave mode when I want to change things or just plug in a usb wifi dongle and connect power to run headless. No other changes needed as it detects which mode to run in by what it’s connected to. Great!

  24. I was doing lots of experimentation with this last night, and found that every time I reboot the Pi Zero, it generates a new random MAC address for each side of the USB-network connection. On Ubuntu this is especially annoying as it creates a new “Wired Connection N” for every unique MAC address it sees – I got up to “Wired Connction 10”! (And for each new Wired Connection that got created, I had to manually set it to LinkLocal as described earlier)
    I did a bit of searching, and found some useful info at http://wiki.openmoko.org/wiki/USB_Networking about hardcoding the MAC addresses. In my case (after connecting to the PiZero over SSH) I added:
    options g_ether host_addr=26:7f:62:5c:48:86 dev_addr=d6:fe:44:ad:8f:13

    to the file /etc/modprobe.d/g_ether.conf and after rebooting again, both sides of the connection now have a static MAC address, which means Ubuntu doesn’t create new “Wired Connection”s, and I was able to then go and delete the all old / redundant “Wired Connection 6” etc. that it had created.
    In the g-ether.conf file, host_addr determines the MAC-address on the PC-side of the connection, and dev_addr determines the MAC address on the PiZero-side of the connection.

    Based on the info at https://github.com/raspberrypi/linux/issues/1212#issuecomment-224105217 I’ve also created a script to automatically setup internet access for the PiZero:

  25. One thing I noticed is the MAC address of the network connections (on both the device and host) are randomly generated at each boot. This is a bit annoying if you want to use a DHCP server to reserve a IP address for your gadget.

    I got round this problem by adding the following after “rootwait modules-load=dwc2,g_ether ” in the “cmdline.txt” file:

    You can also specify other options for host_addr, iManufacturer and iProduct, but I haven’t had time to try these.

    1. LOL, I noticed the same thing about the random MAC addresses too (and found it annoying for a different reason), and I also posted a note about how to fix it earlier today as well! (but my comment contains a couple of URLs, so it hasn’t been approved yet).
      Great minds think alike, etc.

      Your way of fixing it (by adding options to cmdline.txt) is slightly neater than my way of fixing it (by adding options to /etc/modprobe.d/g_ether.conf) though 🙂

    2. Adding that after the modules-load=dwc2,g_ether did not work for me, did you enter this as a new option (space separating it from “dwc2,g_ether”) or as another option t modules-load (comma separating it from dwc2,g_ether)?

  26. Hi

    Im trying to connect via MAC os but looks like Bpnjure does not detect my PI Zero. Do any of you try this on OSX?

    1. I have found the root of the problem. My USB cable is broken. After changing to other one everything works perfectly.

      P.S. Very nice work with this post 😉

  27. Does the rpi0 have two usable USBs? If so, you could build a cambridge ring from them, each one daisychained to the next. [I actually did that (many) years ago with the BBC Micro’s serial port, but that required more complex software – because there was only one serial port, data out went on the TX pin but replies had to go all the way round the ring to come in on the RX pin from the machine on the other side!]

    1. Nope – the BCM2835 (SoC used on the Pi Zero) only has one USB interface, and this is directly exposed on both the Zero and A+ (and ComputeModule). The B+ / Pi2 / Pi3 all use a LAN9514 to provide an Ethernet interface and 4 downstream USB ports (i.e. using a built-in USB hub).

  28. I’ve been trying this on a Macbook Air and I can’t seem to get the raspberrypi.local address to resolve. Are there any other troubleshooting steps you can suggest? It definitely boots and I have made the changes to the two files.

  29. Ok, my previous comment is now null and void. I missed an “=” and put in a “-” instead. It took me three times rechecking it to catch it.

    Now, about internet connection sharing on a Mac…..

  30. I had real trouble with this. The Pi Zero wouldn’t show up as a network device at all on either Jessie Lite or Full.

    I finally got it working after much debugging by changing the cable. So one important note to make is that the cable does make a difference.

    1. Yeah, I guess some USB -> microUSB cables will be power-only (i.e. only two wires connected) – they will still allow the Zero to receive power and boot up, but the PC won’t “see” it.
      You need to use a “normal” USB -> microUSB cable (i.e. with all four wires connected – two for power and two for data) to allow the PC to see the Pi Zero as a USB device.

  31. Excellent stuff – I’ve been developing using the a pi set up with the original instructions all year now 🙂
    But … trying the New Simple Method on a Mac has turned into a World Of Pain – the Pi shows up as either an RNDIS device (g_ether) or CDC device (g_cdc) … but I don’t seem to be able to get the Mac to serve it up an IP number 🙁
    Oh well, a bit of virtual box and such will let me sort it out.
    Did anyone get this to work with a bit of Mac configuration ?

    1. I was able to get it working fine using Mac OS internet sharing without any issue? By default though you shouldn’t need one as should work for dirrection connection (without internet) using raspberrypi.local (bonjour).

      1. I’ll take another look – I looked at the avahi config on the “fresh” image, and it has nothing to enable avahi to advertise the ssh service – just remote disk management.
        Perhaps everything work fine letting the Mac and the Pi do self assigned numbers (in the network)?
        I shall report back.

        1. I haven’t looked at it in detail, but AIUI avahi (a.k.a. bonjour a.k.a zeroconf) is only used here for the name-resolution, i.e. mapping raspberrypi.local to the 169.254.x.y that actually got assigned to your PiZero. As Dody Suria Wijaya noted in another comment, if you change the hostname on your Pi to e.g. mypizero than Avahi maps mypizero.local to 169.254.x.y (and raspberrypi.local won’t exist).

          1. Hi Andrew, I tried this all again with a fresh image … and by following the following steps, everything works – and there’s a note at the bottom about what I think was wrong.

            1. Modify the /boot/cmdline.txt & /boot/config.txt per The New Simple Method
            2. On the Mac, in “System Preferences”, ensure that the “RNDIS/Ethernet Gadget” interface, if it is there, is set to DHCP
            3. Make sure that Internet sharing is NOT enabled. If it is and you have another Pi called “raspberrypi.local”, Bad Things Happen and you may never connect to your Pi over ethernet.
            4. Plug the Zero into the Mac with your (known working) micro-usb cable … and wait …
            5. After a while (about two or three good swigs of tea), use “ping raspberry.local” … and behold, the Zero should respond, and the IP number will be revealed. If not repeat this step. You will not need a new mug of tea.
            6. Use ssh to log in with the IP number from #5.
            7. Some while later, note that avahi/zeroconf/bonjour has got the rhythm and that using “ssh [email protected]” now works.
            8. Change the hostname to something sensible (i.e. unique and memorable), and reboot
            9. Once you can connect using the new hostname, have a go at enabling Internet Sharing for the “RNDIS/Ethernet Gadget”. Don’t change the DHCP setting on the RNDIS thing either.
            10. Reboot, check all working, make a new cup of tea to celebrate.

            So, what was wrong? My guess is that my network is a little complicated and I had some old configuration around internet sharing and on the RNDIS gadget. When I cleaned up the old config, and stopped the VPNs etc. everything sprang into life. I would also say that I was a little quick to try to log in (natural impatience) and this meant that bonjour had not caught up with the adverts from the pi.

            BTW, thanks for publishing this blog – Using the PI with OTG has transformed the way I do things when travelling.

  32. not working on OS X 10.10.5 on the Macbook Air… configured the zero’s /boot/cmdline.txt and /boot/config.txt… zero boots fine, but is not assigned an IP address and is not accessible (Apple’s Bonjour is installed and running and remote login is enabled on OS X)

    any tips? tia!

  33. So: for us Apple OS X users:

    1. configure your Zero’s cmdline.txt and config.txt files
    2. turn on File Sharing via System Preferences
    3. ssh or sftp using [email protected]
    4. if you have previously configured vncserver on your Zero, you can access the running VNC service with:


    hope this helps! now my Zero is a fabulous little Python development platform!

    1. In my own testing, enabling file sharing wasn’t needed to connect to a Pi Zero over SSH, or using SFTP given both of those rely on the services offered by the Pi side, so shouldn’t make any difference?
      I just checked and my test machine running Mac OS does not have it enabled and works fine.

      1. tks! will test on my system again and report back – a very nice feature indeed – quite remarkable … however, i did note that Internet access is not configured or assigned for the usb0 interface as the IP range is outside my router’s LAN addressing?

        the VNC access alone makes this a convenient development system!

        1. Yeah, the IP address for the usb0 interface *has* to be outside the range assigned by your router. If your computer has two interfaces (e.g. eth0 and usb0) in the same network-range, then it won’t know which interface to use when trying to reach a specific address. That’s why eth0 and usb0 have to be in different network ranges, and you need to use ‘internet sharing’ / bridging / etc. so your computer knows to route traffic from one network to the other.

          1. A comment on the terminology, not on the advice:
            That’s usually true if routing (with an exception for routing from some subnet to a ‘more specific subnet’ which some routers support, maybe not on the pi), but if you are bridging between two interfaces, then both interfaces can (and indeed must) be in the same subnet – that’s the very definition of bridging…

          2. Thanks Graham, I guess I must have meant “IP forwarding” rather than “bridging” in my previous comment. Spot the networking noob! 😉

            So maybe you *can* bridge eth0 and usb0 if they’re on the same network subnet, but I’ve no idea how to do that (or whether it’d be better than simple “internet sharing” / forwarding / routing or not).

  34. OK! tks for all the comments on this blog! i can confirm that File Sharing does *not* have to be enabled…

    i should have paid more attention to an earlier comment regarding USB cabling – not all USB cables work! i found one that did work and it was a short, direct cable – no adapters or power switches attached – simply USB malemicro usb male

    connection appears as “RNDIS/Ethernet Gadget” under System Preferences->Network… using DHCP, it is assigned… i then ssh in using:

    ssh [email protected]

    and start a vnc session (on :1) , then connect using


    thanks all!

  35. oh, and configuring ‘net access for the raspberrypi.local was easy with a couple mouse clicks:

    System Preferences->Sharing->Internet Sharing (then select the checkbox for “RNDIS/Ethernet Gadget”

    Raspberry Pi Zero – what a great little computer!

  36. Can anyone point me in the right direction to be able to SSH into the zero if i already have another (or several?) devices on my network that identify as raspberrypi.local (presumably the default for all Pis?)

    1. Well, one simple option is to disable your other network connection, ssh into the connected Pi Zero and grab its IP address, then simply use it when you reconnect your networking. Or you could disable other network connections, ssh into Pi and change its hostname?

      1. “Or you could disable other network connections, ssh into Pi and change its hostname”

        Is the solution that I used 🙂

  37. Pi-Zero working fine to screen/keybd/mouse but can’t get this neat USB link to go. Using XP with Bonjour installed and PZ shows up on XP as Local Area Connection icon but with a yellow triangle and ‘limited or no connectivity’. Tried different cable, tried updating driver but when I use Putty to raspberrypi.local on port 22 Putty times out. If I try to connect to the IP address that shows up for the RNDIS Gadget I get an immediate ‘connection refused’.

    Any suggestions?

    1. I haven’t played around with it on XP. Someone had mentioned a while back it might be too old to have the correct needed drivers installed? Not sure though.

    2. I believe the IP address that shows up for the RNDIS Gadget is the address of the PC-side of the USB-networking connection. And as you’re not running an SSH server on your PC, that’s why you get ‘connection refused’. You actually need to connect to the IP address on the PiZero-side of the USB-networking connection, which will be different.
      But if raspberrypi.local isn’t working, then I don’t know how else you’d discover what IP address the Zero got assigned. And I don’t have any systems still running WinXP that I could use to investigate further. The ‘limited or no connectivity’ probably just means that the USB-network connection doesn’t have an onward connection to the internet (which is obviously to be expected!).

      1. An easy answer to the question of what IP got assigned is to use “ANGRY IP” (AngryIP.org). This is a must have tool for dealing with networks that use DHCP. it will provide a list of the connected ethernet adaptors that can be used to scan for any devices on the address range assigned to that adaptor. very quick and easy. Hope this helps someone

  38. Thanks for suggestions. So far no joy.

    1. Tried PZ with a Win10 PC, same ‘connection refused’ problem

    2. Connected PZ to a Ubuntu Mate PC,
    Gets stuck on ‘requesting Ethernet network address’
    Opened Terminal,
    ssh raspberrypi.local results in ‘name not known’

    3. Tried XP again, before the yellow triange shows over the LocalAreaConnection icon it tries for a few minutes on ‘aquiring network address’

    Looks like PZ doesn’t want to talk to anyone.

    1. Sounds like in all cases the PC itself is trying to get an IP address via DHCP from the USB-network connection (which won’t work, as the PiZero isn’t running a DHCP server).
      This isn’t what you want though, you want the PC to auto-assign a link-local IP address (169.254.x.y) to the USB network device.
      For Ubuntu specifically (I’ve not experimented with Windows yet) see my comment from 2nd June about configuring “Link-Local only”.

      1. how does one do this from the command line only, when I don’t have a desktop interface? 🙂

        I’ve managed to connect to the pi over ipv6, but not with the hostname avahi is assigning it.

        1. I meant in your 2nd of June post, how do you make the same settings on a CLI-only debian/ubuntu, thanks, sorry for the confusion

  39. Andrew: Just followed instructions in your 2nd June post but found no improvement with ssh.
    I then did a reboot and modified the network ip4 setting again, and I can get in!
    And I can also see the ip address, (for me) – so plugged PZ into XP system, manually set that IP, and Putty now connects to [email protected] on port 22!
    Then tried with Win10 machine and after manually assigning the IP address again I can get in using Putty with [email protected].

    Excellent! I now have a single cable link to PiZero on three different bases.

    Many thanks for the help.

  40. Hi

    I have done this tutorial and works perfect in my mac os x laptop, but when i try to share the internet connection, now not recognize any of the ways.
    Someone has had the same problem?


  41. It works fine on my PC running windows 10!
    but if i try to ssh on my laptop (i’m running opensuse leap)
    it only says could not resolve hostname…
    i’m pretty new at Linux and it would be great if someone could help me out here

    1. You may want to have a look and see if you can install the avahi-daemon package, as it is required for Bonjour name resolving.

  42. My pi zero automatically disconnect from usb 🙁

    avahi-browse -alr log:
    + enp0s29u1u3i1 IPv6 raspberrypi [aa:84:97:ad:1a:11] Workstation local
    = enp0s29u1u3i1 IPv6 raspberrypi [aa:84:97:ad:1a:11] Workstation local
    hostname = [raspberrypi.local]
    address = [fe80::a884:97ff:fead:1a11]
    port = [9]
    txt = []
    – enp0s29u1u3i1 IPv6 raspberrypi [aa:84:97:ad:1a:11] Workstation local

    And ssh [email protected] doesn’t work for me (I must use ssh -6 [email protected]%enp0s29u1u3i1). Any idea?

  43. My setup is a Pi Zero connected to a laptop running Ubuntu 16.04.

    I have added these two lines
    options g_ether host_addr=26:7f:62:5c:48:86 dev_addr=d6:fe:44:ad:8f:13

    to the file /etc/modprobe.d/g_ether.conf
    And I modified the Wired Connection 2, IPv4 Settings to Link-Local Only

    per AndrewS postings. I can now ssh into my Zero via USB.

    But still no internet connectivity. Trying to ping for example returns ‘connect: Network is unreachable’

    I must be missing a step someplace.


    1. Did you also run the script (on your Ubuntu laptop) that I posted on github.com at the bottom of my 8th June comment?

      1. Output from your script:
        PC_INET_DEV is enp1s0
        PC_ZERO_DEV (usb0) doesn’t exist

        I’m a complete newbie on Ubuntu but looking at the Connection Information dialogs, I replaced
        and that seems to work. I can now ping from via ssh on my Zero. I suppose the real test is apt-get update. 🙂

        Thank you!

          1. I got it.

            I replaced this line:
            DNS_SERVER=$(nmcli -t -f IP4 device list iface $PC_INET_DEV | grep DNS | head -1 | cut -d: -f2)

            with this one.


            I’m on the internet.

            Thanks again!

  44. Glad you got it sorted! I guess things must work differently on the Ubuntu 16.04 you’re using, to the Ubuntu 14.04 that I’m using. Maybe I’ll try testing with a LiveUSB boot of Ubuntu 16.04 at some point… 😉

  45. Something still not quite right. I can stop and start the pi, disconnect it, reconnect it and it sees the internet just fine. But if the laptop goes to sleep or restarts or powers off and on then the network is not visible to the pi any longer.

    Something isn’t “sticky”.

    1. The two commented-out commands (sysctl and iptables) at the top of my script need to be run on your laptop after every reboot, as their effect is only temporary. I didn’t get round to looking into how to make them “sticky”.

  46. Is there any way to get this working without Bonjour / get the Pi IP address manually from Windows? Also, is there a way to access the file system without SSH with this type of connection?

    Lastly, this seems to work with Windows, but not Ubuntu (it says I have the wrong password on Ubuntu). Any idea why?

    Thank you for your post!

  47. Hi Andrew, thank you for the blog, it was incredible to make it work.

    I must confess it is my first RPi experience, I got my RPi zero for a fun-project and stumbled instantaneously when my usb router didn’t work with Pi. I could not connect neither mouse nor keyboard to it. So I found your solution, every basic operation was unknown to me, so even making SSH work was a victory, then virtual desktop was another victory. It works now!

    My question to you, is how to make RPi connect to internet as well as being hooked via virtual desktop to my laptop. Is it possible to somehow share internet from laptop to RPi??? Or I have to use usb hub anyway to hook a wi-fi dongle???

    Thank you in advance,

    1. It is very possible to forward it, with Mac OS, you just use Internet Sharing from the Sharing section in System Preferences. For Windows, am not sure though, a few people though I believe have documented it in the comments below.

  48. So… would you theoretically be able to connect two pi0 together using this method? (One being powered over the pwr port).

    1. Don’t see any reason why not. James has though gone even better with one of his projects, using a Raspberry Pi 3 and x4 Pi Zeros attached via USB using same method as described above. Is very cool –

  49. For those running a recent flavor of Ubuntu a few more pointers to set this up nicely:
    – In the Network Manager for the wired connection, under IPv4 set “Method:” to “Shared to other computers” in other to let your computer give an IP address to the zero and share the internet connection of your computer. Of course this is possible to configure for yourself, but this one-click option is very nice to have.
    – Each reboot the zero will have a new MAC-address, showing up as a new wired connection in the network manager, requiring to do the configuration once again. To solve this, we can add some more parameters to cmdline.txt. First look up the current MAC addresses:
    “$ dmesg -T | grep MAC”
    Now add to the end of cmdline.txt:
    “g_ether.host_addr=xx:xx:xx:xx:xx:xx g_ether.dev_addr=xx:xx:xx:xx:xx:xx”
    Of course replacing the xx’s with the found mac addresses. Now your pi will always show up as the same device and be automatically bridged to the internet connection of your computer.

    (@ PhilK )

  50. This is a little bit more advanced, might be a better question for source forge, but I will start it here.

    I use a USB wifi adaptor for connecting to my network when I am at home, but would like to also use this trick to connect when I am not near a wifi point I have configured (yet..).

    Is there a way to have a boot script that first checks for a wlan0 device, and then if not fail over to the USB connection described here?

  51. Thanks for posting this guide. I tried it on my new raspberry pi zero and it seems to work fine until the very last step.

    My machine: windows 7 with itunes installed

    I followed all the steps, and at the very end I *am* able to ssh to raspberypi.local using the command “ssh [email protected]“. However it doesn’t seem to accept the default password! The default password should of course be “raspberry”, but it always says Permission denied, please try again.

    Any ideas on what I can do to see what I might be doing wrong?

  52. Great blog! USB connection from PC to Zero is exactly what I need, but I’m getting :
    RNDIS/Ethernet Gadget – no driver found

    on Windows 8, do I need Win 10?

    (I checked, Bonjour is running, double-checked config file edits. Got a dev friend at work to try connecting from his Linux machine, using avahi he could see it, but could not ssh. Avahi showed only IPv6, not v4, could this be an issue?

      1. It worked. I ssh’ed into the Pi Zero from my windows machine and installed xrdp. Once done I disconnected from the usb and connected it to my P1 3. I installed Remmina on it to connect to the raspbian desktop on the Pi Zero. Don’t know what purpose it word serve but it’s possible.

  53. Hmmm. I’m trying to get a Pi Zero without needing a console cable or anything else “magic”. I have a miniHDMI adapter so I can see that the Zero actually boots up (into X).

    After booting and then putting the card back in my OSX machine, the `cmdline` looks like this:

    dwc_otg.lpm_enable=0 console=serial0,115200 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline fsck.repair=yes rootwait modules-load=dwc2,g_ether

    I’ve tried connecting to `raspberrypi.local` and to ``. Neither work. I’m plugging in to the ‘USB’ port (J10) and using a cable that transmits data on other devices.

    Any suggestions? Are there any other “zero console access needed” things to do? The older methods had configuration on the OS itself, not just the boot partition. I don’t see that any other gadget modules are possible without console access.

    1. According to the instructions at the top of this page, you need to edit both cmdline.txt and config.txt

      The two numbers after 169.254. are randomly-generated, so trying to connect to a specific IP address is unlikely to work (which is why you need to have Bonjour running).

      1. I didn’t mention the config.txt because it was trivial. I did try running nmap on the whole class B and found a couple of possible hits, nothing paid off. `dns-sd -B _ssh` failed to find anything.

        Think I’ll get an OTG and keyboard and go that route for setup. (I have the IoT pHAT wifi board, so it’s just the yak shaving required to set that up)

  54. tried on Windows 10 64bit, it seems that Linux is detected as COM instead of RNDIS once you plugin the pi0 (see here: http://answers.microsoft.com/en-us/windows/forum/windows_10-networking/windows-10-vs-remote-ndis-ethernet-usbgadget-not/cb30520a-753c-4219-b908-ad3d45590447?page=1). There are some fixes suggested there, none worked for me.

    Only after update Driver for that com (Driver Manager, COM-device) to be a kindle (no joke) following this http://www.mobileread.com/forums/showthread.php?p=3283986 it worked like a charm 🙂

  55. I went into this blind and followed the directions to no avail, until today.

    I see several posts by with people describing very similar issues so I thought I’d publish my foolishness.

    My environment is a Windows 10 host running Ubuntu 14.04 as a guest VM. When I plug the pizero into a USB port the VM manager lists it under removable devices. In this case it shows up as Netchip RNDIS/Ethernet Gadget. …. all good so far.

    From a linux shell I can see the interface for usb0 with mac address for IPv4 and IPv6…. again all good so far.

    So “ssh [email protected]‘ as documented…. BUZZZ denied
    couldn’t resolve hostname

    how about “ssh [email protected]“… BUZZZ denied

    Here’s where I went wrong. Instead of focusing on the hostname resolution I confused myself by attempting to connect to the IPv6 address of the usb0 interface as many others describe above.

    it pings
    ping6 fe80::4c15:a8ff:fe6f:ff8e%usb0

    ssh -6 [email protected]::4c15:a8ff:fe6f:ff8e%usb0
    [email protected]:~$ ssh -6 [email protected]::4c15:a8ff:fe6f:ff8e%usb0
    The authenticity of host ‘fe80::4c15:a8ff:fe6f:ff8e%usb0 (fe80::4c15:a8ff:fe6f:ff8e%usb0)’ can’t be established.
    ECDSA key fingerprint is 77:b7:05:4c:7b:7f:8f:e5:74:4f:8d:37:32:1a:e2:a7.
    Are you sure you want to continue connecting (yes/no)? yes
    Warning: Permanently added ‘fe80::4c15:a8ff:fe6f:ff8e%usb0’ (ECDSA) to the list of known hosts.
    [email protected]::4c15:a8ff:fe6f:ff8e%usb0’s password:
    piPermission denied, please try again.
    [email protected]::4c15:a8ff:fe6f:ff8e%usb0’s password:
    Permission denied, please try again.
    [email protected]::4c15:a8ff:fe6f:ff8e%usb0’s password:
    Permission denied (publickey,password).

    Now I’m confused and ended up wasting a bunch of time wondering why the default password for raspbian isn’t work… cursing a lot… wishing I’d gotten more than 4 hours sleep in the last 24… etc

    Keep in mind I have lots of Pi’s… this was just the first zero and I was trying to keep it to a single cable 😉

    Went to bed, got 8 hours this time and setup a FTDI console to so I could check the security logs on the PIzero….
    after a couple more failed attempts and NO logs produced, it was clear I was doing something wrong….

    The punchline:
    Thinking the USB0 interface on my Ubuntu machine was where I needed the IP was my mistake… rather I needed the Ipv6 address or IP address from the PI side! For whatever reason and I really don’t care why, raspberrypi.local just wasn’t created… all I had to do was add an entry to /etc/hosts for it using the IP from the PIzero.

    Now this does beg the question as to how you get the PI ip when you can’t log in to the device in the first place, but I digress. if I’d been thinking day I’d have saved myself a lot of aggravation… there are simple ways to scan for ips that I’ll leave for people to google if needed.

    Last thought…. in my first attempts the ping6 worked… ssh was attempting to connect to something… the answer is simple, usb0 was a loopback to my ubuntu vm! Thank god I didn’t have a local pi user… that would have really blown my mind.

    ssh pi@

  56. Didn’t want to install Bonjour or any other name service.

    After enabling ICS on the PC’s network adapter, the gadget network adapter becomes and the Zero is assigned a random address on the 192.168.137.x subnet.

    A quick way to determine the assigned address is to open a command prompt and type: arp -a

    That should return a screen similar to this:

    Interface: — 0x14
    Internet Address Physical Address Type 1a-3c-b4-07-2d-f1 dynamic ff-ff-ff-ff-ff-ff static

    Look for the 192.168.137.x address that is followed by the word “dynamic”. That should be the address you need for SSH.

  57. Anyone got this working with multiple pi zeros? That is, have more than one pi zero connected to a host and be able to ssh into both of them.

  58. Long story short, I finally got this to work. 1) MUST use the usb slot nearest the HDMI slot. The other one only implements power, no data. 2) At least on my Win10 portable, it is actually sensitive to which USB socket on the PC that I connect the Pi to. One works, two don’t. (Different internal hubs).
    Since I already had a Pi connected on a shared connection using 192.168.137 on the wired ether interface, the Zero was assigned an address in the 169.254 space. It has a connection to the PC; I haven’t yet tried sharing to it. Hopefully I can share to both pi’s.

    1. I was able to share the wifi internet connection with both the Pi2 which is directly connected to my Portable using an ethernet wire, and the Pi Zero which is on USB:

      From http://superuser.com/questions/656998/windows-7-share-internet-connection-with-multiple-network-interfaces

      Disable internet connection sharing if you have enabled it before.

      Select both LAN adapters TO WHICH YOU WANT SHARE INTERNET (by holding Ctrl and clicking on LAN cards).

      Right click on one of selected and chose from dropdown menu “create bridge connection (or similar)”.

      From now all LAN settings of these LAN cards you should enter in now created bridge connection.

      Now use the standard internet connection sharing to this bridge from the LAN adapter which connects to network.

  59. This worked great except for one problem, my computer wasn’t recognizing the Pi by its hostname “raspberrypi.local” when attempting to connect via SSH (I am using Ubuntu 16.04 LTS). An easy fix was to go into my connection settings for the Pi (Recognized as wired/ethernet connection #3) and change the IPv4 connection settings to “Local-link only”. After that, SSH was cake. However if you have the IP of the Pi upfront you may not need to change the connection settings what so ever. Now that I am writing this post I realize that I could have just found the IP address of the Pi in connection settings and SSHed to that address. I guess whatever floats your boat (or just works). Hope my comment can be of use!!!

  60. Interesting article. I currently have a line in my config.txt referring to a dtoverlay for a USB DAC attached to my RPi Zero. Is it possible to have multiple dtoverlay references?

  61. I’m on ubuntu 16.04 and it didn’t work for me.
    The network manager was trying to connect to the raspberry pi without success… BUT I read the comment of AndrewS (2 June) and followed its instructions. It works like a charm now.

    Thank you all.

  62. I’ve had mostly success with this approach. The first thing worth mentioning is that Ubuntu 16.04.1’s Network Manager seems to have automated much of this (port forwarding, IP masquerading etc). I initially used Ubuntu 14.04 and followed the stated procedures to manually configure both the host PC and the PiZ. That all worked. I had a 16.04.1 PC sitting idly nearby, and I decided to give it a try also. I should first mention the PiZ had the ‘config.txt’ & ‘cmdline.txt’ changes (including fixed MAC addresses) done at this point. The ease of the 16.04 configuration was amazing!!!
    1.) Plug in the PiZ, after 10-15s the net-manager attempts to connect (propagating radio waves).
    2.) Click the net-manager icon & select ‘Edit Connections’. Choose the latest wired connection; select the IPv4 tab; select “share with other computers”. Make any other desired changes and save this & within several seconds the connection is established. The net-manager makes all the IP forwarding and masquerading changes (Do a ‘iptables -L -x’ before/after connectiong if in doubt). It also creates a ‘’ subnet for the first device, a ‘’ for a second PiZ. (These subnets will be troublesome later on…)
    3.) From a terminal on the host, SSH login to the PiZ.
    $> ssh raspberrybi.local -l (pi, or your user account)
    4.) You’ll be asked for a password (‘raspberry’ in the case of ‘pi’)
    – at this point you’ll be in. DNS and routes will be working!
    5.) To test DNS, ‘ $> ping google.com’. It should be working. ‘apt-get’ etc should also work. You should be able to ping other devices on your local LAN.
    —- What’s NOT possible —-
    I’m not a networking expert so perhaps there a work-arounds for this issues.
    a.) Since the PiZ subnets are unique (10.42.0/16) they will not play with devices on your LAN ( I added routes on the ‘192.168’ subnet devices to allow ‘10.42/24 access’ – but I cannot ping into a Piz from a 192.168 machine.
    I can ping a 192.168 device from the PiZ – but that’s port forwarding and/or masquerading at work.

    — Does anyone believe it’s possible to access a PiZ that’s running ‘ethernet USB’ from another local LAN machine?
    (other than the machine it’s USB connection is physically on)
    Many thanks.

  63. Anyone had success doing this with a Macbook running OSX 10.12 Sierra?

    RPi zero works on my Windows 10 PC but isn’t detected at all on my Macbook, RPi zero boots up but doesn’t show in System Preferences / Network

  64. Just got this working on Windows 10. Didn’t work at first, rebooted the pi with a keyboard, I checked “ip addr” is showing a usb0 network device, so it’s definitely ready to go. So plugged in back into the PC and ssh into it with Putty without a problem, maybe it just need some time to sort out DHCP, I don’t know.

    Anyway, ssh’d in and realised the pi could not get online, so back to Windows and created a bridged connection between the RNDIS adapter and my normal LAN adapter.

    Go here:
    Control Panel\Network and Internet\Network Connections

    Then highlight the two adapters you want to bridge, right click and create a bridge connection, that’s it.

    The pi then took a couple of minutes to pick up a new ip address from the router, and is now part of my LAN. I can get online to update packages.

    Thanks for the guide!

  65. A question: If you use this to set up a Rpi Zero, and then wish to use the Rpi Zero headless, but connected via the network (e.g. disconnect the USB cable to the PC, and connect a WiFi dongle instead), is it necessary to reverse any of the extra settings in order to have the WiFi dongle (or ethernet dongle) work? Can you leave the network-over-USB config in place, and still have the Zero recognize and use a different network device if you disconnect the PC and instead plug in the network device, or do you have to reverse the network-over-USB config?

    1. Yip, you don’t need to do anything to still allow USB to work as normal. But is worth keeping in mind is using the DWC2 driver, instead of the more optimised driver the Pi Foundation has been working on over past few years. So it will be work fine, but may not be as fast.

      1. So, if network speed once headless is a concern, we’ll want to disable DWC2 before going headless. Is it necessary to back the changes out of both files, or will backing out just one get DWC2 out of the way (just in case we want to make it a tad easier to get back to USB network mode in case something goes wrong in headless mode)?

  66. Hi-
    I have got this working on Win10 but, getting to work on my Mac OsX Sierra laptop is a failure so far.
    I made the two file changes (and confirmed it working on Win10; note: it only works in the USB nearest mini-HDMI, but you knew that).
    When I plug it into my make: tried to ssh or ping raspberrypi.local, but no one home.
    I was able to detect that it connects as a gadget using the (built-in) Network Utility. In the “info” tab, up pops “RNDIS/Ethernet gadget (en8)”. It lists the hardware address but, the ip address is blank 🙁 . Curiously, unplugging and re-plugging, it comes up with a different hardware address each time.
    Further, I used Bonjour Browser (http://tildesoft.com/) and found lots of Bonjour services (this will be useful!) but alas, no raspberrypi.local

    I am at a loss: Anyone have any further suggestions?

  67. Got this working well with Ubuntu 16.04.
    Not so good with Ubuntu 16.10, could only SSH when I found the zero’s IPV4 address and no zero internet access via the PC.
    Would love to get it working with a Chromebook if anyone has any ideas?

  68. If you (like me) can’t get this to work on mac / OS X / macOS, try following these detailed step-by-step instructions:

    1. Download Raspbian (https://www.raspberrypi.org/downloads/raspbian/)
    2. Download ApplePi-Baker (http://www.tweaking4all.com/software/macosx-software/macosx-apple-pi-baker/)
    3. Flash Raspbian onto microSD card using ApplePi-Baker
    4. Open boot/config.txt and add dtoverlay=dwc2 at the very bottom
    5. Open boot/cmdline.txt and add modules-load=dwc2,g_ether after rootwait with a single space before and after
    6. Unmount SD card and put it in the Pi Zero
    7. Attach USB data cable to the Pi’s USB (not PWR) port
    8. Connect the USB cable to Mac and wait 90 seconds
    9. Run ifconfig | grep broadcast
    10. Run ping
    11. Run arp -a
    12. Run ssh pi@ (password: raspberry)

    My problem was that raspberrypi.local couldn’t be resolved, so that’s what steps 9-12 takes care of.

    Hope that helps =)

      1. @Arvid Did you need to install anything else onto your Mac, e.g. a DHCPd server? Are you running Sierra?

        I’ve tried rewriting the cards several times, editing the files to confirm the settings are now in there, but no joy on getting it to work.

        I can find other pi’s on my network (Pi3’s) which I have renamed, but not the zero. Just wondering if I am missing a piece.

        1. Also, I am using 2016-09-23-raspbian-jessie-lite so I wanted to ensure this worked with Raspbian Lite. Is it possible those modules are only in the GUI version?

        2. @Scott Schulz No, I didn’t install any special software for this, and my Mac was running OS X El Capitan. I used TextEdit to edit the config files (don’t know if that could make a difference). Are you sure you connected the Pi Zero via its USB port (not PWR)?

          1. @Arvid Kongstad Well, initially I was, but caught that pretty quick. I spent two days messing with the crazy thing: rewrote the card several times, checked the config files (using vim), tried it on Mac and Linux, and then… finally looked at the tag on the USB cable and realized it came with a gunlight, doh! That cable was intended for charging flashlights, and apparently only has the power leads wired up. So I went out and got another cable, and bingo! So thanks for the pointers, and thanks to OP for this post!

  69. Hello, I have a problem. I’m able to connect the pi zero on my ubuntu laptop, I have the IP both in Link-Local and shared with other computer mode, but when i try to connect via ssh it gives me “connection refused: port 22”, It seems to me the the port 22 is closed or something like this. I tried with other port with the same results.

    I hope someone can help me.
    Thanks you.

  70. Working well with Ubuntu 16.04 with PiZero internet access.

    Can only ssh once I find the IP address with Ubuntu 16.10.

    Would like to get working with a Chromebook if anyone has any thoughts?

  71. Andy,
    thanks for your work. Though I had notice a problem on one of my pcs with this configuration. I could make it work only when powering up the Raspi Zero beforehand. If I didn’t power up beforehand and connect only directly through USB I receive the warning “USB Device not recognized”. After a huge search I found a possible solution:

    A small delay in the boot sequence worked for me:

    In /etc/rc.local I put

    /bin/sleep 5
    /sbin/modprobe g_ether

    In cmdline.txt I added


    and in config.txt only


    And then it worked well.

  72. @nicolas: Same here, I can’t get it working and tried on two Windows 10 x64 PCs. Shows up as Serial USB Device (COM3). In the Model-Field it states RDNIS/Ethernet Gadget, but that’s it. Not virtual network adapter.

    I guess it has something to do with hardware ID of the Pi Zero?!

  73. For those that only get the USB Serial COM3 with Windows 10, go to the Device manager, right click on this USB Serial device and select Update Driver. Select Windows should automatically install the best driver. It will then download and install the USB Ethernet/RNDIS Gadget driver. Tested on the latest fast ring build 14971, but should work on others.

  74. I don’t know why but when I connect my zero with Windows 10 and your settings my device manager shows me a new Serial Adapter “Serial USB-device COM7”.

    I cant ping or connect via putty to raspberrypi.local.
    I have installed Bonjour.

    Can anyone help me ?

  75. @ Rick:
    I also tried updating the driver but it didn’t work on my Windows 10 64-bit. It didn’t find any suitable RDNIS-Drivers. Also I don’t want to install non standard drivers because I want to use the pi on multiple non-configured pcs.

    Is there a way to use pi zero as virtual network interface on all Windows 10 installations?

  76. I’ve plugged this in to moth my Mac book and windows computer. My Mac it comes up in network connections with a IP address. But it says can’t connect on both my windows and Mac On my windows computer it keeps trying to install the device. Any help??

  77. OK so heres what i found. With the lines you said to add the ssh did not turn on. I had to boot up the pi with my monitor and keyboard and turn it on then it works fine.

  78. So I’ve gone through these instructions and Adafruits instructions and cannot get this to work. I even tried downloading OpenSSH to make sure Putty wasn’t messing with me. I have Bonjour installed, I have shared teh pi with my WiFI conncetion, I have made sure I have the latest drivers. The pi has a set IP. I have tried connecting SSH to raspberrypi.local, [email protected], the ip address alone. I have tried redoing the sd card. I must be missing something. Anybody got a hawkeyes view of what it is?

  79. @Scott That’s a bummer. Oh well, I’m happy you found the problem/solution! Also (for completeness), I’ve only tried with Raspbian Lite.

  80. Hello Andrew,

    thankx for the instructions. Aside from the SSH configuration everything worked as you explained it.

    Because of security improvements, the newest Jessie images have switched off SSH by default.

    You can circumvent this by creating an empty file named “ssh” (without any file extension) in the boot partition of the sdcard.


  81. I followed your instructions.

    After some trouble with the driver for Ethernet gadget that was missing and which my Win 7 could not find by itself, I found instructions on the Web where to find it and how to install it. I then ran “ping raspberrypi.local -4” on Windows command line and got a reply from (I saw somebody above also getting a 169.254 address from the Pi). So this must be the address of the Pi. I made sure that this is the Pi Zero I am talking to by disconnecting WiFi and LAN adaptor – and yes, this was the Pi Zero as I still got response to the ping. To make double sure I disconnected the Pi – and the responses to ping stopped. It was the Pi all right. I reconnected and got the ping response again.

    I then ran ipconfig in Windows and saw that the address of my PC on this interface is, net mask Moreover, I checked the ipv4 properties of the interface and saw that my PC is configured as a DHCP client on this network. So I assumed that the Pi acts as the DHCP server, which seems logical given that my PC is a client and that the address my PC has on the interface is in the same subnet as the address of the Pi. So far so good.

    However, when I tried to use Putty to ssh into raspberrypi.local :22 it did not work – the Pi did not respond at all. I tried the numeric – same result. I tried to use WinSCP to do SFTP into the Pi – refused to connect, saying that the host does not listen to SFTP but listens to FTP. Tried to connect with FTP – no joy.

    To summarize, the Pi returns a ping but refuses to talk ssh and sftp. Please help!!

  82. Hey guys I need help whrn I try and type in raspberrypi.local in putty and press enter putty starts up but it appears with a error box reading ‘network error: connection refused’

  83. Hi guys,

    I have a problem with g_mass_storage module at Raspberry Pi Zero. When i connect with PC, Windows does not recognize and appears “Unknown Device” and with others and other devices with usb does not recognize too. I tried with g_multi too, I followed several tutorials on the internet and it did not work.

    Can someone please help me?

      1. I do not think I was that clear. When I connect the raspberry pi as mass storage to another device that has usb (eg small sound box) it does not recognize and can not connect and communicate. The usb ports on the notebook are working normally. Do not you have a video of that part of the setup? Thank you

  84. After doing every steps as explained (modifying config.txt and cmdline.txt, enabling ssh, checking USB cable, using correct USB port on RPi Zero, checking Bonjour service is running, enabling a shared internet connection with the Pi, trying different USB port on the computer), my RPi Zero has never been detected by the computer as a “USB Ethernet/RDNIS Gadget”.
    I bought another RPi Zero, used same SD card, plugged it in and magic it was directly detected as a “USB Ethernet/RDNIS Gadget” which allowed me to connect with Putty through ssh and raspberrypi.local!
    I guess there is a hardware issue with my first RPi Zero…so as it costs 5$, don’t spend too much time trying to connect it via USB and get another one!;)
    I bought both my RPi Zero on The Pi Hut and ran Raspbian Jessie Lite (2016-11-25).

    1. Did you ever manage to get your original Pi Zero to work as well?

      I have the same issue no ping/ssh response but these Pi Zeros are pretty hard to get a hold of and was lucky to get one when I did.

      Would appreciate it if there was a solution to the issue other than ‘hunt for a new one’.

  85. I had everything setup and working correctly until I got to the part where I ping google from my pi zero. It would ping successfully but when I went to do “sudo apt update” or “sudo apt upgrade” it would just hang there. It took me a while to figure out but it was my firewall on my pc. Disabled it and voila everything is working!

    Laptop: Windows 10
    Raspberry Pi Zero: Raspbian
    USB OTG cable

    TLDR: Disable firewall or add an exeption

  86. Some more Ubuntu help:

    After struggling with Ubuntu 16.10, I reverted back to Ubuntu 16.04 and a clean build of Jessie Lite (2016-11-25).

    My IPV4 setting is “Shared to other computers”.

    I added the additional to the end of cmdline.txt to stop generating Wired Connections on each boot:
    g_ether.host_addr=26:7f:62:5c:48:86 g_ether.dev_addr=d6:fe:44:ad:8f:13

    I could ping raspberrypi.local but when I tried to ssh [email protected] I kept getting Connection reset.

    Turned out the ssh key files (/etc/ssh/) on the pizero were zero bytes. I deleted them all and then regenerated them following the instructions here (using the ssh-keygen command):

    Hey presto, I could then ssh [email protected]

  87. Great post!!

    Any idea how I can share the OTG USB across the host device and a Wifi dongle?

    The setup I have includes the Pi Zero acting as USB Mass storage (which I got to work) but want the Pi Zero to also have WiFi access (don’t want to share internet with the host)

    I tried using the power OTG port with no success. I also tried using a USB Hub and using a Male-to-Male USB cable, but again the device did not appear as Mass Storage.

    Any help is appreciated!

    1. i beleive you will have to send the ethernet packets over the gpio bus if you want standalone network access. google “ethernet over gpio raspberry pi zero”

      1. Yup, I guess you should investigate one of these options (others solutions may exist too)

        USB hubs only work when the USB port is working in host/master mode – they don’t work when the USB port is working in device/slave mode. This is why the USB OTG only works on the PiZero and not the Model B Pis, as the model B Pis already include a built-in USB hub (forcing them into master mode).

  88. I would just like to say a HUGE thank-you to Andrew for sharing this. I finally decided it was time to do something with a Zero I bought a LONG time ago (a PiHut Zero Essentials kit version) and to cut a long story short, couldn’t get any peripherals to work – I could see it booting up OK, but couldn’t get a keyboard to work, or a USB wifi dongle, so was pretty much stuck. The only suspicious thing in common was the “OTG USB” cable was the one that came with the kit, and the only thing I had that I could use to attach the keyboard/Wifi. So, after a bit of hunting around, I came across this post, and less than 30 minutes later I’m posting this thank-you as I watch “apt-upgrade” messages fly past in a terminal window on my iMac with a working Pi Zero attached to a USB hub on the Mac.
    Many thanks Andrew, hugely appreciated.

  89. Doesn’t work with pi zero W and raspbian jesse lite. Network interface shows up on ubuntu but raspberrypi.local does not respond to ping or ssh

    1. I had the same problem and I was only able to ssh by specifying the IPv6 address of the Pi, and the connection only lasted a few minutes. After a few days of trying everything I found on the internet with no results, I managed to make it work by chance, and actually the solution is pretty simple.

      As you say, a USB network interface shows up if you click on the network icon on Ubuntu. You have to click on edit connections, select the USB network connection and click edit. On that window, go to the IPv4 tab and on method, select “Shared to other computers”. You can do the same on the IPv6 tab. Wait a little bit until a connection is established and a IPv4 address is assigned to your Pi, and then you should be able to ssh through USB with “ssh [email protected]“. Every time you unplug and plug the Pi again, you have to do the above steps. I don’t know if there is a way to automate this, that’s the next thing I want to try. I hope it works for you, it worked for me.

    2. Sorry, the method is not “Shared to other computers” but “Link-Local only”, as some answers above suggest. I’m not on an Ubuntu machine right now so I’ve couldn’t check if what I was saying was correct.

    3. @Joel Hutton System Preferences -> Sharing -> Enable internet sharing service for the “RNDIS/Ethernet gadget” and voila!

  90. Yea as above, struggling to get it working with the new RPi Zero W.
    Not getting it show up as an adapter in Win10 like my other 4 RPi Zero’s do 🙁
    Perhaps something was changed to accomodate the Wifi functionality preventing the nice OTG gadget bits working.

  91. Does this still work with pi zero v1.3 (camera)? I have been trying for weeks and have used numerous guides and still can’t ssh or vnc into the zero via usb. So far usb-serial has been the only way I can connect to it. My searching shows me there are alot of others in the same boat with the v1.3. I have even used every image from the current to the beginning of may 2016.

    1. Yip, I can confirm it works fine for all 3 versions of the Pi Zero. So most likely is an issue with the way networking is set up on your computer.

  92. I tried it with zero w. On the first windows 10 machine it did not work at all, but I was successfull on the second one. Thanks!

  93. Not working.

    I followed all the steps but when I plug the Pi Zero into my laptop, Windows (10 Pro) makes the drive insert sound but I cannot ping the Pi or SSH into it with Putty.

    It does not appear in device management or network and sharing center so maybe its my laptop?

    Would appreciate some support with this

      1. AFAIK it would only “get confused with other interfaces” if you have the same subnet (e.g. 192.168.1.*) assigned to multiple interfaces.
        Although if you have two separate interfaces each configured to the link-local 169.254.*.* range, then I wonder if that might confuse things?

Leave a Reply

Your email address will not be published. Required fields are marked *