SSH into Pi Zero over USB (7 Steps)

UPDATE: This article now covers the new security change that disables ssh access by default. The Raspbian image version has also been updated.

This article covers setting up a Pi Zero for SSH USB access using a Mac. The Windows instructions can be found here: Headless Pi Zero SSH Access over USB (Windows).

When you first get a Pi Zero the big question is -- how do you access it? You can get a powered USB hub, USB keyboard, USB mouse and HDMI adapter. Or you can just plug it into your computer directly and access it over USB using ssh.

These instructions are for a Raspbian Buster image that I downloaded from here:

https://www.raspberrypi.org/downloads/raspbian/

I'm using the lite image (no desktop) version 4.19 from June 20, 2019. I've also done this with an older desktop version and Jessie Lite.

Here are my notes from walking through the process. You can find links to the original instructions in the References section below.

Step 1. Edit the image

To access the Pi Zero over USB you have to edit the image first.

  • If you have the SD card in your Pi Zero, power it down and remove it
  • Put the SD card in an adapter and plug it into your computer
  • On a Mac the SD card should appear on your desktop
  • Open the SD card icon to explore the contents

Step 2. Access the micro SD card from the command line

At a command line do the following:

ls -ls /Volumes/

You should see something like this:

total 13
8 lrwxr-xr-x  1 root   admin     1 Jul 28 09:41 Macintosh HD -> /
5 drwxrwxrwx@ 1 mitch  staff  2560 Jul 28 11:47 boot

The volume named boot should be the SD card with the Raspbian image on it.

Now do this:

ls -ls /Volumes/boot

You should now see the contents of the root of your Raspbian boot image.

Step 3. Enable ssh

There was a security update to the Raspbian images. Now to enable ssh by default you have to do the following:

touch /Volumes/boot/ssh

This will write an empty file to the root of your Raspbian image. That will enable ssh on startup.

Step 4. Edit config.txt

  • In the root folder of the SD card, open config.txt (/Volumes/boot/config.txt) in a text editor
  • Append this line to the bottom of it:
    dtoverlay=dwc2
  • Save the file

Step 5. Edit cmdline.txt

  • In the root folder of the SD card, open cmdline.txt (/Volumes/boot/cmdline.txt) in a text editor
  • After rootwait, append this text leaving only one space between rootwait and the new text (otherwise it might not be parsed correctly):
    modules-load=dwc2,g_ether
  • If there was any text after the new text make sure that there is only one space between that text and the new text
  • Save the file

On a fresh image that has never been booted, you may see extra text after rootwait. But if you boot the pi from the disk at least once, that extra text may go away. That is why you must put the new text directly after rootwait - so it doesn't get accidentally deleted.

Step 6. Boot the Pi Zero

  • Put the SD card into the Pi Zero
  • Plug a Micro-USB cable into the data/peripherals port (the one closest to the center of the board -- see picture above)
  • You do NOT need to plug in external power -- it will get it from your computer
  • Plug the other end into a USB port on your computer
  • Give the Pi Zero plenty of time to bootup (can take as much as 90 seconds -- or more)
  • You can monitor the RNDIS/Ethernet Gadget status in the System Preferences / Network panel (note that the IP address listed is not the host)

Step 7. Login over USB

This part assumes that ssh is enabled for your image and that the default user is pi with a password of raspberry.

  • Open up a terminal window
  • Run the following commands:
    ssh-keygen -R raspberrypi.local
    ssh pi@raspberrypi.local
  • If the pi won't respond, press Ctrl-C and try the last command again
  • If prompted with a warning just hit enter to accept the default (Yes)
  • Type in the password -- by default this is raspberry

Congratulations! You can now access your Pi Zero with just a USB cable.

Related Articles

Here is a list of my related articles that you may find interesting:


References

  • Setting up Pi Zero OTG [1]
  • Raspberry Pi Zero -- Programming Over USB (Part 2) [2]
  • HOWTO: Enable USB device mode on Pi Zero [3]
  • Raspberry Pi Zero -- Turning the Pi into a USB Gadget, over USB [4]

.