Headless Pi: Start to Finish

Goal: Build up a RaspberryPI + Pisound system for running patches headless (no display or keyboard attached).

Difficulty: Intermediate


This tutorial is longer than most. It’s aim is get you from bare parts to a working, headless music computer without having to scour the internet for each step of the way.

These instructions result in a set up that has been battle tested in live performance many times.

Optimized for Headless Use: Yes

Recommended Raspberry Pi Models:

  • Raspberry PI 3B+
  • Raspberry PI 3B

Required Hardware:

  • Pisound
  • Raspberry Pi w/ power supply and micro SD card
  • Windows, macOS or Linux computer w/ micro SD card reader

Chapter 1: Prepare the SD card

Aim of this chapter is to get the SD card ready with the base system image.

If you have already done this, be sure to follow the last step here to enable ssh.

Download Raspian “lite” image

Download from here: https://www.raspberrypi.org/downloads/raspbian/

You want the version named "RASPBIAN STRETCH LITE"

You can use the “DESKTOP” image, and it will have tons of software already installed and set up… but its not small by any means. Most of it has nothing to do with running the Pi as a music computer. Further, some of it might well slow the unit down.

Copy the image to the SD card

Copying the image onto the SD card is not like copying a file. You’ll need to use a special, lowlevel tool designed for the purpose.

Follow one of these:

Enable SSH in the Image

This is very important so that you can connect into the Pi when it boots headless.

After the copying the image, you’ll need to edit it slightly before using it in the Pi. If you can’t see the mounted SD card volume on your desktop, remove it and then insert it again in the card reader. You should have an external disk named boot.

You need to add a file called ssh (no extensions!) at the top of this volume.

On OS X, in the terminal, you can just run this command:

touch /Volumes/boot/ssh

Or you can use any text editor you like to create an empty file. Just be sure it has no file extension (like .txt), and is named just ssh.

Now eject the SD Card from your desktop.

On OS X, from the terminal, you can type:

diskutil eject /dev/disk#

Chapter 2: First boot and basic system set up

The aim at this stage is to get the Pi booted, on the network, and with the basic packages you’ll need.

Network Preparation

You will need to get the Pi on your local wired network:

  • If you have a spare Ethernet jack on your hub or switch or router, you can just plug the Pi into that.

  • If not, you can connect the Ehternet port on the Pi to the Ethernet port on your computer (or perhaps a USB Ethernet adapter on your computer), and sharie access to the internet you get via WiFi:

    Set up network sharing on OS X

Hardware Break

You can now half assemble your Pi:

  • Unpack the Pi: Don’t put it in any case yet. Don’t power it on. Don’t attach heat sinks (ever). Place it on something non-conductive like the paper bag it came in.
  • Insert the SD Card
  • Connect an Ethernet cable between the Pi and your computer.
  • Now plug in the power.

Log In

Back on your computer, in a terminal, run:

ssh pi@raspberrypi.local

If ssh doesn’t seem to ever connect, perhaps your network is a bit unusual. Try Find Raspberry Pi’s IP Address, and use the IP address in place of raspberrypi.local.

You’ll get asked if you trust this new host. Type yes and hit return.

Then you’ll get asked for the password. It’s raspberry.

You’ll see a lot of text, and then the prompt:

pi@raspberrypi:~ $

You’re in! From now on, all the shell commands are to be typed into this terminal.

Update and Install Basics

This will ensure you have the latest version of all the installed packages.

sudo apt-get update
sudo apt-get dist-upgrade

Depending on how old the image you downloaded is, this could be quick or take some time.

Now install the minimal things needed to be able to run a graphical desktop. You’ll use this graphical desktop when you connect to the Pi from your computer. This makes working in PureData or SuperCollider nice. Because we’re setting it up minimal, when you run headless, the desktop will not be running, and the audio programs will run without visual UI.

Run these two commands. Don’t be clever and combine them:

sudo apt-get install --no-install-recommends \
    screen vim \
    git make \
    xserver-xorg xinit \

sudo apt-get install raspberrypi-ui-mods

Swap emacs for vim if you prefer, or install both. You’ll get asked if you want to proceed (‘Y’, of course). These two commands will download well over a hundred packages.


This step uses the standard RaspberryPi configuration program to configure the Pi. This is a funny “terminal menu” program. It uses the arrow keys, the tab key to navigate.

Run in the shell on the Pi:

sudo raspi-config

Here is exactly what you need to set.

Do not be tempted to set more things now - you can always re-run this command later and change things.

1. Change User Password

Change it now! To something you’ll remember.

Then configure:

3. Boot Options
    B1 Desktop / CLI
        B3 Desktop

4. Localisation Options
    I2 Change Timezone
        -- pick your timezone

4. Localisation Options
    I4 Change Wi-fi Country
        -- pick your country

5 Interfacing Options
    P3 VNC
        Yes    (use arrow keys to select)

7. Advanced Options
    A3 Memory Split

7. Advanced Options
    A5 Resolution
        1600x1200   (or whatever you like, but the default is too small!)

Then [tab] key to Finish, hit return, then select Yes to reboot.

Graphic Login

You can work with your Pi entirely from the ssh connection. But having a graphical desktop on the Pi often makes setting up patches, and debugging them much much easier. We’ve taken care that this works when you use it, but is otherwise not taking up significant resources when your not.

On your computer, install RealVNC Viewer

Run it and connect to your Pi (raspberrypi.local). You’ll need to enter login information twice - once so RealVNC and connect to the Pi… and then once to the Pi screen that comes up.

Play around with the desktop if you like. Customize the colors and background image.

From the big raspberry icon on the task bar, Shutdown the pi…

Hardware Break

You can fully assemble your Pi + Pisound:

  • Follow the instructions on Blokas’ web site: Getting Started.

  • If assembling the case, pay attention to the height of the standoffs - there are short and long ones, and the short ones go on the bottom. Also the bottom plate may need to be flipped over as the two sides aren’t exactly the same. Try fitting the long side pieces in before screwing all down to see which way it goes.

  • Leave the SD Card in - it is really hard to insert it once you start assembling the case.

Once it is all assembled, connect the network again, then power it back on.


You’ve got the Pi set up as a minimal system that will just boot up without a display, but can have a desktop when you need it.

That was the hard part… getting audio set up is going to be much easier!

Chapter 3: Pisound software

The aim is to get the Pisound all working.

Log into the Pi via ssh or use RealVNC and open a shell window (On the task bar, click the screen icon (has “>_” symbol).

Install Pisound Drivers

Blokas provides an installer script. You can download it directly into the shell so it runs immediately:

curl https://blokas.io/pisound/install-pisound.sh | sh

That always makes me nervous, so I do it this way:

curl -O https://blokas.io/pisound/install-pisound.sh
less install-pisound.sh   # look at it and see if it sensible
sh install-pisound.sh
rm install-pisound.sh

In either case, you may have to enter your password, since installation runs with sudo.

At the end of the script it suggests:

Now you may run sudo pisound-config to customize your installation!

Hold off!, we will install the music software manually to ensure it is minimal.

Verify Drivers

You can verify that the drivers are installed, and that the Pisound hardware is all operating with the O.S.

Run this to see the list of audio output devices:

aplay -l

You should see this, with pisound listed in the list:

**** List of PLAYBACK Hardware Devices ****
card 0: ALSA [bcm2835 ALSA], device 0: bcm2835 ALSA [bcm2835 ALSA]
  Subdevices: 7/7
  Subdevice #0: subdevice #0
  Subdevice #1: subdevice #1
  Subdevice #2: subdevice #2
  Subdevice #3: subdevice #3
  Subdevice #4: subdevice #4
  Subdevice #5: subdevice #5
  Subdevice #6: subdevice #6
card 0: ALSA [bcm2835 ALSA], device 1: bcm2835 ALSA [bcm2835 IEC958/HDMI]
  Subdevices: 1/1
  Subdevice #0: subdevice #0
card 1: pisound [pisound], device 0: PS-2DES12E snd-soc-dummy-dai-0 []
  Subdevices: 1/1
  Subdevice #0: subdevice #0

Run this to see the list of audio input devices:

arecord -l

You should see:

**** List of CAPTURE Hardware Devices ****
card 1: pisound [pisound], device 0: PS-2DES12E snd-soc-dummy-dai-0 []
  Subdevices: 1/1
  Subdevice #0: subdevice #0

Run this to see the list of MIDI devices:

aconnect -l

You should see this:

client 0: 'System' [type=kernel]
    0 'Timer           '
    1 'Announce        '
client 14: 'Midi Through' [type=kernel]
    0 'Midi Through Port-0'
client 20: 'pisound' [type=kernel,card=1]
    0 'pisound MIDI PS-2DES12E'

If you have some USB MIDI devices plugged in, you’ll see them in that list, too!

Chapter 4: Music software

Finally, install some music software, and make sure it is configured to work with Pisound. These articles are separated out, as they are useful for all

Done! Enjoy! Make Music!


Great and useful tutorial. I have followed it to completion.


Thanks for the tutorial. It helped solidify some of the command line and networking stuff that I was having trouble understanding. Great learning experience. Well recommended.


6 posts were split to a new topic: Getting started and documentation feedback

Once everything’s installed , not sure to understand if our patch starts automatically on Pure Data without the need to open any patch from the graphic interface of the Rasb Pi ?

You can make the system autolaunch some PD patch. I’d recommend starting from Patchbox OS though - it’s presetup with everything to get you going, including automatically launching PD patches, as long as the patch is placed in its own subfolder at /usr/local/puredata-patches, and its entry point is main.pd, or you create a blokas.yml in the subfolder describing the patch, including defining the entry point .pd file.

Does the boot to pd-file memorize the pd project audio interface setup?

It’s launched like this: pisound/start_puredata.sh at patchbox · BlokasLabs/pisound · GitHub - if the audio settings are stored in .pdsettings, those should get used. Patchbox OS provides a preconfigured .pdsettings to use the shared Jack backend for audio.

1 Like