Editing a project

How to change the code and upload to Bela

This page explains how to edit and upload Pure Data patches onto your Bela board.

Table of contents

  1. Get ready: Install Pure Data
  2. How Pure Data and the IDE relate
  3. Creating, editing, and uploading patches
    1. 1. Create a PD project
    2. 2. Download the _main.pd file
    3. 3. Edit your patch
    4. 4. Upload and run
  4. Learning more
  5. Up next

Get ready: Install Pure Data

Pure Data patches are edited on your computer using the Pure Data software, then uploaded to your board. This is different from other Bela-supported languages like C++ and SuperCollider, which are typed and edited directly in the editor window in the IDE.

Ensure that you have the latest version of Pure Data Vanilla installed on your computer.

Pure Data is free and open source software. If you’re curious there’s lots more information about Pd in our Pure Data language guide.

How Pure Data and the IDE relate

It’s important to note that the Bela IDE is not a Pure Data patching environment, which means you can’t edit the graphical objects which make up this language directly in the IDE. Instead, patches are created and edited in Pure Data running on your laptop, and are then uploaded to your Bela project using the IDE.

When you open a Pure Data project in the Project Explorer tab you can see the .pd files listed in your project. If you click on one, it will be visualised in the editor window. This is great for examining the patches in your Bela project, but you can’t edit them here.

Creating, editing, and uploading patches

1. Create a PD project

Go to the Project Explorer tab. Click the Create New Project button at the top, and in the dialog box, select Pure Data. Give your project a name, and click Create project.

This creates a blank Pure Data Bela project. In the Project Explorer tab you’ll see that the only thing there is a file called _main.pd.


The main Pd patch of your project must always be named `_main.pd`. You can have other Pd components, but the core patch always needs this name.

2. Download the _main.pd file

Download _main.pd it by clicking the Download button beside the file name. You can then open it in Pure Data on your computer to make edits to the patch.

3. Edit your patch

Now that you’ve downloaded _main.pd to your computer, you can edit it in Pure Data. The default patch for new Pure Data projects in the Bela IDE is a simple patch that produces a 440Hz sine tone:

This isn’t the most exciting synthesiser in the world, so as a first exercise we’ll edit this default patch and change the sinetone’s frequency.

Open the patch in Pure data, and switch to edit mode - do this by selecting Edit in the top menu, or use the shortcut Cmd + e (Ctrl + e on Windows). Once in edit mode you can move the boxes around, and edit the text in them by double clicking on them. Double click on [osc~ 440] and change 440 to another number, such as 330.

Save the patch, keeping the _main.pd file name.

4. Upload and run

To upload your patch to Bela, locate it in your Finder or File Explorer, and drag and drop it anywhere on the Bela IDE that’s loaded in your browser window.

You will see a dialog box that asks you if you want to overwrite the _main.pd file. The IDE will ask you this every time you want to upload, but since that gets tiresome you can click the tickbox to turn off this warning for your session:

Click Overwrite and your patch will be uploaded. Click the Run button in the toolbar to build and run your patch, and have a listen - you’ll hear a sine tone at a new frequency.


You don't have to stop your patch running to upload an edited patch. Just drag and drop your file from your computer's Finder or File Explorer into the Bela IDE, and the IDE will automatically upload. You will have to press the Run button again to start the new patch running (shortcut of Cmd + s or Ctrl + s).

Learning more

As we progress through these tutorials we cover many of the fundamentals of Pure Data as a programming language, but if you’re just starting and want to get familiar with the very basics this introduction is a great primer: http://www.pd-tutorial.com/english/ch01.html.

We’ve also got a list of helpful resources at the bottom of our Pure Data language guide.

If you’re already quite familiar with Pure Data and would just like to understand how to use the language on Bela in one quick example, have a look at the language-overview sketch in the Pure Data section of the Examples tab of the Bela IDE.

Up next

Next we’ll have a look at how to work with a breadboard.