Running Puredata patches on Bela » History » Version 19

Giulio Moro, 2016-05-24 08:19 PM

1 14 Giulio Moro
h1.  Running Puredata patches on Bela
2 1 Christian Heinrichs
3 13 Giulio Moro
Here's a quick guide to compiling Pd patches on Bela.
4 1 Christian Heinrichs
5 13 Giulio Moro
There are two ways you can run Pd patches on Bela: using Enzien Audio's Heavy Audio Tools or using libpd.
6 13 Giulio Moro
Libpd is a GUI-less version of Pd which allows to embed Pd patches into other programs, whereas Heavy is an online service that generates highly-optimized C code from a Pd patch.
7 13 Giulio Moro
Libpd runs all of Pd vanilla objects, almost all of of which are supported on Bela.
8 13 Giulio Moro
Pd patches compiled with Heavy can only contain a susbet of Pd vanilla objects.
9 13 Giulio Moro
Using libpd, a patch can be run immediately, as soon as it is copied over to the Beaglebone.
10 13 Giulio Moro
When using Heavy, you have to re-compile the patch every time you modify it, which may take up to one minute and requires an internet connection.
11 13 Giulio Moro
In turn, code generated by Heavy runs much faster than libpd, especially when compiled with Clang.
12 1 Christian Heinrichs
13 13 Giulio Moro
h3.  Using analog ins/outs
14 1 Christian Heinrichs
15 13 Giulio Moro
* You can directly address the analog ins and outs from within PD (note that you have to compile and run the patch onto the BeagleBone to receive the data)
16 13 Giulio Moro
17 13 Giulio Moro
* Use the [adc~] and [dac~] objects to receive and send the data
18 13 Giulio Moro
19 13 Giulio Moro
* [adc~ 3] refers to Analog Input 0 (first two channels of [adc~] are audio inputs), likewise for [dac~]
20 13 Giulio Moro
21 13 Giulio Moro
* These inputs are sampled at audio sampling rate, so handle them as you would audio signals. (Use [snapshot~] if you want to turn them into control-rate values). When the analog channels are sampled at a different rate than the audio, they are resampled automatically in the wrapper.
22 13 Giulio Moro
23 13 Giulio Moro
* See the example patches in the /pd folder for more information
24 13 Giulio Moro
25 13 Giulio Moro
h3. Using Digital I/O
26 13 Giulio Moro
27 13 Giulio Moro
* It is not currently possible to use Bela's digital I/O from Pd patches.
28 13 Giulio Moro
While this is totally feasible, we yet have to decide on what the API should look like.
29 13 Giulio Moro
Suggestions are welcome!
30 13 Giulio Moro
Meantime, digital I/O can be reached from the wrapping C++ code.
31 13 Giulio Moro
32 13 Giulio Moro
h3. Using MidiIn
33 13 Giulio Moro
34 15 Giulio Moro
You can use the objects [bela_notein], [bela_ctlin], [bela_pgmin], which you can find in the BeagleRT/projects/heavy/pd/hello-midi/ folder. These are drop-in replacements for Pd's own objects and allow to receive Midi data from a USB device plugged into the Beaglebone.
35 13 Giulio Moro
MidiIn is currently available only when using Heavy.
36 13 Giulio Moro
37 13 Giulio Moro
38 13 Giulio Moro
h2. Libpd
39 13 Giulio Moro
40 13 Giulio Moro
Libpd on Bela is a port of the original libpd with a few minor modifications to make it run smoothly in Bela's Xenomai environment.
41 13 Giulio Moro
To run Pd patches on Bela using libpd, you simply have to compile the basic_libpd project and run it.
42 16 Giulio Moro
A pre-compiled copy of the project is attached to this wiki page.
43 13 Giulio Moro
The project will load the patch called _main.pd from the folder where you launch it from.
44 16 Giulio Moro
You need to have the file installed in /usr/lib on your BBB in order to be able to compile the basic_libpd project.
45 16 Giulio Moro
You can either "compile it from source": or use the pre-compiled file attached to this wiki.
46 13 Giulio Moro
47 13 Giulio Moro
One for all, the original libpd implementation reads files and sockets at every audio callback from within the audio thread, which is bad practice in general, and particularly in the case of Bela, as this causes mode switches in the audio thread.
48 13 Giulio Moro
The file and socket input has therefore been moved to a separate thread so that it does not interfere with the audio thread.
49 13 Giulio Moro
Another thing that changed is the minimum block size, which is now 8 samples per block (vs the 64 of stock Pd/libpd).
50 13 Giulio Moro
Actual block size can be adjusted at runtime using the -C command line parameter.
51 13 Giulio Moro
Accepted values are 8, 16, 32, 64, 128, default is 16.
52 13 Giulio Moro
53 13 Giulio Moro
h2. Heavy
54 13 Giulio Moro
55 13 Giulio Moro
Heavy relies on an online Pd-to-C compiler.
56 13 Giulio Moro
The Pd patch and the related abstractions and audio files are uploaded to the Heavy server and then downloaded on Bela, where they are compiled into machine code.
57 15 Giulio Moro
The use of the compiler is subject to Enzien Audio's terms and conditions and the generated C code is subject to the MIT license for non-commercial use.
58 13 Giulio Moro
59 13 Giulio Moro
h3.  Getting everything up and running
60 13 Giulio Moro
61 19 Giulio Moro
Follow the following steps to get everything up and running on your Beaglebone Black. Commands below must be run in a terminal on the host computer which must be connected to the internet:
62 9 Giulio Moro
63 17 Giulio Moro
*1. Download the project archive from*
64 1 Christian Heinrichs
65 1 Christian Heinrichs
* Extract the archive (and remember where you extracted it to)
66 1 Christian Heinrichs
67 1 Christian Heinrichs
*2. Make sure python is installed:*
68 1 Christian Heinrichs
69 1 Christian Heinrichs
* Type `which python` in a terminal window. If not installed, follow instructions here:
70 1 Christian Heinrichs
71 1 Christian Heinrichs
* Install the most up-to-date version of the *requests* python package (version 2.7.0). You can get it from
72 1 Christian Heinrichs
     or typing the following in a terminal window (make sure it is not currently installed):
73 1 Christian Heinrichs
74 5 Christian Heinrichs
@curl -OL && unzip master && cd kenneth* && sudo python install@
75 1 Christian Heinrichs
76 1 Christian Heinrichs
if the above does not work, try this:
77 1 Christian Heinrichs
78 1 Christian Heinrichs
<pre>curl "" -o ""
79 1 Christian Heinrichs
sudo python #install pip packet manager for python
80 1 Christian Heinrichs
pip install request
81 11 Giulio Moro
82 11 Giulio Moro
*3. Create an account on*
83 1 Christian Heinrichs
84 11 Giulio Moro
* Go to
85 1 Christian Heinrichs
86 10 Giulio Moro
* Click *Login* on the top right corner of the page
87 10 Giulio Moro
88 10 Giulio Moro
* Create a new account
89 1 Christian Heinrichs
90 1 Christian Heinrichs
* Create a new patch and call it **bbb** _(N.B. compiling won't work if you use a different name)_
91 1 Christian Heinrichs
92 1 Christian Heinrichs
*4. Make sure the Beaglebone is plugged in to laptop and open a terminal window:*
93 1 Christian Heinrichs
94 1 Christian Heinrichs
* Navigate to the _scripts_ folder @cd /path/to/folder/scripts@
95 1 Christian Heinrichs
96 1 Christian Heinrichs
* If running for the first time @sh
97 1 Christian Heinrichs
98 1 Christian Heinrichs
*5. Compile your first project!*
99 1 Christian Heinrichs
* If you are on a Mac, you can browse to the BeagleRT/resources/MacOS folder and you will find an app called BelaPdBuild. You just have to drag and drop the folder containing your files on this icon and in a matter of seconds your Pd patch will be running on the Beaglebone.
100 1 Christian Heinrichs
The first time you do this, you will be prompted for your enzienaudio credentials, which you just created in the steps above.
101 1 Christian Heinrichs
102 1 Christian Heinrichs
103 18 Giulio Moro
* @./ -i ../projects/heavy/pd/hello-world/@
104 1 Christian Heinrichs
This script compiles your project, uploads it to the Beaglebone and starts it.
105 1 Christian Heinrichs
If you run this script with the --watch --screen flags, it will check automatically for edits in your Pd files and refresh your build automatically: no need to touch the terminal again, as long as you keep working in the same folder. For example:
106 18 Giulio Moro
@./ -i ../projects/heavy/pd/hello-world/ --screen --watch@
107 1 Christian Heinrichs
108 1 Christian Heinrichs
*6. Create a new pd project*
109 1 Christian Heinrichs
110 1 Christian Heinrichs
* Create a new folder inside the /pd directory
111 12 Giulio Moro
112 12 Giulio Moro
* The pd patch must exist in its own folder and be named *_main.pd*. You can use abstractions if you like.
113 12 Giulio Moro
114 13 Giulio Moro
h3.  Important notes
115 1 Christian Heinrichs
116 1 Christian Heinrichs
* Make sure you aren't using any unsupported objects. For a full list of objects go to
117 6 Christian Heinrichs
118 1 Christian Heinrichs
* The Pd patch must exist in its own folder and be named *_main.pd*. You can use abstractions if you like.
119 6 Christian Heinrichs
120 1 Christian Heinrichs
* See the example pd patches for more information.
121 7 Christian Heinrichs
122 13 Giulio Moro
You can also access the slides from the latest Bela workshop on compiling Pd patches at the following link: This also includes some handy tips for handling Bela's sensor inputs using Puredata.
123 1 Christian Heinrichs
124 1 Christian Heinrichs
*Have fun!*