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 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 (or use a Pi with built-in WiFi).

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:

sudo raspi-config

The following options are required:

  • Under “Interfacing Options,” enable SPI

The following are optional but recommended:

  • Change User Password
  • If your Pi will be on a network (wired or wireless):
    • Under “Interfacing Options,” enable ssh to allow remote login (this makes it easier to copy-and-paste the installation commands later)
    • Under “Network Options” select “Hostname” to distinguish it from other Rasperry Pis on your network; mine is called “lightpaint”
    • If using WiFi, under “Localisation Options” select “Change WiFi Country” to match your location, then under “Network Options” configure the wireless network SSID and password

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

Using a USB WiFi adapter? The LED on most will create a problematic light streak when painting; unplug the adapter when photographing 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:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install git usbmount python-dev python3-pip libopenjp2-7 libtiff5
sudo pip3 install evdev pillow adafruit-circuitpython-dotstar
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:

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.

sudo nano /lib/systemd/system/systemd-udevd.service

Add this line for Pi OS Buster and Bullseye in the [Service] section of the configuration file:


Look for this line (older Raspbian "Stretch") - This syntax no longer works with Buster / Bullseye releases.


And change it to:



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:

python3 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 pip3 commands above?
  • Are the usbmount scripts installed in the correct locations?
  • If it complains about the lightpaint.so file, you may need to recompile that (type “make” in the DotStarPiPainter directory)
Some USB flash drives have a power-on LED. Cover the LED with tape, or use a different flash drive with no onboard light.


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

Without a keyboard and monitor attached, shutting down the system would be problematic. Linux systems really expect an orderly shutdown, you can’t just pull the plug or the SD card may get corrupted.

One option is to configure the SD card to boot in read-only mode, as explained in this guide. This is probably best, but wait until you have the light painter completely configured and working first!

Another choice is installing our gpio-halt utility. This tiny program lets you connect a button that performs an orderly system shutdown. (One or the other, you don’t need both.)

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:

sudo nano /etc/rc.local

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

/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 Mar 08, 2024.

This page (Raspberry Pi Setup) was last updated on Mar 08, 2024.

Text editor powered by tinymce.