Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?
Simple guide for setting up OTG modes on the Raspberry Pi Zero, the fast way!

###Setting up Pi Zero OTG - The quick way (No USB keyboard, mouse, HDMI monitor needed)
More details -

For this method, alongside your Pi Zero, MicroUSB cable and MicroSD card, only an additional computer is required, which can be running Windows (with Bonjour, iTunes or Quicktime installed), Mac OS or Linux (with Avahi Daemon installed, for example Ubuntu has it built in).
1. Flash Raspbian Jessie full or Raspbian Jessie Lite onto the SD card.
2. Once Raspbian is flashed, open up the boot partition (in Windows Explorer, Finder etc) and add to the bottom of the config.txt file dtoverlay=dwc2 on a new line, then save the file.
3. If using a recent release of Jessie (Dec 2016 onwards), then create a new file simply called ssh in the SD card as well. By default SSH is now disabled so this is required to enable it. Remember - Make sure your file doesn't have an extension (like .txt etc)!
4. Finally, open up the cmdline.txt. Be careful with this file, it is very picky with its formatting! Each parameter is seperated by a single space (it does not use newlines). Insert modules-load=dwc2,g_ether after rootwait. To compare, an edited version of the cmdline.txt file at the time of writing, can be found here.
5. That's it, eject the SD card from your computer, put it in your Raspberry Pi Zero and connect it via USB to your computer. It will take up to 90s to boot up (shorter on subsequent boots). It should then appear as a USB Ethernet device. You can SSH into it using raspberrypi.local as the address.


shrx commented May 19, 2016

Thanks, it just works. (also on the Jessie Lite image, I had no problems.)

ZudoMC commented May 19, 2016

My Zero (Jessie full) doesn't show up as a device. Followed all the steps here.

Could this effectively be used to VNC into the Zero for a GUI interface?

I can't seem to get Avahi Daemon installed on OSX. Any pointers would be greatly appreciated.

On PC Windows 10 I had to modify the firewall settings for Bonjour so that the "Setting up Pi Zero OTG" worked!

andrewn commented May 22, 2016

@langphil, you don't need to install Avahi Daemon on OSX as it comes with Bonjour pre-installed and already running, which does the same thing. Once you've followed the steps above you can just ssh pi@raspberrypi.local to access the Zero.

Whenever I try this the Raspberry Pi shows up as an unknown USB device in Windows. I've tried Windows 10 and Windows 7 with the same results. Any way to fix this?

On my windows 10 computer the Zero is detected as Serial USB device (COM3) but not as Ethernet device. Plus when I look at the cmdline.txt afterwards it looks like this:
'dwc_otg.lpm_enable=0 console=serial0,115200 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline rootwait modules-load=dwc2,g_ether'

jimbolimbo3 commented May 24, 2016

Same as TweetPete here: I see the Zero as a Seriel USB Device (COM4) and not as Ethernet device.
edit: using serial comunication doesn't work anyway, but maybe I'm using just the wrong baud rate.

Pndy commented May 26, 2016

For me it didnt recognize as anything, just a "RNDIS/Ethernet Gadget". But after i manually gave it some drivers found on this guide.
It is now working fine, and im able to use it 👍

@jimbolimbo3 if you're using an Acer u can try to install this driver
after that it was recognized as the right device and together with Bonjour running I can log in as raspberrypi.local

christophe94700 commented May 27, 2016

I have a solution for Windows 10 . the driver is on in my website : []

Sorry for my english :(.

alexellis commented May 29, 2016

Thanks for this. What if you want to use the USB port (once set up for ethernet) for a wifi dongle etc? @gbaman

Not sure if it's only in my case, but using Win7 i had to plug the USB power jack into the RPi0 first, let it boot up and then connect it via USB otg with my PC. Only then windows ill recognize it as network adapter (had to force it to install the driver using the method @xcna mentioned).

Nice one! It's working here, can we get it to connect through USB to the internet? I know we can connect TO it, but can it connect outside?

Awesome! I was also able to get my pi0 to have internet access by following instructions from

(And I can start the rpi and run it by simply backfeeding on the data usb port, although I'm unsure how sane that is)

andypiper commented Jun 6, 2016

Has anyone got this working with OS X by any chance?
edit: I'm thinking it may be related to lack of RNDIS support on OS X. I've tried HoRNDIS but it doesn't seem to want to play :-/

phattmatt commented Jun 7, 2016

This worked fine on my MacBook Pro (El Capitan). The Ethernet device was detected and I could connect to the Pi Zero using the hostname (ssh pi@raspberrypi.local).

To grant the Pi Zero Internet access I configured Internet Sharing for the RNDIS NIC (shared my Wifi connection) and then restarted the Pi (so it would pick up the new IP address).

I'm on El Capitan and I cannot seem to be able to SSH into my Raspberry Pi Zero.

kool601 commented Jun 13, 2016

I was having troubles SSH'ing into the RPi Zero. But I figured out I had to have Bonjour installed, xD. ( I didn't think that it was the right software because it said Print Services, but it worked so.... I'm not complaining! lol.)

massens commented Jun 18, 2016

I'm on Mavericks, I could see RNDIS/Ethernet Gadget in "System information" but couldn't connect to it. I had to go to System Preferences>Network and asign the following configuration
screen shot 2016-06-18 at 14 13 03

Windows wasn't seeing the Pi at all if I powered it off the same USB port.

Once I plugged in the power separately and the stand-alone USB into my PC, it would recognize it but it would be in a "problem" state in Device Manager - for some reason the Zero booting up while connected wasn't working.

As soon as it was booted, I would unplug the USB from the PC and plug it back in (while the Zero remains powered on from the other USB port) and Windows recognized it just fine.

Abem568 commented Jun 25, 2016

Its not working for me. I installed bonjour, made changes to the txt files and waited for it to boot. when i connect to pc it shows as unknown usb device (device description request failed) under Universal Serial Bus controller in device manager. i get this in both win8 and win10. I use a microusb cable to pc.

I am using the current jessie os.

What am I doing wrong?

The RPi appears in the output of ifconfig however it doesn't have an IP address, and I'm not sure how do I get it for raspberrypi.local address. The good thing is that I can see it in the network devices, though.

Any advice?

eichin commented Jul 8, 2016

This is great, but conecting to a Debian (Jessie) system, I only get an ipv6 link address by default - which shows up in avahi but ssh doesn't work with it. Turns out that has the key, of using the address explicitly and adding %usb0 to the end. Overall, nice trick! Thanks!

Will this also work for raspberry pi 3?

Kylir commented Jul 15, 2016

Not working for me :'(
I'm using Windows 7 Pro, Raspberry Pi Zero v1.3 with Jessie 2016-05-27. I edited the 2 files as per the Gist. The Pi seems to boot but Windows does absolutely nothing - the device manager doesn't show any new peripheral (not even a new COM port as some of you reported.)

I also tried to power the Pi, wait a bit and then plug the USB, still nothing. I even tried different USB cables...

I'll try at home with my Windows 10.

PS: just for the joke, using Putty with raspberrypi.local I managed to connect to a colleague's Pi :)

One thing that may help others, as it had me stumped for a good 10 minutes... is that the micro USB cable must plug into the port marked [USB] rather than the power port marked [PWR].
Both will boot but only the [USB] marked port will give the intended behaviour.

Sorsly commented Aug 14, 2016

Silly me, I was using a power micro usb cord for the micro usb data port and a data micro usb cord for the micro usb power port.

So far it works for me. I am using Windows 10. Shows up as ethernet. I was able to ssh into it with rapsberrypi.local and once I shared my internet connection, I was able to download and install software.

Nixes commented Aug 19, 2016

Has anyone got this working with the model A? I know the otg pins are wired to the port.

perhaps this is a silly question, but will this work w/ a hub? (so i can connect a wifi adapter at the same time)

Manoj-nathwani commented Aug 25, 2016

Finally worked for me! Make sure to use a very up-to-date version of jessie, not one you've had lingering around for months :P

I have this working, but I was wondering about how we can get the RPIz to look like a keyboard and mouse, storage and all those other things.

@nathantsoi: No, the Pi can be in only one USB mode, either host or device/gadget. In host mode (via an OTG adapter), it can have a USB hub connected, but in gadget mode, it can only connect to the upstream USB host.

@scndthe2nd See this page for instructions on how to make your Zero show up as other types of gadget:

putztzu commented Sep 24, 2016

I think that the working method I found is different than what is mentioned above although rodoubleday and massens come close because in both their cases it's not obvious whether they are displaying what the automatic service configured or if they had to manually configure their settings. I have modified my copy of the gist but you're welcome to update your own with it if you wish

Unlike the above, I'm pretty sure I checked off every box which could have prevented Avahi/Bonjour/iTunes from working... Disabled FW, enabled simple Printer/File sharing, make sure the daemon for Avahi/Bonjour/iTunes (whatever was applicable) was running. Stopped/started the RPi to ensure advertising itself. The device would be detected correctly, but just wouldn't be configured for a network connection.

So, in the end I gave up on any network services and configured the network connection manually.

Great tutorial, however in order for me to connect via my Ubuntu 16.04 desktop I had to change the ipv4 connection settings to local link only in order to use the raspberrypi.local hostname when connecting over ssh. If you have the IP address of the Pi then the connection settings seem to be irrelevant.

No joy here. I do note if I plug the memory card back into the host PC the content of cmdline.txt has been truncated just after the added text. I was careful to just leave one space.

DSdavidDS commented Sep 26, 2016

Works great for me.

However, I tried this exact same thing with this tutorial and I get an error "Unknown USB Device (Device Descriptor Request Failed)"

Does anyone have a solution?

edit: Got it working! ^.^

TDGalea commented Sep 27, 2016

May I ask how you fixed it?
A lot of people have mentioned this and I am now getting it too; I've not seen a working solution anywhere here.

garynl commented Sep 28, 2016

This seems so straightforward, but if it doesn't work, no one seems to have a way of trouble shooting it. I created a jessie image and made the changes necessary to config.txt and cmdline.txt. Connected the pi to a win7 laptop. nothing, pi not detected. installed bonjour (print services) - not detected. Connected the pi to a keyboard and tv and confirmed that messages about g_ether etc appear in dmesg. ifconfig says there is a usb0 interface (but without an ip address). So pi looks ok, it must be windows. Check in the device manager for new unknown devices, nothing. Ok, connect pi to a laptop running Linux Mint 18 - pi not detected. Check avahi running, yes. Connect pi to mac book, bonjour running - pi not detected. May be it is the pi after all. I dont know.

oh and used two different cables (which I know both work) in all the usb ports the host laptops had to offer (2.0 and 3.0)

tillcarlos commented Oct 1, 2016

Thanks for the tutorial, it'd be exactly what I need. It DOES NOT work for me:

  • macOS Sierra 10.12
  • Raspberry Pi 4 (only has one micro USB, which is power)
  • 32GB sandisk card.
  • Rasbpian Jesse full

Any ideas?

Update: NOT possible "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."

Please help!!!!!

I have been trying to get this working for several days but I always get the device descriptor request failed... I have messed with my firewall settings, changed how I am plugging in the USB, changed USB cables, everything!!!!!! I don't understand why this is not working and it is driving me insane. I have tried several different sd cards and different images.

Nam0 commented Oct 17, 2016

I'm on Ubuntu 16.04.1 LTS and I flashed 2016-09-23-raspbian-jessie-lite.img

I bought a brand new PI Zero installed jessie lite onto a micro sd, added both lines of code, inserted it, but when I try to ssh into my pi I get the error...
r@R-pc:~$ ssh raspberrypi.local
ssh: Could not resolve hostname raspberrypi.local: Name or service not known
What am I doing wrong?
When I boot it I get solid green on the act led

phil432 commented Nov 12, 2016

I tried this but couldnt ssh in to the raspberry pi. The output was 'ssh: Could not resolve hostname raspberrypi.local: Name or service not known'. When I checked dmesg I could see the following:

[ 2060.683489] usb 2-1: new high-speed USB device number 6 using xhci_hcd
[ 2065.979176] usb 2-1: new high-speed USB device number 7 using xhci_hcd
[ 2066.108051] usb 2-1: New USB device found, idVendor=0525, idProduct=a4a2
[ 2066.108056] usb 2-1: New USB device strings: Mfr=1, Product=2, SerialNumber=0
[ 2066.108058] usb 2-1: Product: RNDIS/Ethernet Gadget
[ 2066.108060] usb 2-1: Manufacturer: Linux 4.4.21+ with 20980000.usb
[ 2066.233624] cdc_subset: probe of 2-1:1.0 failed with error -22
[ 2066.234408] cdc_subset 2-1:1.1 usb0: register 'cdc_subset' at usb-0000:00:14.0-1, Linux Device, 6a:2b:ee:30:07:6e
[ 2066.235273] usbcore: registered new interface driver cdc_subset
[ 2066.236484] cdc_ether: probe of 2-1:1.0 failed with error -16
[ 2066.236507] usbcore: registered new interface driver cdc_ether
[ 2066.238455] cdc_subset 2-1:1.1 enp0s20u1i1: renamed from usb0
[ 2066.264145] IPv6: ADDRCONF(NETDEV_UP): enp0s20u1i1: link is not ready
[ 2066.264275] cdc_subset 2-1:1.1 enp0s20u1i1: kevent 12 may have been dropped
[ 2066.264281] cdc_subset 2-1:1.1 enp0s20u1i1: kevent 12 may have been dropped
[ 2066.264627] cdc_subset 2-1:1.1 enp0s20u1i1: kevent 12 may have been dropped
[ 2066.265568] cdc_subset 2-1:1.1 enp0s20u1i1: kevent 12 may have been dropped
[ 2066.265575] cdc_subset 2-1:1.1 enp0s20u1i1: kevent 12 may have been dropped
[ 2066.274193] cdc_subset 2-1:1.1 enp0s20u1i1: kevent 12 may have been dropped
[ 2111.934891] cdc_subset 2-1:1.1 enp0s20u1i1: kevent 12 may have been dropped
[ 2111.934898] cdc_subset 2-1:1.1 enp0s20u1i1: kevent 12 may have been dropped
[ 2111.936117] cdc_subset 2-1:1.1 enp0s20u1i1: kevent 12 may have been dropped
[ 2111.948226] cdc_subset 2-1:1.1 enp0s20u1i1: kevent 12 may have been dropped
[ 2111.948247] cdc_subset 2-1:1.1 enp0s20u1i1: kevent 12 may have been dropped
[ 2111.948251] cdc_subset 2-1:1.1 enp0s20u1i1: kevent 12 may have been dropped

Is anyone able to interpret that output?

NilsBe commented Nov 18, 2016

I managed to make it work.
But only if I power up the Raspberry Pi Zero for about 30 seconds or longer before I connect it to the pc.
Then it's connected properly as a network device and I can ssh and I can also disconnect the direct power and power it through the data connection only.

If I connect the Raspberry Pi Zero only to the Windows pc without additionally powering up before, It gets recognized and connected as unknown USB device.

I thought of adding a good delay in config.txt by BOOTCODE_DELAY and BOOT_DELAY. But that didn't help.

winkste commented Nov 18, 2016

Worked at the first try with my pi zero, raspian jessie and host system El Capitan. After that I changed all standard settings in raps_config including the computer name (ohh, didn't recognized it) and couldn't connect after restart. Than, did everything again without renaming the computer and everything worked fine!
Again: great tutorial.

One piece of information missing, you need to connect your pi in the port that says USB, not the one that says PWR IN

noelfranc commented Nov 20, 2016

I can't ssh into the device without a password. What did I do wrong?

ssh pi@raspberrypi.local
pi@raspberrypi.local's password:
Permission denied, please try again.

I found the answer.
It's funny that the password is NEVER mentioned anywhere here.

tylerlindell commented Nov 25, 2016

I'm having the same issue @Nam0 is having

ssh pi@raspberrypi.local
ssh: Could not resolve hostname raspberrypi.local: nodename nor servname provided, or not known

+Raspberry Pi Model A (link)
+Mac OS X El Capitan (v 10.11.5 (15F34))
+with Adafruit USB to TTL cable (link)

@christophe94700 thank you for the driver!

@Nam0 @tylerlindell
I used
avahi-resolve-host-name raspberrypi.local
do get the IPv6 address of my pi0.
I also had to configure a static IP address ( netmask: for my computer, so that this won't kill the connection, because he could not get a IPv4 address.

But I coud not reach the internet from the pi0.

Kubuntu 16.04 64bit

cd-rum commented Nov 30, 2016

Cannot connect on Sierra.

$ ssh pi@raspberrypi.local
ssh: Could not resolve hostname raspberrypi.local: nodename nor servname provided, or not known

Tried all IP addresses found with ifconfig, ditto the address in network settings preference pane. Same thing, just hangs.

$ ssh pi@
ssh: connect to host port 22: Operation timed out

I connected once. Now it just hangs and refuses no matter what I try. Using:

  • Raspberry Pi Zero v1.3;
  • macOS Sierra;
  • micro USB cable.

Any help?


Share your internet connection with your Pi. Simple.

kwunlyou commented Dec 2, 2016

@cd-rum: I have the same setting like yours, but I did not manage to connect. I have a few questions about your setting

  • do you use another cable to power the pi zero?
  • your mac use wifi or cable to connect the internet?
  • how do you configure your RNDIS/Ethernet Gadget? do you use manually configure ipv4?

Thank you.

invious commented Dec 2, 2016

@cd-rum running Sierra too, how do I share the connection?

Aymons-MacBook-Air:~ aymon$ ping raspberrypi.local
PING raspberrypi.local ( 56 data bytes
64 bytes from icmp_seq=0 ttl=64 time=0.366 ms
64 bytes from icmp_seq=1 ttl=64 time=0.404 ms
Aymons-MacBook-Air:~ aymon$ ssh pi@raspberrypi.local
ssh: connect to host raspberrypi.local port 22: Connection refused

edit: oh

Still doesn't work :( do I need to have a power cable as well as the data cable?

shonenx333 commented Dec 2, 2016

I did all the things provided in the tutorial but my pi just shows up as COM Serial on Windows not matter if i use DATA USB or DATA and PWR Usb. No Idea why its always showing up as a COM Device. On my Linux Desktop it is showing up as ethernet but a ping to raspberrypi.local is unsuccessfull....
hope someone can help.

same as @invious ...

kwunlyou commented Dec 3, 2016

Finally, make it!
Please see this article. The new update disable SSH by default.

@kwunlyou did you follow the instructions? I did but my pi always shows up as a COM Device in Windows... (ssh is enabled)

jpm165 commented Dec 3, 2016

FYI This doesn't work as-is with the latest version of Jessie (2016-11-2015) (on MacOS Sierra at least) for 2 reasons:

  1. There is some extra gobbledy-gook in cmdline.txt file that differs from the version you link to. Whatever it is prevents it from appearing as an Ethernet gadget to Sierra. I fixed it by deleting what came after 'quiet' and replacing it with the version you link to. I'm pretty sure you can just use what's in the version you link to verbatim.

  2. SSH is (infuriatingly) disabled by default in Jessie, as of 11-2016. So you will get 'Connection Refused' when you try to ssh in. The solution is either to use an older version, or after you edit the 2 files, do 'touch /path/to/boot_volume/ssh' (add a blank file named 'ssh' in the same directory where config.txt and cmdline.txt are.

kwunlyou commented Dec 3, 2016

@shonenx333: yes, I only followed this gist and this article.

BTW, I am using a mac. But your problem looks like due to the missing driver?

@kwunlyou i cant even install the driver cause it shows up as a com device not a unknown ethernet device or sth... :( it works on my linux box (not the internet sharing but ssh... its something i guess)

EnGassa commented Dec 5, 2016

In case of SSH connection refused error, enable SSH since the newer images have it disabled by default due to security concerns.
You can enable it by adding an empty file called ssh in the root of the SD Card

touch ssh

Thank you @christophe94700 RPi Zero work with your driver ! 👍

@jpm165 I have not been able to get the pi zero to work in OTG even after following your steps. Does anyone have any further insight? This is frustrating. I am using the latest Raspbian with PIXEL; I have modified the config.txt and the cmdline.txt file. I have also created a blank 'ssh' file in the /boot directory. And yet... nothing!

davegallant commented Dec 7, 2016

I can't get this to work using Jessie Lite on Ubuntu 16.04. It shows up as a wired device, and I am able to connect to it only if I change the ipv4 settings to link-local in network manager) but when I try to ssh:

$ ssh pi@raspberrypi.local
Connection reset by 169.***.**.*** port 22

I am able to ping it.

The ssh service is now disabled by default.
Thank you to @kwunlyou to point to the answer

To enable the ssh service, create a file called ssh in the /boot/ directory. It can be an empty file. In the terminal you can type:
touch /boot/ssh

It works in OS X El Capitan without extra network settings.

jpm165 commented Dec 12, 2016

@stormshadowci - I've had "interesting" results trying to connect my pi0 to my MacBook pro. Here are some things you can try:

  • Try a different cable: I was using the white cable that came with the pi and I was sure it worked for at least one attempt, but it appears not to work for subsequent attempts. When I swapped out the USB cable for a different one, then it just worked. Network settings went from "Cable Unplugged" to self-assigned IP
  • Verify the pi shows up as "Self-Assigned IP": I was not able to do ssh via bonjour in any other state (i.e. ssh pi@raspberrypi.local)
  • Pay attention to the error message: Does it say "Not found" (or similar) or "Refused connection"? Refused means your mac can see it, but the pi isn't letting you connect. Not found means it's not seeing it. That may be obvious for some but it's subtle and worth mentioning.
    -Check your internet sharing settings: This might sound weird, but there appears to be 2 "on states" for internet sharing. If you check the box beside the RNDIS/Ethernet Gadget (Under the dropdown where you choose where to share from) that is one 'on state'.If you check the box in the left column where it says "Service" (Internet Sharing) that is another 'on state'. I'm not sure what the difference is, but these two check boxes seem to work independently of one another. At any rate, it seems that if your pi is not setup for the network, if sharing is ON, you won't be able to see it on the network at all. Also, if you toggle between states in Internet sharing while the pi is connected it seems to kill the connection.
  • Verify your image burned correctly: If you can rustle up an HDMI cable, just plug it into your TV and see if it's booting all the way. I've heard that people have had trouble flashing with the MacBook Pro's built in card reader. You might have to use an external one.
  • If it's not booting at all, check your SD card: From what I've read, people have reported mixed results with cards >32GB, and cheaper off brand cards.

Just so you know, I thoroughly bricked two SD cards trying this. Flashed all right, files edited all right, but then no signal on the Pi's HDMI (on a known-good Pi Zero hardware setup). One showed up as RNDIS device but of couse I couldn't SSH into it (connection refused) and the other simply appeared as "BCM2708 boot". And when I put the SD's back in the PC, Windows only shows me a drive letter. The poor cards don't even show up in disk management. They don't appear salvageable. From where I stand, serious waste of time and about 10 dollars in SD cards down the drain.

Xorgon commented Dec 15, 2016


"SSH is (infuriatingly) disabled by default in Jessie, as of 11-2016. So you will get 'Connection Refused' when you try to ssh in. The solution is either to use an older version, or after you edit the 2 files, do 'touch /path/to/boot_volume/ssh' (add a blank file named 'ssh' in the same directory where config.txt and cmdline.txt are."

Adding the file made it work, thank you!

digital-synapse commented Dec 26, 2016

This does not work on the PI Zero v 1.3 (the new pi zero with the added camera port)
I have tried everything and every suggestion. I have tried multiple versions of raspian lite including 2016-11-25 and 2016-5-27. I tried booting up via power adapter then connecting the usb to my windows laptop after the RPI had fully booted. I connected to a monitor and verified the rpi does fully boot to the shell. Does anyone have any suggestion to get this to work on the pi zero 1.3? At this point I'm willing to try anything.

nothing is detected when connecting the rpi to windows 10. Im running USBDeview to monitor all connected USB devices. nothing shows up when plugging in the RPI. I am able to plug in devices to the RPI usb and they appear to turn on and work normally so I don;t think the usb port is bad.

Mikey31200 commented Dec 27, 2016

I have the same problem too on both windows 7 and windows 10 systems.
I used I Zero v 1.3 and rasbian jessie 2016-09-23.
I have followed the previous steps on the first post + create ssh empty file but when I tried to log in ssh via putty I obtained the following message:

I have found that it is caused by the bad connexion as raspberrypi.local is not recognize by windows by default (
To prevent this, if not already on your system, please install Bonjour.exe software from Apple (for Windows 10 this software is not available standalone so you need to install iTunes) , but if you read carefully it is also mentioned in the first post (I have missed this step at first).

After that my connection via ssh worked well. However, I don't know why but I need to enable vnc serveur after each reboot (sudo raspi-config via ssh and putty) if I want to use vnc client but it is another problem...
Also, the display is not available via HMDI...

digital-synapse commented Dec 28, 2016

I have downloaded and installed Bonjour Print Services from (also did try the full iTunes installer just in case) no change also disabled windows firewall just in case.
I'm using Win32DiskImager as described above, modified the files and included the blank ssh file.
My problem seems to be more of a hardware / driver issue ??? because the pi zero does not even show up as a connected device in windows however I'm having the same issue on both my desktop and my laptop running windows 10.

I connect the pi zero with the latest jessie. the green read LED turns on.
No pop up in from the task bar when connecting stating that a USB device has connected.
Nothing in device manager (iv'e looked for RNDIS gadget, SERIAL ports, COM ports, etc)
Nothing shows up in network connections either.
Can't ping raspberrypi.local ... ( Packets: Sent = 4, Received = 0, Lost = 4 (100% loss))
Cant ssh via putty... (Network error: Connection timed out)

  • I would say that its just a bad cable except when I connect the PI zero with the same cable but without the sd card inserted the device is detected and shows up in Other Devices as "BCM2708 Boot" as expected.
  • I would say that its just a bad sd card except I have connected the HDMI and verified that it boots fully to the shell. and i see the usb gadget driver being loaded.


Not sure what else to try to get this working.

Mikey31200 commented Dec 28, 2016

It seems effectively a driver problem. You have to focuse on this problem first so it is normal you don't have response to ping if you cannot see Ethernet Gadget in Devices manager. In my computer, it looks like :

If I disconnect raspberry, the item disapears.
Also when you connect Pi zero on your computer, make sure you connect it on the usb port and also not connect an external alim (the power is just enough from your computer)

Just strange you can see display from HDMI because I cannot see anything...(I am sure HDMI is working because I have display by using noobs)

On the Pi 3, model B I'm able to get to the ssh password prompt, but pi as the username and raspberry as the password fails with permission denied, please try again.

I tried it using a Raspberry Pi B+ as the USB master. After several trials I succeeded. Having the Zero set to wait for the network upon boot ruined my day - well, the afternoon. If you run into problems and reuse an already installed SD card in your Zero the check this using raspi-config under the boot options.

After that one has to configure the host for IP-forwarding and NAT and the Zero has to get a default route and an entry for the nameserver.
At least if the Zero should have access to all hosts in the local network and to the internet.

I know how to do this (well, Google did) per hand or via a script, but I would really like to tick some options or switch some defaults in config files to let the avahi daemons do the work. Any clue?

I'm also having trouble. By following these instructions I can connect my Raspberry Pi Zero to Ubuntu 14.04 and to Debian. I can set up a network address for it and ping it successfully - it appears as an RNDIS/Ethernet Gadget.
But I can't ssh into it! When I try to
ssh pi@ (the address I set it)
I get a password authentication prompt, put in raspberry which should be the default for Raspbian Jessie Lite, but am denied access as if the password is wrong. I used a clean Raspbian Jessie image (the latest one) and never changed the password so am flummoxed by this. If anyone else has experienced this issue I would dearly love to know. I feel as if I'm stumbling at the final hurdle!

(Side note, it also doesn't appear as pi@raspberrypi.local - if I try to ping raspberrypi.local I get back the message
unknown host pi@raspberrypi.local
I've tried all sorts of tweaks and reinstalling of avahi-daemon to no avail with this and have given up on this more minor issue - if only I could get ssh to work! I mention this only because it may be perhaps connected...)

fangfufu commented Jan 2, 2017

If you want stable MAC address, so your Linux Network Manager can remember your RPi 0's connection settings, add the following kernel options in cmdline.txt:

g_ether.host_addr=72:8d:1f:c4:e8:ca g_ether.dev_addr=46:10:3a:b3:af:d9

D3vJust commented Jan 7, 2017

I'm trying it now for six or more hours.. ._.
I'm using Windows 10, but I also tryed it with Ubuntu.
Putty or ssh on ubuntu can't resolve "raspberrypi.local".
On Windows I installed the "Bonjour" service. I followed the tutorial - so I edited the config and the cmdline.txt and created the emptfy ssh file... Can someone help me? :c

clyfe commented Jan 8, 2017

There are 2 USB connectors. Make sure to connect the cable from the laptop to the inner one marked USB, not the outer one marked PWR IN (power). On connection method in Ubuntu can select "Link Local" but the pi won't be able to access the internet, or "Shared with other computers" then the pi will have internet access.


I am able to follow this guide to set up the pi zero. But how could I configure the ethernet port after I ssh raspberrypi.local? I have usb/ethernet port adapter, but the only usb port is taken already.

Thanks in advance!

For my own attempts, it seems from the thread above that some folks alread have RNDIS pre-installed and working on their Windows 7 or Windows 10 machines. Neither of mine do and references to RNDIS seem to have disappeared in Google searches some time ago, not sure why, perhaps it was considered a potential security vector?? This weekend I attempted working around the missing drivers by using the Intel Android SDK (link below), which says includes the RNDIS driver, no happiness for me :(

While the Intel driver Zip seems to have the RNDIS drivers needed to support Android development over USB, for me they didn't work out-of-box so for now i'm putting this on hold.

While the proposed solution seems elegant and has a certain cool factor, it also seems limited by the ability to having or acquiring RNDIS drivers.

For the present, I guess i'll be sticking with Plan B, the undocked standalone configuration.

kayjtea commented Jan 9, 2017

I just did this with Pi Zero 1.3 and Jessie (Full) 2016-11-25, with Mac OS X Sierra 10.12.2 using shell & dd exactly as described in the gist. The only issue I ran into was with the USB cable(s). Out of the 7 or 8 Micro-USB cables I dug up, only two worked and they were both thicker and at least looked better built. All the cables powered up the Zero fine, but it never showed up in the Mac's system info hardware report. Even when I used one of the "good" cables for power into a decent power supply, the "bad" cables still didn't work for USB. I'm going to pick up a few more zeros to rule out something wrong with this particular board/port, but hopefully this will save someone some time -- look for a good cable and try as many as you can find.

Next up g_multi...

I had the same issue as kayjtea, commented here:

I now have it working on both Windows 7 and Windows 10 and it seems to be a simple as Mr gbaman described.

The problem I encountered was the result of a 2' USB Micro cable I was using. It applied power and the Zero booted, but (guessing) the data line was defective or not intended for use in the original device.

Couple other points:

For troubleshooting, you'll want Bonjour Browser

Or to use cmd shell dns-sd.
i.e. dns-sd -B _services._dns-sd._udp

Also, raspberrypi.local is the default hostname of a virgin pi, if you change the hostname you'll be ssh'ing to yourHostname.local

Thanks gbaman!

300cpilot commented Jan 12, 2017

For those that run across this later and find that things are not as clear as they should be. This thing is for beginners, but it could be easier. I'm no beginner and this took two hours of screwing with to get going. I am using a brand new pi zero ver#1.3 with camera port, Sandisk 8 gig SD card from Walmart, cheapest one there.

The things that made this work for me. Do everything in the original post here, plus:
###1 Follow this post and put a static ip on the pi zero.

The most frustrating thing was that when I added an ssh file to the boot partition on the sd card under windows, it would be deleted when the pi was booted up. I fixed this by mounting the SD card under Fedora, in Virtualbox. cd to the folder you mount it in and run "touch ssh" without the "". This will create a blank file.

Now you edit the (Mountedin folder)/etc/network/interfaces file with nano and include this on the bottom of it.
Command = nano (Mountedin folder)/etc/network/interfaces

allow-hotplug usb0
iface usb0 inet static

Un mount the sd card from the linux Virtualbox guest and then shut down the guest. Then unmount it from your windows/mac computer and then put it into the pi.

Then set the ip on the RNDIS ethernet interface on your pc/mac as directed in the link.

You can now boot the pi.

#2. To get past the Windows10/Macbook Sierra not finding it, I used 2 usb cables. I used one to power it up (Power Port)and then I plugged the second one (USB port) in after 2 minutes. Your computers will find them if they up to date. After it found the pi once then afterwards it only took one cable connected to the usb port. Also note that not all usb cables have all the wires in them. I found a couple of cables that came with chargers would not work for data.

#3 Review your files that you edit for typo's. My first headache was a "." instead of a ","

#4. This has been a learning experience!

himijendrix24 commented Jan 16, 2017

For me it also didn't work.

After changing the cmdline.tx and config.txt I enabled SSH.
First by ssh file (which gets deleted after boot, see:
later by using sudo raspi-config.
On Windows 10 I had to reinstall the driver because it was recognized as a COM device.

Than I saw the device and could send a ping to raspberrypi.local. But Bitvise SSH and Putty could not start a connection (Errors like "Connection refused" "Connection closed by software"). I also used the IP (instead of raspberrypi.local) and disabled the firewall. Bonjour is also installed. I googled a lot but found nothing and than gave up.

brunoaduarte commented Jan 24, 2017

Worked for me with latest Raspbian Jessie Lite

Minimal image based on Debian Jessie
Version:January 2017
Release date:2017-01-11
Kernel version:4.4

i did everything as explained, plus cleared arp table before connecting PiZ
arp -a -d

Thanks !

himijendrix24 commented Feb 5, 2017

Now I got it running right away, but spend a couple of hours trying to share my internet connection using windows 10.
My setup is Router [Ethernet] PC [USB] Raspberry Pi Zero.

When sharing the LAN connection in Windows 10,
the adapter who will access the shared connection (here the "USB Ethernet/RNDIS Gadget")
will be automatically set to a fixed ip:

So before sharing the connection you have to set your zeros ip to and not to the
which is mentioned in all the tutorials and probably works under Linux and macOS.

Here is the setting of my interfaces file:

allow-hotplug usb0
iface usb0 inet static

After this is updated, you can share the internet connection at the windows pc.

SSH was giving "Connection reset" for me too.
Yes, I created /boot/ssh
Booted with a monitor and checked /var/log/auth.log, turns out the host keys didn't get generated (empty files)

Generated them with:
sudo rm /etc/ssh/ssh_host_*
sudo dpkg-reconfigure openssh-server

Back to gadget mode and SSH is working

asterisch commented Feb 25, 2017

I wanted to access RPI with SSH over usb and i only had a Linux machine with Ubuntu 16.04, rpi zero and a micro-USB cable.
I had a lot of trouble to be honest.The outcomes was that raspberrypi.local couldn't be resolved,when i found RPI's ipv6 i couldn't connect via ssh getting connection refused and a network-manager showing a "trying to connect" indicator on some "Wired connection".
Possible Reasons:

Avahi-deamon (restart)
Avahi-dnsconfd (restart connecting rpi)
Docker (check ip route & iptables rules)

What i did was:
To begin with i removed docker interfaces and their iptables rules so as to not interfere with the process because these rules where associated with ip range of .
Using the log files of the RPI's filesystem on SD /var/log i realized that its IP was so i assigned to the interface on ubuntu an ipv4 address

sudo ifconfig enp0s20u10 down
sudo ifconfig enp0s20u10

if inside the output of

ip route

there is not a line like: dev enp0s20u10 proto kernel scope link src

then add a route with "sudo ip route add ...

Running avahi browse you should see something like

avahi-browse -ar
hostname = [raspberrypi.local]
address = []

if you see that last one seems that u r ok to ssh to pi@raspberrypi.local

Finally the whole point was to configure enp0s20u10 with an ip address in range of and also clearing any interfering iptables rules and ip routes . To make this permanent change etc/network/interfaces file appropriately..
another alternative is to edit "Wired connection 1" and set ipv4 settings like: IP: mask: gw: but keep in mind that other connections might be affected this way..

Drjacky commented Mar 9, 2017

There is no config.txt file on my SDcard!

tunix commented Mar 13, 2017

I just got my hands on the new Raspberry Pi Zero W. Now that it has built-in wifi on it, is it possible to connect to the internet by setting up correct wlan0 connection settings? I'm able to connect to it by SSH'ing over USB. I'm also able to connect to the wifi AP. But it doesn't seem to have any internet connectivity. I thought it was related to /etc/resolv.conf because it didn't have any IP's in it (although wlan0 setup was configured for DHCP). I manually set 2 DNS addresses but I still wasn't able to cURL anywhere. Is this because Pi is in gadget mode or could it be something with my wifi network?

JawzCue commented Mar 21, 2017

tunix - What system are you using? Linux/Mac/Win?? I am in the same boat, however I cannot get my Win10 to recognize the rpi0w as an ethernet device to save my life. I have tried all methods published. Pls share as I am at my wits end with this.

doesn't work for me: dmesg turns up this:

dwc2 20980000.usb: dwc2_hsotg_enqueue_setup: failed queue (-11)

How is this to be fixed?

sirkus9 commented Mar 25, 2017

Once connected, does anyone know how to then use this connection to enable the rpi to connect to the Internet through the laptop? I would like to be able to install new packages to the pi from this connection. Doing some reading, I noticed Samy Kamkar indicates this is how he does it when describing the poisontap project, but I haven't figured it out yet. Anyone have any tips? I'm currently doing this from a Mac and Linux machine, and will keep playing with it.

rricharz commented Mar 26, 2017

To enable the rpi to connect to the internet, look under sharing network access in the following tutorial

didn't work on my pi zero w, don't know the specifics but non of the steps seemed to work. when i connect with PuTTY i get a connection timed out error, even after a 5 minute boot time.

TheDiveO commented Apr 4, 2017

Got my replacement RPi0W, which unfortunately is broken too: USB gadget mode does not work either! Cross-checked the same mSD in the working RPi0W: there, it works correctly. I've only now noticed that the good one also shows the error message in dmesg, so the presence of this error doesn't seem to be a clear indication. Good one works, can be ping'ed. Bad ones cannot be ping'ed and cannot ping.

All three RPi0W's which I tested, one good, two bad, all show this dmesg error:

dwc2 20980000.usb: dwc2_hsotg_enqueue_setup: failed queue (-11)

My Zero W is working fine for OTG networking, I followed the steps above. Make sure you've got the latest OS (I'm on Jessie Lite)

CliffC1 commented Apr 18, 2017

I found that the pi zero w uses a different hostname. In Ubuntu if you run 'avahi-browse -art' you should see an entry something like enp0s220u10, and the hostname is piZeroW.local

a1exus commented Apr 21, 2017

@gbaman, I followed all your steps:

  1. flashed latest raspbian (2017-04-10).
  2. modified config.txt by adding dtoverlay=dwc2 on new line.
  3. created blank ssh file on /boot partition.
  4. modified cmdline.txt by adding modules-load=dwc2,g_ether after rootwait.
  5. booted raspberry pi zero and cannot ssh in to pi@raspberrypi.local

yet can't ssh in( is there any way to troubleshoot that somehow (without monitor,keyboard,mouse)

Jswee1 commented Apr 21, 2017

When i try to use my RPIZeroW on windows i get a general failure when trying to ping it and no connection and putty `C:\WINDOWS\system32>ping raspberrypi.local

Pinging raspberrypi.local [----------------------] with 32 bytes of data:
General failure.
General failure.
General failure.
General failure.

Ping statistics for --------------------------------------:
Packets: Sent = 4, Received = 0, Lost = 4 (100% loss),`
my drivers are configured but it says unidentified network any tips?

brucehohl commented Apr 23, 2017

Since there are so many who have experienced various problems with their Pi setup and connection the following are the steps I used from Linux Mint 18 (Xfce desktop version) with success:

(1)- Downloaded Raspbian Jessie Lite image from here:

(2)- Copied image to Micro SDHC card via these instructions:
$ sudo dd bs=4M if=2017-04-10-raspbian-jessie.img of=/dev/sdb status=progress
$ sudo unzip -p | sudo dd of=/dev/sdX bs=4096

(3)- Edits made to image edits for SSH over USB per following web pages:

To /boot/config.txt add line with: dtoverlay=dwc2
To /boot add empty file: ssh
To /boot/cmdline.txt after rootwait add: modules-load=dwc2,g_ether

(4)- Unmount sd card; put in Pi Zero; connect USB cable between
Pi Zero power port and Linux computer.

(5)- From Linux computer:
Open the nm-connection-editor (from the panel).
Select Wired connection 2 (RasPi on USB) & click Edit.
Under 'IPv4 Setting' set 'Method' = 'Shared to other computers'. <<< IMPORTANT!

(6)- $ ssh pi@raspberrypi.local (password = raspberry)
Connection OK! Good luck to all!

Hello, I'm wondering if anyone can help someone who's new to this.
I have a Pi Zero W which is running the latest Raspbian. I have followed the instructions and from what I understand I have everything working on the Pi (running ifconfig shows a usb0 along with lo and wlan0) but none of the computers I've tried connecting it to recognise it as an RNDIS gadget. Originally I had tried to set up the Pi as both an ethernet and a serial gadget with modules-load=dwc2,g_ether,g_serial (I was originally following the Adafruit tutorial and wanted to experiment) but eventually set it back to modules-load=dwc2,g_ether after it didn't show up as either device, but even after setting the file back to known working code it still won't show up. I'm thinking my experiment was where I messed up, but I'm not totally sure since I had originally flashed Raspbian lite to the SD card, but later reformatted it with full Raspbian because I thought a GUI would be useful.

Anyway, thanks in advance, and I'm sorry if this has come up before but I've been looking around various places all day without much luck.

Like @NHellFire, I was also getting ssh: connect to host port 22: Connection refused, and when i checked /var/log/auth.log, I saw:

 18 Apr 10 10:17:20 raspberrypi sshd[447]: Server listening on port 22.                                                                                       
 19 Apr 10 10:17:20 raspberrypi sshd[447]: Server listening on :: port 22.                                                                                            
 20 Apr 10 10:18:44 raspberrypi sshd[476]: error: key_load_public: invalid format                                                                                     
 21 Apr 10 10:18:44 raspberrypi sshd[476]: error: Could not load host key: /etc/ssh/ssh_host_rsa_key                                                                  
 22 Apr 10 10:18:44 raspberrypi sshd[476]: error: key_load_public: invalid format                                                                                     
 23 Apr 10 10:18:44 raspberrypi sshd[476]: error: Could not load host key: /etc/ssh/ssh_host_dsa_key                                                                  
 24 Apr 10 10:18:44 raspberrypi sshd[476]: error: key_load_public: invalid format                                                                                     
 25 Apr 10 10:18:44 raspberrypi sshd[476]: error: Could not load host key: /etc/ssh/ssh_host_ecdsa_key                                                                
 26 Apr 10 10:18:44 raspberrypi sshd[476]: error: key_load_public: invalid format                                                                                     
 27 Apr 10 10:18:44 raspberrypi sshd[476]: error: Could not load host key: /etc/ssh/ssh_host_ed25519_key                                                              
 28 Apr 10 10:18:44 raspberrypi sshd[476]: fatal: No supported key exchange algorithms [preauth]          

Likewise my key files in /etc/ssh/ were empty.

I wasn't able to log into the Pi Zero to generate them (as @NHellFire did -- i have no other way to log in!) but I mounted the SD card on an Ubuntu machine and went into the /etc/ssh/ directory of the non-boot partition of the card, and ran (as per but for files local to this folder):

sudo ssh-keygen -t rsa -f ssh_host_key -b 1024
sudo ssh-keygen -t rsa -f ssh_host_rsa_key
sudo ssh-keygen -t rsa -f ssh_host_dsa_key

...each time saying "yes" to the prompt to overwrite. Then put the SD card back in the Pi and...

I'm in!!!! (a half-day project just to get in there!) Thanks all 🎈

Jabz commented May 1, 2017

For those having issues with your password, if using terminal on a mac make sure to check that you are using pi@raspberrypi.local as the address. If you don't you will still be asked for a password but it won't ever work. Password, as said above I believe, is "raspberry"

Thank you very much, works like a charm.

Hello guys,
Can anyone help me with mass storage thing. After changing cmdline.txt and config.txt when I am connecting R pi Zero with my pc I am getting Unknown USB device (Device Description not Found) .
Please help me out.
Thank you in advance

Hi all.

Is there any way I can setup my pi as HID with the g_hid module? I try it but I am not sure if I do everything right!

Many thanks

you can take look at this tutorial
Keyboard / Mouse / Joystick (HID)

Great guide, worked first time for me (if it's not working for you - be patient, it takes a while for the zero to come up on it's first boot!)

zambelly commented Aug 18, 2017

Raspbian Stretch was released yesterday and I couldn't get this to work on this new version. You can download the last release of Raspbian Jessie here and Jessie Lite here.

Tried these instructions with Stretch and it worked for me on a mac. Was able to ssh into raspberrypi.local

Linux raspberrypi 4.9.41+ #1023 Tue Aug 8 15:47:12 BST 2017 armv6l

I needed to configure manual address for usb0 in /etc/network/interfaces on the PI SD card to finally connect. So e.g.:

allow-hotplug usb0
iface usb0 inet static

This one is copied from

Without it i would just get an ethernet interface pop up with ping raspberrypi.local not replying, nmap not finding it and local dhcp server not receiving requests.
So finally i just set manual IP on the ethernet interface that pops up to and gateway to (exact opposite of what pi has). Ubuntu created a bridged interface too, i didnt touch that one AFAIK.

aldoaldoaldo commented Oct 11, 2017

I have a Pi Zero W.
I made the USB working on Win7 by

I had to edit my interfaces file adding:
allow-hotplug usb0
iface usb0 inet static

That's nice but the wifi on the Pi Zero W (that I did configure dropping a simple wpa_supplicant.conf in the /boot) stopped working.
I tried to place the conf directly in /etc/wpa_supplicant/wpa_supplicant.conf and to modify the file interfaces this way, but no luck :(

source-directory /etc/network/interfaces.d

auto lo
iface lo inet loopback

allow-hotplug usb0
iface usb0 inet static

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

iface default inet dhcp

Any idea?

ulab commented Oct 18, 2017

I had some problems getting this to work, for me it seems to be important to power up the Zero using the PWR USB port first, wait for a few seconds and then connect the MAC to the USB port of the Zero.

In addition, using Raspbian Stretch, I also needed to add an avahi file in the boot directory on the SD card. And since I was on a Mac I had to enable internet sharing via ethernet in my settings.

raoulj commented Nov 28, 2017

Worked just fine on Rapsbian Stretch Lite.

earcam commented Dec 14, 2017

For Linux (Mint/Ubuntu/Debian), configure the Wired Connection with method=link-local only under IPv4/IPv6 settings

BioBoost commented Dec 16, 2017

Maybe a small tip for windows 10 user who don't want to install the Bonjour service (like me). Just open a powershell window and check the arp cache using arp -a. Should show the ip address of the pi for the 169 subnet.

Interface: --- 0x1f
  Internet Address      Physical Address      Type           6e-47-03-c3-81-3c     dynamic       ff-ff-ff-ff-ff-ff     static             01-00-5e-00-00-02     static            01-00-5e-00-00-16     static           01-00-5e-00-00-fb     static           01-00-5e-00-00-fc     static       01-00-5e-7f-ff-fa     static       ff-ff-ff-ff-ff-ff     static here is my computer interface and is the Rpi.

Hope this helps

Hello guys,
when I am connecting R pi Zero with my pc I am getting Unknown USB device (Device Description not Found) .
Please help me out.

I still cant get this to work on Zero W with Stretch or Jessie with macOS Sierra -- the device would show up as Not Connected in Network but show up in ioreg

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment