Introduction: Pure Pi: Control Custom Stompbox Effects on a Raspberry Pi With a Smartphone

This is my first instructable, although I have been working with Pure Data, Raspberry Pi, and other digital audio for quite some time. If you'd like to see more instructables like this, vote for me!

Ever wonder how digital effects are created? Want to customize your favorite effects wirelessly from a smartphone? Then Pure Pi may be your best option. The Pure Pi uses a Raspberry Pi Model B running the Raspbian distro of Pure Data Extended, all controlled from an iPhone or Android phone via TouchOSC. Sounds like a lot of work, but thanks to the work done by the Pure Data and Raspberry Pi communities, it’s a Wheezy breeze. Here are the steps to getting the Pure Pi set up on your Raspberry Pi and controlling it by phone.

Step 1: Materials Needed

  • Raspberry Pi running Raspbian (any model should work, I’ve used Model B)
  • USB audio interface (I’ve used a Behringer UCG102, there are several that work out of the box)
  • A WiFi dongle (if you don’t want to connect via ethernet cable)
  • A Smartphone with TouchOSC installed (see below) or similar OSC software
  • (optional) wireless access point connected to your Raspberry Pi

Step 2: Install Pure Data Extended on the Pi

Pure Data is an open source visual 'computer music system' which allows you to create and customize digital effects, called "patches", to tweak and mod audio to your heart's content. The most popular version, PD extended, has built in features and patches to make it easier to learn how to use Pure Data and design your custom effects.

(Update: A newer version of PD Extended has been released for Raspian on SourceForge, it may be easier to download directly from them but I'll provide steps for installing from the Pi).
The following installation guide is what I used to install PD Extended on my Raspberry Pi running the newest version of Raspbian Wheezy (the $ lines are typed into the Pi terminal without the $ symbol):

1. Edit the sources list to include the new archives

$ sudo nano /etc/apt/sources.list

2. Add the following line to the end of the list (note the spaces):

deb-src wheezy main contrib non-free rpi

3. Save and Exit:

ctrl+o, Enter (to save). ctrl+x (to exit)

4. Update Raspbian:

$ sudo apt-get update

5. Download PD Extended:

$ wget

6. Unpack the PD Extended .deb file:

$ sudo dpkg -i Pd-0.43.3-extended-20121004.deb

7. Install PD Extended

$ sudo apt-get -f install

8. After installation type this for root priorities:

$ sudo chmod 4755 /usr/bin/pd-extended

If everything went successfully, you should now have PD Extended installed on your Raspberry Pi. Feel free to poke around in PD to learn how to use it, configure PD, install plugins or try out various patches.

Step 3: Configure Your Audio Input/output

Depending on your audio card, you might need to download drivers or configure the Raspberry Pi audio settings (I use Pi’s standard ALSA). For me, it was as simple as plugging in the USB and typing lsusb and/or lsmod (those are lowercase L's) in the Pi terminal to show if it was working correctly. Most USB audio cards should work out-of-box but check the ALSA Project page to make sure if your card is compatible or not. Once you’ve plugged in the USB interface it’s as simple as running PD extended (type pd-extended in the terminal) and then opening the PD test patch to see that the audio is working. (Note: in order to see the graphical PD windows while running 'headless' you need to use a GUI like LXDE).

At this point you should be able to hear something coming from your USB audio output. If you're having problems with your USB audio or sound quality not what you expected, check out these helpful links:

Step 4: Install the LADSPA Plugins and Custom Patches

If you’re interested in using my own custom patch for TouchOSC, then first you need to install plugins that contain most of the effects by downloading the TAP-Plugins from SourceForge or this instructable. Once you’ve downloaded them you can copy the file directly to your Raspberry Pi. I use WinSCP to directly transfer files to the Raspberry Pi, but you can also download the files directly from the Pi by typing the following into the Pi terminal:

1. Update Raspbian:

$ sudo apt-get update

2. Install the tap-plugins:

$ sudo apt-get install tap-plugins

Once you’ve got these plugins installed, you can mess around with them in PD-Extended using the [plugin~] command. Check GuitarExtended’s site for more details if you’re interested in learning more about how to use plugins within PureData, as well as a ton of cool patches I’ve included in my own set. If you want to just use my patch collection, then go ahead and download the osc_munch.pd file from this instructable.

This is the patch I use for jamming and gigs. It contains 16 different
effects (roughly grouped into 4 categories: “Distortion”, “Pitch”, “Modulation” and “Echo/Delay”) as well as a 4-stage mixer and tap-tempo controlled looper. You can use the patch directly without a phone, though it may seem a bit confusing to anyone new to Pure Data. If you get any errors you might need to re-install the LADSPA plugins above, or unclick the OSC router to stop constantly attempting to connect to a phone.

Step 5: Install TouchOSC and Connect!

I’ve used MIDI in the past to control effects in PD (check out my sixplugins patch set to see how to use MIDI commands with various patches in PD Extended), but recently found a huge improvement in communication control thanks to OSC. By using WiFi instead of cables, it also allows you to control your patches wireless by phone or any device with an OSC app installed. For android phones, it's as simple as installing the Android version of TouchOSC onto the phone, and then creating my own custom interface by installing touchOSCeditor on my computer. If you just want the layout I use on my phone, then follow these steps:

1. Download and install the appropriate version of TouchOSC from the Appstore/GooglePlay

2. Download the munchlayout.touchosc file and copy it to your phone's TouchOSC folder

3. Open TouchOSC and select Layout -> Add from File -> munchlayout.touchosc

4. Run the OSC_munch patch in PD-Extended and make sure your phone and Raspberry Pi are on the same WiFi router (see the next step to learn how to create an AD-HOC connection without a router).

5. You might need to adjust the settings in TouchOSC and in the PD Patch to send/receive messages.

  • In TouchOSC on your phone, change the following settings:
    • Host – your Raspberry Pi’s IP address
    • Port(outgoing) – 8000
    • Port(incoming) – 9000
  • In the munch_OSC patch in PD-extended:
    1. Open up the PD patch in the top-right corner called [pd OSCrouter]
    2. Hit Ctrl+E to enter edit mode, click on the message that says [connect 9000] and change it to your phone’s IP address

That should do it, now you’re ready to rock out with a phone-controlled 16-effect DSP machine! Throw the Pi into a Hammond 1590BB case, add a few lines of code to auto-load your patch on startup and you’ve got your own custom effect pedal. Feel free to modify the patch to your needs, or post comments/questions in the comments section for more help.

Step 6: Going Further: Set Up Your Pi to Auto-connect Directly With Your Phone

This step is a work in progress, as I’ve only recently managed to find a way to hack my android phone in order to connect to ad-hoc networks. I won’t get into the details, but there are several sources on the web for setting up a rooted android phone to connect to an ad-hoc network. If you’ve got an iPhone or have a rooted/ad-hoc friendly Android phone, then this might just work for you.

Notice I say might work, as I’ve had unreliable connections from my WiFi dongle. It may be a power issue or a crappy WiFi module, since it sometimes doesn’t send/receive messages correctly, doesn’t stay connected, or my phone can’t see it at all. But, if you’re still reading this and are undaunted, continue on:

1. Set up your Raspberry Pi to run headless (no keyboard, mouse, or screen)

2. Configure your Pi to either connect to WiFi or create an Ad-Hoc network

This step brought me a lot of frustration and I nearly gave up until I realized it was my WiFi dongle that wasn’t working properly. I think some WiFi dongles can't draw enough power for AdHoc mode without an external powered USB hub. Once you complete these two steps you should have an available network connection to your Pi even when there isn’t a router available. Now set up your Pi to auto-load the patch on startup.

3. To Auto-login your Pi on startup, type:

$ sudo nano /etc/inittab

comment out (by typing # in front of the line):

1:2345:respawn:/sbin/getty -coclear 38400 tty1

add the following line (note the spaces):

1:2345:respawn:/bin/login -f pi tty1 /dev/tty1 2>&1

4. To Load a Pure Data patch on startup, type:

$ nano

Type the following 5 lines exactly as they appear:


startx &

sleep 10 #delay for xserver

export DISPLAY=:0 #This is a zero

pd-extended -alsa -alsamidi -midiindev “1” /home/pi/osc_munch.pd #change this to your pd patch

Save and exit, then edit your startup file:

$ sudo nano /etc/rc.local

add the following line:

sudo sh /home/pi/

Now you should have a standalone effect box that will allow you to directly connect to your phone without the need of a router. Add a shutdown button, set up serial port MIDI, throw it in a 1590BB stomp box and you’ve got it made! It’s Pure Pi.


samuelS188 made it! (author)2017-02-28

I'm having an issue with inputting audio from my guitar into pd. Output and the effects work fine I just can't get the signal from my guitar into the program. I know it's not an issue with the sound card or with the settings in pd, i can plug my phone in and not have issues. I tested all my adapters and they're working as well. I'm assuming the solution to this problem is simple but any help would be appreciated.

jmuncher made it! (author)jmuncher2017-02-28

Sure I'd be happy to help! So just to clarify, you can hear the audio output from PD but not get any audio input? Or just the guitar signal isn't being picked up by PD? If it's the latter case, then most likely you will need a preamp of some sort to boost the signal. Either try using a pedal with a boost or search for "simple guitar preamp" online.

I hope this helps, but let me know if you still can't get a clean signal from PD. What adapter are you using? I think it may depend on whether the analog to digital converter has a strong signal coming into it.

samuelS188 made it! (author)samuelS1882017-03-01

do you have a recommendation on a cheap audio card??

jmuncher made it! (author)jmuncher2017-03-01

If your phone signal works I don't think it's the audio card. It could be a mono vs. stereo issue, since your phone signal probably outputs stereo and your guitar only has mono. Do you see any signal in the VU meter (like in the photo)? If there is no signal, then try switching the input device under audio settings to 2 channels and see if anything changes. If there is a low signal response, then you will need a signal booster (preamp) between your guitar and the usb adapter.

samuelS188 made it! (author)samuelS1882017-03-01

He output works fine. In-N-Out only stops working when i plug my guitar in (audio from my phone works fine). Here's the sound card I'm using:

I tried putting my overdrive pedal between the guitar and pi but it didn't work. Thanks for the advice. I guess I'll get a new audio card.

fdmusse made it! (author)2016-12-08

pd-extended has been abandoned. You can do the same by using Pd vanilla and installing the required externals (as a bonus, it works with Raspbian Jessie, which is not supported by pd-extended):

sudo apt-get install puredata pd-osc pd-ggee pd-maxlib pd-hcs pd-plugin pd-iemnet

Don't forget to add the externals to Pd's path (File > Preferences > Path). I have added the following externals: osc, ggee, maxlib, hcs, plugin~, iemnet (the ones installed above) and Gem (came with Pd). Add each external's folder individually to the path. They are located in /usr/lib/pd/extra.

You can delete import mreach from the the author's patch, iemnet provides the required objects.

fenyvesi made it! (author)fenyvesi2016-12-22

I tried the method you defined with pd-vanilla and add the externals you proposed, deleted mrpeach import from the original source file.

When I start the osc_munch.pd besides the info lines there is a failure:

/~: no method for 'bang'

I have no idea what is related to. Any idea? Thanks.

George Fenyvesi

fenyvesi made it! (author)fenyvesi2016-12-23

Pd says that the cause is the pitchsifter.pd with the following:box:

/~ tapehead rotation freq

brickinthewall10 made it! (author)2015-12-12

Thanks for the response! I have been searching around on the Internet tonight to try and figure it out but I'm still having troubles. I'm sure it's some noob mistake.
Its just a constant distortion sound. None of the effects work in oscmunch. Clicking the buttons doesn't do anything. I also created my own pd file that should just send out clean tone but still it's just the same distortion sound. I am going through ALSA. Is that okay? I also went ahead and plugged in to my laptop to see if it sounded any better on there but it's also exactly the same distortion sound that I get for output. I'm thinking maybe my audio settings aren't right? I bought the same behringer USB interface that you did. Here's also an attached picture of my audio settings

jmuncher made it! (author)jmuncher2015-12-14

Your settings are exactly the same as mine, have you tried selecting 'test audio and MIDI' in that same drop down menu (Media) and then clicking the box labeled 60 or 80 to play a test tone? If you don't hear anything then It might be that your audio output to the USB jack isn't initializing properly. Let me know if you can't play any sounds and I'll try to help you figure out why it isn't playing. The Behringer USB audio device should be plugged in before you turn on the Pi, it'll autodetect with no need to install drivers. Are you running Raspbian Wheezy?

brickinthewall10 made it! (author)2015-12-10


I have attempted this project and I have a quick question. I have gotten all the way to the point of connecting the PI to the phone in OSC. I have all the connections right. Yet for some reason I am only getting a constant fuzz tone in my amp. It shows no hosts on the phone and messing with OSC_munch doesnt change the fuzz tone. Any ideas?

Thanks, Collin

jmuncher made it! (author)jmuncher2015-12-11

Hi Collin,

Glad to hear you've gotten started, it was a little tough for me at the beginning to get the audio working reliably. I'm not exactly sure what the cause is, but here's a good checklist of why it might be happening:
1. Are you able to get clean sound by unchecking all the boxes in both the colored 4x4 grid and the 4 black boxes in the top left corner of the OSC_munch patch in PD Extended (not the TouchOSC phone app)? The 4x4 grid are the effects themselves, while the 4 black boxes are for each 'loop' of effects. Unclicking all of them should bypass all the effects and give you a clean sound.
2. Does the box labeled [pd OSCrouter ] have an X or does it blink on and off? This is the phone connection, if it's blinking it hasn't properly connected. If it stays connected, you should be able to see the sliders in the patch move when you move them on the phone.
3. Have you tried using headphones in place of your amp? I don't think this is the problem but it's easier to diagnose problems using headphones and not as a result of too much amp gain.

Hopefully we can figure out what's going wrong, it's good that you've already got the patch up and running! For me, configuring the audio and installing all the LADSPA plugins were the most difficult. It sounds like you're almost there!