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:
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:
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:
- 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):
- 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 firstname.lastname@example.org
- 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.
- Headless Pi Zero SSH Access over USB (Windows).
- Raspberry Pi Touchscreen Kiosk Setup
- Raspberry Pi Resource Guide
- Setting up Pi Zero OTG -- The quick way (No USB keyboard, mouse, HDMI monitor needed)
- Raspberry Pi Zero -- Programming Over USB (Part 2)
- HOWTO: Enable USB device mode on Pi Zero
- Raspberry Pi Zero -- Turning the Pi into a USB Gadget, over USB
About the Author
Mitch Allen works for a robotics company in New England.