Bela

h1.  Running Puredata patches on Bela

Here's a quick guide to compiling Pd patches on Bela.

There are two ways you can run Pd patches on Bela: using Enzien Audio's Heavy Audio Tools or using libpd.

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.

Libpd runs all of Pd vanilla objects, almost all of of which are supported on Bela.

Pd patches compiled with Heavy can only contain a susbet of Pd vanilla objects.

Using libpd, a patch can be run immediately, as soon as it is copied over to the Beaglebone.

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.

In turn, code generated by Heavy runs much faster than libpd, especially when compiled with Clang.

h3.  Using analog ins/outs

* 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)

* Use the [adc~] and [dac~] objects to receive and send the data

* [adc~ 3] refers to Analog Input 0 (first two channels of [adc~] are audio inputs), likewise for [dac~]

* 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.

* See the example patches in the /pd folder for more information

h3. Using Digital I/O

* It is not currently possible to use Bela's digital I/O from Pd patches.

While this is totally feasible, we yet have to decide on what the API should look like.

Suggestions are welcome!

Meantime, digital I/O can be reached from the wrapping C++ code.

h3. Using MidiIn

* 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.

MidiIn is currently available only when using Heavy.

h2. Libpd

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.

To run Pd patches on Bela using libpd, you simply have to compile the basic_libpd project and run it.

The project will load the patch called _main.pd from the folder where you launch it from.

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.

The file and socket input has therefore been moved to a separate thread so that it does not interfere with the audio thread.

Another thing that changed is the minimum block size, which is now 8 samples per block (vs the 64 of stock Pd/libpd).

Actual block size can be adjusted at runtime using the -C command line parameter.

Accepted values are 8, 16, 32, 64, 128, default is 16.

h2. Heavy

Heavy relies on an online Pd-to-C compiler.

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.

TODO: License

h3.  Getting everything up and running

Follow the following steps to get everything up and running on your Beaglebone Black:

*1. Download the project archive from https://code.soundsoftware.ac.uk/*

* Extract the archive (and remember where you extracted it to)

*2. Make sure python is installed:*

* Type `which python` in a terminal window. If not installed, follow instructions here: https://wiki.python.org/moin/BeginnersGuide/Download

* 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/

     or typing the following in a terminal window (make sure it is not currently installed):

@curl -OL https://github.com/kennethreitz/requests/zipball/master && unzip master && cd kenneth* && sudo python setup.py install@

if the above does not work, try this:

<pre>curl "https://bootstrap.pypa.io/get-pip.py" -o "get-pip.py"

sudo python get-pip.py #install pip packet manager for python

pip install request

</pre>

*3. Create an account on enzienaudio.com:*

* Go to http://www.enzienaudio.com

* Click *Login* on the top right corner of the page

* Create a new account

* Create a new patch and call it **bbb** _(N.B. compiling won't work if you use a different name)_

*4. Make sure the Beaglebone is plugged in to laptop and open a terminal window:*

* Navigate to the _scripts_ folder @cd /path/to/folder/scripts@

* If running for the first time @sh setup_board.sh@

*5. Compile your first project!*

* 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.

The first time you do this, you will be prompted for your enzienaudio credentials, which you just created in the steps above.

Alternatively:

* @./build_pd.sh -i ../projects/heavy/pd/hello-world/@

This script compiles your project, uploads it to the Beaglebone and starts it.

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:

@./build_pd.sh -i ../projects/heavy/pd/hello-world/ --screen --watch@

*6. Create a new pd project*

* Create a new folder inside the /pd directory

* The pd patch must exist in its own folder and be named *_main.pd*. You can use abstractions if you like.

h3.  Important notes

* Make sure you aren't using any unsupported objects. For a full list of objects go to https://enzienaudio.com/docs/pdobjects.html

* The Pd patch must exist in its own folder and be named *_main.pd*. You can use abstractions if you like.

* See the example pd patches for more information.

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.

*Have fun!*