Running Puredata patches on Bela » History » Version 14

Giulio Moro, 2016-04-09 02:30 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 13 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 13 Giulio Moro
The project will load the patch called _main.pd from the folder where you launch it from.
43 13 Giulio Moro
44 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.
45 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.
46 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).
47 13 Giulio Moro
Actual block size can be adjusted at runtime using the -C command line parameter.
48 13 Giulio Moro
Accepted values are 8, 16, 32, 64, 128, default is 16.
49 13 Giulio Moro
50 13 Giulio Moro
h2. Heavy
51 13 Giulio Moro
52 13 Giulio Moro
Heavy relies on an online Pd-to-C compiler.
53 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.
54 13 Giulio Moro
TODO: License
55 13 Giulio Moro
56 13 Giulio Moro
h3.  Getting everything up and running
57 13 Giulio Moro
58 1 Christian Heinrichs
Follow the following steps to get everything up and running on your Beaglebone Black:
59 9 Giulio Moro
60 13 Giulio Moro
*1. Download the project archive from https://code.soundsoftware.ac.uk/*
61 1 Christian Heinrichs
62 1 Christian Heinrichs
* Extract the archive (and remember where you extracted it to)
63 1 Christian Heinrichs
64 1 Christian Heinrichs
*2. Make sure python is installed:*
65 1 Christian Heinrichs
66 1 Christian Heinrichs
* Type `which python` in a terminal window. If not installed, follow instructions here: https://wiki.python.org/moin/BeginnersGuide/Download
67 1 Christian Heinrichs
68 1 Christian Heinrichs
* Install the most up-to-date version of the *requests* python package (version 2.7.0). You can get it from http://docs.python-requests.org/en/latest/user/install/
69 1 Christian Heinrichs
     or typing the following in a terminal window (make sure it is not currently installed):
70 1 Christian Heinrichs
71 5 Christian Heinrichs
@curl -OL https://github.com/kennethreitz/requests/zipball/master && unzip master && cd kenneth* && sudo python setup.py install@
72 1 Christian Heinrichs
73 1 Christian Heinrichs
if the above does not work, try this:
74 1 Christian Heinrichs
75 1 Christian Heinrichs
<pre>curl "https://bootstrap.pypa.io/get-pip.py" -o "get-pip.py"
76 1 Christian Heinrichs
sudo python get-pip.py #install pip packet manager for python
77 1 Christian Heinrichs
pip install request
78 11 Giulio Moro
</pre>
79 11 Giulio Moro
*3. Create an account on enzienaudio.com:*
80 1 Christian Heinrichs
81 11 Giulio Moro
* Go to http://www.enzienaudio.com
82 1 Christian Heinrichs
83 10 Giulio Moro
* Click *Login* on the top right corner of the page
84 10 Giulio Moro
85 10 Giulio Moro
* Create a new account
86 1 Christian Heinrichs
87 1 Christian Heinrichs
* Create a new patch and call it **bbb** _(N.B. compiling won't work if you use a different name)_
88 1 Christian Heinrichs
89 1 Christian Heinrichs
*4. Make sure the Beaglebone is plugged in to laptop and open a terminal window:*
90 1 Christian Heinrichs
91 1 Christian Heinrichs
* Navigate to the _scripts_ folder @cd /path/to/folder/scripts@
92 1 Christian Heinrichs
93 1 Christian Heinrichs
* If running for the first time @sh setup_board.sh@
94 1 Christian Heinrichs
95 1 Christian Heinrichs
*5. Compile your first project!*
96 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.
97 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.
98 1 Christian Heinrichs
99 1 Christian Heinrichs
Alternatively:
100 1 Christian Heinrichs
* @./build_pd.sh -i ../projects/heavy/pd/hello-world/@
101 1 Christian Heinrichs
This script compiles your project, uploads it to the Beaglebone and starts it.
102 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:
103 1 Christian Heinrichs
@./build_pd.sh -i ../projects/heavy/pd/hello-world/ --screen --watch@
104 1 Christian Heinrichs
105 1 Christian Heinrichs
*6. Create a new pd project*
106 1 Christian Heinrichs
107 1 Christian Heinrichs
* Create a new folder inside the /pd directory
108 12 Giulio Moro
109 12 Giulio Moro
* The pd patch must exist in its own folder and be named *_main.pd*. You can use abstractions if you like.
110 12 Giulio Moro
111 13 Giulio Moro
h3.  Important notes
112 1 Christian Heinrichs
113 1 Christian Heinrichs
* Make sure you aren't using any unsupported objects. For a full list of objects go to https://enzienaudio.com/docs/pdobjects.html
114 6 Christian Heinrichs
115 1 Christian Heinrichs
* The Pd patch must exist in its own folder and be named *_main.pd*. You can use abstractions if you like.
116 6 Christian Heinrichs
117 1 Christian Heinrichs
* See the example pd patches for more information.
118 7 Christian Heinrichs
119 13 Giulio Moro
You can also access the slides from the latest Bela workshop on compiling Pd patches at the following link: https://goo.gl/59hShW This also includes some handy tips for handling Bela's sensor inputs using Puredata.
120 1 Christian Heinrichs
121 1 Christian Heinrichs
*Have fun!*