I only occasionally work with a Raspberry Pi, which means I keep forgetting and having to rediscovery some pretty basic tasks.

This post is my crib sheet for working with a headless Pi…

OS Install (SD Card set up)

Download the latest Raspbian (e.g., 2017-09-07-raspbian-stretch) and unzip it to expose the .img file.

Insert the SD card and find the device name:

mac$ diskutil list

For example, you’ll probably see something like:

/dev/disk2 (external, physical):
   #:                       TYPE NAME          SIZE       IDENTIFIER
   0:     FDisk_partition_scheme              *15.9 GB    disk2
   1:             Windows_FAT_16 RECOVERY      1.5 GB     disk2s1
   2:                      Linux               33.6 MB    disk2s5

So: the SD card is /dev/disk2. Install the OS…

mac$ sudo dd bs=1m if=/path/to/2017-09-07-raspbian-stretch.img of=/dev/disk2

This takes about 30 minutes.

Prepare for First Boot

We want to:

  1. Enable SSH
  2. Configure WiFi (e.g., for Pi Zero W 1.1)
  3. Possibly modify cmdline.txt boot configuration
  4. Eject the SD card

Enable SSH

Add an empty file called ssh on the SD card to enable SSH on boot. The boot partition will be mounted in MacOS as /Volumes/boot, so:

mac$ touch /Volumes/boot/ssh

Configure WiFi

The WiFi configuration is set up by creating a wpa_supplicant.conf file on the boot partition. Note: this file is automatically moved elsewhere on boot, and so will vanish from the boot partition.

The file should be something like:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=GB

network={
    ssid="Your Network SID"
    psk="Your Wifi Password"
    key_mgmt=WPA-PSK
}

Configure cmdline

I’m not sure if this is needed or not anymore.

Modify /Volumes/boot/cmdline.txt to read:

dwc_otg.lpm_enable=0 console=serial0,115200 console=tty1 root=PARTUUID=e17410f1-02 rootfstype=ext4 elevator=deadline fsck.repair=yes rootwait modules-load=dwc2,g_ether quiet splash plymouth.ignore-serial-consoles

Eject the SD card

mac$ diskutil unmountDisk /dev/disk2

First Boot

Put the SD card into the Pi and power it up.

Connect via Wifi

mac$ ssh pi@raspberrypi.home

Connect via USB

Check you plug the cable into the USB socket, and not the one marked for power.

The USB connection also provides power, so you don’t need both plugged in.

For SSH connection you need an OTG USB cable: other kinds of USB cable just won’t work.

mac$ ssh pi@raspberrypi.local

To access the internet from the Pi over SSH: On Mac, in system settings, sharing, enable internet sharing with RNDIS/Ethernet Gadget.

Without an internet connection the Pi will not keep accurate time, unless you also add a RTC.

Troubleshooting

Locating the Pi on the network

nmap is great but you have to install it from source on the mac. Use it like this:

mac$ ~/Developer/third-party/nmap/nmap-7.60/nmap -sn 192.168.1.0/24

…assuming you installed in in ~/Developer.

Or use apr -a instead.

After boot

  1. Change the password.
  2. scp a new ssh key across.
  3. Run sudo raspi-config to enable ssh, camera, VNC, or whatever you need.

SSH key

The instructions for this are on the raspberrypi.org.

Running VNC

Install the viewer on the Mac.

Accessing the Pi Filesystem

It’s sometimes convenient to take the SD card, plug it into the Mac, and noodle around the ext3 filesystem (e.g., to look at logs).

MacOS doesn’t support ext3 out of the box. Buy Paragon ExtFS: it works really well.

Update

pi$ sudo apt-get update
pi$ sudo apt-get upgrade

Camera

To enable access to the camera via /dev/video0, run:

pi$ sudo modprobe bcm2835-v4l2

This is needed for some software packages (e.g., motion and maybe timolo).

To view the camera real-time over VNC, you need to enable hardware capture.

As per the instructions from Real VNC:

pi$ sudo vi root/.vnc/config.d/vncserver-x11

…and add:

CaptureTech=raspi
ExperimentalRaspiCapture=1
ServerPreferredEncoding=JPEG

And restart:

pi$ sudo systemctl restart vncserver-x11-serviced