Raspberry Pi Setup

If using a single-USB-port system (Model A, A+ or Pi Zero), either use a USB hub so you can have keyboard and wireless attached during setup, or borrow a Model B/B+/Pi 2 for setup and then move the card over to the target system once finished.

This project works well with the Raspbian “Lite” operating system — a pared-down system that doesn’t include any GUI apps. Don’t bother with the full-featured Raspbian image for this project, it’s enormous!

Fetch Raspbian Lite here:

Raspberry Pi Downloads Page

If you’re new to Raspberry Pi and Linux, we strongly suggest working through the first few guides in the Learn Raspberry Pi tutorial series…know how to “burn” an SD image, perform a first-time setup and get the Raspberry Pi connected to a network. Some familiarity with one of the text editors (such as the simple nano or the more daunting vi or emacs) is also recommended.

Install the Raspbian Jessie Lite image on a 2GB or larger microSD card. You’ll need to connect a monitor and USB keyboard for basic system configuration, but this is only temporary…we’ll set it up to run “headless” later. For networking, connect either an Ethernet cable or a USB WiFi adapter.

The first-time boot takes longer than usual; this is normal as the system does some self-configuration.

Log in as user “pi”, password is “raspberry”, then run the system configuration tool:

Download: file
sudo raspi-config

The following options are required:

  • Expand Filesystem
  • Under “Advanced Options,” enable SPI and load kernel module by default

The following are optional but recommended:

  • Change User Password
  • Under “Internationalisation Options,” Change Keyboard Layout. If getting unexpected symbols when typing, this is why. I typically use Generic 104-key PC, English (US).
  • If your Pi will be on a network (wired or wireless), then under “Advanced Options” select:
    • Change Hostname to distinguish it from other Rasperry Pis on your network; mine is called “lightpaint.”
    • Enable SSH for remote administration (this makes it easier to copy-and-paste the installation commands later).

You can further twiddle system settings to your liking. Tab over to the “Finish” button and reboot the system when prompted.

If you’re setting up on a wired network, skip ahead to “Installing Packages” below. Otherwise, log in as “pi” again and let’s set up WiFi…

Download: file
sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

Add the “network” section shown here, changing the network name and password to match your setup:

Download: file
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev

Note: this file is super-persnickety about formatting. The lines in the network section should be indented with a single tab (not spaces). If the Pi won’t join the WiFi network, it may be an extra space or two somewhere in this file.

Save changes and reboot the system to activate wireless networking.

Download: file
sudo reboot
WiFi is handy for setup and administration, but the LED on most wireless adapters will create a light streak when painting; remove it for photography or cover the LED with tape.

Install Packages

With ssh enabled, you can use a terminal program and log into the system remotely at lightpaint.local or whatever name you’ve given the system. This is preferable as you can copy-and-paste commands directly. Otherwise, you can log in with screen and keyboard as usual, just be very mindful of spelling.

Lets install a few prerequisite packages and fetch the light-painting software:

Download: file
sudo apt-get update
sudo apt-get install git usbmount python-dev python-imaging python-pip
sudo pip install evdev
git clone https://github.com/adafruit/Adafruit_DotStar_Pi
git clone https://github.com/adafruit/DotStarPiPainter

usbmount is a package for sensing when USB drives are plugged in or removed. We need to install a couple of scripts so that it can inform our light-painter code of these events:

Download: file
cd DotStarPiPainter
sudo cp 99_lightpaint_mount /etc/usbmount/mount.d
sudo cp 99_lightpaint_umount /etc/usbmount/umount.d

If running a Raspbian “Stretch” operating system (the current/latest major revision of Raspbian), we need to edit an obscure system file for usbmount to work correctly.

Download: file
sudo nano /lib/systemd/system/systemd-udevd.service

Look for this line:

Download: file

And change it to:

Download: file


Download: file
sudo reboot

Dry Run

You don’t need any LEDs connected yet, let’s just make sure all of the software parts are working as expected. Start the light-painting program with:

Download: file
sudo python DotStarPiPainter.py

If all goes well, nothing should happen…it’s waiting for a USB drive to be inserted. Plug in a USB flash drive with one or more images on it, and after a moment you should see it print a message that it’s loading and processing an image. Fantastic! Press Control+C to break out of the program and we’ll do some final setup.

If the program throws an error, or if it doesn’t detect the USB drive:

  • Usually it’s a missing package. DId you do the entire apt-get and pip commands above?
  • Are the usbmount scripts installed in the correct locations?
  • If it complains about the dotstar.so file, you may need to recompile that (type “make” in the Adafruit_DotStar_Pi directory) and copy it to this directory.
Some USB flash drives have a power-on LED. Cover the LED with tape, or switch to a “dark” drive with no light.


Let’s set up the Pi to run fully headless now.

I recommend installing our gpio-halt utility. This tiny program lets you connect a button that performs an orderly system shutdown. (Just pulling the plug on a Linux system is a bad idea and can corrupt the SD card, so you’d have to start over.)

Download: file
git clone https://github.com/adafruit/Adafruit-GPIO-Halt
cd Adafruit-GPIO-Halt
sudo make install

Then edit the rc.local file to start up our code automatically at boot time:

Download: file
sudo nano /etc/rc.local

Just before final “exit 0” line, insert this line:

Download: file
/usr/local/bin/gpio-halt 21 &

Change the “21” to whatever GPIO pin your shutdown button is connected to (the other leg of the button should connect to a ground pin). On Pi models with the 40-pin header, GPIO 21 is at the very end (nearest the USB ports) with an adjacent ground pin, so it’s very convenient to connect a button across these two pins. On older Pi models with a 28-pin header, GPIO 7 is similarly situated at the end of the header:

This will take effect on the next reboot. Then, to shutdown, tap the button (or jumper across the pins with a screwdriver if no button installed yet) then wait at least 15 seconds before disconnecting power. Test it once with a monitor connected to confirm that it’s working before running the system headless.

This guide was first published on Dec 11, 2015. It was last updated on Dec 11, 2015. This page (Raspberry Pi Setup) was last updated on Feb 21, 2018.