Raspberry Pi Zero W headless setup on macOS
Tags: raspberrypi, macos, raspbian
Published: 2018-03-24 18:52:36

---
title: Raspberry Pi Zero W headless setup on macOS
published: true
tags: raspberrypi,macos,raspbian
canonical_url: https://brandonb.ca/raspberry-pi-zero-w-headless-setup-on-macos
---

Recently I acquired a RaspberryPi Zero W, a few years after I regretted selling my RaspberryPi B board back in 2013. The following is an account of the trials and tribulations I endured to get it connected to the internet!

This setup requires no monitor, or external keyboard, not even the OTG USB cable that I bought because I thought I needed it.

<!-- break -->
## Prerequisites

If you’re reading this you’re probably here to learn how to get a rPi Zero W running Raspbian and connected wirelessly to the internet. To do that, there’s a few things you’ll need:

1. A copy of the [Raspbian Jessie Lite image](https://www.raspberrypi.org/downloads/raspbian/)
2. An 8GB+ MicroSD card (and some way to plug it into your computer in order to flash an image to it)
3. A micro USB cable (to plug the rPi into your computer temporarily)
4. A 2.4Ghz wifi access point (the rPi Zero W doesn’t support 5Ghz which I learned the hard way 😞 )

If you have all of these things, great! If not, order all the parts quickly on BuyAPi and continue as if you have them in hand.

## Preparing the SD card

I’ve ran these commands on macOS, so your mileage may vary on Windows/Linux. Plug the SD Card into your computer and once it is mounted you’ll want to unmount it from the terminal to flash it.

To unmount the drive and prep it for writing the image, run the following:

```
sudo df -h # Use the output of this to determine <diskname> in the next command
sudo diskutil unmount /dev/<diskname>
```

If the previous command completed, you have a drive that you can copy the Raspbian image to!

## Writing the image to the SD card

Run the command below to start writing the image to the SD card:

```
sudo dd bs=1m if=/path/to/raspbian-jessie-lite.img of=/dev/rdisk2
# Where disk2 is the number of the disk from earlier
```

The command above should only take a few minutes depending on the size of the SD card. After it completes you’ll need to do a few things.

Start by opening your terminal and running `touch /Volumes/boot/ssh`. The existence of this empty file in the root of the drive will enable SSH on first boot when we connect it with the USB cable.

Next, append `dtoverlay=dwc2` to the end of the `/Volumes/boot/config.txt` file on a new line.

Finally, open `/Volumes/boot/cmdline.txt` and insert `modules-load=dwc2,g_ether` after the `rootwait` entry following the same space-delimited pattern as the rest of the file.

Once you’ve completed the steps outlined above, unmount the drive again from the terminal and plug it into the rPi and connect the power USB cable to the board.

## First boot into the OS

Give the rPi about 60s to boot up and then connect the other USB cable from the OTG port to your computer.

Once connected, open `System Preferences -> Network` and you’ll notice there is a new `RNDIS/Ethernet Gadget` network adapter added in the list. It will probably show up with a `169...` IP address so you’ll need to head to `System Preferences -> Sharing` now to enable “Internet Sharing” for the `RNDIS/Ethernet Gadget` adapter.

Make sure you check the correct boxes as illustrated below:

<picture>
          <source data-srcset="https://dc1r9kxqg42ml.cloudfront.net/brandonb.ca/posts/raspberry-pi-zero-w-headless-macos/network-adapters.png, https://dc1r9kxqg42ml.cloudfront.net/brandonb.ca/posts/raspberry-pi-zero-w-headless-macos/network-adapters@2x.png 2x"></source>
          <img src="https://dc1r9kxqg42ml.cloudfront.net/brandonb.ca/posts/raspberry-pi-zero-w-headless-macos/network-adapters.png" srcset="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" data-sizes="auto" data-srcset="https://dc1r9kxqg42ml.cloudfront.net/brandonb.ca/posts/raspberry-pi-zero-w-headless-macos/network-adapters.png, https://dc1r9kxqg42ml.cloudfront.net/brandonb.ca/posts/raspberry-pi-zero-w-headless-macos/network-adapters@2x.png 2x" alt="macOS Network Adapters">
        </picture><picture>
          <source data-srcset="https://dc1r9kxqg42ml.cloudfront.net/brandonb.ca/posts/raspberry-pi-zero-w-headless-macos/network-configuration.png, https://dc1r9kxqg42ml.cloudfront.net/brandonb.ca/posts/raspberry-pi-zero-w-headless-macos/network-configuration@2x.png 2x"></source>
          <img src="https://dc1r9kxqg42ml.cloudfront.net/brandonb.ca/posts/raspberry-pi-zero-w-headless-macos/network-configuration.png" srcset="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" data-sizes="auto" data-srcset="https://dc1r9kxqg42ml.cloudfront.net/brandonb.ca/posts/raspberry-pi-zero-w-headless-macos/network-configuration.png, https://dc1r9kxqg42ml.cloudfront.net/brandonb.ca/posts/raspberry-pi-zero-w-headless-macos/network-configuration@2x.png 2x" alt="macOS Network Sharing Configuration">
        </picture>

Once you have local network access to the rPi, you can ssh in with:

```
ssh pi@raspberrypi.local
```

## SSH into the RaspberryPi

Once you’re ssh’d into the rPi, you can setup the wifi so that being connected via USB is nolonger required.

In order to get the right configuration for your wifi, run the `wpa_passphrase` utility with your SSID and it will ask for your password:

```
wpa_passphrase "SSID HERE"
# You will be prompted to enter your password.
# The utility should generate something like:
# network={
# ssid="SSID"
# #psk="PASSWORD"
# psk=...
# }
```

**NOTE** : If you have a custom wifi setup that isn’t WPA2-PSK/TKIP encrypted network, you will need to do some research into the [config values](https://linux.die.net/man/5/wpa_supplicant.conf) for `wpa_supplicant`!

Copy the output of the command above into the `/etc/wpa_supplicant/wpa_supplicant.conf` file and overwrite whats in the `network={...}` section.

```
sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
```

After pasting the output, save and exit the file. `wpa_supplicant` should pick up on the changes to the file and connect to the wifi automatically.

You can confirm that your rPi has connected to your wifi by running `sudo ifconfig wlan0` on the rPi in your SSH session. In the output, look for `inet addr:...` which should display an ip address. If this looks correct, then your rPi is connected to your DHCP server/router.

The other option is by checking in the GUI of the router itself in your browser to see if the router issued an IP address to the rPi.

## Update the system

Once you’re connected to the wifi, the first thing you should do is update `apt-get` and upgrade Raspbian as there are undoubtedly some security packages between the image creation and the time you install it on your rPi.

```
sudo apt-get update -y
sudo apt-get upgrade -y
sudo apt-get dist-upgrade -y
```

* * *

Once you’d completed the above steps, you should now have a functioning RaspberryPi Zero W connected to the internet and ssh’able!

### Optional things to do after setup

- [Setup an MOTD](https://github.com/gagle/raspberrypi-motd)
- Install [oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh)
- Install [nodejs](https://github.com/creationix/nvm)

### Resources

- [http://blog.gbaman.info/?p=791](http://blog.gbaman.info/?p=791)
- [https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md](https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md)
- [http://blog.remmelt.com/2017/03/20/easy-headless-setup-for-raspberry-pi-zero-w-on-osx/](http://blog.remmelt.com/2017/03/20/easy-headless-setup-for-raspberry-pi-zero-w-on-osx/)