⚠️ This may still work, but isn't maintained, and you can now use the Raspberry Pi Imager to set network/WiFi settings directly while flashing an OS image: https://www.raspberrypi.com/software/
Bootstrap a headless Raspberry Pi 3 (without a keyboard, mouse, or monitor) using Docker on macOS.
This Docker image lets you manipulate the Raspbian .img
image (which has an ext4
partition unreadable by macOS) directly from Docker on macOS without having to run a Linux VM or use a Linux host.
The included bash scripts can automatically set up the configuration for Bluetooth, WiFi, and SSH, and correctly mount the Raspbian image's two partitions for manipulation.
There are many guides online that achieve the same goal, but unfortunately require you to run a Linux VM to modify the ext4
partition.
I suggest the Bluetooth option as it is the most straightforward, and you can then setup WiFi directly on the Pi through the Bluetooth terminal. Getting the WiFi to bootstrap itself can be tricky, and hard to troubleshoot without a keyboard/mouse/monitor.
Inspiration :
- https://caffinc.github.io/2016/12/raspberry-pi-3-headless/
- https://hacks.mozilla.org/2017/02/headless-raspberry-pi-configuration-over-bluetooth/
-
Download Docker
-
Clone this repository
git clone https://github.com/nihalgonsalves/headless-pi-setup.git
-
Grab an image of Raspbian
- Desktop environment: https://downloads.raspberrypi.org/raspbian_latest
- Lite terminal-only: https://downloads.raspberrypi.org/raspbian_lite_latest
Save the resulting
.img
file (unzip first) somewhere, we will need to mount this later.
Edit the wpa_supplicant.conf.diff
and dhcpcd.conf.diff
files in src/pi_files
. Add your own network and configure the IP ranges, router and DNS correctly (you can leave the lines commented if you have a working DHCP setup)
# when inside this repo's root
docker build . -t headless-pi-setup
# absolute path to raspbian img from earlier
export IMAGE=/host/path/to/raspbian.img
# to customise, replace bt with: eth / wlan / all
docker run \
--rm \
--privileged \
-v $IMAGE:/home/images/raspbian.img:consistent \
headless-pi-setup bash -c './auto.sh bt'
You should see output similar to this:
[headless-pi-setup] Auto-configuring all
mount: /dev/loop0 mounted on /mnt/pi/boot.
mount: /dev/loop1 mounted on /mnt/pi/os.
[headless-pi-setup] Mounted
[headless-pi-setup] SSH enabled
[headless-pi-setup] WiFi setup complete
[headless-pi-setup] Bluetooth setup complete
[headless-pi-setup] Unmounted
[headless-pi-setup] Auto-configuration done!
Now simply burn the image file (for example with Etcher) to your microSD card and boot up your Raspberry Pi 3
If you want to manually run commands or inspect the img
's file system:
docker run \
-it \
--rm \
--privileged \
-v $IMAGE:/home/images/raspbian.img:consistent \
headless-pi-setup
# once you're inside the container, mount the img:
./mount.sh
# don't forget to unmount and exit when done:
./umount.sh && exit
-
Boot up the Pi, wait a minute or two, and then restart it. This lets the Bluetooth config take effect.
-
Pair with it from your Mac
-
Find the serial device:
ls /dev/cu.*
- Connect
screen /dev/cu.raspberrypi-SerialPort 115200
- Stop other devices from pairing
./headless/btsecure.sh
(You need to do this on each reboot).
If all went well, you should be able to ssh into the Pi:
ssh pi@raspberrypi.local # password is raspberry
(Try a static IP or a tool such as Pi Finder if you cannot connect)
Simply delete the folder, and restore rc.local
sudo rm -fR /home/pi/headless/
sudo rm /etc/rc.local
sudo mv /etc/rc.local.backup /etc/rc.local
The WiFi bootstrapping simply adds network data to /etc/wpa_supplicant/wpa_supplicant.conf
and /etc/dhcpcd.conf
. You can update these files if you would like to remove any data.
Delete the ssh
file in the root of the boot volume on the SD card.