Running Puredata patches on Bela

#Running Puredata 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.

The inputs and outputs are handled the same way for both Heavy and libpd.

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

• Note that analog inputs and outputs have a range between 0 and 1, unlike regular audio signals which have a range between -1 and 1.

• See the example patches in the /puredata folder for more information

###Using Digital I/O

• Bela's digital inputs and outputs can be addressed from pd. They can either be received as messages at message rate or as signals. Unlike analog channels, each digital pin can function as an input or an output - this needs to be set explicitly from within the patch.

• Before using digital I/O the pins need to be initialised by sending messages to the bela_setDigital receiver.

• To set a pin to be an input or output at message rate the following message needs to be passed to the receiver: [PINMODE PIN#(, where pinmode is in for input or out for output. The pin numbers PIN# range from 11-26, where 11 refers to digital pin 0 and 26 refers to digital pin 15. The reason for this numbering scheme is to retain consistency with the [adc~] and [dac~] numberings used. To set a pin to be received or written to at audio rate a tilde (~) is added as a third component of the message. To disable a pin the message [disable PIN#( can be sent to the receiver. See the following screenshot for example usage:

• If a pin is set to message rate, messages will only be received or written when the pin's value changes. If audio rate is specified, values are treated as a signal where values can change between low and high (0 and 1) 44100 times per second. Use [adc~] and [dac~] channels 11-26 to address the corresponding pin (after it has been initialised).

• See the digital example inside the Puredata examples folder for more information and practical examples.

###Using MIDI input

Most class-compliant USB MIDI devices are compatible with Bela. You can use the [notein] and [ctlin] objects to receive midinote and CC messages from the device. See the hello-midi example inside the Puredata examples folder for more information.

##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. Libpd patches can be compiled from the IDE or from the command line using the supplied build scripts.

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.

###Running libpd patches from the IDE

• You can run any PureData example simply by selecting it and hitting the run button, just like any other project. When you open the example, the _main.pd file will be previewed in the browser window. At this point, it is not possible to edit the file in the browser.

• To start a new libpd project in the browser IDE navigate to the Project Explorer tab and click New Project. You will then be presented with a dialogue allowing you to choose between a C++ or a Puredata project. Select Puredata.

• You can now simply drag-and-drop the from your PD patch into the browser IDE, replacing the default _main.pd file in the folder. Note that the top-level patch needs to be named _main.pd. To edit existing examples or write your own patches, you will need to install PureData on your computer. Get the latest version of Pd from here: http://puredata.info/downloads/pure-data

###Compiling libpd projects using the build scripts

To run Pd patches on Bela using libpd, you simply have to compile any project that contains a _main.pd file and run it. You need to have the libpd.so file installed in /usr/lib on your BBB in order to be able to run projects with libpd. This is provided with the Bela image and is updated through the update_board script.

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

###Getting everything up and running

Follow the following steps to get everything up and running on your Beaglebone Black. Commands below must be run in a terminal on your computer which must be connected to the internet:

1. Download the project archive from https://github.com/BelaPlatform/Bela/archive/master.zip

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

1. 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:

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

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 bela (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!

• ./build_pd_heavy.sh ../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_heavy.sh ../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.

###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!